Files
MeshCore/docs/kiss_modem_protocol.md
T
agessaman f4f394c0d7 kiss_modem: default AGC reset interval to 32 s
The AGC interval is set in 4 s steps, matching MeshCore's
agc.reset.interval, so the old 30 s default could not be restored by a
host: setting 30 gives 28. Found on hardware. Use 32 s, the nearest
multiple of 4 above it.
2026-09-23 18:51:03 -07:00

21 KiB

MeshCore KISS Modem Protocol

Standard KISS TNC firmware for MeshCore LoRa radios. Compatible with any KISS client (Direwolf, APRSdroid, YAAC, etc.) for sending and receiving raw packets. MeshCore-specific extensions (cryptography, radio configuration, telemetry) are available through the standard SetHardware (0x06) command.

Serial Configuration

115200 baud, 8N1, no flow control.

Frame Format

Standard KISS framing per the KA9Q/K3MC specification.

Byte Name Description
0xC0 FEND Frame delimiter
0xDB FESC Escape character
0xDC TFEND Escaped FEND (FESC + TFEND = 0xC0)
0xDD TFESC Escaped FESC (FESC + TFESC = 0xDB)
┌──────┬───────────┬──────────────┬──────┐
│ FEND │ Type Byte │ Data (escaped)│ FEND │
│ 0xC0 │  1 byte   │ 0-510 bytes  │ 0xC0 │
└──────┴───────────┴──────────────┴──────┘

Type Byte

The type byte is split into two nibbles:

Bits Field Description
7-4 Port Port number (0 for single-port TNC)
3-0 Command Command number

Maximum unescaped frame size: 512 bytes.

Standard KISS Commands

Host to TNC

Command Value Data Description
Data 0x00 Raw packet Queue packet for transmission (one pending at a time)
TXDELAY 0x01 Delay (1 byte) Transmitter keyup delay in 10ms units (default: 50 = 500ms)
Persistence 0x02 P (1 byte) CSMA persistence parameter 0-255 (default: 63)
SlotTime 0x03 Interval (1 byte) CSMA slot interval in 10ms units (default: 10 = 100ms)
TXtail 0x04 Delay (1 byte) Post-TX hold time in 10ms units (default: 0)
FullDuplex 0x05 Mode (1 byte) 0 = half duplex, nonzero = full duplex (default: 0)
SetHardware 0x06 Sub-command + data MeshCore extensions (see below)
Return 0xFF - Exit KISS mode (no-op)

TNC to Host

Type Value Data Description
Data 0x00 Raw packet Received packet from radio

Data frames carry raw packet data only, with no metadata prepended. The Data command payload is limited to 255 bytes to match the MeshCore maximum transmission unit (MAX_TRANS_UNIT); frames larger than 255 bytes are silently dropped. The KISS specification recommends at least 1024 bytes for general-purpose TNCs; this modem is intended for MeshCore packets only, whose protocol MTU is 255 bytes.

Only one packet may be pending for radio transmission at a time. If the host sends a second Data frame before the first has completed, the modem responds with Error (0xF1) and TxBusy (0x07).

Host Output Backpressure

Outbound frames are encoded into a 2-slot queue and flushed when serial output space is available; loop() never blocks on writes. Radio TX state advances independently of host read speed. TxDone is retained until it can be queued. If the outbound queue is full, the modem responds with Error (0xF1) and TxBusy (0x07). Hosts should read serial promptly to avoid delayed responses.

CSMA Behavior

The TNC implements p-persistent CSMA for half-duplex operation:

  1. When a packet is queued, monitor carrier detect
  2. When the channel clears, generate a random value 0-255
  3. If the value is less than or equal to P (Persistence), wait TXDELAY then transmit
  4. Otherwise, wait SlotTime and repeat from step 1

In full-duplex mode, CSMA is bypassed and packets transmit after TXDELAY.

SetHardware Extensions (0x06)

MeshCore-specific functionality uses the standard KISS SetHardware command. The first byte of SetHardware data is a sub-command. Standard KISS clients ignore these frames.

Frame Format

┌──────┬──────┬─────────────┬──────────────┬──────┐
│ FEND │ 0x06 │ Sub-command  │ Data (escaped)│ FEND │
│ 0xC0 │      │   1 byte    │   variable   │ 0xC0 │
└──────┴──────┴─────────────┴──────────────┴──────┘

Request Sub-commands (Host to TNC)

Sub-command Value Data
GetIdentity 0x01 -
GetRandom 0x02 Length (1 byte, 1-64)
VerifySignature 0x03 PubKey (32) + Signature (64) + Data
SignData 0x04 Data to sign
EncryptData 0x05 Key (32) + Plaintext
DecryptData 0x06 Key (32) + MAC (2) + Ciphertext
KeyExchange 0x07 Remote PubKey (32)
Hash 0x08 Data to hash
SetRadio 0x09 Freq (4) + BW (4) + SF (1) + CR (1)
SetTxPower 0x0A Power dBm (1)
GetRadio 0x0B -
GetTxPower 0x0C -
GetCurrentRssi 0x0D -
IsChannelBusy 0x0E -
GetAirtime 0x0F Packet length (1)
GetNoiseFloor 0x10 -
GetVersion 0x11 -
GetStats 0x12 -
GetBattery 0x13 -
GetMCUTemp 0x14 -
GetSensors 0x15 Permissions (1)
GetDeviceName 0x16 -
Ping 0x17 -
Reboot 0x18 -
SetSignalReport 0x19 Enable (1): 0x00=disable, nonzero=enable
GetSignalReport 0x1A -
GetCapabilities 0x1B -
SetAgcResetInterval 0x1C Seconds (2): 0=disable, 0-1020
GetAgcResetInterval 0x1D -
SetFemState 0x1E Apply mask (1) + Value mask (1)
GetFemState 0x1F -
SetRxBoostedGain 0x20 Enable (1): 0x00=disable, nonzero=enable
GetRxBoostedGain 0x21 -

Response Sub-commands (TNC to Host)

Response codes use the high-bit convention: response = command | 0x80. Generic and unsolicited responses use the 0xF0+ range. Set commands that report state (SetSignalReport, SetAgcResetInterval, SetFemState, SetRxBoostedGain) reply with the matching Get response, so 0x9C, 0x9E and 0xA0 are never sent.

Sub-command Value Data
Identity 0x81 PubKey (32)
Random 0x82 Random bytes (1-64)
Verify 0x83 Result (1): 0x00=invalid, 0x01=valid
Signature 0x84 Signature (64)
Encrypted 0x85 MAC (2) + Ciphertext
Decrypted 0x86 Plaintext
SharedSecret 0x87 Shared secret (32)
Hash 0x88 SHA-256 hash (32)
Radio 0x8B Freq (4) + BW (4) + SF (1) + CR (1)
TxPower 0x8C Power dBm (1)
CurrentRssi 0x8D RSSI dBm (1, signed)
ChannelBusy 0x8E Result (1): 0x00=clear, 0x01=busy
Airtime 0x8F Milliseconds (4)
NoiseFloor 0x90 dBm (2, signed)
Version 0x91 Version (1) + Reserved (1)
Stats 0x92 RX (4) + TX (4) + Errors (4)
Battery 0x93 Millivolts (2)
MCUTemp 0x94 Temperature (2, signed)
Sensors 0x95 CayenneLPP payload
DeviceName 0x96 Name (variable, UTF-8)
Pong 0x97 -
SignalReport 0x9A Status (1): 0x00=disabled, 0x01=enabled
Capabilities 0x9B Feature bits (4)
AgcResetInterval 0x9D Effective seconds (2)
FemState 0x9F Capability mask (1) + Value mask (1)
RxBoostedGain 0xA1 Status (1): 0x00=disabled, 0x01=enabled
OK 0xF0 -
Error 0xF1 Error code (1)
TxDone 0xF8 Result (1): 0x00=failed, 0x01=success
RxMeta 0xF9 SNR (1) + RSSI (1)

Error Codes

Code Value Description
InvalidLength 0x01 Request data too short
InvalidParam 0x02 Invalid parameter value
NoCallback 0x03 Feature not available
MacFailed 0x04 MAC verification failed
UnknownCmd 0x05 Unknown sub-command
EncryptFailed 0x06 Encryption failed
TxBusy 0x07 Radio TX busy, or host output queue full
Unsupported 0x08 Command known, but not supported by this board

Unsolicited Events

The TNC sends these SetHardware frames without a preceding request:

TxDone (0xF8): Sent after radio transmission completes. Contains a single byte: 0x01 for success, 0x00 for failure. Delivery to the host may be delayed under serial backpressure but is not dropped.

RxMeta (0xF9): Sent after each standard data frame (type 0x00) with SNR (1 byte, signed, value x4) and RSSI (1 byte, signed, dBm). Queued with the data frame; omitted if the data frame cannot be queued. Enabled by default; toggle with SetSignalReport. Standard KISS clients ignore this frame.

Data Formats

Radio Parameters (SetRadio / Radio response)

All values little-endian.

Field Size Description
Frequency 4 bytes Hz (e.g., 869618000)
Bandwidth 4 bytes Hz (e.g., 62500)
SF 1 byte Spreading factor (5-12)
CR 1 byte Coding rate (5-8)

Version (Version response)

Field Size Description
Version 1 byte Firmware version
Reserved 1 byte Always 0

Encrypted (Encrypted response)

Field Size Description
MAC 2 bytes HMAC-SHA256 truncated to 2 bytes
Ciphertext variable AES-128 block-encrypted data with zero padding

Airtime (Airtime response)

All values little-endian.

Field Size Description
Airtime 4 bytes uint32_t, estimated air time in milliseconds

Noise Floor (NoiseFloor response)

All values little-endian.

Field Size Description
Noise floor 2 bytes int16_t, dBm (signed)

The modem recalibrates the noise floor every 2 seconds. AGC resets follow the configured AGC reset interval (default 32 seconds).

Capabilities (Capabilities response)

All values little-endian. Hosts should probe capabilities rather than infer them from the firmware version: boards running the same version expose different hardware controls. Firmware older than version 2 answers GetCapabilities with UnknownCmd; treat that as no capabilities.

Field Size Description
Feature bits 4 bytes uint32_t, see below
Bit Value Description
0 0x01 AGC reset interval control (always set)
1 0x02 External FEM RX (LNA) gain control
2 0x04 External FEM TX (PA) gain control
3 0x08 Radio chip boosted RX gain control

Remaining bits are reserved and sent as 0.

AGC Reset Interval (SetAgcResetInterval / AgcResetInterval response)

All values little-endian.

Field Size Description
Seconds 2 bytes uint16_t, 0 = disabled, maximum 1020

The modem periodically resets the radio's AGC while idle (no transmission in progress and host output not backed up). The interval has 4-second resolution, matching the MeshCore agc.reset.interval setting: requested values are rounded down to a multiple of 4, so 1-3 disable the reset. Values above 1020 return InvalidParam. SetAgcResetInterval replies with the AgcResetInterval response carrying the effective value, and restarts the countdown from the time of the request.

The default is 32 seconds (previously a fixed 30; changed so the default is a settable 4-second multiple). The setting is not persisted; hosts should re-send it after reconnecting or rebooting the modem.

FEM State (SetFemState / FemState response)

Controls the board's external LoRa front-end module gain. This is separate from the radio chip's own RX boosted gain. TX/RX switching of the FEM is handled by the board and is not affected by these settings.

Bit Value Description
0 0x01 RX gain (LNA enabled)
1 0x02 TX gain (PA high gain enabled)

SetFemState data:

Field Size Description
Apply mask 1 byte Bits to change; bits not set are left as-is
Value mask 1 byte New value for each bit in the apply mask

FemState response data:

Field Size Description
Capability mask 1 byte Bits this board can control
Value mask 1 byte Current state; always 0 for uncontrollable bits

Example: enable RX gain without changing TX gain: apply 0x01, value 0x01.

If any bit in the apply mask is not in the board's capability mask (including reserved bits), the modem replies Unsupported and changes nothing. Otherwise SetFemState replies with the FemState response carrying the state read back from the board; if a bit differs from the request, that change did not take effect. SetFemState and GetFemState requests, including their error replies, are answered strictly in the order received. A SetFemState received while a packet is on air (before its TxDone is queued) is held and applied after TxDone, so its reply follows TxDone, and FEM requests that arrive after it wait behind it. Up to 4 FEM requests can wait; beyond that the modem replies TxBusy immediately. Capabilities come from the board's own get/set radio.fem.rxgain and radio.fem.txgain CLI commands (see cli_commands.md): a gain is controllable when the board answers get with > on or > off. Any board that implements those commands is supported without KISS changes, and a board with a fixed, board-managed FEM (for example RAK3401) reports none. Changes made over KISS are not saved to the board's preferences.

The setting is not persisted; the board's power-on default applies after reboot.

RX Boosted Gain (SetRxBoostedGain / RxBoostedGain response)

Controls the radio chip's own boosted RX gain mode (SX1262, SX1268, LLCC68, LR11x0, LR2021), the equivalent of the MeshCore radio.rxgain setting. This is independent of the external FEM RX gain controlled by SetFemState; a board can support either, both or neither.

Field Size Description
Status 1 byte 0x00 = power-saving, 0x01 = boosted

SetRxBoostedGain always replies with the RxBoostedGain response carrying the effective state read back from the radio; if it differs from the requested value, the change did not take effect. Some radios must drop to standby to apply it, so the modem replies TxBusy and changes nothing while a packet is on air or host output is backed up; retry later. Before applying, any completed received packet is delivered to the host first. A packet still being received at that moment can be lost. Radios whose driver has no boosted RX gain control (for example SX127x and STM32WLx) do not set capability bit 3 and reply Unsupported to both commands. The power-on default is the build's SX126X_RX_BOOSTED_GAIN setting; the value is not persisted, and periodic AGC resets preserve it.

Stats (Stats response)

All values little-endian.

Field Size Description
RX 4 bytes Packets received
TX 4 bytes Packets transmitted
Errors 4 bytes Receive errors

Battery (Battery response)

All values little-endian.

Field Size Description
Millivolts 2 bytes uint16_t, battery voltage in mV

MCU Temperature (MCUTemp response)

All values little-endian.

Field Size Description
Temperature 2 bytes int16_t, tenths of °C (e.g., 253 = 25.3°C)

Returns NoCallback error if the board does not support temperature readings.

Device Name (DeviceName response)

Field Size Description
Name variable UTF-8 string, no null terminator

Reboot

Sends an OK response, flushes serial, then reboots the device. The host should expect the connection to drop.

Sensor Permissions (GetSensors)

Bit Value Description
0 0x01 Base (battery)
1 0x02 Location (GPS)
2 0x04 Environment (temp, humidity, pressure)

Use 0x07 for all permissions.

Sensor Data (Sensors response)

Data returned in CayenneLPP format. See CayenneLPP documentation for parsing.

Cryptographic Algorithms

Operation Algorithm
Identity / Signing / Verification Ed25519
Key Exchange X25519 (ECDH)
Encryption AES-128 block encryption with zero padding + HMAC-SHA256 (MAC truncated to 2 bytes)
Hashing SHA-256

Notes

  • Data payload limit (255 bytes) matches MeshCore MAX_TRANS_UNIT; no change needed for KISS “1024+ recommended” (that applies to general TNCs, not MeshCore)
  • Modem generates identity on first boot (stored in flash)
  • All multi-byte values are little-endian unless stated otherwise
  • SNR values in RxMeta are multiplied by 4 for 0.25 dB precision
  • TxDone is sent as a SetHardware event after each transmission
  • Standard KISS clients receive only type 0x00 data frames and can safely ignore all SetHardware (0x06) frames
  • See packet_format.md for packet format