File Server Client Documentation

The File Server Client is a command‑line tool designed for interacting with a remote file server via the KISS protocol. It establishes a connection (over TCP or serial) with the file server, sends commands (such as LIST, GET, PUT, and local LS), and then processes responses. File transfers are performed by spawning external receiver and sender processes.

Overview
Installation & Build
Command‑Line Options
Usage & Examples
Additional Notes

Overview

The File Server Client communicates with a remote file server using the KISS protocol. It supports two main modes of operation:

Command Processing: User commands are read from standard input. Commands (e.g., LIST, GET filename, PUT filename) are packed into an AX.25‑formatted command packet, framed with KISS, and sent to the server.
File Transfers: For file‑related commands (LIST, GET, PUT), the client spawns external processes: receiver for downloading files or file listings, and sender for uploading files.

Additionally, a transparent TCP listener is started for passthrough data. A Broadcaster disseminates incoming KISS frames from the underlying connection (which may be over TCP or serial) to all active subscribers. The client also monitors connection activity and automatically attempts to reconnect if the link is lost.

Installation & Build

To build the File Server Client, ensure you have Go installed. Then compile the program with:

go build -o fileserverclient fileserverclient.go

Make sure that any external binaries (the receiver and sender executables) are available in your system’s PATH or specify their paths via command‑line options.

Command‑Line Options

The table below lists all available command‑line options along with their descriptions and default values:

Flag	Description	Default Value
`--my-callsign`	Your own callsign. This value is required.	none
`--file-server-callsign`	Target file server's callsign. This value is required.	none
`--connection`	Type of connection to use: `tcp` or `serial`.	`tcp`
`--host`	TCP host to connect to (if using TCP connection).	`127.0.0.1`
`--port`	TCP port to connect to (if using TCP connection).	`9001`
`--serial-port`	Serial port device (e.g. `COM3` or `/dev/ttyUSB0`). Required for serial connections.	empty
`--baud`	Baud rate for the serial connection.	`115200`
`--receiver-port`	TCP port for the transparent passthrough (for file transfers and external processes).	`5012`
`--receiver-binary`	Path to the receiver binary used for file downloads or listing.	`receiver`
`--sender-binary`	Path to the sender binary used for file uploads.	`sender`
`--debug`	Enable verbose debug logging.	`false`
`--save-directory`	Directory to save files retrieved via the `GET` command.	`.`
`--serve-directory`	Directory from which files are sent for the `PUT` command and listed with the local `LS` command.	`.`
`--run-command`	Optional. Runs a single command non-interactively (e.g. `"PUT my-file.txt"`) and then exits.	empty

Usage & Examples

After building the client, run it from the command line by providing the required options. The client will prompt for commands.

Example 1: Basic TCP Connection

This example starts the client using a TCP connection to a file server at 127.0.0.1:9001 and specifies your callsign along with the file server’s callsign.

./fileserverclient --my-callsign=YOURCALL --file-server-callsign=SERVER1

Example 2: Using a Serial Connection

This command uses a serial connection (for example on /dev/ttyUSB0) at 115200 baud.

./fileserverclient --my-callsign=YOURCALL --file-server-callsign=SERVER1 --connection=serial --serial-port=/dev/ttyUSB0 --baud=115200

Example 3: File Listing & Transfer Commands (Interactive Mode)

Once the client is running, you can enter commands at the prompt. For example:

LS: Lists files in the local serve-directory.
LIST: Requests a remote file listing from the file server.
GET filename: Retrieves the specified file from the file server.
PUT filename: Uploads a file from the serve-directory to the file server.

At the prompt, you might see:

> LS

Example 4: Non‑Interactive Command Execution

To run a single command and exit immediately (for example, to upload a file), use the --run-command flag:

./fileserverclient --my-callsign=YOURCALL --file-server-callsign=SERVER1 --run-command="PUT my-file.txt"

This command will execute PUT my-file.txt as if entered interactively, then exit once completed.

Additional Notes

The client uses KISS framing (with AX.25 headers) for all command packets. Commands are automatically tagged with a unique 2‑character ID to match responses.
For file transfers, the client spawns external receiver and sender processes. Ensure that the binaries specified via --receiver-binary and --sender-binary are accessible.
A separate TCP listener (on the port specified by --receiver-port) is used to relay data transparently between the file server and the external processes.
The client monitors connection activity and will attempt to reconnect automatically if no data is received within a defined period.
Use the --debug flag to enable verbose logging for troubleshooting.

Contact & Support

For further questions, suggestions, or to report issues, please contact the project maintainer or visit the project’s repository.