From 24ef375fc764ee8ed5c97ceccb022dcbb19b9b34 Mon Sep 17 00:00:00 2001 From: Haylin Moore Date: Thu, 14 Aug 2025 15:51:02 -0700 Subject: [PATCH 01/16] default.nix: add python3 to the shell There are many systems that chose to not have a global python install, namely my own systems :p. I end up having to nix-shell -p python3 anytime I want to run the build.sh as the last step uf2conv depends on python --- default.nix | 1 + 1 file changed, 1 insertion(+) diff --git a/default.nix b/default.nix index 828c0ee8..4f9e1c59 100644 --- a/default.nix +++ b/default.nix @@ -4,6 +4,7 @@ in pkgs.mkShell { buildInputs = [ pkgs.platformio + pkgs.python3 # optional: needed as a programmer i.e. for esp32 pkgs.avrdude ]; From f462113f4c442148924f924a7b61ab54f3291a05 Mon Sep 17 00:00:00 2001 From: uncle lit <43320854+LitBomb@users.noreply.github.com> Date: Wed, 20 Aug 2025 12:20:06 -0700 Subject: [PATCH 02/16] Update faq.md updated .mp3 file list for sound customization on t-deck added instruction to take a screenshot on t-deck Added link to MeshCore Ultra firmware user guide update github link from /meshcore to /meshcore-dev Update current hardware list to point to flasher.meshcore.co.uk --- docs/faq.md | 106 +++++++++++++++++++++++++++++++--------------------- 1 file changed, 63 insertions(+), 43 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 6dc8fe9e..c3a29462 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,7 +1,7 @@ **MeshCore-FAQ** A list of frequently-asked questions and answers for MeshCore -The current version of this MeshCore FAQ is at https://github.com/ripplebiz/MeshCore/blob/main/docs/faq.md. +The current version of this MeshCore FAQ is at https://github.com/meshcore-dev/MeshCore/blob/main/docs/faq.md. This MeshCore FAQ is also mirrored at https://github.com/LitBomb/MeshCore-FAQ and might have newer updates if pull requests on Scott's MeshCore repo are not approved yet. author: https://github.com/LitBomb @@ -27,18 +27,20 @@ author: https://github.com/LitBomb - [3.3. Q: What is the password to administer a repeater or a room server?](#33-q-what-is-the-password-to-administer-a-repeater-or-a-room-server) - [3.4. Q: What is the password to join a room server?](#34-q-what-is-the-password-to-join-a-room-server) - [4. T-Deck Related](#4-t-deck-related) - - [4.1. Q: What are the steps to get a T-Deck into DFU (Device Firmware Update) mode?](#41-q-what-are-the-steps-to-get-a-t-deck-into-dfu-device-firmware-update-mode) - - [4.2. Q: Why is my T-Deck Plus not getting any satellite lock?](#42-q-why-is-my-t-deck-plus-not-getting-any-satellite-lock) - - [4.3. Q: Why is my OG (non-Plus) T-Deck not getting any satellite lock?](#43-q-why-is-my-og-non-plus-t-deck-not-getting-any-satellite-lock) - - [4.4. Q: What size of SD card does the T-Deck support?](#44-q-what-size-of-sd-card-does-the-t-deck-support) - - [4.5. Q: What is the public key for the default public channel?](#45-q-what-is-the-public-key-for-the-default-public-channel) - - [4.6. Q: How do I get maps on T-Deck?](#46-q-how-do-i-get-maps-on-t-deck) - - [4.7. Q: Where do the map tiles go?](#47-q-where-do-the-map-tiles-go) - - [4.8. Q: How to unlock deeper map zoom and server management features on T-Deck?](#48-q-how-to-unlock-deeper-map-zoom-and-server-management-features-on-t-deck) - - [4.9. Q: How to decipher the diagnostics screen on T-Deck?](#49-q-how-to-decipher-the-diagnostics-screen-on-t-deck) - - [4.10. Q: The T-Deck sound is too loud?](#410-q-the-t-deck-sound-is-too-loud) - - [4.11. Q: Can you customize the sound?](#411-q-can-you-customize-the-sound) - - [4.12. Q: What is the 'Import from Clipboard' feature on the t-deck and is there a way to manually add nodes without having to receive adverts?](#412-q-what-is-the-import-from-clipboard-feature-on-the-t-deck-and-is-there-a-way-to-manually-add-nodes-without-having-to-receive-adverts) + - [4.1. Q: Is there a user guide for T-Deck, T-Pager, T-Watch, or T-Display Pro?](#41-q-is-there-a-user-guide-for-t-deck-t-pager-t-watch-or-t-display-pro) + - [4.2. Q: What are the steps to get a T-Deck into DFU (Device Firmware Update) mode?](#42-q-what-are-the-steps-to-get-a-t-deck-into-dfu-device-firmware-update-mode) + - [4.3. Q: Why is my T-Deck Plus not getting any satellite lock?](#43-q-why-is-my-t-deck-plus-not-getting-any-satellite-lock) + - [4.4. Q: Why is my OG (non-Plus) T-Deck not getting any satellite lock?](#44-q-why-is-my-og-non-plus-t-deck-not-getting-any-satellite-lock) + - [4.5. Q: What size of SD card does the T-Deck support?](#45-q-what-size-of-sd-card-does-the-t-deck-support) + - [4.6. Q: what is the public key for the default public channel?](#46-q-what-is-the-public-key-for-the-default-public-channel) + - [4.7. Q: How do I get maps on T-Deck?](#47-q-how-do-i-get-maps-on-t-deck) + - [4.8. Q: Where do the map tiles go?](#48-q-where-do-the-map-tiles-go) + - [4.9. Q: How to unlock deeper map zoom and server management features on T-Deck?](#49-q-how-to-unlock-deeper-map-zoom-and-server-management-features-on-t-deck) + - [4.10. Q: How to decipher the diagnostics screen on T-Deck?](#410-q-how-to-decipher-the-diagnostics-screen-on-t-deck) + - [4.11. Q: The T-Deck sound is too loud?](#411-q-the-t-deck-sound-is-too-loud) + - [4.12. Q: Can you customize the sound?](#412-q-can-you-customize-the-sound) + - [4.13. Q: What is the 'Import from Clipboard' feature on the t-deck and is there a way to manually add nodes without having to receive adverts?](#413-q-what-is-the-import-from-clipboard-feature-on-the-t-deck-and-is-there-a-way-to-manually-add-nodes-without-having-to-receive-adverts) + - [4.14. Q: How to capture a screenshot on T-Deck?](#414-q-how-to-capture-a-screenshot-on-t-deck) - [5. General](#5-general) - [5.1. Q: What are BW, SF, and CR?](#51-q-what-are-bw-sf-and-cr) - [5.2. Q: Do MeshCore clients repeat?](#52-q-do-meshcore-clients-repeat) @@ -68,10 +70,10 @@ author: https://github.com/LitBomb - [6.6. Q: My RAK/T1000-E/xiao\_nRF52 device seems to be corrupted, how do I wipe it clean to start fresh?](#66-q-my-rakt1000-exiao_nrf52-device-seems-to-be-corrupted-how-do-i-wipe-it-clean-to-start-fresh) - [6.7. Q: WebFlasher fails on Linux with failed to open](#67-q-webflasher-fails-on-linux-with-failed-to-open) - [7. Other Questions:](#7-other-questions) - - [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) - - [7.2 Q: How to update ESP32-based devices over the air?](#72-q-how-to-update-esp32-based-devices-over-the-air) - - [7.3 Q: Is there a way to lower the chance of a failed OTA device firmware update (DFU)?](#73-q-is-there-a-way-to-lower-the-chance-of-a-failed-ota-device-firmware-update-dfu) - - [7.4 Q are the MeshCore logo and font available?](#74-q-are-the-meshcore-logo-and-font-available) + - [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) + - [7.2. Q: How to update ESP32-based devices over the air?](#72-q-how-to-update-esp32-based-devices-over-the-air) + - [7.3. Q: Is there a way to lower the chance of a failed OTA device firmware update (DFU)?](#73-q-is-there-a-way-to-lower-the-chance-of-a-failed-ota-device-firmware-update-dfu) + - [7.4. Q are the MeshCore logo and font available?](#74-q-are-the-meshcore-logo-and-font-available) ## 1. Introduction @@ -105,9 +107,11 @@ Anyone is able to build anything they like on top of MeshCore without paying any You need LoRa hardware devices to run MeshCore firmware as clients or server (repeater and room server). #### 1.2.1. Hardware -To use MeshCore without using a phone as the client interface, you can run MeshCore on a T-Deck or T-Deck Plus. It is a complete off-grid secure communication solution. +MeshCore is available on a variety of 433MHz, 868MHz and 915MHz LoRa devices. For example, Lilygo T-Deck, T-Pager, RAK Wireless WisBlock RAK4631 devices (e.g. 19003, 19007, 19026), Heltec V3, Xiao S3 WIO, Xiao C3, Heltec T114, Station G2, Nano G2 Ultra, Seeed Studio T1000-E. More devices are being added regularly. -MeshCore is also available on a variety of 868MHz and 915MHz LoRa devices. For example, RAK4631 devices (19003, 19007, 19026), Heltec V3, Xiao S3 WIO, Xiao C3, Heltec T114, Station G2, Seeed Studio T1000-E. More devices will be supported later. +For an up-to-date list of supported devices, please go to https://flasher.meshcore.co.uk/ + +To use MeshCore without using a phone as the client interface, you can run MeshCore on a LiLygo's T-Deck, T-Deck Plus, T-Pager, T-Watch, or T-Display Pro. MeshCore Ultra firmware running on these devices are a complete off-grid secure communication solution. #### 1.2.2. Firmware MeshCore has four firmware types that are not available on other LoRa systems. MeshCore has the following: @@ -116,7 +120,7 @@ MeshCore has four firmware types that are not available on other LoRa systems. M Companion radios are for connecting to the Android app or web app as a messenger client. There are two different companion radio firmware versions: 1. **BLE Companion** - BLE Companion firmware runs on a supported LoRa device and connects to a smart device running the Android MeshCore client over BLE (iOS MeshCore client will be available soon) + BLE Companion firmware runs on a supported LoRa device and connects to a smart device running the Android or iOS MeshCore client over BLE 2. **USB Serial Companion** @@ -147,7 +151,7 @@ A room server can also take on the repeater role. To enable repeater role on a ## 2. Initial Setup ### 2.1. Q: How many devices do I need to start using MeshCore? -**A:** If you have one supported device, flash the BLE Companion firmware and use your device as a client. You can connect to the device using the Android client via Bluetooth (iOS client will be available later). You can start communicating with other MeshCore users near you. +**A:** If you have one supported device, flash the BLE Companion firmware and use your device as a client. You can connect to the device using the Android or iOS client via Bluetooth. You can start communicating with other MeshCore users near you. If you have two supported devices, and there are not many MeshCore users near you, flash both to BLE Companion firmware so you can use your devices to communicate with your near-by friends and family. @@ -157,7 +161,7 @@ After you flashed the latest firmware onto your repeater device, keep the device `set freq {frequency}` -The repeater and room server CLI reference is here: https://github.com/ripplebiz/MeshCore/wiki/Repeater-&-Room-Server-CLI-Reference +The repeater and room server CLI reference is here: https://github.com/meshcore-dev/MeshCore/wiki/Repeater-&-Room-Server-CLI-Reference If you have more supported devices, you can use your additional devices with the room server firmware. @@ -255,7 +259,11 @@ You can get the latitude and longitude from Google Maps by right-clicking the lo ## 4. T-Deck Related -### 4.1. Q: What are the steps to get a T-Deck into DFU (Device Firmware Update) mode? +### 4.1. Q: Is there a user guide for T-Deck, T-Pager, T-Watch, or T-Display Pro? + +**A:** Yes, it is available on https://buymeacoffee.com/ripplebiz/ultra-v7-7-guide-meshcore-users + +### 4.2. Q: What are the steps to get a T-Deck into DFU (Device Firmware Update) mode? **A:** 1. Device off 2. Connect USB cable to device @@ -266,20 +274,20 @@ You can get the latitude and longitude from Google Maps by right-clicking the lo 7. T-Deck in DFU mode now 8. At this point you can begin flashing using -### 4.2. Q: Why is my T-Deck Plus not getting any satellite lock? +### 4.3. Q: Why is my T-Deck Plus not getting any satellite lock? **A:** For T-Deck Plus, the GPS baud rate should be set to **38400**. Also, some T-Deck Plus devices were found to have the GPS module installed upside down, with the GPS antenna facing down instead of up. If your T-Deck Plus still doesn't get any satellite lock after setting the baud rate to 38400, you might need to open the device to check the GPS orientation. GPS on T-Deck is always enabled. You can skip the "GPS clock sync" and the T-Deck will continue to try to get a GPS lock. You can go to the `GPS Info` screen; you should see the `Sentences:` counter increasing if the baud rate is correct. [Source](https://discord.com/channels/826570251612323860/1330643963501351004/1356609240302616689) -### 4.3. Q: Why is my OG (non-Plus) T-Deck not getting any satellite lock? +### 4.4. Q: Why is my OG (non-Plus) T-Deck not getting any satellite lock? **A:** The OG (non-Plus) T-Deck doesn't come with a GPS. If you added a GPS to your OG T-Deck, please refer to the manual of your GPS to see what baud rate it requires. Alternatively, you can try to set the baud rate from 9600, 19200, etc., and up to 115200 to see which one works. -### 4.4. Q: What size of SD card does the T-Deck support? +### 4.5. Q: What size of SD card does the T-Deck support? **A:** Users have had no issues using 16GB or 32GB SD cards. Format the SD card to **FAT32**. -### 4.5. Q: what is the public key for the default public channel? +### 4.6. Q: what is the public key for the default public channel? **A:** T-Deck uses the same key the smartphone apps use but in base64 `izOH6cXN6mrJ5e26oRXNcg==` @@ -290,7 +298,7 @@ The smartphone app key is in hex: [Source](https://discord.com/channels/826570251612323860/1330643963501351004/1354194409213792388) -### 4.6. Q: How do I get maps on T-Deck? +### 4.7. Q: How do I get maps on T-Deck? **A:** You need map tiles. You can get pre-downloaded map tiles here (a good way to support development): - (Europe) - (US) @@ -304,19 +312,20 @@ There is also a modified script that adds additional error handling and parallel UK map tiles are available separately from Andy Kirby on his discord server: -### 4.7. Q: Where do the map tiles go? +### 4.8. Q: Where do the map tiles go? Once you have the tiles downloaded, copy the `\tiles` folder to the root of your T-Deck's SD card. -### 4.8. Q: How to unlock deeper map zoom and server management features on T-Deck? +### 4.9. Q: How to unlock deeper map zoom and server management features on T-Deck? **A:** You can download, install, and use the T-Deck firmware for free, but it has some features (map zoom, server administration) that are enabled if you purchase an unlock code for \$10 per T-Deck device. Unlock page: -### 4.9. Q: How to decipher the diagnostics screen on T-Deck? +### 4.10. Q: How to decipher the diagnostics screen on T-Deck? **A: ** Space is tight on T-Deck's screen, so the information is a bit cryptic. The format is : `{hops} l:{packet-length}({payload-len}) t:{packet-type} snr:{n} rssi:{n}` -See here for packet-type: [https://github.com/ripplebiz/MeshCore/blob/main/src/Packet.h#L19](https://github.com/ripplebiz/MeshCore/blob/main/src/Packet.h#L19 "https://github.com/ripplebiz/MeshCore/blob/main/src/Packet.h#L19") +See here for packet-type: +https://github.com/meshcore-dev/MeshCore/blob/main/src/Packet.h#L19 #define PAYLOAD_TYPE_REQ 0x00 // request (prefixed with dest/src hashes, MAC) (enc data: timestamp, blob) @@ -330,15 +339,25 @@ See here for packet-type: [https://github.com/ripplebiz/MeshCore/blob/main/src/P [Source](https://discord.com/channels/1343693475589263471/1343693475589263474/1350611321040932966) -### 4.10. Q: The T-Deck sound is too loud? -### 4.11. Q: Can you customize the sound? +### 4.11. Q: The T-Deck sound is too loud? +### 4.12. Q: Can you customize the sound? -**A:** You can customise the sounds on the T-Deck, just by placing `.mp3` files onto the `root` dir of the SD card. `startup.mp3`, `alert.mp3` and `new-advert.mp3` +**A:** You can customise the sounds on the T-Deck, by placing `.mp3` files onto the `root` dir of the SD card. The files are: -### 4.12. Q: What is the 'Import from Clipboard' feature on the t-deck and is there a way to manually add nodes without having to receive adverts? +* `startup.mp3` +* `error.mp3` +* `alert.mp3` +* `new-advert.mp3` +* `existing-advert.mp3` + +### 4.13. Q: What is the 'Import from Clipboard' feature on the t-deck and is there a way to manually add nodes without having to receive adverts? **A:** 'Import from Clipboard' is for importing a contact via a file named 'clipboard.txt' on the SD card. The opposite, is in the Identity screen, the 'Card to Clipboard' menu, which writes to 'clipboard.txt' so you can share yourself (call these 'biz cards', that start with "meshcore://...") +### 4.14. Q: How to capture a screenshot on T-Deck? + +**A:** To capture a screenshot on a T-Deck, long press the top-left corner of the screen. The screenshot is saved to the microSD card, if one is inserted into the device. + --- ## 5. General @@ -393,7 +412,7 @@ The third character is the capital letter 'O', not zero `0` ### 5.7. Q: Is MeshCore open source? **A:** Most of the firmware is freely available. Everything is open source except the T-Deck firmware and Liam's native mobile apps. -- Firmware repo: +- Firmware repo: https://github.com/meshcore-dev/MeshCore ### 5.8. Q: How can I support MeshCore? **A:** Provide your honest feedback on GitHub and on [MeshCore Discord server](https://discord.gg/BMwCtwHj5V). Spread the word of MeshCore to your friends and communities; help them get started with MeshCore. Support Scott's MeshCore development at . @@ -521,7 +540,7 @@ To start managing your USB serial-connected device using picocom, use the follow - `picocom -b 115200 /dev/ttyUSB0 --imap lfcrlf` From here, reference repeater and room server command line commands on MeshCore github wiki here: - - https://github.com/ripplebiz/MeshCore/wiki/Repeater-&-Room-Server-CLI-Reference + - https://github.com/meshcore-dev/MeshCore/wiki/Repeater-&-Room-Server-CLI-Reference ### 5.14. Q: Are there are projects built around MeshCore? @@ -603,7 +622,7 @@ Allow the browser user on it: --- ## 7. Other Questions: -### 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? +### 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? **A:** The steps below work on both Android and iOS as nRF has made both apps' user interface the same on both platforms: @@ -622,7 +641,7 @@ Allow the browser user on it: 14. Wait for the update to complete. It can take a few minutes. -### 7.2 Q: How to update ESP32-based devices over the air? +### 7.2. Q: How to update ESP32-based devices over the air? **A:** For ESP32-based devices (e.g. Heltec V3): 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) @@ -634,7 +653,7 @@ Allow the browser user on it: 8. From a browser, go to http://192.168.4.1/update and upload the non-merged bin from the flasher -### 7.3 Q: Is there a way to lower the chance of a failed OTA device firmware update (DFU)? +### 7.3. Q: Is there a way to lower the chance of a failed OTA device firmware update (DFU)? **A:** Yes, developer `che aporeps` has an enhanced OTA DFU bootloader for nRF52 based devices. With this bootloader, if it detects that the application firmware is invalid, it falls back to OTA DFU mode so you can attempt to flash again to recover. This bootloader has other changes to make the OTA DFU process more fault tolerant. @@ -646,9 +665,10 @@ Currently, the following boards are supported: - Seeed Studio XIAO nRF52840 BLE SENSE - RAK 4631 -### 7.4 Q are the MeshCore logo and font available? +### 7.4. Q are the MeshCore logo and font available? -**A:** Yes, it is on the MeshCore github repo here: https://github.com/ripplebiz/MeshCore/tree/main/logo +**A:** Yes, it is on the MeshCore github repo here: +https://github.com/meshcore-dev/MeshCore/tree/main/logo --- From 82184c583635db7769af476a75fc22a4fc5fcd52 Mon Sep 17 00:00:00 2001 From: uncle lit <43320854+LitBomb@users.noreply.github.com> Date: Wed, 20 Aug 2025 22:08:19 -0700 Subject: [PATCH 03/16] Update faq.md update verbiage on room server's repeat functionality to discourage turning repeat on on room server. Update repeater flood advert to 3 hours and mentioning pending PR to change that to 12 hours. --- docs/faq.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index c3a29462..8f099bb7 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -142,9 +142,11 @@ A room server can be remotely administered using a T-Deck running the MeshCore f When a client logs into a room server, the client will receive the previously 32 unseen messages. -A room server can also take on the repeater role. To enable repeater role on a room server, use this command: +Although room server can also repeat with the command line command `set repeat on`, it is not recommended nor encouraged. A room server with repeat set to `on` lacks the full set of repeater and remote administration features that are only available in the repeater firmware. + +The recommendation is to run repeater and room server on separate devices for the best experience. + -`set repeat {on|off}` --- @@ -201,10 +203,12 @@ MeshCore allows you to manually broadcast your name, position and public encrypt * Zero hop means your advert is broadcasted out to anyone that can hear it, and that's it. * Flooded means it's broadcasted out and then repeated by all the repeaters that hear it. -MeshCore clients only advertise themselves when the user initiates it. A repeater (and room server?) advertises its presence once every 240 minutes. This interval can be configured using the following command: +MeshCore clients only advertise themselves when the user initiates it. A repeater sends a flood advert once every 3 hours by default. This interval can be configured using the following command: `set advert.interval {minutes}` +As of Aug 20 2025, a pending PR on github will change the flood advert to 12 hours to minimize airtime utilization caused by repeaters' flood adverts. + ### 2.5. Q: Is there a hop limit? **A:** Internally the firmware has maximum limit of 64 hops. In real world settings it will be difficult to get close to the limit due to the environments and timing as packets travel further and further. We want to hear how far your MeshCore conversations go. From 02ad2bed4d194036cf94041afb56651190dcb6d9 Mon Sep 17 00:00:00 2001 From: uncle lit <43320854+LitBomb@users.noreply.github.com> Date: Mon, 25 Aug 2025 17:20:13 -0700 Subject: [PATCH 04/16] Update faq.md update instruction to add a node to the Internet Map from the app, and note that you can use the same companion radio to remove the nodes you added previously add channel and contact QR code URL format --- docs/faq.md | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 8f099bb7..9f176d36 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -73,7 +73,8 @@ author: https://github.com/LitBomb - [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) - [7.2. Q: How to update ESP32-based devices over the air?](#72-q-how-to-update-esp32-based-devices-over-the-air) - [7.3. Q: Is there a way to lower the chance of a failed OTA device firmware update (DFU)?](#73-q-is-there-a-way-to-lower-the-chance-of-a-failed-ota-device-firmware-update-dfu) - - [7.4. Q are the MeshCore logo and font available?](#74-q-are-the-meshcore-logo-and-font-available) + - [7.4. Q: are the MeshCore logo and font available?](#74-q-are-the-meshcore-logo-and-font-available) + - [7.5. Q: What is the format of a contact or channel QR code?](#75-q-what-is-the-format-of-a-contact-or-channel-qr-code) ## 1. Introduction @@ -480,10 +481,14 @@ This could change in the future if MeshCore develops a client firmware that repe [Source](https://discord.com/channels/826570251612323860/1330643963501351004/1354780032140054659) ### 5.12. Q: How do I add a node to the [MeshCore Map]([url](https://meshcore.co.uk/map.html)) -**A:** From the smartphone app, connect to a BLE Companion radio -- To add the BLE Companion radio your smartphone is connected to to the map, tap the `advert` icon, then tap `Advert (To Clipboard)`. -- To add a Repeater or Room Server to the map, tap the 3 dots next to the Repeater or Room Server you want to add to the map, then tap `Share (To Clipboard)`. -- Go to the [MeshCore Map web site]([url](https://meshcore.co.uk/map.html)), tap the plus sign on the lower right corner and paste in the meshcore://... blob, then tap `Add Node` +**A:** + +To add a BLE Companion radio, connect to the BLE Companion radio from the MeshCore smartphone app. In the app, tap the `3 dot` menu icon at the top right corner, then tap `Internet Map`. Tap the `3 dot` menu icon again and choose `Add me to the Map` + +To add a Repeater or Room Server to the map, go to the Contact List, tap the `3 dot` next to the Repeater or Room Server you want to add to the Internet Map, tap `Share`, then tap `Upload to Internet Map`. + +You can use the same companion (same public key) that you used to add your repeaters or room servers to remove them from the Internet Map. + ### 5.13. Q: Can I use a Raspberry Pi to update a MeshCore radio? ** A:** Yes. @@ -669,10 +674,25 @@ Currently, the following boards are supported: - Seeed Studio XIAO nRF52840 BLE SENSE - RAK 4631 -### 7.4. Q are the MeshCore logo and font available? +### 7.4. Q: are the MeshCore logo and font available? **A:** Yes, it is on the MeshCore github repo here: https://github.com/meshcore-dev/MeshCore/tree/main/logo +### 7.5. Q: What is the format of a contact or channel QR code? + +**A:** +Channel: +`meshcore://channel/add?name=&secret=` + +Contact: +`meshcore://contact/add?name=&public_key=&type=` + +where `&type` is: +`chat = 1` +`repeater = 2` +`room = 3` +`sensor = 4` + --- From b3adaa790abfb47c483d7877413eda5269a6cea0 Mon Sep 17 00:00:00 2001 From: Matthias Wientapper Date: Sat, 30 Aug 2025 20:53:57 +0200 Subject: [PATCH 05/16] Update faq.md --- docs/faq.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/faq.md b/docs/faq.md index 9f176d36..09e83c29 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -75,6 +75,7 @@ author: https://github.com/LitBomb - [7.3. Q: Is there a way to lower the chance of a failed OTA device firmware update (DFU)?](#73-q-is-there-a-way-to-lower-the-chance-of-a-failed-ota-device-firmware-update-dfu) - [7.4. Q: are the MeshCore logo and font available?](#74-q-are-the-meshcore-logo-and-font-available) - [7.5. Q: What is the format of a contact or channel QR code?](#75-q-what-is-the-format-of-a-contact-or-channel-qr-code) + - [7.6. Q: How do I connect to the comnpanion via WIFI, e.g. using a heltec v3?](#76-q-how-do-i-connect-to-the-comnpanion-via-wifi-eg-using-a-heltec-v3) ## 1. Introduction @@ -694,5 +695,9 @@ where `&type` is: `room = 3` `sensor = 4` +### 7.6. Q: How do I connect to the comnpanion via WIFI, e.g. using a heltec v3? + **A:** +WiFi firmware requires you to compile it yourself, as you need to set the wifi ssid and password. +Edit WIFI_SSID and WIFI_PWD in `./variants/heltec_v3/platformio.ini` and then flash it to your device. --- From f3c52d84dbd0b7e2c874933c1a23cba28e176caf Mon Sep 17 00:00:00 2001 From: ripplebiz Date: Mon, 1 Sep 2025 22:00:06 +1000 Subject: [PATCH 06/16] Update README.md --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index fa5b3cd0..179553b0 100644 --- a/README.md +++ b/README.md @@ -90,6 +90,15 @@ Here are some general principals you should try to adhere to: * No dynamic memory allocation, except during setup/begin functions. * 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) +## Road-Map / To-Do + +There are a number of fairly major feature features in the pipeline, with no particular time-frames attached yet. In very rough chronological order: +- [X] Companion radio: UI redesign +- [ ] Core: round-trip manual path support +- [ ] Companion + Apps: support for multiple sub-meshes (and 'off-grid' client repeat mode) +- [ ] Core: new framework for hosting multiple virtual nodes on one physical device +- [ ] V2 protocol spec: discussion and concensus around V2 packet protocol, including path hashes, new encryption specs, etc + ## 📞 Get Support - Report bugs and request features on the [GitHub Issues](https://github.com/ripplebiz/MeshCore/issues) page. From 4849b863e9fc7345b8ae1fa12a2c8b3cc27483f5 Mon Sep 17 00:00:00 2001 From: ripplebiz Date: Mon, 1 Sep 2025 22:07:36 +1000 Subject: [PATCH 07/16] Update README.md --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 179553b0..cc94bbef 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,7 @@ Here are some general principals you should try to adhere to: There are a number of fairly major feature features in the pipeline, with no particular time-frames attached yet. In very rough chronological order: - [X] Companion radio: UI redesign +- [ ] Core + Repeater: enhanced zero-hop neighbour discovery - [ ] Core: round-trip manual path support - [ ] Companion + Apps: support for multiple sub-meshes (and 'off-grid' client repeat mode) - [ ] Core: new framework for hosting multiple virtual nodes on one physical device From c3fb3bcefe94cc58919a3c50dbb8e6e00230c888 Mon Sep 17 00:00:00 2001 From: ripplebiz Date: Mon, 1 Sep 2025 22:14:21 +1000 Subject: [PATCH 08/16] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index cc94bbef..cef44e0e 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,7 @@ Here are some general principals you should try to adhere to: ## Road-Map / To-Do -There are a number of fairly major feature features in the pipeline, with no particular time-frames attached yet. In very rough chronological order: +There are a number of fairly major features in the pipeline, with no particular time-frames attached yet. In very rough chronological order: - [X] Companion radio: UI redesign - [ ] Core + Repeater: enhanced zero-hop neighbour discovery - [ ] Core: round-trip manual path support From b64e78b7eb4f5c5a7881e6f6095d53191e78b102 Mon Sep 17 00:00:00 2001 From: taco Date: Tue, 2 Sep 2025 08:06:43 +1000 Subject: [PATCH 09/16] fix: Heltec Vision Master E290: rename companion target --- variants/heltec_vision_master_e290/platformio.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/variants/heltec_vision_master_e290/platformio.ini b/variants/heltec_vision_master_e290/platformio.ini index 4150adc8..8ac01cfb 100644 --- a/variants/heltec_vision_master_e290/platformio.ini +++ b/variants/heltec_vision_master_e290/platformio.ini @@ -27,7 +27,7 @@ lib_deps = ${esp32_base.lib_deps} https://github.com/Quency-D/heltec-eink-modules/archive/563dd41fd850a1bc3039b8723da4f3a20fe1c800.zip -[env:Heltec_Vision_Master_E290_radio_ble] +[env:Heltec_Vision_Master_E290_companion_radio_ble] extends = Heltec_Vision_Master_E290_base build_flags = ${Heltec_Vision_Master_E290_base.build_flags} From 0dfd2bcbb89f8d7f250dd84887a394e603f039e5 Mon Sep 17 00:00:00 2001 From: Frieder Schrempf Date: Mon, 8 Sep 2025 22:57:48 +0200 Subject: [PATCH 10/16] README.md: Explain that companion nodes do not repeat messages This is a key difference compared to other systems and I see people asking this a lot. It is mentioned in the FAQ but let's make it more prominent in the README. --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index cef44e0e..c14f20fd 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,10 @@ MeshCore provides the ability to create wireless mesh networks, similar to Mesht ## ⚡ Key Features -* Multi-Hop Packet Routing – Devices can forward messages across multiple nodes, extending range beyond a single radio's reach. MeshCore supports up to a configurable number of hops to balance network efficiency and prevent excessive traffic. +* Multi-Hop Packet Routing + * Devices can forward messages across multiple nodes, extending range beyond a single radio's reach. + * Supports up to a configurable number of hops to balance network efficiency and prevent excessive traffic. + * Nodes use fixed roles where "Companion" nodes are not repeating messages at all to prevent adverse routing paths from being used. * Supports LoRa Radios – Works with Heltec, RAK Wireless, and other LoRa-based hardware. * Decentralized & Resilient – No central server or internet required; the network is self-healing. * Low Power Consumption – Ideal for battery-powered or solar-powered devices. From bb29b66b29c7f957d68600c343e8a53232aeb258 Mon Sep 17 00:00:00 2001 From: ripplebiz Date: Tue, 9 Sep 2025 14:05:07 +1000 Subject: [PATCH 11/16] Update README.md --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index cef44e0e..7d5186ec 100644 --- a/README.md +++ b/README.md @@ -94,9 +94,14 @@ Here are some general principals you should try to adhere to: There are a number of fairly major features in the pipeline, with no particular time-frames attached yet. In very rough chronological order: - [X] Companion radio: UI redesign +- [ ] Repeater + Room Server: add ACL's (like Sensor Node has) +- [ ] Standardise Bridge mode for repeaters +- [ ] Repeater/Bridge: Standardise the Transport Codes for zoning/filtering - [ ] Core + Repeater: enhanced zero-hop neighbour discovery - [ ] Core: round-trip manual path support - [ ] Companion + Apps: support for multiple sub-meshes (and 'off-grid' client repeat mode) +- [ ] Core + Apps: support for LZW message compression +- [ ] Core: dynamic CR (Coding Rate) for weak vs strong hops - [ ] Core: new framework for hosting multiple virtual nodes on one physical device - [ ] V2 protocol spec: discussion and concensus around V2 packet protocol, including path hashes, new encryption specs, etc From a6a0183d440152467675374161b0ec7f343c9740 Mon Sep 17 00:00:00 2001 From: Patrick <4002194+askpatrickw@users.noreply.github.com> Date: Sat, 13 Sep 2025 14:04:31 -0700 Subject: [PATCH 12/16] Update FAQ with new server administration screenshot --- docs/faq.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 09e83c29..4757896f 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -229,8 +229,7 @@ Repeater or room server can be administered with one of the options below: - After a repeater or room server firmware is flashed on to a LoRa device, go to and use the web user interface to connect to the LoRa device via USB serial. From there you can set the name of the server, its frequency and other related settings, location, passwords etc. -![image](https://github.com/user-attachments/assets/bec28ff3-a7d6-4a1e-8602-cb6b290dd150) - +image - Connect the server device using a USB cable to a computer running Chrome on https://flasher.meshcore.co.uk/, then use the `console` feature to connect to the device From 9b2dbf51cb28ffee875d1c63da9b2d80c6f1c636 Mon Sep 17 00:00:00 2001 From: Patrick <4002194+askpatrickw@users.noreply.github.com> Date: Sat, 13 Sep 2025 14:05:57 -0700 Subject: [PATCH 13/16] fix markdown --- docs/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faq.md b/docs/faq.md index 4757896f..78e31aa6 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -229,7 +229,7 @@ Repeater or room server can be administered with one of the options below: - After a repeater or room server firmware is flashed on to a LoRa device, go to and use the web user interface to connect to the LoRa device via USB serial. From there you can set the name of the server, its frequency and other related settings, location, passwords etc. -image +![image](https://github.com/user-attachments/assets/2a9d9894-e34d-4dbe-b57c-fc3c250a2d34) - Connect the server device using a USB cable to a computer running Chrome on https://flasher.meshcore.co.uk/, then use the `console` feature to connect to the device From 19fb7aae63130e848a0eee5a08d5777e9c901657 Mon Sep 17 00:00:00 2001 From: Wesley Ellis Date: Tue, 16 Sep 2025 18:15:14 -0400 Subject: [PATCH 14/16] Use python3 not python in build.sh Since the bin/uf2conv/uf2conf.py script uses python3, use python3 as the command instead of python. On my ubuntu 24.04 machine, I don't have a python command in my path by default --- build.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build.sh b/build.sh index 47fec4a3..5b091b5a 100755 --- a/build.sh +++ b/build.sh @@ -60,7 +60,7 @@ build_firmware() { # build .uf2 for nrf52 boards if [[ -f .pio/build/$1/firmware.zip && -f .pio/build/$1/firmware.hex ]]; then - python bin/uf2conv/uf2conv.py .pio/build/$1/firmware.hex -c -o .pio/build/$1/firmware.uf2 -f 0xADA52840 + python3 bin/uf2conv/uf2conv.py .pio/build/$1/firmware.hex -c -o .pio/build/$1/firmware.uf2 -f 0xADA52840 fi # copy .bin, .uf2, and .zip to out folder From adecd1e58d6fe13e3c01f908a088478bea830f7f Mon Sep 17 00:00:00 2001 From: silverphish-io Date: Mon, 22 Sep 2025 21:49:56 +0100 Subject: [PATCH 15/16] Updated some typos and spelling mistakes in FAQ --- docs/faq.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 78e31aa6..5ed1d2a5 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -75,7 +75,7 @@ author: https://github.com/LitBomb - [7.3. Q: Is there a way to lower the chance of a failed OTA device firmware update (DFU)?](#73-q-is-there-a-way-to-lower-the-chance-of-a-failed-ota-device-firmware-update-dfu) - [7.4. Q: are the MeshCore logo and font available?](#74-q-are-the-meshcore-logo-and-font-available) - [7.5. Q: What is the format of a contact or channel QR code?](#75-q-what-is-the-format-of-a-contact-or-channel-qr-code) - - [7.6. Q: How do I connect to the comnpanion via WIFI, e.g. using a heltec v3?](#76-q-how-do-i-connect-to-the-comnpanion-via-wifi-eg-using-a-heltec-v3) + - [7.6. Q: How do I connect to the companion via WIFI, e.g. using a heltec v3?](#76-q-how-do-i-connect-to-the-comnpanion-via-wifi-eg-using-a-heltec-v3) ## 1. Introduction @@ -101,7 +101,7 @@ Anyone is able to build anything they like on top of MeshCore without paying any Main web site: [https://meshcore.co.uk/](https://meshcore.co.uk/) Firmware Flasher: https://flasher.meshcore.co.uk/ Phone Client Applications: https://meshcore.co.uk/apps.html - MeshCore Fimrware GitHub: https://github.com/ripplebiz/MeshCore + MeshCore Firmware GitHub: https://github.com/ripplebiz/MeshCore NOTE: Andy Kirby has a very useful [intro video](https://www.youtube.com/watch?v=t1qne8uJBAc) for beginners. @@ -159,7 +159,7 @@ The recommendation is to run repeater and room server on separate devices for th If you have two supported devices, and there are not many MeshCore users near you, flash both to BLE Companion firmware so you can use your devices to communicate with your near-by friends and family. -If you have two supported devices, and there are other MeshcCore users nearby, you can flash one of your devices with BLE Companion firmware and flash another supported device to repeater firmware. Place the repeater high above ground to extend your MeshCore network's reach. +If you have two supported devices, and there are other MeshCore users nearby, you can flash one of your devices with BLE Companion firmware and flash another supported device to repeater firmware. Place the repeater high above ground to extend your MeshCore network's reach. After you flashed the latest firmware onto your repeater device, keep the device connected to your computer via USB serial, use the console feature on the web flasher and set the frequency for your region or country, so your client can remote administer the repeater or room server over RF: @@ -391,7 +391,7 @@ In MeshCore, only repeaters and room server with `set repeat on` repeat. **A:** If you used to reach a node through a repeater and the repeater is no longer reachable, the client will send the message using the existing (but now broken) known path, the message will fail after 3 retries, and the app will reset the path and send the message as flood on the last retry by default. This can be turned off in settings. If the destination is reachable directly or through another repeater, the new path will be used going forward. Or you can set the path manually if you know a specific repeater to use to reach that destination. -In the case if users are moving around frequently, and the paths are breaking, they just see the phone client retries and revert to flood to attempt to reestablish a path. +In the case if users are moving around frequently, and the paths are breaking, they just see the phone client retries and revert to flood to attempt to re-establish a path. ### 5.4. Q: How does a node discovery a path to its destination and then use it to send messages in the future, instead of flooding every message it sends like Meshtastic? @@ -463,7 +463,7 @@ Andy also has a video on how to build using VS Code: ### 5.10. Q: Are there other MeshCore related open source projects? -**A:** [Liam Cottle](https://liamcottle.net)'s MeshCore web client and MeshCore Javascript libary are open source under MIT license. +**A:** [Liam Cottle](https://liamcottle.net)'s MeshCore web client and MeshCore Javascript library are open source under MIT license. Web client: https://github.com/liamcottle/meshcore-web Javascript: https://github.com/liamcottle/meshcore.js @@ -471,7 +471,7 @@ Javascript: https://github.com/liamcottle/meshcore.js ### 5.11. Q: Does MeshCore support ATAK **A:** ATAK is not currently on MeshCore's roadmap. -Meshcore would not be best suited to ATAK because MeshCore: +Meshcore would not be best suited to ATAK because MeshCore: clients do not repeat and therefore you would need a network of repeaters in place will not have a stable path where all clients are constantly moving between repeaters @@ -569,7 +569,7 @@ Bindings to access your MeshCore companion radio nodes in python. https://github.com/fdlamotte/meshcore_py #### 5.14.4. meshcore-cli -CLI interface to MeshCore companion radio over BLE, TCP, or serial. Uses Pyton MeshCore above. +CLI interface to MeshCore companion radio over BLE, TCP, or serial. Uses Python MeshCore above. https://github.com/fdlamotte/meshcore-cli #### 5.14.5. meshcore.js @@ -637,13 +637,13 @@ Allow the browser user on it: 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` 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) -3. From the MeshCore app, login remotely to the repeater you want to update with admin priviledge +3. From the MeshCore app, login remotely to the repeater you want to update with admin privilege 4. Go to the Command Line tab, type `start ota` and hit enter. 5. you should see `OK` to confirm the repeater device is now in OTA mode 6. Run the DFU app,tab `Settings` on the top right corner 7. Enable `Packets receipt notifications`, and change `Number of Packets` to 10 for RAK, 8 for T114. 8 also works for RAK. 9. Select the firmware zip file you downloaded -10. 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 +10. Select the device you want to update. If the device you want to update is not on the list, try enabling`OTA` on the device again 11. If the device is not found, enable `Force Scanning` in the DFU app 12. Tab the `Upload` to begin OTA update 13. If it fails, try turning off and on Bluetooth on your phone. If that doesn't work, try rebooting your phone. @@ -654,7 +654,7 @@ Allow the browser user on it: **A:** For ESP32-based devices (e.g. Heltec V3): 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) -2. From the MeshCore app, login remotely to the repeater you want to update with admin priviledge +2. From the MeshCore app, login remotely to the repeater you want to update with admin privilege 4. Go to the Command Line tab, type `start ota` and hit enter. 5. you should see `OK` to confirm the repeater device is now in OTA mode 6. The command `start ota` on an ESP32-based device starts a wifi hotspot named `MeshCore OTA` @@ -694,7 +694,7 @@ where `&type` is: `room = 3` `sensor = 4` -### 7.6. Q: How do I connect to the comnpanion via WIFI, e.g. using a heltec v3? +### 7.6. Q: How do I connect to the companion via WIFI, e.g. using a heltec v3? **A:** WiFi firmware requires you to compile it yourself, as you need to set the wifi ssid and password. Edit WIFI_SSID and WIFI_PWD in `./variants/heltec_v3/platformio.ini` and then flash it to your device. From cc822c029b8176c3793726ce74b10ab7e25c52f7 Mon Sep 17 00:00:00 2001 From: David Hall Date: Sat, 27 Sep 2025 11:14:28 +0100 Subject: [PATCH 16/16] Create Xiao_S3_WIO_companion_radio_usb profile Create Xiao_S3_WIO_companion_radio_usb profile from Xiao_S3_WIO_companion_radio_ble profile --- variants/xiao_s3_wio/platformio.ini | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/variants/xiao_s3_wio/platformio.ini b/variants/xiao_s3_wio/platformio.ini index b4f25e53..8f163105 100644 --- a/variants/xiao_s3_wio/platformio.ini +++ b/variants/xiao_s3_wio/platformio.ini @@ -75,6 +75,28 @@ lib_deps = ${Xiao_S3_WIO.lib_deps} densaugeo/base64 @ ~1.4.0 +[env:Xiao_S3_WIO_companion_radio_usb] +extends = Xiao_S3_WIO +build_flags = + ${Xiao_S3_WIO.build_flags} + -I examples/companion_radio/ui-new + -D MAX_CONTACTS=300 + -D MAX_GROUP_CHANNELS=8 + -D DISPLAY_CLASS=SSD1306Display + -D OFFLINE_QUEUE_SIZE=256 +; -D MESH_PACKET_LOGGING=1 +; -D MESH_DEBUG=1 +build_src_filter = ${Xiao_S3_WIO.build_src_filter} + + + + + + + +<../examples/companion_radio/*.cpp> + +<../examples/companion_radio/ui-new/*.cpp> +lib_deps = + ${Xiao_S3_WIO.lib_deps} + densaugeo/base64 @ ~1.4.0 + adafruit/Adafruit SSD1306 @ ^2.5.13 + [env:Xiao_S3_WIO_companion_radio_ble] extends = Xiao_S3_WIO build_flags =