Skip to content

Commit 9405e8b

Browse files
author
Scott Powell
committed
Merge branch 'dev'
# Conflicts: # docs/payloads.md
2 parents 8b68b5a + 91e9fce commit 9405e8b

File tree

163 files changed

+5620
-800
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

163 files changed

+5620
-800
lines changed

‎boards/ESP32-S3-WROOM-1-N4.json‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
{
2+
"build": {
3+
"arduino": {
4+
"ldscript": "esp32s3_out.ld"
5+
},
6+
"core": "esp32",
7+
"extra_flags": [
8+
"-D ARDUINO_USB_CDC_ON_BOOT=0",
9+
"-D ARDUINO_USB_MSC_ON_BOOT=0",
10+
"-D ARDUINO_USB_DFU_ON_BOOT=0",
11+
"-D ARDUINO_USB_MODE=0",
12+
"-D ARDUINO_RUNNING_CORE=1",
13+
"-D ARDUINO_EVENT_RUNNING_CORE=1"
14+
],
15+
"f_cpu": "240000000L",
16+
"f_flash": "80000000L",
17+
"flash_mode": "qio",
18+
"hwids": [["0x303A", "0x1001"]],
19+
"mcu": "esp32s3",
20+
"variant": "ESP32-S3-WROOM-1-N4"
21+
},
22+
"connectivity": ["wifi", "bluetooth"],
23+
"debug": {
24+
"default_tool": "esp-builtin",
25+
"onboard_tools": ["esp-builtin"],
26+
"openocd_target": "esp32s3.cfg"
27+
},
28+
"frameworks": ["arduino", "espidf"],
29+
"name": "ESP32-S3-WROOM-1-N4 (4 MB Flash, No PSRAM)",
30+
"upload": {
31+
"flash_size": "4MB",
32+
"maximum_ram_size": 524288,
33+
"maximum_size": 4194304,
34+
"require_upload_port": true,
35+
"speed": 921600
36+
},
37+
"url": "https://www.espressif.com/sites/default/files/documentation/esp32-s3-wroom-1_wroom-1u_datasheet_en.pdf",
38+
"vendor": "Espressif"
39+
}

‎boards/heltec_tracker_v2.json‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
{
2+
"build": {
3+
"arduino": {
4+
"ldscript": "esp32s3_out.ld",
5+
"partitions": "default_8MB.csv"
6+
},
7+
"core": "esp32",
8+
"extra_flags": [
9+
"-DARDUINO_USB_CDC_ON_BOOT=1",
10+
"-DARDUINO_USB_MODE=0",
11+
"-DARDUINO_RUNNING_CORE=1",
12+
"-DARDUINO_EVENT_RUNNING_CORE=1"
13+
],
14+
"f_cpu": "240000000L",
15+
"f_flash": "80000000L",
16+
"flash_mode": "qio",
17+
"hwids": [["0x303A", "0x1001"]],
18+
"mcu": "esp32s3",
19+
"variant": "heltec_tracker_v2"
20+
},
21+
"connectivity": ["wifi", "bluetooth", "lora"],
22+
"debug": {
23+
"default_tool": "esp-builtin",
24+
"onboard_tools": ["esp-builtin"],
25+
"openocd_target": "esp32s3.cfg"
26+
},
27+
"frameworks": ["arduino", "espidf"],
28+
"name": "heltec_tracker v2",
29+
"upload": {
30+
"flash_size": "8MB",
31+
"maximum_ram_size": 327680,
32+
"maximum_size": 8388608,
33+
"use_1200bps_touch": true,
34+
"wait_for_upload_port": true,
35+
"require_upload_port": true,
36+
"speed": 921600
37+
},
38+
"url": "https://heltec.org/",
39+
"vendor": "heltec"
40+
}

‎boards/rak4631.json‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
{
2+
"build": {
3+
"arduino": {
4+
"ldscript": "nrf52840_s140_v6.ld"
5+
},
6+
"core": "nRF5",
7+
"cpu": "cortex-m4",
8+
"extra_flags": "-DARDUINO_NRF52840_FEATHER -DNRF52840_XXAA",
9+
"f_cpu": "64000000L",
10+
"hwids": [
11+
[
12+
"0x239A",
13+
"0x8029"
14+
],
15+
[
16+
"0x239A",
17+
"0x0029"
18+
],
19+
[
20+
"0x239A",
21+
"0x002A"
22+
],
23+
[
24+
"0x239A",
25+
"0x802A"
26+
]
27+
],
28+
"usb_product": "WisCore RAK4631 Board",
29+
"mcu": "nrf52840",
30+
"variant": "WisCore_RAK4631_Board",
31+
"bsp": {
32+
"name": "adafruit"
33+
},
34+
"softdevice": {
35+
"sd_flags": "-DS140",
36+
"sd_name": "s140",
37+
"sd_version": "6.1.1",
38+
"sd_fwid": "0x00B6"
39+
},
40+
"bootloader": {
41+
"settings_addr": "0xFF000"
42+
}
43+
},
44+
"connectivity": [
45+
"bluetooth"
46+
],
47+
"debug": {
48+
"jlink_device": "nRF52840_xxAA",
49+
"svd_path": "nrf52840.svd"
50+
},
51+
"frameworks": [
52+
"arduino"
53+
],
54+
"name": "WisCore RAK4631 Board",
55+
"upload": {
56+
"maximum_ram_size": 248832,
57+
"maximum_size": 815104,
58+
"speed": 115200,
59+
"protocol": "nrfutil",
60+
"protocols": [
61+
"jlink",
62+
"nrfjprog",
63+
"nrfutil",
64+
"stlink"
65+
],
66+
"use_1200bps_touch": true,
67+
"require_upload_port": true,
68+
"wait_for_upload_port": true
69+
},
70+
"url": "https://www.rakwireless.com",
71+
"vendor": "RAKwireless"
72+
}

‎build.sh‎

Lines changed: 40 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,45 @@
11
#!/usr/bin/env bash
22

3-
# usage
4-
# sh build.sh build-firmware RAK_4631_Repeater
5-
# sh build.sh build-firmwares
6-
# sh build.sh build-matching-firmwares RAK_4631
7-
# sh build.sh build-companion-firmwares
8-
# sh build.sh build-repeater-firmwares
9-
# sh build.sh build-room-server-firmwares
3+
global_usage() {
4+
cat - <<EOF
5+
Usage:
6+
sh build.sh <command> [target]
7+
8+
Commands:
9+
help|usage|-h|--help: Shows this message.
10+
build-firmware <target>: Build the firmware for the given build target.
11+
build-firmwares: Build all firmwares for all targets.
12+
build-matching-firmwares <build-match-spec>: Build all firmwares for build targets containing the string given for <build-match-spec>.
13+
build-companion-firmwares: Build all companion firmwares for all build targets.
14+
build-repeater-firmwares: Build all repeater firmwares for all build targets.
15+
build-room-server-firmwares: Build all chat room server firmwares for all build targets.
16+
17+
Examples:
18+
Build firmware for the "RAK_4631_repeater" device target
19+
$ sh build.sh build-firmware RAK_4631_repeater
20+
21+
Build all firmwares for device targets containing the string "RAK_4631"
22+
$ sh build.sh build-matching-firmwares <build-match-spec>
23+
24+
Build all companion firmwares
25+
$ sh build.sh build-companion-firmwares
26+
27+
Build all repeater firmwares
28+
$ sh build.sh build-repeater-firmwares
29+
30+
Build all chat room server firmwares
31+
$ sh build.sh build-room-server-firmwares
32+
EOF
33+
}
34+
35+
# Catch cries for help before doing anything else.
36+
case $1 in
37+
help|usage|-h|--help)
38+
global_usage
39+
exit 1
40+
;;
41+
esac
42+
1043

1144
# get a list of pio env names that start with "env:"
1245
get_pio_envs() {

‎create-uf2.py‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
#!/usr/bin/python3
2+
3+
# Adds PlatformIO post-processing to convert hex files to uf2 files
4+
5+
import os
6+
7+
Import("env")
8+
9+
firmware_hex = "${BUILD_DIR}/${PROGNAME}.hex"
10+
uf2_file = os.environ.get("UF2_FILE_PATH", "${BUILD_DIR}/${PROGNAME}.uf2")
11+
12+
def create_uf2_action(source, target, env):
13+
uf2_cmd = " ".join(
14+
[
15+
'"$PYTHONEXE"',
16+
'"$PROJECT_DIR/bin/uf2conv/uf2conv.py"',
17+
'-f', '0xADA52840',
18+
'-c', firmware_hex,
19+
'-o', uf2_file,
20+
]
21+
)
22+
env.Execute(uf2_cmd)
23+
24+
env.AddCustomTarget(
25+
name="create_uf2",
26+
dependencies=firmware_hex,
27+
actions=create_uf2_action,
28+
title="Create UF2 file",
29+
description="Use uf2conv to convert hex binary into uf2",
30+
always_build=True,
31+
)

‎docs/packet_structure.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,10 @@ bit 0 means the lowest bit (1s place)
4444
| `0x08` | `PAYLOAD_TYPE_PATH` | Returned path. |
4545
| `0x09` | `PAYLOAD_TYPE_TRACE` | trace a path, collecting SNI for each hop. |
4646
| `0x0A` | `PAYLOAD_TYPE_MULTIPART` | packet is part of a sequence of packets. |
47+
| `0x0B` | `PAYLOAD_TYPE_CONTROL` | control packet data (unencrypted) |
48+
| `0x0C` | . | reserved |
49+
| `0x0D` | . | reserved |
50+
| `0x0E` | . | reserved |
4751
| `0x0F` | `PAYLOAD_TYPE_RAW_CUSTOM` | Custom packet (raw bytes, custom encryption). |
4852

4953
## Payload Version Values

‎docs/payloads.md‎

Lines changed: 44 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Inside of each [meshcore packet](./packet_structure.md) is a payload, identified
1111
* Group text message (unverified).
1212
* Group datagram (unverified).
1313
* Multi-part packet
14+
* Control data packet
1415
* Custom packet (raw bytes, custom encryption).
1516

1617
This document defines the structure of each of these payload types.
@@ -57,7 +58,7 @@ Appdata Flags
5758

5859
# Acknowledgement
5960

60-
An acknowledgement that a message was received. Note that for returned path messages, an acknowledgement will be sent in the "extra" payload (see [Returned Path](#returned-path)) and not as a discrete acknowledgement. CLI commands do not require an acknowledgement, neither discrete nor extra.
61+
An acknowledgement that a message was received. Note that for returned path messages, an acknowledgement can be sent in the "extra" payload (see [Returned Path](#returned-path)) instead of as a separate ackowledgement packet. CLI commands do not cause acknowledgement responses, neither discrete nor extra.
6162

6263
| Field | Size (bytes) | Description |
6364
|----------|--------------|------------------------------------------------------------|
@@ -140,13 +141,13 @@ Request data about sensors on the node, including battery level.
140141

141142
## Plain text message
142143

143-
| Field | Size (bytes) | Description |
144-
|-----------------|-----------------|--------------------------------------------------------------|
145-
| timestamp | 4 | send time (unix timestamp) |
146-
| flags + attempt | 1 | upper six bits are flags (see below), lower two bits are attempt number (0..3) |
147-
| message | rest of payload | the message content, see next table |
144+
| Field | Size (bytes) | Description |
145+
|--------------------|-----------------|--------------------------------------------------------------|
146+
| timestamp | 4 | send time (unix timestamp) |
147+
| txt_type + attempt | 1 | upper six bits are txt_type (see below), lower two bits are attempt number (0..3) |
148+
| message | rest of payload | the message content, see next table |
148149

149-
Flags
150+
txt_type
150151

151152
| Value | Description | Message content |
152153
|--------|---------------------------|------------------------------------------------------------|
@@ -163,13 +164,20 @@ Flags
163164
| cipher MAC | 2 | MAC for encrypted data in next field |
164165
| ciphertext | rest of payload | encrypted message, see below for details |
165166

166-
Plaintext message
167+
## Room server login
167168

168169
| Field | Size (bytes) | Description |
169170
|----------------|-----------------|-------------------------------------------------------------------------------|
170-
| timestamp | 4 | send time (unix timestamp) |
171-
| sync timestamp | 4 | NOTE: room server only! - sender's "sync messages SINCE x" timestamp |
172-
| password | rest of message | password for repeater/room |
171+
| timestamp | 4 | sender time (unix timestamp) |
172+
| sync timestamp | 4 | sender's "sync messages SINCE x" timestamp |
173+
| password | rest of message | password for room |
174+
175+
## Repeater/Sensor login
176+
177+
| Field | Size (bytes) | Description |
178+
|----------------|-----------------|-------------------------------------------------------------------------------|
179+
| timestamp | 4 | sender time (unix timestamp) |
180+
| password | rest of message | password for repeater/sensor |
173181

174182
# Group text message / datagram
175183

@@ -182,7 +190,31 @@ Plaintext message
182190
The plaintext contained in the ciphertext matches the format described in [plain text message](#plain-text-message). Specifically, it consists of a four byte timestamp, a flags byte, and the message. The flags byte will generally be `0x00` because it is a "plain text message". The message will be of the form `<sender name>: <message body>` (eg., `user123: I'm on my way`).
183191

184192

185-
TODO: describe what datagram looks like
193+
# Control data
194+
195+
| Field | Size (bytes) | Description |
196+
|--------------|-----------------|--------------------------------------------|
197+
| flags | 1 | upper 4 bits is sub_type |
198+
| data | rest of payload | typically unencrypted data |
199+
200+
## DISCOVER_REQ (sub_type)
201+
202+
| Field | Size (bytes) | Description |
203+
|--------------|-----------------|----------------------------------------------|
204+
| flags | 1 | 0x8 (upper 4 bits), prefix_only (lowest bit) |
205+
| type_filter | 1 | bit for each ADV_TYPE_* |
206+
| tag | 4 | randomly generate by sender |
207+
| since | 4 | (optional) epoch timestamp (0 by default) |
208+
209+
## DISCOVER_RESP (sub_type)
210+
211+
| Field | Size (bytes) | Description |
212+
|--------------|-----------------|--------------------------------------------|
213+
| flags | 1 | 0x9 (upper 4 bits), node_type (lower 4) |
214+
| snr | 1 | signed, SNR*4 |
215+
| tag | 4 | reflected back from DISCOVER_REQ |
216+
| pubkey | 8 or 32 | node's ID (or prefix) |
217+
186218

187219
# Custom packet
188220

0 commit comments

Comments
 (0)