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 ] [ --debug ] |
| serialink | dir [ <path> ] [ --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 ] [ --debug ] |
| serialink | download <path> [ -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 ] [ --debug ] |
| serialink | -l [ -v ] [ --debug ] |
| serialink | --init [ --config <config> ] [ -v ] [ --debug ] |
| serialink | --help | --sysinfo [ -v ] |
DESCRIPTION
This manual page documents the serialink command. The serve operation
exports a local directory read-only through a serial TTY or COM port. A client
uses dir to list the exported root or one of its subdirectories and uses
download to copy a regular file to the local system. The server remains
active until interrupted, for example with Ctrl+C.
The two peers must be connected using an appropriate null-modem or crossover
connection with a common ground. Both sides must use matching baud rate, data
bits, parity, stop bits and physical flow-control settings. Use –list-ports
to obtain the system aliases accepted by –port. The port can alternatively
be configured in serialink.ini.
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 1 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. |
| <path>: | The remote path relative to the exported directory. It is optional for dir and required for download. |
| --acknowledge-retries <acknowledgeRetries>: | The number of acknowledgement 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, from five through 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. |
| --reply-retries <replyRetries>: | The number of request 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 number of acknowledgement retries, e.g.
5 - replyTimeoutMillis= The response timeout in milliseconds, e.g.
3000 - replyRetries= The number of request retries, 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