Add new commands and responses for RSSI, channel status, airtime, noise floor, statistics, battery, and sensors.

Author: ViezeVingertjes

docs/kiss_modem_protocol.md

@@ -48,38 +48,55 @@ 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
 
 | Code | Value | Description |
 |------|-------|-------------|
 | `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

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);
+  }
+}

examples/kiss_modem/KissModem.h

@@ -28,35 +28,59 @@
 #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
 #define ERR_NO_CALLBACK       0x03
 #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 @@ class KissModem {
   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);