Skip to content

Commit 7b49ed4

Browse files
author
Scott Powell
committed
Merge branch 'main' into dev
2 parents 9bcab09 + 47b1854 commit 7b49ed4

File tree

7 files changed

+232
-63
lines changed

7 files changed

+232
-63
lines changed

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,11 @@ MeshCore is open-source software released under the MIT License. You are free to
9595
Please submit PR's using 'dev' as the base branch!
9696
For minor changes just submit your PR and I'll try to review it, but for anything more 'impactful' please open an Issue first and start a discussion. Is better to sound out what it is you want to achieve first, and try to come to a consensus on what the best approach is, especially when it impacts the structure or architecture of this codebase.
9797

98+
Here are some general principals you should try to adhere to:
99+
* Keep it simple. Please, don't think like a high-level lang programmer. Think embedded, and keep code concise, without any unecessary layers.
100+
* No dynamic memory allocation, except during setup/begin functions.
101+
* Use the same brace and indenting style that's in the core source modules. (A .clang-format is prob going to be added soon, but please do NOT retroactively re-format existing code. This just creates unnecessary diffs that make finding problems harder)
102+
98103
## 📞 Get Support
99104

100105
- Report bugs and request features on the [GitHub Issues](https://github.com/ripplebiz/MeshCore/issues) page.

‎docs/faq.md‎

Lines changed: 25 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,8 @@ author: https://github.com/LitBomb<!-- omit from toc -->
6565
- [6.4. Q: I can't connect via Bluetooth, what is the Bluetooth pairing code?](#64-q-i-cant-connect-via-bluetooth-what-is-the-bluetooth-pairing-code)
6666
- [6.5. Q: My Heltec V3 keeps disconnecting from my smartphone. It can't hold a solid Bluetooth connection.](#65-q-my-heltec-v3-keeps-disconnecting-from-my-smartphone--it-cant-hold-a-solid-bluetooth-connection)
6767
- [7. Other Questions:](#7-other-questions)
68-
- [7.1. Q: How to Update repeater and room server firmware over the air?](#71-q-how-to--update-repeater-and-room-server-firmware-over-the-air)
68+
- [7.2 Q: How to update ESP32-based devices over the air?](#72-q-how-to-update-esp32-based-devices-over-the-air)
69+
- [7.1 Q: How to update nRF (RAK, T114, Seed XIAO) repeater and room server firmware over the air using the new simpler DFU app?](#71-q-how-to-update-nrf-rak-t114-seed-xiao-repeater-and-room-server-firmware-over-the-air-using-the-new-simpler-dfu-app)
6970

7071
## 1. Introduction
7172

@@ -534,74 +535,35 @@ You can get the epoch time on <https://www.epochconverter.com/> and use it to se
534535

535536
---
536537
## 7. Other Questions:
537-
### 7.1. Q: How to Update repeater and room server firmware over the air?
538538

539-
**A:** Only nRF-based RAK4631 and Heltec T114 OTA firmware update are verified using nRF smartphone app. Lilygo T-Echo doesn't work currently.
540-
You can update repeater and room server firmware with a Bluetooth connection between your smartphone and your LoRa radio using the nRF app.
539+
### 7.2 Q: How to update ESP32-based devices over the air?
541540

542-
1. Download the ZIP file for the specific node from the web flasher to your smartphone
543-
2. On the phone client, log on to the repeater as administrator (default password is `password`) to issue the `start ota`command to the repeater or room server to get the device into OTA DFU mode
544-
545-
![image](https://github.com/user-attachments/assets/889bb81b-7214-4a1c-955a-396b5a05d8ad)
541+
**A:** For ESP32-based devices (e.g. Heltec V3):
542+
1. On flasher.meshcore.co.uk, download the **non-merged** version of the firmware for your ESP32 device (e.g. `Heltec_v3_repeater-v1.6.2-4449fd3.bin`, no `"merged"` in the file name)
543+
2. From the MeshCore app, login remotely to the repeater you want to update with admin priviledge
544+
4. Go to the Command Line tab, type `start ota` and hit enter.
545+
5. you should see `OK` to confirm the repeater device is now in OTA mode
546+
6. The command `start ota` on an ESP32-based device starts a wifi hotspot named `MeshCore OTA`
547+
7. From your phone or computer connect to the 'MeshCore OTA' hotspot
548+
8. From a browser, go to http://192.168.4.1/update and upload the non-merged bin from the flasher
546549

547-
1. `start ota` can be initiated from USB serial console on the web flasher page or a T-Deck
548-
4. On the smartphone, download and run the nRF app and scan for Bluetooth devices
549-
5. Connect to the repeater/room server node you want to update
550-
1. nRF app is available on both Android and iOS
551550

552-
**Android continues after the iOS section:**
551+
### 7.1 Q: How to update nRF (RAK, T114, Seed XIAO) repeater and room server firmware over the air using the new simpler DFU app?
553552

554-
**iOS continues here:**
555-
5. Once connected successfully, a `DFU` icon ![Pasted image 20250309173039](https://github.com/user-attachments/assets/af7a9f78-8739-4946-b734-02bade9c8e71)
556-
appears in the top right corner of the app
557-
![Pasted image 20250309171919](https://github.com/user-attachments/assets/08007ec8-4924-49c1-989f-ca2611e78793)
553+
**A:** The steps below work on both Android and iOS as nRF has made both apps' user interface the same on both platforms:
558554

559-
6. Scroll down to change the `PRN(s)` number:
560-
561-
![Pasted image 20250309190158](https://github.com/user-attachments/assets/11f69cdd-12f3-4696-a6fc-14a78c85fe32)
562-
563-
- For the T114, change the number of packets `(PRN(s)` to 8
564-
- For RAK, it can be 10, but it also works on 8.
565-
566-
7. Click the `DFU` icon ![Pasted image 20250309173039](https://github.com/user-attachments/assets/af7a9f78-8739-4946-b734-02bade9c8e71), select the type of file to upload (choose ZIP), then select the ZIP file that was downloaded earlier from the web flasher
567-
8. The upload process will start now. If everything goes well, the node resets and is flashed successfully.
568-
![Pasted image 20250309190342](https://github.com/user-attachments/assets/a60e25d0-33b8-46cf-af90-20a7d8ac2adb)
569-
570-
571-
572-
**Android steps continues below:**
573-
1. on the top left corner of the nRF Connect app on Android, tap the 3-bar hamburger menu, then `Settings`, then `nRF5 DFU Options`
574-
575-
![Android nRF Hamberger](https://github.com/user-attachments/assets/ea6dfeef-9367-4830-bd70-1441d517c706)
576-
577-
![Android nRF Settings](https://github.com/user-attachments/assets/c63726bf-cecd-4987-be68-afb6358c7190)
578-
579-
![Android nRF DFU Options](https://github.com/user-attachments/assets/b20e872f-5122-41d9-90df-0215cff5fbc9)
580-
581-
2. Change `Number of packets` to `10` for RAK, `8` for Heltec T114
582-
583-
![Android nRF Number of Packets](https://github.com/user-attachments/assets/c092adaf-4cb3-460b-b7ef-8d7f450d602b)
584-
585-
3. Go back to the main screen
586-
4. Your LoRa device should already ben in DFU mode from previous steps
587-
5. tap `SCANNER` and then `SCAN` to find the device you want to update, tap `CONNECT`
588-
589-
![Android nRF Scanner Scan Connect](https://github.com/user-attachments/assets/37218717-f167-48b6-a6ca-93d132ef77ca)
590-
591-
6. On the top left corner of the nRF Connect app, tap the `DFU` icon next to the three dots
592-
593-
![Android nRF DFU](https://github.com/user-attachments/assets/1ec3b818-bf0c-461f-8fdf-37c41a63cafa)
594-
595-
7. Choose `Distribution packet (ZIP)` and then `OK`
596-
597-
![Android nRF Distribution Packet (ZIP)](https://github.com/user-attachments/assets/e65f5616-9793-44f5-95c0-a3eb15aa7152)
598-
599-
8. Choose the firmware file in ZIP formate that you downloaded earlier from the MeshCore web flasher, update will start as soon as you tap the file
600-
601-
![Android nRF FW Updating](https://github.com/user-attachments/assets/0814d123-85ce-4c87-90a7-e1a25dc71900)
602-
603-
9. When the update process is done, the device will disconnect from nRF app and the LoRa device is updated
555+
1. Download nRF's DFU app from iOS App Store or Android's Play Store, you can find the app by searching for `nrf dfu`, the app's full name is `nRF Device Firmware Update`
556+
2. On flasher.meshcore.co.uk, download the **ZIP** version of the firmware for your nRF device (e.g. RAK or Heltec T114 or Seeed Studio's Xiao)
557+
3. From the MeshCore app, login remotely to the repeater you want to update with admin priviledge
558+
4. Go to the Command Line tab, type `start ota` and hit enter.
559+
5. you should see `OK` to confirm the repeater device is now in OTA mode
560+
6. Run the DFU app,tab `Settings` on the top right corner
561+
7. Enable `Packets receipt notifications` and change `Number of Packets` to 10 for RAK, 8 for T114. 8 also works for RAK.
562+
8. Select the firmware zip file you downloaded
563+
9. Select the device you want to update. If the device you want to updat is not on the list, try enabling`OTA` on the device again
564+
10. Tab the `Upload` to begin OTA update
565+
11. If it fails, try turning off and on Bluetooth on your phone. If that doesn't work, try rebooting your phone.
566+
12. Wait for the update to complete. It can take a few minutes.
604567

605568

606569
---
607-

‎docs/payloads.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Meshcore payloads
2+
Inside of each [meshcore packet](./packet_structure.md) is a payload, identified by the payload type in the packet header. The types of payloads are:
3+
4+
* Request (destination/source hashes + MAC).
5+
* Response to REQ or ANON_REQ.
6+
* Plain text message.
7+
* Acknowledgment.
8+
* Node advertisement.
9+
* Group text message (unverified).
10+
* Group datagram (unverified).
11+
* Anonymous request.
12+
* Returned path.
13+
* Custom packet (raw bytes, custom encryption).
14+
15+
This document defines the structure of each of these payload types
16+
17+
# Node advertisement
18+
This kind of payload notifies receivers that a node exists, and gives information about the node
19+
20+
| Field | Size (bytes) | Description |
21+
|---------------|-----------------|----------------------------------------------------------|
22+
| public key | 32 | Ed25519 public key |
23+
| timestamp | 4 | unix timestamp of advertisement |
24+
| signature | 64 | Ed25519 signature of public key, timestamp, and app data |
25+
| appdata | rest of payload | optional, see below |
26+
27+
Appdata
28+
29+
| Field | Size (bytes) | Description |
30+
|---------------|-----------------|-------------------------------------------------------|
31+
| flags | 1 | specifies which of the fields are present, see below |
32+
| latitude | 4 | decimal latitude multiplied by 1000000, integer |
33+
| longitude | 4 | decimal longitude multiplied by 1000000, integer |
34+
| feature 1 | 2 | reserved for future use |
35+
| feature 2 | 2 | reserved for future use |
36+
| name | rest of appdata | name of the node |
37+
38+
Appdata Flags
39+
40+
| Value | Name | Description |
41+
|--------|-----------|---------------------------------------|
42+
| `0x10` | location | appdata contains lat/long information |
43+
| `0x20` | feature 1 | Reserved for future use. |
44+
| `0x40` | feature 2 | Reserved for future use. |
45+
| `0x80` | name | appdata contains a node name |
46+
47+
# Acknowledgement
48+
| Field | Size (bytes) | Description |
49+
|----------|--------------|------------------------------------------------------------|
50+
| checksum | 4 | CRC checksum of message timestamp, text, and sender pubkey |
51+
52+
53+
# Returned path, request, response, and plain text message
54+
| Field | Size (bytes) | Description |
55+
|------------------|-----------------|------------------------------------------------------|
56+
| destination hash | 1 | first byte of destination node public key |
57+
| source hash | 1 | first byte of source node public key |
58+
| cipher MAC | 2 | MAC for encrypted data in next field |
59+
| ciphertext | rest of payload | encrypted message, see subsections below for details |
60+
61+
## Returned path
62+
63+
| Field | Size (bytes) | Description |
64+
|-------------|--------------|----------------------------------------------------------------------------------------------|
65+
| path length | 1 | length of next field |
66+
| path | see above | a list of node hashes (one byte each) describing the route from us to the packet author |
67+
| extra type | 1 | extra, bundled payload type, eg., acknowledgement or response. See packet structure spec |
68+
| extra | rest of data | extra, bundled payload content, follows same format as main content defined by this document |
69+
70+
## Request
71+
72+
| Field | Size (bytes) | Description |
73+
|--------------|-----------------|----------------------------|
74+
| timestamp | 4 | send time (unix timestamp) |
75+
| request type | 1 | see below |
76+
| request data | rest of payload | depends on request type |
77+
78+
Request type
79+
80+
| Value | Name | Description |
81+
|--------|--------------------|---------------------------------------|
82+
| `0x01` | get status | get status of repeater or room server |
83+
| `0x02` | keepalive | TODO |
84+
| `0x03` | get telemetry data | TODO |
85+
86+
### Get status
87+
88+
Gets information about the node, possibly including the following:
89+
90+
* Battery level (millivolts)
91+
* Current transmit queue length
92+
* Current free queue length
93+
* Last RSSI value
94+
* Number of received packets
95+
* Number of sent packets
96+
* Total airtime (seconds)
97+
* Total uptime (seconds)
98+
* Number of packets sent as flood
99+
* Number of packets sent directly
100+
* Number of packets received as flood
101+
* Number of packets received directly
102+
* Error flags
103+
* Last SNR value
104+
* Number of direct route duplicates
105+
* Number of flood route duplicates
106+
* Number posted (?)
107+
* Number of post pushes (?)
108+
109+
### Keepalive
110+
111+
No-op request.
112+
113+
### Get telemetry data
114+
115+
Request data about sensors on the node, including battery level.
116+
117+
## Response
118+
119+
| Field | Size (bytes) | Description |
120+
|---------|-----------------|-------------|
121+
| tag | 4 | TODO |
122+
| content | rest of payload | TODO |
123+
124+
## Plain text message
125+
126+
| Field | Size (bytes) | Description |
127+
|--------------|-----------------|--------------------------------------------------------------|
128+
| timestamp | 4 | send time (unix timestamp) |
129+
| flags + TODO | 1 | first six bits are flags (see below), last two bits are TODO |
130+
| message | rest of payload | the message content, see next table |
131+
132+
Flags
133+
134+
| Value | Description | Message content |
135+
|--------|---------------------------|------------------------------------------------------------|
136+
| `0x00` | plain text message | the plain text of the message |
137+
| `0x01` | CLI command | the command text of the message |
138+
| `0x02` | signed plain text message | two bytes of sender prefix, followed by plain text message |
139+
140+
# Anonymous request
141+
142+
| Field | Size (bytes) | Description |
143+
|------------------|-----------------|-------------------------------------------|
144+
| destination hash | 1 | first byte of destination node public key |
145+
| public key | 32 | sender's Ed25519 public key |
146+
| cipher MAC | 2 | MAC for encrypted data in next field |
147+
| ciphertext | rest of payload | encrypted message, see below for details |
148+
149+
Plaintext message
150+
151+
| Field | Size (bytes) | Description |
152+
|----------------|-----------------|-------------------------------------------------------------------------------|
153+
| timestamp | 4 | send time (unix timestamp) |
154+
| sync timestamp | 4 | for room server, otherwise absent: sender's "sync messages SINCE x" timestamp |
155+
| password | rest of message | password for repeater/room |
156+
157+
# Group text message / datagram
158+
159+
| Field | Size (bytes) | Description |
160+
|--------------|-----------------|------------------------------------------|
161+
| channel hash | 1 | TODO |
162+
| cipher MAC | 2 | MAC for encrypted data in next field |
163+
| ciphertext | rest of payload | encrypted message, see below for details |
164+
165+
Plaintext for text message
166+
167+
| Field | Size (bytes) | Description |
168+
|-----------|-----------------|----------------------------------|
169+
| timestamp | 4 | send time (unix timestamp) |
170+
| content | rest of message | plain group text message content |
171+
172+
TODO: describe what datagram looks like
173+
174+
# Custom packet
175+
176+
Custom packets have no defined format.

‎logo/meshcore.afdesign‎

20 KB
Binary file not shown.

‎logo/meshcore.png‎

12.2 KB
Loading

0 commit comments

Comments
 (0)