KISS File Transfer Monitor Documentation

The Monitor program connects to a broadcast server over TCP and continuously reads incoming KISS‑framed packets. It removes the KISS framing, unescapes special byte sequences, and decodes packets from the file transfer system – including header, data, ACK, as well as CMD and RSP packets. Additionally, it can decode AX.25 packets and publish raw frame data to an MQTT broker.

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

Overview

The Monitor program is designed for debugging and observing the file transfer process. It works by:

Connecting to a broadcast server (via TCP) to receive continuous streams of KISS‑framed data.
Removing the KISS framing (delimited by the flag byte 0xC0) and unescaping the payload.
Decoding packet contents – including sender and receiver callsigns (using AX.25 addressing), file IDs, sequence numbers, header metadata (such as timeout settings, file name, sizes, MD5 hash, encoding and compression flags), and ACK values.
Recognizing and processing special CMD and RSP packets embedded in file transfer packets.
Optionally decoding all AX.25 packets when required.
Optionally publishing raw frame data to an MQTT broker for further processing.

Installation & Build

To build the Monitor program, ensure that you have Go installed. Then compile the program using the following command:

go build -o monitor monitor.go

Command‑Line Options

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

Flag	Description	Default Value
`--host`	Host address of the broadcast server.	`127.0.0.1`
`--port`	TCP port of the broadcast server (required).	none
`--mqtt-host`	Hostname of the MQTT broker. When provided, all MQTT parameters must be specified.	empty
`--mqtt-port`	Port number of the MQTT broker.	empty
`--mqtt-user`	MQTT username.	empty
`--mqtt-pass`	MQTT password.	empty
`--mqtt-tls`	Use TLS for connecting to the MQTT broker.	`false`
`--mqtt-topic`	MQTT topic to which raw frames are published.	empty
`--ascii`	Display raw frames as ASCII text instead of hexadecimal.	`false`
`--decode-file-transfer`	Decode known file transfer packets and display human‑readable summaries (including header, data, ACK, CMD, and RSP packets).	`false`
`--decode-ax25`	Decode all AX.25 packets. This option is mutually exclusive with `--ascii` and `--decode-file-transfer`.	`false`

Usage Examples

Example 1: Monitor Mode over TCP (Decoding File Transfer Packets)

Connect to a broadcast server at 127.0.0.1 on port 9001 and decode incoming file transfer packets:

go run monitor.go --host=127.0.0.1 --port=9001 --decode-file-transfer

Example 2: Monitor Mode over TCP (Decoding AX.25 Packets)

Connect to a broadcast server and decode all AX.25 packets. Note that this option cannot be combined with --ascii or --decode-file-transfer:

go run monitor.go --host=127.0.0.1 --port=9001 --decode-ax25

Example 3: Monitor Mode with MQTT Publishing

Connect to a broadcast server and publish all raw frames to an MQTT broker at mqtt.example.com:1883:

go run monitor.go --host=127.0.0.1 --port=9001 --mqtt-host=mqtt.example.com --mqtt-port=1883 --mqtt-user=myuser --mqtt-pass=mypassword --mqtt-topic=kiss/frames

Example 4: Monitor Mode with ASCII Output

Display the raw, unescaped frames as ASCII text:

go run monitor.go --host=127.0.0.1 --port=9001 --ascii

Additional Notes

The --port flag is required.
When using MQTT, all MQTT parameters (--mqtt-host, --mqtt-port, --mqtt-user, --mqtt-pass, and --mqtt-topic) must be provided.
The --decode-file-transfer option instructs the program to parse and print details for file transfer packets. This includes:
- Header packets with file metadata (timeout settings, file name, sizes, MD5 hash, encoding, and compression flags).
- Data packets with sequence information.
- ACK packets showing the ACK value.
- CMD and RSP packets, where command IDs and response statuses are extracted and displayed.
The --decode-ax25 option decodes all AX.25 packets. It is mutually exclusive with --ascii and --decode-file-transfer.
The program tracks metrics such as total frames processed, total bytes received, and the minimum/maximum time between packets. When you press Ctrl-C to exit, a summary of these metrics is printed.

Contact & Support

For questions, bug reports, or feature requests regarding the Monitor program, please contact the project maintainer or visit the project repository.