Skip to content

Commit e03f311

Browse files
ripplebizripplebiz
authored
Merge pull request #1545 from ViezeVingertjes/kiss-modem-firmware
Add KISS-like Modem example and protocol documentation
2 parents ab99466 + f0ba14f commit e03f311

5 files changed

Lines changed: 860 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,9 +39,11 @@ For developers;
3939
- Clone and open the MeshCore repository in Visual Studio Code.
4040
- See the example applications you can modify and run:
4141
- [Companion Radio](./examples/companion_radio) - For use with an external chat app, over BLE, USB or WiFi.
42+
- [KISS Modem](./examples/kiss_modem) - Serial KISS protocol bridge for host applications. ([protocol docs](./docs/kiss_modem_protocol.md))
4243
- [Simple Repeater](./examples/simple_repeater) - Extends network coverage by relaying messages.
4344
- [Simple Room Server](./examples/simple_room_server) - A simple BBS server for shared Posts.
4445
- [Simple Secure Chat](./examples/simple_secure_chat) - Secure terminal based text communication between devices.
46+
- [Simple Sensor](./examples/simple_sensor) - Remote sensor node with telemetry and alerting.
4547

4648
The Simple Secure Chat example can be interacted with through the Serial Monitor in Visual Studio Code, or with a Serial USB Terminal on Android.
4749

‎docs/kiss_modem_protocol.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# MeshCore KISS Modem Protocol
2+
3+
Serial protocol for the KISS modem firmware. Enables sending/receiving MeshCore packets over LoRa and cryptographic operations using the modem's identity.
4+
5+
## Serial Configuration
6+
7+
115200 baud, 8N1, no flow control.
8+
9+
## Frame Format
10+
11+
Standard KISS framing with byte stuffing.
12+
13+
| Byte | Name | Description |
14+
|------|------|-------------|
15+
| `0xC0` | FEND | Frame delimiter |
16+
| `0xDB` | FESC | Escape character |
17+
| `0xDC` | TFEND | Escaped FEND (FESC + TFEND = 0xC0) |
18+
| `0xDD` | TFESC | Escaped FESC (FESC + TFESC = 0xDB) |
19+
20+
```
21+
┌──────┬─────────┬──────────────┬──────┐
22+
│ FEND │ Command │ Data (escaped)│ FEND │
23+
│ 0xC0 │ 1 byte │ 0-510 bytes │ 0xC0 │
24+
└──────┴─────────┴──────────────┴──────┘
25+
```
26+
27+
Maximum unescaped frame size: 512 bytes.
28+
29+
## Commands
30+
31+
### Request Commands (Host → Modem)
32+
33+
| Command | Value | Data |
34+
|---------|-------|------|
35+
| `CMD_DATA` | `0x00` | Packet (2-255 bytes) |
36+
| `CMD_GET_IDENTITY` | `0x01` | - |
37+
| `CMD_GET_RANDOM` | `0x02` | Length (1 byte, 1-64) |
38+
| `CMD_VERIFY_SIGNATURE` | `0x03` | PubKey (32) + Signature (64) + Data |
39+
| `CMD_SIGN_DATA` | `0x04` | Data to sign |
40+
| `CMD_ENCRYPT_DATA` | `0x05` | Key (32) + Plaintext |
41+
| `CMD_DECRYPT_DATA` | `0x06` | Key (32) + MAC (2) + Ciphertext |
42+
| `CMD_KEY_EXCHANGE` | `0x07` | Remote PubKey (32) |
43+
| `CMD_HASH` | `0x08` | Data to hash |
44+
| `CMD_SET_RADIO` | `0x09` | Freq (4) + BW (4) + SF (1) + CR (1) |
45+
| `CMD_SET_TX_POWER` | `0x0A` | Power dBm (1) |
46+
| `CMD_SET_SYNC_WORD` | `0x0B` | Sync word (1) |
47+
| `CMD_GET_RADIO` | `0x0C` | - |
48+
| `CMD_GET_TX_POWER` | `0x0D` | - |
49+
| `CMD_GET_SYNC_WORD` | `0x0E` | - |
50+
| `CMD_GET_VERSION` | `0x0F` | - |
51+
| `CMD_GET_CURRENT_RSSI` | `0x10` | - |
52+
| `CMD_IS_CHANNEL_BUSY` | `0x11` | - |
53+
| `CMD_GET_AIRTIME` | `0x12` | Packet length (1) |
54+
| `CMD_GET_NOISE_FLOOR` | `0x13` | - |
55+
| `CMD_GET_STATS` | `0x14` | - |
56+
| `CMD_GET_BATTERY` | `0x15` | - |
57+
| `CMD_PING` | `0x16` | - |
58+
| `CMD_GET_SENSORS` | `0x17` | Permissions (1) |
59+
60+
### Response Commands (Modem → Host)
61+
62+
| Command | Value | Data |
63+
|---------|-------|------|
64+
| `CMD_DATA` | `0x00` | SNR (1) + RSSI (1) + Packet |
65+
| `RESP_IDENTITY` | `0x21` | PubKey (32) |
66+
| `RESP_RANDOM` | `0x22` | Random bytes (1-64) |
67+
| `RESP_VERIFY` | `0x23` | Result (1): 0x00=invalid, 0x01=valid |
68+
| `RESP_SIGNATURE` | `0x24` | Signature (64) |
69+
| `RESP_ENCRYPTED` | `0x25` | MAC (2) + Ciphertext |
70+
| `RESP_DECRYPTED` | `0x26` | Plaintext |
71+
| `RESP_SHARED_SECRET` | `0x27` | Shared secret (32) |
72+
| `RESP_HASH` | `0x28` | SHA-256 hash (32) |
73+
| `RESP_OK` | `0x29` | - |
74+
| `RESP_RADIO` | `0x2A` | Freq (4) + BW (4) + SF (1) + CR (1) |
75+
| `RESP_TX_POWER` | `0x2B` | Power dBm (1) |
76+
| `RESP_SYNC_WORD` | `0x2C` | Sync word (1) |
77+
| `RESP_VERSION` | `0x2D` | Version (1) + Reserved (1) |
78+
| `RESP_ERROR` | `0x2E` | Error code (1) |
79+
| `RESP_TX_DONE` | `0x2F` | Result (1): 0x00=failed, 0x01=success |
80+
| `RESP_CURRENT_RSSI` | `0x30` | RSSI dBm (1, signed) |
81+
| `RESP_CHANNEL_BUSY` | `0x31` | Result (1): 0x00=clear, 0x01=busy |
82+
| `RESP_AIRTIME` | `0x32` | Milliseconds (4) |
83+
| `RESP_NOISE_FLOOR` | `0x33` | dBm (2, signed) |
84+
| `RESP_STATS` | `0x34` | RX (4) + TX (4) + Errors (4) |
85+
| `RESP_BATTERY` | `0x35` | Millivolts (2) |
86+
| `RESP_PONG` | `0x36` | - |
87+
| `RESP_SENSORS` | `0x37` | CayenneLPP payload |
88+
89+
## Error Codes
90+
91+
| Code | Value | Description |
92+
|------|-------|-------------|
93+
| `ERR_INVALID_LENGTH` | `0x01` | Request data too short |
94+
| `ERR_INVALID_PARAM` | `0x02` | Invalid parameter value |
95+
| `ERR_NO_CALLBACK` | `0x03` | Feature not available |
96+
| `ERR_MAC_FAILED` | `0x04` | MAC verification failed |
97+
| `ERR_UNKNOWN_CMD` | `0x05` | Unknown command |
98+
| `ERR_ENCRYPT_FAILED` | `0x06` | Encryption failed |
99+
| `ERR_TX_PENDING` | `0x07` | TX already pending |
100+
101+
## Data Formats
102+
103+
### Radio Parameters (CMD_SET_RADIO / RESP_RADIO)
104+
105+
All values little-endian.
106+
107+
| Field | Size | Description |
108+
|-------|------|-------------|
109+
| Frequency | 4 bytes | Hz (e.g., 869618000) |
110+
| Bandwidth | 4 bytes | Hz (e.g., 62500) |
111+
| SF | 1 byte | Spreading factor (5-12) |
112+
| CR | 1 byte | Coding rate (5-8) |
113+
114+
### Received Packet (CMD_DATA response)
115+
116+
| Field | Size | Description |
117+
|-------|------|-------------|
118+
| SNR | 1 byte | Signal-to-noise × 4, signed |
119+
| RSSI | 1 byte | Signal strength dBm, signed |
120+
| Packet | variable | Raw MeshCore packet |
121+
122+
### Stats (RESP_STATS)
123+
124+
All values little-endian.
125+
126+
| Field | Size | Description |
127+
|-------|------|-------------|
128+
| RX | 4 bytes | Packets received |
129+
| TX | 4 bytes | Packets transmitted |
130+
| Errors | 4 bytes | Receive errors |
131+
132+
### Sensor Permissions (CMD_GET_SENSORS)
133+
134+
| Bit | Value | Description |
135+
|-----|-------|-------------|
136+
| 0 | `0x01` | Base (battery) |
137+
| 1 | `0x02` | Location (GPS) |
138+
| 2 | `0x04` | Environment (temp, humidity, pressure) |
139+
140+
Use `0x07` for all permissions.
141+
142+
### Sensor Data (RESP_SENSORS)
143+
144+
Data returned in CayenneLPP format. See [CayenneLPP documentation](https://docs.mydevices.com/docs/lorawan/cayenne-lpp) for parsing.
145+
146+
## Notes
147+
148+
- Modem generates identity on first boot (stored in flash)
149+
- SNR values multiplied by 4 for 0.25 dB precision
150+
- Wait for `RESP_TX_DONE` before sending next packet
151+
- Sending `CMD_DATA` while TX is pending returns `ERR_TX_PENDING`
152+
- See [packet_structure.md](./packet_structure.md) for packet format

0 commit comments

Comments
 (0)