Describes the modules as they are in the source tree (the version is [project].version in
pyproject.toml); update it with every change that adds a module, a CLI command or a public name.
Repository: https://github.com/bitranox/sercomm-printserver
Documentation: README.md, INSTALL.md, CONFIG.md, DEVELOPMENT.md, CONTRIBUTING.md, CHANGELOG.md,
docs/python-api.md (library reference)
Device notes: docs/Manual-PS301.md, docs/config-keys.md, docs/adr/0001-memory-adapters-in-src.md
Public API: src/sercomm_printserver/init.py (__all__; every name resolving is checked by tests/test_public_api.py)
SerComm-based network print servers (PS301 and OEM variants) are configured through a handful of virtual files over FTP and TFTP, report port state on a Telnet console, and print over LPD or RAW sockets. Each protocol has firmware quirks, the CONFIG file is a numbered line format, and a device with an unknown address can only be reached by mapping a borrowed IP to its MAC.
- Typed CONFIG -
render_config(parse_config(text)) == textfor a device-produced file; every write shows the diff first. - One use-case object -
PrintServerreads, configures, restarts, guards destructive actions and prints, over injected protocol ports. - Discovery - finds devices by their FTP greeting
220 Print Server Ready.. - ARP trick - reaches a device by MAC through a static neighbour entry held for one call.
- CLI - every device command answers for a person or as a JSON envelope, with exit codes that do not depend on the output format.
composition/ wires adapters to ports (build_production, build_testing)
| imports
adapters/ ftp, telnet, tftp, lpd, raw, snmp, discovery, neighbors, config, logging, cli, memory
| imports
application/ PrintServer, discovery, arp_trick, ports (Protocols)
| imports
domain/ pure models and parsers: no I/O, logging or frameworks
Import contracts (tool.importlinter, run by lint-imports):
"Domain is pure (no adapter dependencies)" forbids domain from importing adapters or
composition; "Clean Architecture layers" enforces composition -> adapters -> application ->
domain.
Runtime dependencies: rich-click, click, lib_cli_exit_tools, lib_log_rich, python-dotenv, lib_layered_config, pydantic, orjson, ipscout. Python >= 3.10.
| Module | Contents |
|---|---|
config_lines.py |
ConfigLine, split_lines, join_lines: the NNNN TOKEN:VALUE line format |
config_catalogue.py |
Line numbers and tokens of the modelled CONFIG parameters |
config_types.py |
Value types (Text15, Byte, BaudRate, Parity, LptMode, ...) |
config_model.py |
DeviceConfig and its sections (TcpIp, Smb, Snmp, NetWare, ...) |
config_reader.py |
read_config: lines to DeviceConfig |
config_writer.py |
write_config: DeviceConfig back to lines |
config_codec.py |
parse_config, render_config, diff_config, with_value, ConfigChange |
device_files.py |
ReadableFile, WritableFile, DeviceAction (RESET, DEFAULTC, PASSRESET, SETIP) |
device_info.py |
DeviceInfo from PSINF and the FTP SYST reply; MAC helpers |
endpoint.py |
DeviceEndpoint (where and how to reach one device), PrintJob, Port |
print_data.py |
PrintData, Piece, PIECE_SIZE: a job's bytes from memory, a path or a stream |
port_status.py |
PortStatus, Occupant, PortState, PortType, PrinterStatus, parse_monitor |
port_health.py |
PortVerdict, PortHealth, is_wedge_candidate, probed_verdict, unprobed_verdict: a wedged port |
link.py |
LinkDrain, link_drain_for: how long a job takes to cross the serial link |
neighbor.py |
AddressHolder, LookupMethod: who holds an address, asked by ARP or from the cache |
enums.py |
OutputFormat, DeployTarget |
errors.py |
The exception types (see Exit Codes) |
print_server.py-PrintServer(endpoint, firmware_version, info, status, read_config, read_config_text, queue_state, plan_config, write_config, reset, set_password, clear_password, store_ip, factory_default, print_lpd, print_raw, print_raw_verified, check, reset_if_wedged),DevicePorts,ConfigWriteResult,CheckResult,DEFAULT_VERIFY_TIMEOUT(30 s).discovery.py-discover(scanner, networks=, timeout=)returningDiscoveryReportofDiscoveredDevice;LocalScope(the default sweep plan the scanner port returns),MAX_HOSTS,PRINT_SERVER_GREETING.arp_trick.py-borrowed_address,reach,assign_ip,factory_reset,ArpResult.ports.py- the Protocols below.
| Protocol | Implemented by (production) |
|---|---|
FtpPort |
adapters/ftp/client.py FtpClient |
TelnetPort |
adapters/telnet/client.py |
TftpPort |
adapters/tftp/client.py |
LpdPort |
adapters/lpd/client.py |
RawPort |
adapters/raw/printer.py |
UptimePort |
adapters/snmp/uptime.py |
HostScanner |
adapters/discovery/scanner.py |
NeighborTable, OpenNeighborTable |
adapters/neighbors/table.py |
OpenPrintServer |
composition.open_print_server |
GetConfig, GetDefaultConfigPath, DeployConfiguration, DisplayConfig |
adapters/config/ |
InitLogging, CheckLoggingConfig |
adapters/logging/setup.py |
ftp/,telnet/(client.py,iac.py),tftp/,lpd/,raw/,snmp/- one protocol client each;snmpreadssysUpTimethrough ipscout'sread_snmp_system(SNMPv1).lpd/client.py(LpdClient) spools data of unknown size to atempfile.TemporaryFilebefore the send (SpoolErrorwhen that fails) and raisesPrintSourceChangedErrorwhen the data delivers another byte count than announced.raw/printer.pyexportsRawPrinter(send with the serial drain wait,accepts_connectionfor the wedge probe),connect_retrying_refusalsandsend_failure, which reports a broken send asDeviceUnavailableErroronly while no byte was taken and asDeliveryUnconfirmedError(exit 110) once any was.discovery/scanner.py-FtpBannerScanner: FTP-port probes (ipscout'sgrab_banners, one connection per host), MACs and local networks, all through ipscout.neighbors/table.py-IpscoutNeighborTable: static ARP entries; maps ipscout's refusal toHostPrivilegeError.holder_ofasks with an ARP request, reads the cache only when it cannot, and says which (AddressHolder.method).config/- layered configuration (loader.py,deploy.py,display.py,overrides.py) anddevice_settings.py(DeviceSettings,resolve_endpoint) for the[device]section.logging/setup.py- lib_log_rich initialization.memory/- in-memory doubles:config.py,logging.py,device.py(FakeDevice,FakeTftp),discovery.py(FakeScanner),neighbors.py(FakeNeighborTable).cli/-root.py(group),main.py,context.py,config_load.py,envelope.py(Envelope,ErrorEnvelope,OutputMode),exit_codes.py,safe_console.py,typed_click.py,constants.py, andcommands/(arp.py,config.py,device.py,device_config.py,discover.py,info.py,printing.py,_device.pywith the shared options andexit_code_for).
composition/__init__.py-AppServices(frozen container of every port),build_production,build_testing(device=, scanner=, neighbors=),open_print_server.entry.py- console scriptsercomm-printserver(alsosercomm_printserver).scripts/ps301_wedge_probe.py(outside the package) - reproduces the RAW wedge on a real device, alternating trials with and without the drain wait, one JSON line per trial; it prints on every trial and runs only with--confirm-print.__main__.py-python -m sercomm_printserver.__init__conf__.py- static package metadata andprint_info.
Root options: --version, --traceback/--no-traceback, --profile NAME,
--set SECTION.KEY=VALUE (repeatable), --env-file FILE, -h/--help. Device commands take
--timeout, --json, --json-bare, and all but discover and arp take --host; discover
takes --network, the arp commands --mac, --ip and --interface (assign-ip also
--netmask, --gateway). Changing commands need --yes, and password clear, store-ip,
factory-default and arp factory-reset also --confirm-name.
| Command | Purpose |
|---|---|
info |
Print package metadata |
config |
Display the merged configuration |
config-deploy |
Deploy default configuration to app/host/user directories |
config-generate-examples |
Write example configuration files |
discover |
Find print servers by FTP greeting (--network CIDR, repeatable) |
firmware |
Firmware version (FTP SYST; PSINF when SYST garbles it, as on 6A10) |
device-info |
PSINF self-description: names, MAC, firmware, addresses |
status |
Per-port state and printer status (Telnet monitor) |
queue [QUEUE] |
LPD queue state of L1..L8 (default L1); sends no print data |
device-config show |
Show the whole CONFIG |
device-config get |
One parameter by token (IP_ADDR) or line number (4000) |
device-config set |
Change KEY=VALUE parameters; shows the diff, writes with --yes |
device-config export |
Save CONFIG exactly as the device sends it |
device-config import |
Write an exported CONFIG; shows the diff, writes with --yes |
reset |
Restart and wait until the device answers again (--no-wait) |
password set |
Set the login password from --from-file or a hidden prompt |
password clear |
Clear the login password (PASSRESET) |
store-ip |
Store the current address as static IP (SETIP) |
factory-default |
Restore factory settings (stored IP 0.0.0.0 with DHCP on, name empty) |
print lpd QUEUE SOURCE |
Send a file or stdin to an LPD queue (--job-name) |
print raw PRINTER SOURCE |
Send a file or stdin to the RAW port of logical printer 1..3 (--verify, --verify-timeout) |
check |
Tell wedged ports from busy ones; restart with --reset --yes |
arp reach |
Read the identity of the device behind --mac at borrowed --ip |
arp assign-ip |
Store --ip as static address (DHCP off) and restart there |
arp factory-reset |
Restore factory settings of the device behind --mac |
ExitCode in adapters/cli/exit_codes.py; device commands map errors through exit_code_for
in adapters/cli/commands/_device.py (first match wins, anything else exits 1).
| Code | Name | Raised for |
|---|---|---|
| 0 | SUCCESS |
Command completed |
| 1 | GENERAL_ERROR |
NeighborTableError, or any unmapped failure |
| 2 | FILE_NOT_FOUND |
click's usage error (bad option or missing argument); no command raises it |
| 3 | PORT_WEDGED |
check found a wedged port (with --reset: still wedged after the restart); not an exception |
| 13 | PERMISSION_DENIED |
HostPrivilegeError (no right to change the ARP table), UnverifiedAddressError (no ARP request possible, cache knows nothing); config-deploy refusals |
| 22 | INVALID_ARGUMENT |
ValueError, including ConfigFormatError; config section not found |
| 65 | PRINT_SOURCE_CHANGED |
PrintSourceChangedError: a file changed size while print lpd sent it; the job was left unterminated |
| 69 | DEVICE_UNAVAILABLE |
DeviceUnavailableError: refused, timed out, no route |
| 74 | SPOOL_FAILED |
SpoolError: print lpd could not spool a pipe to a temporary file; nothing was sent |
| 75 | PORT_BUSY |
PortBusyError: print raw --verify found the port busy until the deadline and sent nothing |
| 76 | PROTOCOL_ERROR |
DeviceResponseError: the device answered in an unexpected form |
| 77 | REFUSED |
ConfirmationRequiredError, AuthenticationRequiredError |
| 78 | CONFIG_ERROR |
ConfigurationError: configuration missing, not loadable or invalid |
| 110 | TIMEOUT |
JobNotDrainedError: print raw --verify sent the data and the port was not read as idle |
| 130 | SIGNAL_INT |
SIGINT (translated by lib_cli_exit_tools) |
| 141 | BROKEN_PIPE |
Output pipe closed |
| 143 | SIGNAL_TERM |
SIGTERM |
Envelope: with --json (indented) or --json-bare (one line) stdout carries only
{ok, command, data, skipped}; a failure is an ErrorEnvelope with the same ok and command
keys. Messages for a person go to stderr.
Configuration writes: PrintServer.write_config uploads only when diff_config finds a
change, verifies the upload, and with apply restarts the device and reports where it is
reachable (ConfigWriteResult).
Restart wait: the device restarts about 5 s after the triggering session ends. reset waits
until an SNMP uptime read afterwards is no longer than the time since the trigger, then until FTP
answers again, for at most 120 s.
Verified RAW print: PrintServer.print_raw_verified reads the printer's routing from CONFIG,
then reads that port every second until it is idle, sends, and reads it the same way again, with
timeout for each wait. An unanswered read before a deadline is ignored, and a routing the status
does not list is refused with nothing sent. A port busy until the first deadline is
PortBusyError, since a busy port would accept the job behind the one holding it. Every failure
after the send is JobNotDrainedError, never DeviceUnavailableError, so exit 69 cannot lead a
caller to send a job the device already has.
Serial drain: print_raw reads CONFIG first. For a logical printer routed to SP,
link_drain_for gives a LinkDrain at baud / (1 + data + parity + stop bits) bytes per second, and
RawPrinter.send keeps the connection fully open until the bytes the socket took have crossed
that link, plus 0.25 s, before the half-close. A new RAW connection opened while the device still
passes a job on loses its data and wedges the port; a half-close does not help, since the device
closes about 0.07 s after EOF. Parallel and USB ports get no wait.
Wedge check: PrintServer.check reads status and, for each port reading Printing, occupied by
Direct Socket, 0 bytes serviced, asks RawPort.accepts_connection on every RAW port routed there
(a bare connect, no data, measured safe). All accepted: WEDGED. Any refusal: HELD by a client.
A candidate with no RAW port routed to it is UNPROBED; other ports read IDLE or PRINTING.
Only WEDGED makes CheckResult.wedged true (CLI exit 3). reset_if_wedged restarts only on a
wedge and checks again.
Streaming print data: PrintData reads its source in pieces of at most PIECE_SIZE (64 KiB):
of(bytes), from_path (size taken at creation, file re-opened on every read) or from_stream
(read once; a pipe has no size). PrintJob.data is always a PrintData (bytes are wrapped). LPD
announces the size before the data, so data of unknown size is spooled first; RAW sends the pieces
as they are read and returns the count sent. An empty job is refused before the device is
contacted.
Bounded operator reads: device-config import reads at most CONFIG_FILE_LIMIT (64 KiB) plus
one byte and refuses a larger file with ConfigFormatError; password set --from-file reads only
the first line. print_raw_verified words its busy
errors from the same verdict.
ARP trick: the static neighbour entry lives only inside borrowed_address; the device is
then spoken to over FTP at the borrowed address, and the entry is removed in every case.
factory_reset refuses unless the PSINF default name matches both --mac and --confirm-name.
[device] defaults (adapters/config/defaultconfig.d/50-device.toml): host = "",
login = "", password = "", timeout = 10.0, raw_port_base = 9100 (L2 and L3 use the next
two ports; L4..L8 have no RAW port).
All under tests/:
- Protocol adapters against loopback fakes (
fake_ftp_server.py,fake_telnet_server.py,fake_tftp_server.py,fake_lpd_server.py,fake_raw_server.py): thetest_adapter_*.pymodules (ftp, telnet, tftp, lpd, raw, snmp, neighbors). - Use cases over in-memory adapters:
test_print_server.py,test_discovery.py,test_arp_trick.py,test_config_codec.py,test_device_reports.py,test_ports.py. - Streaming and the wedge:
test_print_data.py,test_port_status.py,test_port_health.py,test_link_drain.py, andtest_streaming_memory.py(Linux only: peak memory of a large job stays flat, measured in a child process,streaming_memory_child.py). - CLI:
test_cli_device.py,test_cli_arp.py,test_cli_exit_codes.py,test_cli_main_exit.py,test_cli_core.py,test_cli_bounded_reads.pyand the config/overridetest_cli_*.pymodules. - Scripts:
test_wedge_probe.pycoversscripts/ps301_wedge_probe.pyoffline. - Real device:
test_e2e_device.py, markerdevice(needsSERCOMM_E2E=1andtest-device.json);test_e2e_printer.py, markerprinter, also needsSERCOMM_E2E_PRINTER=1and aprintersection intest-device.json.
Doctests: --doctest-modules. Platform markers: os_agnostic, os_windows, os_macos,
os_posix, os_linux; local_only, integration. Coverage gate: fail_under = 80.
PrintServertriggers actions over FTP. The PS301 does takeRESETover TFTP but refusesPASSRESET, and TFTP reports nothing back about the result.print rawreaches only L1..L3: the RAW ports belong to those three logical printers.password clearworks without a login on firmware 6022: a password does not stop anyone on the network from clearing it.password setaccepts at most 19 printable ASCII characters.checkcannot see a RAW port that refuses every connect whilestatusreads it idle, nor an idle port whose printer does not answer.- The ARP trick needs the right to change this host's neighbour table (exit 13 otherwise).
- The password is never taken from the command line (
--from-fileor a hidden prompt) andconfigshows the configuredpasswordredacted. - Destructive commands refuse (exit 77) without
--yesand, where listed,--confirm-name. - Discovery reads only the FTP greeting; it never logs in and never prints.
from sercomm_printserver import DeviceEndpoint, PrintJob, discover_print_servers, open_print_server
report = discover_print_servers(networks=["192.0.2.0/24"])
server = open_print_server(DeviceEndpoint(host="192.0.2.52"))
print(server.info().firmware_version)
server.print_lpd("L1", PrintJob(data=b"hello\r\n\f", name="greeting"))sercomm-printserver discover --network 192.0.2.0/24
sercomm-printserver status --host 192.0.2.52 --json
sercomm-printserver device-config set --host 192.0.2.52 CONTACT="printer room" --yes
sercomm-printserver arp reach --mac 00:00:5e:00:53:01 --ip 192.0.2.200