From 1bcb52bab318926b014d0a46d98ebc2f35ff5e3f Mon Sep 17 00:00:00 2001 From: ViezeVingertjes Date: Sat, 31 Jan 2026 15:05:25 +0100 Subject: [PATCH] Add new commands and responses for RSSI, channel status, airtime, noise floor, statistics, battery, and sensors. --- docs/kiss_modem_protocol.md | 74 +++++++++++++---- examples/kiss_modem/KissModem.cpp | 128 ++++++++++++++++++++++++++++++ examples/kiss_modem/KissModem.h | 78 ++++++++++++++---- examples/kiss_modem/main.cpp | 46 +++++++++++ 4 files changed, 294 insertions(+), 32 deletions(-) diff --git a/docs/kiss_modem_protocol.md b/docs/kiss_modem_protocol.md index f85bfe6c..e80c3b29 100644 --- a/docs/kiss_modem_protocol.md +++ b/docs/kiss_modem_protocol.md @@ -48,27 +48,43 @@ Maximum unescaped frame size: 512 bytes. | `CMD_GET_TX_POWER` | `0x0D` | - | | `CMD_GET_SYNC_WORD` | `0x0E` | - | | `CMD_GET_VERSION` | `0x0F` | - | +| `CMD_GET_CURRENT_RSSI` | `0x10` | - | +| `CMD_IS_CHANNEL_BUSY` | `0x11` | - | +| `CMD_GET_AIRTIME` | `0x12` | Packet length (1) | +| `CMD_GET_NOISE_FLOOR` | `0x13` | - | +| `CMD_GET_STATS` | `0x14` | - | +| `CMD_GET_BATTERY` | `0x15` | - | +| `CMD_PING` | `0x16` | - | +| `CMD_GET_SENSORS` | `0x17` | Permissions (1) | ### Response Commands (Modem → Host) | Command | Value | Data | |---------|-------|------| | `CMD_DATA` | `0x00` | SNR (1) + RSSI (1) + Packet | -| `RESP_IDENTITY` | `0x11` | PubKey (32) | -| `RESP_RANDOM` | `0x12` | Random bytes (1-64) | -| `RESP_VERIFY` | `0x13` | Result (1): 0x00=invalid, 0x01=valid | -| `RESP_SIGNATURE` | `0x14` | Signature (64) | -| `RESP_ENCRYPTED` | `0x15` | MAC (2) + Ciphertext | -| `RESP_DECRYPTED` | `0x16` | Plaintext | -| `RESP_SHARED_SECRET` | `0x17` | Shared secret (32) | -| `RESP_HASH` | `0x18` | SHA-256 hash (32) | -| `RESP_OK` | `0x19` | - | -| `RESP_RADIO` | `0x1A` | Freq (4) + BW (4) + SF (1) + CR (1) | -| `RESP_TX_POWER` | `0x1B` | Power dBm (1) | -| `RESP_SYNC_WORD` | `0x1C` | Sync word (1) | -| `RESP_VERSION` | `0x1D` | Version (1) + Reserved (1) | -| `RESP_ERROR` | `0x1E` | Error code (1) | -| `RESP_TX_DONE` | `0x1F` | Result (1): 0x00=failed, 0x01=success | +| `RESP_IDENTITY` | `0x21` | PubKey (32) | +| `RESP_RANDOM` | `0x22` | Random bytes (1-64) | +| `RESP_VERIFY` | `0x23` | Result (1): 0x00=invalid, 0x01=valid | +| `RESP_SIGNATURE` | `0x24` | Signature (64) | +| `RESP_ENCRYPTED` | `0x25` | MAC (2) + Ciphertext | +| `RESP_DECRYPTED` | `0x26` | Plaintext | +| `RESP_SHARED_SECRET` | `0x27` | Shared secret (32) | +| `RESP_HASH` | `0x28` | SHA-256 hash (32) | +| `RESP_OK` | `0x29` | - | +| `RESP_RADIO` | `0x2A` | Freq (4) + BW (4) + SF (1) + CR (1) | +| `RESP_TX_POWER` | `0x2B` | Power dBm (1) | +| `RESP_SYNC_WORD` | `0x2C` | Sync word (1) | +| `RESP_VERSION` | `0x2D` | Version (1) + Reserved (1) | +| `RESP_ERROR` | `0x2E` | Error code (1) | +| `RESP_TX_DONE` | `0x2F` | Result (1): 0x00=failed, 0x01=success | +| `RESP_CURRENT_RSSI` | `0x30` | RSSI dBm (1, signed) | +| `RESP_CHANNEL_BUSY` | `0x31` | Result (1): 0x00=clear, 0x01=busy | +| `RESP_AIRTIME` | `0x32` | Milliseconds (4) | +| `RESP_NOISE_FLOOR` | `0x33` | dBm (2, signed) | +| `RESP_STATS` | `0x34` | RX (4) + TX (4) + Errors (4) | +| `RESP_BATTERY` | `0x35` | Millivolts (2) | +| `RESP_PONG` | `0x36` | - | +| `RESP_SENSORS` | `0x37` | CayenneLPP payload | ## Error Codes @@ -76,10 +92,11 @@ Maximum unescaped frame size: 512 bytes. |------|-------|-------------| | `ERR_INVALID_LENGTH` | `0x01` | Request data too short | | `ERR_INVALID_PARAM` | `0x02` | Invalid parameter value | -| `ERR_NO_CALLBACK` | `0x03` | Radio callback not set | +| `ERR_NO_CALLBACK` | `0x03` | Feature not available | | `ERR_MAC_FAILED` | `0x04` | MAC verification failed | | `ERR_UNKNOWN_CMD` | `0x05` | Unknown command | | `ERR_ENCRYPT_FAILED` | `0x06` | Encryption failed | +| `ERR_TX_PENDING` | `0x07` | TX already pending | ## Data Formats @@ -102,9 +119,34 @@ All values little-endian. | RSSI | 1 byte | Signal strength dBm, signed | | Packet | variable | Raw MeshCore packet | +### Stats (RESP_STATS) + +All values little-endian. + +| Field | Size | Description | +|-------|------|-------------| +| RX | 4 bytes | Packets received | +| TX | 4 bytes | Packets transmitted | +| Errors | 4 bytes | Receive errors | + +### Sensor Permissions (CMD_GET_SENSORS) + +| Bit | Value | Description | +|-----|-------|-------------| +| 0 | `0x01` | Base (battery) | +| 1 | `0x02` | Location (GPS) | +| 2 | `0x04` | Environment (temp, humidity, pressure) | + +Use `0x07` for all permissions. + +### Sensor Data (RESP_SENSORS) + +Data returned in CayenneLPP format. See [CayenneLPP documentation](https://docs.mydevices.com/docs/lorawan/cayenne-lpp) for parsing. + ## Notes - Modem generates identity on first boot (stored in flash) - SNR values multiplied by 4 for 0.25 dB precision - Wait for `RESP_TX_DONE` before sending next packet +- Sending `CMD_DATA` while TX is pending returns `ERR_TX_PENDING` - See [packet_structure.md](./packet_structure.md) for packet format diff --git a/examples/kiss_modem/KissModem.cpp b/examples/kiss_modem/KissModem.cpp index 4e227d7f..c6e2f2bd 100644 --- a/examples/kiss_modem/KissModem.cpp +++ b/examples/kiss_modem/KissModem.cpp @@ -10,6 +10,13 @@ KissModem::KissModem(Stream& serial, mesh::LocalIdentity& identity, mesh::RNG& r _setRadioCallback = nullptr; _setTxPowerCallback = nullptr; _setSyncWordCallback = nullptr; + _getCurrentRssiCallback = nullptr; + _isChannelBusyCallback = nullptr; + _getAirtimeCallback = nullptr; + _getNoiseFloorCallback = nullptr; + _getStatsCallback = nullptr; + _getBatteryCallback = nullptr; + _getSensorsCallback = nullptr; _config = {0, 0, 0, 0, 0, 0x12}; } @@ -91,6 +98,8 @@ void KissModem::processFrame() { writeErrorFrame(ERR_INVALID_LENGTH); } else if (data_len > KISS_MAX_PACKET_SIZE) { writeErrorFrame(ERR_INVALID_LENGTH); + } else if (_has_pending_tx) { + writeErrorFrame(ERR_TX_PENDING); } else { memcpy(_pending_tx, data, data_len); _pending_tx_len = data_len; @@ -142,6 +151,30 @@ void KissModem::processFrame() { case CMD_GET_VERSION: handleGetVersion(); break; + case CMD_GET_CURRENT_RSSI: + handleGetCurrentRssi(); + break; + case CMD_IS_CHANNEL_BUSY: + handleIsChannelBusy(); + break; + case CMD_GET_AIRTIME: + handleGetAirtime(data, data_len); + break; + case CMD_GET_NOISE_FLOOR: + handleGetNoiseFloor(); + break; + case CMD_GET_STATS: + handleGetStats(); + break; + case CMD_GET_BATTERY: + handleGetBattery(); + break; + case CMD_PING: + handlePing(); + break; + case CMD_GET_SENSORS: + handleGetSensors(data, data_len); + break; default: writeErrorFrame(ERR_UNKNOWN_CMD); break; @@ -360,3 +393,98 @@ void KissModem::onTxComplete(bool success) { uint8_t result = success ? 0x01 : 0x00; writeFrame(RESP_TX_DONE, &result, 1); } + +void KissModem::handleGetCurrentRssi() { + if (!_getCurrentRssiCallback) { + writeErrorFrame(ERR_NO_CALLBACK); + return; + } + + float rssi = _getCurrentRssiCallback(); + int8_t rssi_byte = (int8_t)rssi; + writeFrame(RESP_CURRENT_RSSI, (uint8_t*)&rssi_byte, 1); +} + +void KissModem::handleIsChannelBusy() { + if (!_isChannelBusyCallback) { + writeErrorFrame(ERR_NO_CALLBACK); + return; + } + + uint8_t busy = _isChannelBusyCallback() ? 0x01 : 0x00; + writeFrame(RESP_CHANNEL_BUSY, &busy, 1); +} + +void KissModem::handleGetAirtime(const uint8_t* data, uint16_t len) { + if (len < 1) { + writeErrorFrame(ERR_INVALID_LENGTH); + return; + } + if (!_getAirtimeCallback) { + writeErrorFrame(ERR_NO_CALLBACK); + return; + } + + uint8_t packet_len = data[0]; + uint32_t airtime = _getAirtimeCallback(packet_len); + writeFrame(RESP_AIRTIME, (uint8_t*)&airtime, 4); +} + +void KissModem::handleGetNoiseFloor() { + if (!_getNoiseFloorCallback) { + writeErrorFrame(ERR_NO_CALLBACK); + return; + } + + int16_t noise_floor = _getNoiseFloorCallback(); + writeFrame(RESP_NOISE_FLOOR, (uint8_t*)&noise_floor, 2); +} + +void KissModem::handleGetStats() { + if (!_getStatsCallback) { + writeErrorFrame(ERR_NO_CALLBACK); + return; + } + + uint32_t rx, tx, errors; + _getStatsCallback(&rx, &tx, &errors); + uint8_t buf[12]; + memcpy(buf, &rx, 4); + memcpy(buf + 4, &tx, 4); + memcpy(buf + 8, &errors, 4); + writeFrame(RESP_STATS, buf, 12); +} + +void KissModem::handleGetBattery() { + if (!_getBatteryCallback) { + writeErrorFrame(ERR_NO_CALLBACK); + return; + } + + uint16_t mv = _getBatteryCallback(); + writeFrame(RESP_BATTERY, (uint8_t*)&mv, 2); +} + +void KissModem::handlePing() { + writeFrame(RESP_PONG, nullptr, 0); +} + +void KissModem::handleGetSensors(const uint8_t* data, uint16_t len) { + if (len < 1) { + writeErrorFrame(ERR_INVALID_LENGTH); + return; + } + if (!_getSensorsCallback) { + writeErrorFrame(ERR_NO_CALLBACK); + return; + } + + uint8_t permissions = data[0]; + uint8_t buf[255]; + uint8_t result_len = _getSensorsCallback(permissions, buf, 255); + if (result_len > 0) { + writeFrame(RESP_SENSORS, buf, result_len); + } else { + writeFrame(RESP_SENSORS, nullptr, 0); + } +} diff --git a/examples/kiss_modem/KissModem.h b/examples/kiss_modem/KissModem.h index 34d9577f..e223d92d 100644 --- a/examples/kiss_modem/KissModem.h +++ b/examples/kiss_modem/KissModem.h @@ -28,22 +28,38 @@ #define CMD_GET_TX_POWER 0x0D #define CMD_GET_SYNC_WORD 0x0E #define CMD_GET_VERSION 0x0F +#define CMD_GET_CURRENT_RSSI 0x10 +#define CMD_IS_CHANNEL_BUSY 0x11 +#define CMD_GET_AIRTIME 0x12 +#define CMD_GET_NOISE_FLOOR 0x13 +#define CMD_GET_STATS 0x14 +#define CMD_GET_BATTERY 0x15 +#define CMD_PING 0x16 +#define CMD_GET_SENSORS 0x17 -#define RESP_IDENTITY 0x11 -#define RESP_RANDOM 0x12 -#define RESP_VERIFY 0x13 -#define RESP_SIGNATURE 0x14 -#define RESP_ENCRYPTED 0x15 -#define RESP_DECRYPTED 0x16 -#define RESP_SHARED_SECRET 0x17 -#define RESP_HASH 0x18 -#define RESP_OK 0x19 -#define RESP_RADIO 0x1A -#define RESP_TX_POWER 0x1B -#define RESP_SYNC_WORD 0x1C -#define RESP_VERSION 0x1D -#define RESP_ERROR 0x1E -#define RESP_TX_DONE 0x1F +#define RESP_IDENTITY 0x21 +#define RESP_RANDOM 0x22 +#define RESP_VERIFY 0x23 +#define RESP_SIGNATURE 0x24 +#define RESP_ENCRYPTED 0x25 +#define RESP_DECRYPTED 0x26 +#define RESP_SHARED_SECRET 0x27 +#define RESP_HASH 0x28 +#define RESP_OK 0x29 +#define RESP_RADIO 0x2A +#define RESP_TX_POWER 0x2B +#define RESP_SYNC_WORD 0x2C +#define RESP_VERSION 0x2D +#define RESP_ERROR 0x2E +#define RESP_TX_DONE 0x2F +#define RESP_CURRENT_RSSI 0x30 +#define RESP_CHANNEL_BUSY 0x31 +#define RESP_AIRTIME 0x32 +#define RESP_NOISE_FLOOR 0x33 +#define RESP_STATS 0x34 +#define RESP_BATTERY 0x35 +#define RESP_PONG 0x36 +#define RESP_SENSORS 0x37 #define ERR_INVALID_LENGTH 0x01 #define ERR_INVALID_PARAM 0x02 @@ -51,12 +67,20 @@ #define ERR_MAC_FAILED 0x04 #define ERR_UNKNOWN_CMD 0x05 #define ERR_ENCRYPT_FAILED 0x06 +#define ERR_TX_PENDING 0x07 -#define KISS_FIRMWARE_VERSION 1 +#define KISS_FIRMWARE_VERSION 2 typedef void (*SetRadioCallback)(float freq, float bw, uint8_t sf, uint8_t cr); typedef void (*SetTxPowerCallback)(uint8_t power); typedef void (*SetSyncWordCallback)(uint8_t syncWord); +typedef float (*GetCurrentRssiCallback)(); +typedef bool (*IsChannelBusyCallback)(); +typedef uint32_t (*GetAirtimeCallback)(uint8_t len); +typedef int16_t (*GetNoiseFloorCallback)(); +typedef void (*GetStatsCallback)(uint32_t* rx, uint32_t* tx, uint32_t* errors); +typedef uint16_t (*GetBatteryCallback)(); +typedef uint8_t (*GetSensorsCallback)(uint8_t permissions, uint8_t* buffer, uint8_t max_len); struct RadioConfig { uint32_t freq_hz; @@ -84,6 +108,13 @@ class KissModem { SetRadioCallback _setRadioCallback; SetTxPowerCallback _setTxPowerCallback; SetSyncWordCallback _setSyncWordCallback; + GetCurrentRssiCallback _getCurrentRssiCallback; + IsChannelBusyCallback _isChannelBusyCallback; + GetAirtimeCallback _getAirtimeCallback; + GetNoiseFloorCallback _getNoiseFloorCallback; + GetStatsCallback _getStatsCallback; + GetBatteryCallback _getBatteryCallback; + GetSensorsCallback _getSensorsCallback; RadioConfig _config; @@ -107,6 +138,14 @@ class KissModem { void handleGetTxPower(); void handleGetSyncWord(); void handleGetVersion(); + void handleGetCurrentRssi(); + void handleIsChannelBusy(); + void handleGetAirtime(const uint8_t* data, uint16_t len); + void handleGetNoiseFloor(); + void handleGetStats(); + void handleGetBattery(); + void handlePing(); + void handleGetSensors(const uint8_t* data, uint16_t len); public: KissModem(Stream& serial, mesh::LocalIdentity& identity, mesh::RNG& rng); @@ -117,6 +156,13 @@ public: void setRadioCallback(SetRadioCallback cb) { _setRadioCallback = cb; } void setTxPowerCallback(SetTxPowerCallback cb) { _setTxPowerCallback = cb; } void setSyncWordCallback(SetSyncWordCallback cb) { _setSyncWordCallback = cb; } + void setGetCurrentRssiCallback(GetCurrentRssiCallback cb) { _getCurrentRssiCallback = cb; } + void setIsChannelBusyCallback(IsChannelBusyCallback cb) { _isChannelBusyCallback = cb; } + void setGetAirtimeCallback(GetAirtimeCallback cb) { _getAirtimeCallback = cb; } + void setGetNoiseFloorCallback(GetNoiseFloorCallback cb) { _getNoiseFloorCallback = cb; } + void setGetStatsCallback(GetStatsCallback cb) { _getStatsCallback = cb; } + void setGetBatteryCallback(GetBatteryCallback cb) { _getBatteryCallback = cb; } + void setGetSensorsCallback(GetSensorsCallback cb) { _getSensorsCallback = cb; } bool getPacketToSend(uint8_t* packet, uint16_t* len); void onPacketReceived(int8_t snr, int8_t rssi, const uint8_t* packet, uint16_t len); diff --git a/examples/kiss_modem/main.cpp b/examples/kiss_modem/main.cpp index 2f843a99..0a54c9d3 100644 --- a/examples/kiss_modem/main.cpp +++ b/examples/kiss_modem/main.cpp @@ -2,6 +2,7 @@ #include #include #include +#include #include "KissModem.h" #if defined(NRF52_PLATFORM) @@ -56,6 +57,42 @@ void onSetSyncWord(uint8_t sync_word) { radio_set_sync_word(sync_word); } +float onGetCurrentRssi() { + return radio_driver.getCurrentRSSI(); +} + +bool onIsChannelBusy() { + return radio_driver.isReceiving(); +} + +uint32_t onGetAirtime(uint8_t len) { + return radio_driver.getEstAirtimeFor(len); +} + +int16_t onGetNoiseFloor() { + return radio_driver.getNoiseFloor(); +} + +void onGetStats(uint32_t* rx, uint32_t* tx, uint32_t* errors) { + *rx = radio_driver.getPacketsRecv(); + *tx = radio_driver.getPacketsSent(); + *errors = radio_driver.getPacketsRecvErrors(); +} + +uint16_t onGetBattery() { + return board.getBattMilliVolts(); +} + +uint8_t onGetSensors(uint8_t permissions, uint8_t* buffer, uint8_t max_len) { + CayenneLPP telemetry(max_len); + if (sensors.querySensors(permissions, telemetry)) { + uint8_t len = telemetry.getSize(); + memcpy(buffer, telemetry.getBuffer(), len); + return len; + } + return 0; +} + void setup() { board.begin(); @@ -73,10 +110,19 @@ void setup() { while (!Serial && millis() - start < 3000) delay(10); delay(100); + sensors.begin(); + modem = new KissModem(Serial, identity, rng); modem->setRadioCallback(onSetRadio); modem->setTxPowerCallback(onSetTxPower); modem->setSyncWordCallback(onSetSyncWord); + modem->setGetCurrentRssiCallback(onGetCurrentRssi); + modem->setIsChannelBusyCallback(onIsChannelBusy); + modem->setGetAirtimeCallback(onGetAirtime); + modem->setGetNoiseFloorCallback(onGetNoiseFloor); + modem->setGetStatsCallback(onGetStats); + modem->setGetBatteryCallback(onGetBattery); + modem->setGetSensorsCallback(onGetSensors); modem->begin(); }