KISS over Serial

Connect a hardware TNC or radio with a built-in KISS serial port directly to graywolf over a USB or RS-232 serial link.

Overview

Some TNCs and radios speak KISS natively over a serial port rather than over TCP. Connecting one of these devices lets graywolf use it as a full radio channel — beacon into it, digipeat across it, and iGate from it — without an audio modem or a network connection between graywolf and the device.

Common examples include the Kenwood TH-D75 and TH-D74 handhelds (which expose a USB serial port and speak KISS when placed in packet mode), Mobilinkd TNCs (which attach over Bluetooth serial or USB serial), and the Kantronics KPC-3+ (classic RS-232 TNC with a KISS mode). Any device that presents a serial port and speaks the KISS protocol works.

Graywolf opens the serial port, reads KISS frames as they arrive, and writes KISS frames when transmitting. The device handles all RF carrier sensing, timing, and actual transmission; graywolf is just the packet router on top.

Device Paths

When graywolf asks for a device path, enter the operating-system path to the serial port:

On Linux, if you are unsure which path corresponds to your device, unplug it, run ls /dev/ttyACM* /dev/ttyUSB*, plug it back in, and run the command again. The new entry is your device. The dmesg output also shows the assigned path when the kernel recognizes the USB device.

Baud Rate

The baud rate you enter in graywolf must match the baud rate configured on the device. Common values:

• 9600 — the most common default for TNCs and many radios with built-in KISS serial support.
• 4800 — used by some older TNCs and low-speed configurations.
• 19200, 38400, 57600, 115200 — higher speeds used by some modern USB TNCs; check your device's documentation.

A baud-rate mismatch produces garbage framing. If the KISS interface appears connected but no frames arrive (or arrive as decode errors), verify that both sides are set to the same rate.

Configuration

Step 1 — Create a KISS-only channel

1. Open Radio → Channels in the web UI.
2. Click + Add Channel.
3. In the channel-type segmented control at the top of the form, choose KISS-TNC only. The audio device, modem type, and TX timing fields disappear — a KISS-only channel is a logical routing lane, not a modulated radio channel.
4. Name it to reflect the attached device (for example, TH-D75 or Mobilinkd). Give it a channel number that does not collide with your existing RF channels.
5. Click Save. The channel appears on the list with a KISS-TNC only badge. Its backing shows — Unbound until you attach the serial KISS interface below.

Step 2 — Create a serial KISS interface

1. Open Interfaces → KISS TNC (the page is titled KISS Interfaces).
2. Click + Add KISS.
3. In the Type field, choose Serial.
4. In Serial Device, enter the operating-system path to the serial port (see Device Paths above).
5. Set Baud Rate to match the rate configured on the device (9600 is the most common starting point).
6. In the Channel picker, select the KISS-only channel you just created.
7. Set Mode to TNC. In TNC mode the interface is treated as a radio, not a software client. This also reveals the transmit opt-in checkbox.
8. Check the box labeled Allow digipeater/beacon/iGate to transmit on this interface to allow graywolf's TX pipeline to send frames to the device. Without this checkbox the interface only receives.
9. Click Create. Graywolf opens the serial port immediately. The row's status badge shows Connected if the port opened successfully. The channel's backing on the Channels page flips to ● Live.

Reconnect Behavior

If the serial device is unplugged or the port closes unexpectedly, graywolf's serial supervisor backs off and automatically retries opening the port. You do not need to restart the daemon. When the device is plugged back in and the operating system reassigns the same path, graywolf reconnects and the channel returns to ● Live status.

Editing the device path, baud rate, or mode on the KISS TNC page and clicking Save triggers a hot reload: graywolf closes the existing connection and re-opens the port with the new settings. No daemon restart is required.

Troubleshooting

Linux permission denied (EACCES)

On Linux the serial port device is typically owned by the dialout group (or uucp on some distributions). The user running graywolf must be a member of that group. Add the user with:

sudo usermod -aG dialout <username>

You must log out and log back in (or start a new login session) for the group change to take effect. If graywolf runs as the graywolf system user (the default for deb/rpm/AUR package installs), the post-install script adds that user to dialout automatically.

Port busy (EBUSY / "device or resource busy")

Another process holds the serial port open. Common culprits are a terminal emulator left open (minicom, screen, picocom), a competing TNC application, or the ModemManager service on Linux (which probes newly-connected serial devices). Check with:

fuser /dev/ttyACM0

That command prints the PID of any process holding the device. On systems running ModemManager you can stop it for a session with sudo systemctl stop ModemManager or add a udev rule to prevent it from touching your TNC's USB vendor/product ID.

Interface connects but no frames arrive

Check in order:

1. Confirm the device is actually in KISS mode. Most radios and TNCs default to a human-readable command mode and must be explicitly switched. Consult your device's manual.
2. Verify the baud rate matches on both sides. A mismatch produces garbage bytes that the KISS framer discards.
3. Confirm the device is transmitting. On a radio such as the TH-D75, the APRS channel must be active and a beacon must be due — the port is silent between packets.
4. Check the Logs page in the graywolf UI for any serial framing or open errors.

My beacon on the channel does not transmit

Likely causes:

• Transmit checkbox is off. Open the KISS interface, confirm Mode is TNC and the Allow digipeater/beacon/iGate to transmit on this interface box is checked.
• Port is not open. The status badge on the KISS page shows Reconnecting if graywolf cannot open the port. Confirm the device is connected and the path is correct.
• Channel is unbound. If you created the channel but never attached the serial interface to it, the channel's backing is — Unbound and no frame goes anywhere.

Known-Working Devices

Related Pages

• KISS TNC — TCP server and client KISS interfaces.
• Remote KISS TNC — dialing out to a remote KISS server over TCP.
• Radio Channels — channel types, backing, and TX timing.
• Known-Working Configs — example hardware configurations.