SERIALINK(1) General Commands Manual
NAME
serialink - Browses and downloads files over a serial TTY connection using a declarative REFCODES protocol.
SYNOPSIS
| serialink | serve [ -D <directory> ] [ --config <config> ] [ -p <port> ] [ -b <baudRate> ] [ --data-bits <dataBits> ] [ --parity <parity> ] [ --stop-bits <stopBits> ] [ --handshake <handshake> ] [ -c <chunkSize> ] [ --acknowledge-timeout-millis <acknowledgeTimeoutMillis> ] [ --acknowledge-retries <acknowledgeRetries> ] [ --reply-timeout-millis <replyTimeoutMillis> ] [ --reply-retries <replyRetries> ] [ -v ] [ -q ] [ --debug ] |
| serialink | dir [ --config <config> ] [ -p <port> ] [ -b <baudRate> ] [ --data-bits <dataBits> ] [ --parity <parity> ] [ --stop-bits <stopBits> ] [ --handshake <handshake> ] [ -c <chunkSize> ] [ --acknowledge-timeout-millis <acknowledgeTimeoutMillis> ] [ --acknowledge-retries <acknowledgeRetries> ] [ --reply-timeout-millis <replyTimeoutMillis> ] [ --reply-retries <replyRetries> ] [ -v ] [ -q ] [ --debug ] [ <remotePath> ] |
| serialink | download [ -o <outputFile> ] [ --config <config> ] [ -p <port> ] [ -b <baudRate> ] [ --data-bits <dataBits> ] [ --parity <parity> ] [ --stop-bits <stopBits> ] [ --handshake <handshake> ] [ -c <chunkSize> ] [ --acknowledge-timeout-millis <acknowledgeTimeoutMillis> ] [ --acknowledge-retries <acknowledgeRetries> ] [ --reply-timeout-millis <replyTimeoutMillis> ] [ --reply-retries <replyRetries> ] [ -v ] [ -q ] [ --debug ] <remotePath> |
| serialink | -l [ -v ] [ -q ] [ --debug ] |
| serialink | --init [ --config <config> ] [ -v ] [ -q ] [ --debug ] |
| serialink | --help | --sysinfo [ -v ] [ -q ] |
DESCRIPTION
This manual page documents the serialink command. The serve operation exports
a local directory read-only through a serial TTY or a COM port. A client uses
the dir operation to list the exported root folder or one of its subdirectories
and the download operation to copy a regular file to the local system. The server
remains active until interrupted with Ctrl+C. The two peers must be connected by
null-modem or crossover connection (with a common ground) and both sides must use
matching connection metrics such as baud rate, data bits, parity, stop bits and
physical flow-control settings. The list flag –list-ports prints the system
aliases accepted by the –port option. All being configurable --config in a
serialink.ini configuration.
The wire format is assembled from declarative refcodes-serial segments. Its
requests and responses contain magic bytes, a protocol version, operation and
status values, length-prefixed UTF-8 text and binary sections, offsets, lengths
and big-endian numeric fields. The surrounding refcodes-serial-ext-handshake
frames provide allocation lengths, sequence numbers, acknowledgements, retries
and enforced CRC-32 validation. Files and directory listings are transferred in
bounded chunks. Downloads are written to a temporary sibling file and moved to the
selected target only after the complete transfer has been validated. Existing targets
therefore remain intact when a transfer fails. Requested server paths are resolved
against the canonical shared directory; path traversal and symbolic links escaping
that directory are rejected.
SERIALINK is intended for physically trusted links. It does not provide
authentication, authorization or encryption.
Depending on the executable’s flavor the command might also be named serialink-x.y.z.jar, serialink-bundle-x86_64-x.y.z.elf, serialink-bundle-x86_64-x.y.z.exe, serialink-launcher-x.y.z.sh, serialink-launcher-x86_64-x.y.z.elf, serialink-launcher-x86_64-x.y.z.exe, serialink-native-x86_64-x.y.z.elf where x.y.z stands for the version of the serialink command. The according executable’s name will be referenced to in this manual as serialink.
The command-line help follows the effective message locale. Set the Java system property org.refcodes.messages.locale or the environment variable ORG_REFCODES_MESSAGES_LOCALE to de to explicitly select German output; otherwise the JVM’s default display locale is used, with English as the fallback when no localized bundle is available.
OPTIONS
| serve: | Serves a local directory read-only through the selected serial port. |
| dir: | Lists the exported root or a remote subdirectory. Each line contains the entry type, escaped name, byte length and last-modified instant separated by tabs. |
| download: | Downloads a regular file from the exported directory. |
| <remotePath>: | The remote path relative to the exported directory. It is optional for dir and required for download. |
| --acknowledge-retries <acknowledgeRetries>: | The total number of acknowledgement attempts including the initial attempt; one disables retries (defaults to <5>). |
| --acknowledge-timeout-millis <acknowledgeTimeoutMillis>: | The timeout in milliseconds for a transmission acknowledgement (defaults to <1000>). |
| -b --baud-rate <baudRate>: | The line speed in bits per second (defaults to <115200>). |
| -c --chunk-size <chunkSize>: | The application payload bytes requested per response, from 1 through 65536 (defaults to <4096>). |
| --config <config>: | Specifies the resource or file to use when loading the configuration. |
| -D --directory <directory>: | The local directory exported by the server (defaults to the current directory). |
| --data-bits <dataBits>: | The number of data bits; SERIALINK requires eight (defaults to <8>). |
| --debug: | Enables debug mode with additional developer-readable informational output. |
| --handshake <handshake>: | The physical flow-control mode: { NONE, SOFTWARE, RTS, DTR, AUTO } (defaults to <NONE>). |
| --help: | Shows this help. |
| --init: | Initializes the configuration from a template. |
| -l --list-ports: | Lists the available serial port aliases. |
| -o --output-file <outputFile>: | The local download target. The final component of the remote path is used in the current directory when omitted. |
| --parity <parity>: | The parity mode: { AUTO, NONE, ODD, EVEN, MARK, SPACE } (defaults to <NONE>). |
| -p --port <port>: | The system alias of the serial port. This is required for serve, dir and download, unless configured in serialink.ini. |
| -q --quiet: | Suppresses informational status, progress and server request messages without hiding requested result data or errors. |
| --reply-retries <replyRetries>: | The total number of request attempts including the initial attempt; one disables retries (defaults to <5>). |
| --reply-timeout-millis <replyTimeoutMillis>: | The timeout in milliseconds for a request response (defaults to <3000>). |
| --stop-bits <stopBits>: | The stop-bit mode: { AUTO, ONE, ONE_POINT_FIVE, TWO } (defaults to <ONE>). |
| --sysinfo: | Shows some system information for debugging purposes. |
| -v --verbose: | Enables verbose mode with additional human-readable informational output. |
EXAMPLES
List the serial ports recognized by the JVM:
- serialink -l
Export the local shared directory through a serial port:
- serialink serve -p ttyUSB0 -D shared
List the exported root directory:
- serialink dir -p ttyUSB0
List an exported subdirectory:
- serialink dir documents -p ttyUSB0
Download a remote file to an explicit local target:
- serialink download documents/arecibo.txt -p ttyUSB0 -o target/arecibo.txt
Use a configured port and line settings:
- serialink dir
Create an editable configuration file:
- serialink --init
FILES
The serialink.ini configuration supports the following properties. Command-line options take precedence over configured values:
- port= The system alias of the serial TTY or COM port, e.g.
ttyUSB0 - baudRate= The line speed in bits per second, e.g.
115200 - dataBits= The number of data bits, e.g.
8 - parity= The parity mode, e.g.
NONE - stopBits= The stop-bit mode, e.g.
ONE - handshake= The physical flow-control mode, e.g.
NONE - chunkSize= The maximum application payload requested per response, e.g.
4096 - acknowledgeTimeoutMillis= The acknowledgement timeout in milliseconds, e.g.
1000 - acknowledgeRetries= The total number of acknowledgement attempts including the initial attempt, e.g.
5 - replyTimeoutMillis= The response timeout in milliseconds, e.g.
3000 - replyRetries= The total number of request attempts including the initial attempt, e.g.
5 - directory= The local directory exported by serve, e.g.
.
BUGS
See BitBucket issues at <https://bitbucket.org/funcodez/funcodes-serialink/issues>
AUTHOR
Siegfried Steiner steiner@refcodes.org