KISS File Transfer WebSockets Gateway Documentation

This program serves as a WebSockets and raw TCP gateway for KISS data. It establishes a connection to an underlying device—using either a serial port or a TCP connection—reads KISS-framed data, and then:

Broadcasts complete KISS frames to all connected Socket.IO clients via the raw_kiss_frame event.
Forwards the frames to raw TCP clients that connect on a port one higher than the HTTP server port.
Relays events from the most recently connected (active) Socket.IO client back to the device.
Monitors device activity (for TCP-based connections) using a read deadline—if no data is received within the specified period, it automatically triggers a reconnect.

Overview
Installation & Build
Command‑Line Options
Examples
Additional Notes

Overview

The WebSockets Gateway is designed to integrate with a KISS TNC device. It opens a connection to the device using either a serial port or a TCP connection, reads data framed using the KISS protocol, and:

Broadcasts complete KISS frames to connected Socket.IO clients using the raw_kiss_frame event.
Forwards the same frames to raw TCP clients that connect on a port equal to -listen-port + 1.
Forwards events from the active Socket.IO client back to the device.
Automatically attempts to reconnect to the device if the connection is lost or if no data is received within a specified timeout.

Installation & Build

To build the WebSockets Gateway, ensure you have Go installed. Then compile the program using:

go build -o websockets websockets.go

Command‑Line Options

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

Flag	Description	Default Value
`-connection`	Type of connection to the device. Must be either `serial` or `tcp`.	none
`-serial-port`	Device file for the serial connection (e.g. `/dev/ttyUSB0` or `COM3`). Required when using a serial connection.	empty
`-baud`	Baud rate for the serial connection.	`115200`
`-host`	TCP host or IP to connect to when `-connection` is set to `tcp`.	empty
`-port`	TCP port to connect to when `-connection` is set to `tcp`.	0
`-listen-ip`	IP address on which to bind the HTTP server (serving both the Socket.IO endpoint and static files).	`0.0.0.0`
`-listen-port`	Port on which to bind the HTTP server. The raw TCP server will bind on this port + 1.	`5000`
`-debug`	Enable verbose debug logging.	`false`
`-tcp-read-deadline`	For TCP-based TNC connections, specifies the read deadline in seconds. If no data is received within this period (default is 600 seconds), the connection is considered stalled and a reconnect is triggered.	`600`
`-web-root`	Path to the HTML files which will be served from the built in web server. Usually you would want to point to where the web based application lives. Defaults to current working directory.	`.`

Examples

Example 1: Using a Serial Connection

This command opens a serial connection to the device on /dev/ttyUSB0 with a baud rate of 115200, and starts the HTTP server on port 5000 (with raw TCP on port 5001). Specifies /home/web/html as the web root.

go run websockets.go -connection=serial -serial-port=/dev/ttyUSB0 -baud=115200 -web-root /home/web/html

Example 2: Using a TCP Connection with Default Read Deadline

This command connects to the device over TCP at 192.168.1.50:8000 and starts the HTTP server on port 5000. It uses the default read deadline of 600 seconds. If no data is received within 600 seconds, the gateway will reconnect to the device.

go run websockets.go -connection=tcp -host=192.168.1.50 -port=8000

Example 3: Using a TCP Connection with a Custom Read Deadline

This command connects to the device over TCP at 192.168.1.50:8000 but sets the read deadline to 300 seconds.

go run websockets.go -connection=tcp -host=192.168.1.50 -port=8000 -tcp-read-deadline=300

Example 4: Custom HTTP Server Binding

This command runs the gateway with a TCP connection to the device, but binds the HTTP server to IP 127.0.0.1 on port 8080 (with raw TCP listening on port 8081):

go run websockets.go -connection=tcp -host=192.168.1.50 -port=8000 -listen-ip=127.0.0.1 -listen-port=8080

Example 5: Enabling Debug Logging

To enable verbose output for troubleshooting, use the -debug flag:

go run websockets.go -connection=serial -serial-port=COM3 -baud=115200 -debug

Additional Notes

When using a serial connection, ensure that you have permission to access the device file (for example, by adding your user to the appropriate group on Unix systems).
The HTTP server serves both the Socket.IO endpoint at /socket.io/ and static files (an index.html file should be present in the working directory).
Raw TCP connections are accepted on the port equal to -listen-port + 1; these clients receive complete KISS frames directly.
Only events from the most recently connected (active) Socket.IO client are forwarded to the device.
The -tcp-read-deadline flag applies to TCP-based connections. If no data is received within the specified number of seconds, the connection is considered stalled, and the gateway will close the connection and attempt to reconnect every 5 seconds.
The gateway handles graceful shutdown on receiving termination signals (e.g., SIGINT, SIGTERM), ensuring that the HTTP server and open connections are closed properly.

Contact & Support

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