dandri/MeshCore
1
0
Fork 0
mirror of https://github.com/meshcore-dev/MeshCore.git synced 2026-03-29 13:00:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
ViezeVingertjes
2026-01-31 15:05:25 +01:00
parent c786cfe613
commit 1bcb52bab3
4 changed files with 294 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
docs/kiss_modem_protocol.md
View File

@@ -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

128
examples/kiss_modem/KissModem.cpp
View File

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

78
examples/kiss_modem/KissModem.h
View File

@@ -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);

46
examples/kiss_modem/main.cpp
View File

@@ -2,6 +2,7 @@
#include <target.h>
#include <helpers/ArduinoHelpers.h>
#include <helpers/IdentityStore.h>
#include <CayenneLPP.h>
#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();
}