# 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](./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](https://docs.mydevices.com/docs/lorawan/cayenne-lpp) 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](./packet_format.md) for packet format