Ares Frames¶
The firmware communicates with the host computer over serial with a frames. These frames are called "Ares Frames." The frames have a common structure and consist of a variety of frames types. The frame structure and frame types are described as follows:
| Field | Header | Payload Length | Type | Payload | Footer |
|---|---|---|---|---|---|
| Size (bytes) | 1 | 2 | 1 | n | 1 |
| Value | ^ | n | ... | ... | @ |
| Type | Value | Direction | Description |
|---|---|---|---|
| SETTING | 0 | TX/RX | Configure or read persistent firmware settings |
| START | 1 | TX/RX | Time to start I/Q data collection |
| LORA_CONFIG | 2 | RX | Set new LoRa modem configurations |
| LED | 3 | TX/RX | Set or read the LED state/action |
| HEARTBEAT | 4 | TX/RX | Heartbeat indicating that the node is working and if it is ready to collect data |
| CLAIM | 5 | TX/RX | Claim master node request |
| LOG | 6 | TX/RX | Logging message |
| LOG_ACK | 7 | TX | Logging message received acknowledgement |
| VERSION | 8 | TX/RX | Firmware versions |
| ACK | 9 | TX | Frame acknowledgement |
| FRAMING_ERROR | 10 | TX | Framing error (internal error) |
| DBG | 11 | TX | Firmware debugging message |
| PKT_RX | 12 | TX | Notification from firmware that indicates a LoRa packet was received |
| PKT_TX | 13 | TX | Notification from firmware that indicates how many packets were sent over LoRa |
Note
The frame directions are described in relation to the microcontroller.
SETTING Frame¶
The setting frame is used to read or set firmware settings that persist over firmware reboots. There are two payload structures associated with this frame: Key/Value and Key. A table of settings, their ID's, defaults, and ranges is shown below:
| Setting | ID | Default | Minimum | Maximum | Description |
|---|---|---|---|---|---|
| ID | 0 | 0 | 1 | 65535 | LoRa node identifier. This must be set before use. |
| WAIT_USB_HOST | 1 | 0 | 0 | 1 | Wait for a USB connection to host computer before transmitting over serial. |
| PANID | 2 | 0 | 0 | 65535 | Personal Area Network ID. |
| REPETITION_CNT | 4 | 10 | 1 | 4294967295 | Default for the number of times to send a message over LoRa. |
Note
All bounds are inclusive.
Key/Value Payload Structure (TX/RX)¶
This payload structure is used in 2 different scenarios:
- To set a persistent firmware setting
- Firmware indicating what the value of a setting is
The payload is structured as such:
| Field | id | value |
| Type | uint16_t |
uint32_t |
- Payload Size: 6 bytes
Key Payload Structure (RX)¶
This payload structure is used in scenarios where the host is requesting the current value of a setting. The payload is structured as such:
| Field | id |
| Type | uint16_t |
- Payload Size: 2 bytes
START Frame¶
Start frames are used to indicate to the other nodes on the network when to start data collection. This frame consists of a start time, node id, broadcast flag, sequence count, and packet ID. The payload is structured as such:
| Field | second | nanoseconds | id | broadcast | sequence count | packet id |
| Type | int64_t |
uint64_t |
uint16_t |
bool |
uint8_t |
uint16_t |
- Payload size: 22 bytes
ID Field
The ID field can mean different things depending on the direction of the frame. If the frame is being sent, it indicates the source of the start message. When receiving, it indicates the destination ID for the message.
Broadcast Field
The broadcast field, when receiving, indicates if a message should be broadcasted to all listening nodes or not. If
it is broadcasting the message, the id field is ignored. When sending the frame, it is used to indicate if the
message was broadcasted or not.
Sequence Count and Packet ID
Sequence Count and Packet ID are derived from the LoRa packet and are ignored by the microcontroller when receiving this packet.
LORA_CONFIG Frame¶
LoRa configuration frames are used to configure the LoRa modem. These configurations do not persist after reboots. The payload structure is as follows:
| Field | Frequency | Preamble Length | Bandwidth | Data Rate | Coding Rate | Tx Power | CAD Mode | CAD Symbol Number | Detection Peak | Detection Minimum |
| Type | uint32_t |
uint16_t |
uint8_t |
uint8_t |
uint8_t |
int8_t |
uint8_t |
uint8_t |
uint8_t |
uint8_t |
| Field | Default Configuration | Description |
|---|---|---|
| Frequency | 915000000 | Frequency in Hz to use for transceiving. |
| Preamble Length | 8 | Length of the preamble. |
| Bandwidth | 0 | The bandwidth to use for transceiving. |
| Data Rate | 12 | The data-rate to use for transceiving. |
| Coding Rate | 1 | The coding rate to use for transceiving. |
| Tx Power | 4 | TX-power in dBm to use for transmission. |
| CAD Mode | 0 | Channel Activity Detection mode. |
| CAD Symbol Number | 0 | Number of symbols used for Channel Activity Detection. |
| Detection Peak | 0 | Detection peak threshold (hardware-specific, dimensionless). |
| Detection Minimum | 0 | Minimum detection threshold (hardware-specific, dimensionless). |
- Payload size: 14 bytes
Note
CAD Mode, CAD Symbol Number, Detection Peak, and Detection Minimum are unused (for future use). Zephyr RTOS kernel version v4.4.0 or newer is required for these fields.
LED Frame¶
LED frames are used to either get the current state/action of the LED or to set a new state/action of the LED. The payload is structured as follows:
| Field | led | State/Action |
| Type | uint8_t |
uint8_t |
| State/Action | Value | Description |
|---|---|---|
| OFF | 0 | Turn LED off. |
| ON | 1 | Turn LED on. |
| BLINK | 2 | Blink LED at 1 Hz. |
| FADE | 3 | Fade LED on and off. |
| FETCH | 4 | Retrieve the current LED state/action. (RX only) |
- Payload size: 2 bytes
HEARTBEAT Frame¶
The heartbeat frame is used to serve 2 purposes:
- Indicate if a node is live
- Indicate if a node is ready to collect data
The payload is structured as follows:
| Field | Flags | TX Count | Node ID |
| Type | uint8_t |
uint8_t |
uint16_t |
| Field | Description |
|---|---|
| Flags | bit 0: ready bit 1: broadcast bit 7:2: Reserved |
| TX Count | How many times to send the heartbeat message. |
| Node ID | The node ID the message is directed to, or the node ID of source. |
- Payload size: 4 bytes
Note
When receiving, if the broadcast flag is set, the Node ID field is ignored.
When transmitting, the broadcast flag indicates if the message was broadcasted, and the Node ID is the source
of the message.
CLAIM Frame¶
The claim frame is used to indicate which node is the master node in the network. The payload is structured as follows:
| Field | id |
| Type | uint16_t |
- Payload size: 2 bytes
Note
When receiving the frame, id is the node id that the message should be directed to.
When sending the frame, id is the node ID of the message source.
LOG Frame¶
Log frames are used to send logging messages to other nodes, either through a broadcast or a direct message. The payload is structured as follows:
| Field | broadcast | id | tx count | part | number of parts | log Id | message |
| Type | bool |
uint16_t |
uint8_t |
uint8_t |
uint8_t |
uint16_t |
char[] |
- Payload size: 8 +
len(message)
Note
When receiving, if broadcast is set to true, id is ignored. If broadcast is set to false, then id is the
destination ID.
When transmitting, the broadcast flag indicates if the message received was a broadcast message, and id is the
source ID of the message. tx count is ignored.
Warning
To avoid network congestion, log messages should be kept short and sent rarely.
LOG_ACK Frame¶
Log ACK frames are used to indicate that a log message was acknowledged by the node that it was directed to. The payload is structured as follows:
| Field | part | number of parts | log id |
| Type | uint8_t |
uint8_t |
uint16_t |
- Payload size: 4 bytes
Note
This frame is expected if the LOG frame sent was directed to another node.
VERSION Frames¶
Version frames are used to indicate the firmware versions. The payload is structured as follows:
| Field | App version | NCS version | Zephyr RTOS version |
| Type | uint32_t |
uint32_t |
uint32_t |
Note
On reception, the payload is ignored.
ACK Frame¶
The ACK frame is one of the ways for the firmware to acknowledge the received frame. Additionally, it provides an error code to indicate if the previous request from the host succeeded or not. The payload is structured as follows:
| Field | error code |
| Type | int32_t |
- Payload size: 4 bytes
Note
An error code of 0 indicates success.
FRAMING_ERROR Frame¶
The Framing error frame is used by the firmware to indicate if there was an error deserializing or deploying a frame. The payload is structured as follows:
| Field | error |
| Type | uint32_t |
| Error | Value | Description |
|---|---|---|
| Bad frame | 0 | Not framed correctly. |
| Bad type | 1 | Frame type invalid. |
| Not implemented | 2 | Frame type not implemented. |
- Payload size: 4 bytes
DBG Frame¶
The debug frame is used to indicate errors in the firmware that are not related to other frames. The payload is structures as follows:
| Field | code |
| Type | int32_t |
- Payload size: 4 bytes
PKT_RX Frame¶
The packet received frame is a notification from firmware that a packet was received and recovered. The payload is structured as follows:
| Field | sequence_count | packet_id | source_id |
| Type | uint8_t |
uint16_t |
uint16_t |
- Payload size: 5 bytes
PKT_TX Frame¶
The packet transmitted frame is a notification from firmware that a packet was transmitted a certain number of times. The payload is structured as follows:
| Field | count |
| Type | uint32_t |
- Payload size: 4 bytes