mudhorn/meshtastic
1
0
Fork 0
mirror of https://github.com/meshtastic/meshtastic.git synced 2024-11-12 16:44:20 -08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge branch 'master' into wio-e5
Some checks failed
CI / quality (push) Has been cancelled
Details
CI / build (push) Has been cancelled
Details

Browse source
This commit is contained in:
Ben Meadors 2024-11-01 14:51:51 -05:00 committed by GitHub
parent 6191014727 376957d25b
commit e122a62366
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
144 changed files with 4378 additions and 3111 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.github/ISSUE_TEMPLATE/documentation-change-request.md vendored
View file

@ -6,7 +6,7 @@ labels: ""
assignees: ""
---
Please - if you just have a question, post in our [forum](https://meshtastic.discourse.group) instead. Please reserve this system for requesting changes to the Meshtastic documentation.
If you have a question, please post it on our [Meshtastic Discussions page](https://github.com/orgs/meshtastic/discussions) instead. This system is reserved specifically for requesting changes to the Meshtastic documentation.
**Describe what section of the docs is outdated or otherwise in need of change**
Be as clear and concise as possible. Provide a URL or GitHub path to the doc you are referencing.

12
.github/pull_request_template.md vendored Normal file
View file

@ -0,0 +1,12 @@
<!-- Add or remove sections as needed -->
## What did you change
<!-- Describe what your changes will do if merged -->
## Why did you change it
<!-- Be sure to link any relevant changes such as other PRs, issues, or Discord convos -->
## Screenshots
### Before
### After

BIN
a0a26e4d40a5b9ccba9185eb70e2eaf66f0b0587_2_1380x888.jpeg Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 295 KiB

20
blog/2024/October/meshtastic-solutions.mdx Normal file
View file

@ -0,0 +1,20 @@
---
title: "Introducing Meshtastic Solutions: Supporting the Future of the Open Source Meshtastic Project"
description: "Meshtastic Solutions is a new initiative designed to support the growth and long-term success of the open source Meshtastic project"
slug: introducing-meshtastic-solutions
authors: MeshtasticTeam
tags: [meshtastic, meshtastic-solutions]
date: 2024-10-23T13:00
hide_table_of_contents: false
image: "/design/web/social-preview-1200x630.png"
---
The Meshtastic Team is excited to announce Meshtastic Solutions. This new venture will support the Meshtastic open source project, as well as provide a pool of expertise for anyone building tools and systems with Meshtastic. Meshtastic Solutions will ensure the long-term health and success of the Meshtastic team and ecosystem, as well as to spur development of the Meshtastic firmware, clients, libraries, and utilities.
This support will be fueled by partnerships with hardware vendors, many that you are familiar with, and some that are new to Meshtastic. In time, high quality devices will bear the Meshtastic seal of approval. Individual devices will be eligible for registration through Meshtastic, providing assurance of genuine hardware, as well as identity and cryptographic key attestation.
Meshtastic Solutions will also serve as a hub for businesses that need custom solutions or expert consultation within the Meshtastic ecosystem. Meshtastic Solutions is open for business for providing engineering, software solutions, and other support for custom use-cases. The first stage of this support is the Backer program, where existing manufacturers can financially support Meshtastic. This will be extended to include a full Partner program, offering in-depth design, close support, and device testing assistance. All with the goal of helping hardware vendors produce the best products possible for Meshtastic.
Meshtastic Solutions is separate from both the Meshtastic open source project, and Meshtastic LLC, the license and trademark holding entity. There will be no drastic changes to the Meshtastic project as a result of this new venture, with the exception of more development and higher quality products and solutions to choose from. This support from Backers and Partners will fuel some long-awaited milestones, including a well-tested Stable firmware release.
We’re looking forward to a stronger Meshtastic ecosystem that continues in the strong open source legacy the project has worked hard to foster. Follow our progress at [Meshtastic.com](https://meshtastic.com), and feel free to contact us with questions or to discuss business opportunities.

56
blog/2024/September/introducing-new-public-key-cryptography-in-v2_5.mdx Normal file
View file

@ -0,0 +1,56 @@
---
title: "Meshtastic Encryption: Evolving from Simple Messaging to a Versatile Solution"
description: "Meshtastic's encryption has evolved, introducing our new Public Key Cryptography in v2.5.0 to enhance security in off-grid communication."
slug: introducing-new-public-key-cryptography-in-v2_5
authors: [Jonathan, crichton]
tags: [meshtastic, technical]
date: 2024-09-12T21:00
hide_table_of_contents: false
image: "/img/blog/Meshtastic_PKC_ECDH.png"
---
Meshtastic began with a straightforward goal: to keep hiking buddies connected in the outdoors when cell service was unavailable. What started as a simple project has grown, thanks to a passionate community pushing the boundaries of what's possible. Today, Meshtastic is used in Search and Rescue operations, off-grid communication, disaster recovery, and even grid-down scenarios. Whether it's preparing for the next flood or tornado, extending communication over the Internet with MQTT, or simply enjoying an off-grid adventure, Meshtastic has become an essential tool for many.
{/* truncate */}
### Balancing Encryption with Practical Use
For many, Meshtastic's encryption is a key part of the appeal. Over the years, the challenge has been finding a balance: implementing strong encryption without excluding low-power IoT platforms or overwhelming LoRa's limited bandwidth. Before version 2.5, encryption relied on a static pre-shared key per channel, which was quite robust. However, it had one notable limitation: Direct Messages (DMs).
DMs were sent using the same shared channel key, which meant that while DMs were theoretically private, they were accessible to anyone on the same channel. The honor system was the only safeguard, particularly since the default Meshtastic setup uses a publicly known encryption key, leaving DMs effectively unencrypted out of the box.
### Challenges with Remote Administration
Remote administration also presented hurdles. The conventional method involved creating an "admin" channel, allowing any node on that channel to be controlled remotely. This approach had drawbacks, notably that nodes open to administering others were also vulnerable to being administered themselves.
## Introducing Public Key Cryptography (PKC) to Meshtastic
In 2022, a user named edinnen proposed a solution with a pull request that introduced a public/private key scheme for DMs. Although the initial feedback was promising, the patch became outdated as time passed. Recently, everything aligned, and we revisited and reworked this patch, making it the foundation of Meshtastic's version 2.5 development.
Our new PKC implementation is now a core feature, providing each node with a unique public key generated at first boot. This key enables secure, encrypted connections between nodes and serves as a unique identifier within the mesh. It also solves the remote administration challenge—nodes can now be identified and authorized as remote administrators through their public keys.
### A Major Step Forward in Security
With this new PKC scheme, Meshtastic offers enhanced encryption for DMs and secure remote administration for difficult-to-reach nodes. While we still caution against relying solely on Meshtastic encryption for life-or-death situations, this update marks a significant advancement in privacy and security for the mesh network.
### Technical Deep Dive: The Mechanics of Meshtastic's New Encryption
At the heart of Meshtastic's new encryption system lies the X25519 elliptic curve Diffie-Hellman key exchange. This process unfolds in two key steps:
1. Key Generation: Upon first boot, each device generates a random private key and derives a corresponding public key using the X25519 algorithm. This public key is then broadcast to the mesh as part of the node's regular announcements.
2. Secure Communication: When a node initiates a Direct Message (DM), it completes the X25519 key exchange by combining its private key with the recipient's public key. This process generates a unique shared secret, which is then used to encrypt the DM. The receiving node can independently derive the same shared secret using its private key and the sender's public key, enabling secure decryption.
> ![Meshtastic's X25519 Key Exchange Process](/img/blog/Meshtastic_PKC_ECDH.png) Figure 1: Visual representation of Meshtastic's X25519 key exchange process
The encryption scheme employs AES-CCM (Counter with CBC-MAC), which provides both confidentiality and authenticity. A notable feature is the inclusion of a short Message Authentication Code, verifying the sender's identity and ensuring message integrity. To further enhance security, DM messages incorporate an additional 4 bytes of random nonce, effectively preventing potential compromises due to nonce reuse.
Remote administration has also seen significant improvements. Administration messages now include an 8-byte session key, set by the node being administered. This key is included in responses and must be present in any packet attempting to make changes. With a 300-second timeout, this mechanism provides robust protection against replay attacks of captured administration traffic.
## Conclusion
Meshtastic's journey from a simple hiking communication tool to a versatile, secure mesh networking solution showcases the power of community-driven development. The introduction of our new Public Key Cryptography scheme in version 2.5 represents a significant advancement in the platform's security capabilities, addressing long-standing challenges in direct messaging and remote administration.
As we continue to refine and expand Meshtastic's features, we remain committed to balancing robust security with practical usability. While this update significantly enhances the platform's privacy and security, we encourage users to approach encryption with a clear understanding of its strengths and limitations, especially in critical scenarios.
Looking ahead, we're excited about the possibilities this new encryption framework opens up. We invite our community to explore these new features, provide feedback, and continue pushing the boundaries of what's possible with Meshtastic. Together, we're building a more secure and connected future for off-grid communication.

16
blog/authors.yml
View file

@ -19,4 +19,18 @@ GUVWAF:
image_url: https://github.com/GUVWAF.png
socials:
github: GUVWAF
Jonathan:
name: Jonathan Bennett
title: "Lead: The Linux Guy, Amateur Cryptographer, Position Wrangler, Privacy Protector, Bug Hunter"
url: https://github.com/jp-bennett
image_url: https://github.com/jp-bennett.png
socials:
github: jonathanbennett
MeshtasticTeam:
name: Meshtastic Team
url: https://meshtastic.org
image_url: https://github.com/meshtastic.png
MeshtasticSolutions:
name: Meshtastic Solutions
url: https://meshtastic.com
image_url: https://github.com/meshtastic-solutions.png

2
docs/about/contributing.mdx
View file

@ -34,7 +34,7 @@ Key components include:
- **Protocol Buffers**: The backbone of communication and interactions, with changes and definitions managed in the [Meshtastic Protobuf Definitions repository](https://github.com/meshtastic/protobufs). For detailed information, see the [Protobuf API Reference](https://buf.build/meshtastic/protobufs/).
- **Device Firmware**: Development for ESP32, nRF52, and RP2040 based devices occurs in the [firmware repository](https://github.com/meshtastic/firmware), focusing on C and C++ code for hardware interaction and communication.
- **Firmware Modules**: Extend the core functionalities of devices and mesh networks, implemented mainly within the firmware repository. Modules are essential for adding new features and integrating devices within the ecosystem.
- **CLI Apps (Device Interface)**: The [Meshtastic Python CLI](https://github.com/meshtastic/Meshtastic-python) enables interaction with device settings and functionalities, serving both as a utility and a library for application development.
- **CLI Apps (Device Interface)**: The [Meshtastic Python CLI](https://github.com/meshtastic/python) enables interaction with device settings and functionalities, serving both as a utility and a library for application development.
- **Web and JavaScript Apps**: Development for the hosted web server on ESP32 devices is done in [Meshtastic Web](https://github.com/meshtastic/web), with a JavaScript library for device interfaces available in [Meshtastic JS](https://github.com/meshtastic/meshtastic.js).
- **Mobile and Desktop Apps**: Android, iOS, iPadOS, and macOS applications provide user interfaces for interacting with Meshtastic devices. Development for Android is detailed in the [Meshtastic-Android repository](https://github.com/meshtastic/Meshtastic-Android), while Apple platforms are supported by the [Meshtastic-Apple repository](https://github.com/meshtastic/Meshtastic-Apple).
- **Documentation**: The source for the Meshtastic website and documentation resides in the [meshtastic/meshtastic repository](https://github.com/meshtastic/meshtastic). For guidelines on maintaining documentation, visit the [Maintaining Documentation](/docs/development/docs) page.

8
docs/about/faq.mdx
View file

@ -60,7 +60,7 @@ export const Faq = {
"apple": [
{
title: "What version of iOS/iPadOS/macOS does the Meshtastic App Require?",
content: `The Meshtastic App on Apple Clients require the following minimum OS versions: iOS 16.2, iPadOS 16.2, and macOS 13.`,
content: `The Meshtastic Apple app supports the last two major versions of iOS, iPadOS or macOS.`,
},
{
title: "How do I get the Apple Meshtastic App?",
@ -164,9 +164,9 @@ If you use your ham radio license with Meshtastic, consider both the privileges
{
title: "How do I set my ham call sign?",
content: `
- On Android navigate to Radio configuration -> User and set Long name to your Ham Radio callsign, then activate the slider for 'Licensed amateur radio'.
- On iPhone navigate to Settings -> User and set Long Name to your Ham Radio callsign, then activate the slider for 'Licensed Operator'.
- Instructions for Enabling ham License from the Python CLI can be found [here](/docs/software/python/cli/usage#ham-radio-support).
- On Android navigate to Radio configuration -> User and set Long name to your Ham Radio callsign, then activate the slider for 'Licensed amateur radio'.
- On iPhone navigate to Settings -> User and set Long Name to your Ham Radio callsign, then activate the slider for 'Licensed Operator'.
- Instructions for Enabling ham License from the Python CLI can be found [here](/docs/software/python/cli/usage#ham-radio-support).
`,
},
],

4
docs/about/introduction.mdx
View file

@ -14,7 +14,7 @@ Meshtastic® is a project that enables you to use inexpensive LoRa radios as a l
### Features
- Long range ([_254km record by kboxlabs_](/docs/overview/range-tests#current-ground-record-254km))
- Long range ([_331km record by MartinR7 & alleg_](/docs/overview/range-tests#current-ground-record-331km))
- No phone required for mesh communication
- Decentralized communication - no dedicated router required
- Encrypted communication
@ -44,7 +44,7 @@ If you are interested in a more technical overview of how Meshtastic works, visi
## Contributors
Meshtastic is an open source project available on GitHub. Our generous volunteers donate their personal time to write and maintain this codebase. If you would like to contribute see our [GitHub](https://github.com/meshtastic), join our [Discord server](https://discord.gg/ktMAKGBnBs), and read up on our [forum](https://meshtastic.discourse.group).
Meshtastic is an open source project available on GitHub. Our generous volunteers donate their personal time to write and maintain this codebase. If you would like to contribute see our [GitHub](https://github.com/meshtastic), join our [Discord server](https://discord.gg/ktMAKGBnBs), and read up on our [Meshtastic Discussions](https://github.com/orgs/meshtastic/discussions).
<div className="indexCtasBody">
<Link

151
docs/about/overview/encryption.mdx
View file

@ -1,151 +0,0 @@
---
id: encryption
title: Meshtastic Encryption
sidebar_label: Encryption
slug: /overview/encryption
sidebar_position: 3
description: "Understand Meshtastic's encryption: optional network-wide AES256 security for off-grid communication, ensuring confidentiality against passive eavesdropping."
---
## Explanation
Meshtastic provides AES256-CTR encryption for the payload of each packet when sending via LoRa, with a different key for each [channel](/docs/configuration/radio/channels/). The [packet header](/docs/overview/mesh-algo/#layer-1-unreliable-zero-hop-messaging) is always sent unencrypted, which allows nodes to relay packets they can't decrypt as well. One can disable this by setting a different [rebroadcast mode](/docs/configuration/radio/device#rebroadcast-mode).
By default you have one primary channel which is encrypted with a simple known key ("AQ=="), so to use proper encryption you **must change** this key first, or create a new channel and share it with the ones you want to communicate with. However, if you don't have the default key, it means you will not be able to communicate with devices that don't have your key.
Direct messages to a specific node (e.g. text, traceroute or position requests) may use any channel you share with the recipient. Namely, the device will use the one where it most recently heard a NodeInfo packet from the recipient on. Client apps will not show messages directed to other nodes, but in principle they could be read by **anyone** who knows the used channel key. This means that if it uses the default key, you have to assume anyone could read your direct messages.
All periodic broadcasts (position, telemetry, etc.) the device sends out itself are sent over the primary channel and thus encrypted with that key.
The device will decrypt the payload before sending it to a client app via BLE, serial, Wi-Fi/Ethernet. For MQTT you can [specify](/docs/configuration/module/mqtt#encryption-enabled) whether you want to send an encrypted or unencrypted payload.
## Is it as secure as Wi-Fi WPA3, HTTPS TLS1.3 or Signal ?
**No**.
[WPA3](https://en.wikipedia.org/wiki/WPA3), [TLS1.3](https://en.wikipedia.org/wiki/TLS1.3), [Signal](https://en.wikipedia.org/wiki/Signal_Protocol) and Meshtastic can all use AES256, yet AES is one of the many cogs required in a modern encryption system, see below the main features "missing" in Meshtastic.
### Perfect-Forward-Secrecy
[**P**erfect-**F**orward-**S**ecrecy also known as **PFS**](https://en.wikipedia.org/wiki/Forward_secrecy) means *previous* communications and more generally anything *passively captured* cannot be decrypted ***even when the key is compromised***.
This means Meshtastic is vulnerable to [**« Harvest now, Decrypt later »**](https://en.wikipedia.org/wiki/Harvest_now,_decrypt_later) attacks, **this attack itself is not enough to decrypt messages** it relies on an other failure leaking the channel key such as:
- Accidently sharing the channel key with the wrong person.
- One of your nodes being stolen.
- Any unknown bug revealing the channel key to an attacker.
Other protocols such as *misconfigured TLS1.2* are far more impacted by Harvest now, Decrypt later attacks because their keys will be broken by near future Quantum-Computers yet they do not provide PFS.
Meshtastic's encryption is not threatened by Quantum-Computers\* so realistic attack vectors are accidental miss-handling of channel keys and nodes being lost.
\*on the Quantum-Resistance of AES256 see:
- [this stackoverflow question, contain a bit of debates and two good answers](https://crypto.stackexchange.com/q/6712)
- [NIST's Post-Quantum FAQ](https://csrc.nist.gov/projects/post-quantum-cryptography/faqs) section « To protect against the threat of quantum computers, should we double the key length for AES now? (added 11/18/18) »
**Recommendations** for users using *private channels*:
- **Do not configure private channels on unattended nodes**, nodes will relay meshtastic traffic even if they are not able to decrypt it.
Your unattended routers should not have the private PSK configured as it is easy to gain physical access and extract the channel key.
- Keep in mind, everything sent on a channel can be stored and decrypted later by anyone who gain access to the key even if you locally delete the messages.
- Change your Channel Keys from time to time.
### Integrity
Integrity means ensuring messages cannot be modified without the key.
Meshtastic does not check messages have not been tempered with, see [`#4030`](https://github.com/meshtastic/firmware/issues/4030) for details.
**Recommendations**:
- Keep in mind, by applying a known plaintext attack anyone *could* send messages on a channel even with the channel key is private and secure.
- For developers of third party applications integrating meshtastic, include a cryptographic MAC over the message content and PSK,
we are also considering an [AEAD secured channel mode which would provide this natively](https://github.com/meshtastic/firmware/issues/4030).
### Authentication
Authentication means nodes say who they are on the network, meshtastic does not implement this so it is trivial to impersonate anyone else if you have access to the channel key.
This is because node ids are based on hardware [MAC address](https://en.wikipedia.org/wiki/MAC_address), theses are hardcoded by the manufacturer.
Some other networks like [Yggdrasil](https://yggdrasil-network.github.io/), [cjdns](https://github.com/cjdelisle/cjdns) or [libp2p](https://libp2p.io/) use [public / private key pairs](https://en.wikipedia.org/wiki/Public-key_cryptography) and the Public Key becomes the Node Identity, this make all messages bigger and or require an interactive handshake process.
**Recommendations**:
- Keep in mind, the sender field is indicative and anyone with access to the channel key can trivially lie.
## Direct-Messages
Direct-Messages are implemented as channel messages which have a `to` protobuf field set.
This means anyone in the channel can read all your direct-messages.
Also the node needs to know the right channel to use, this is done by using the latest one a NodeInfo was received, due to the lack of `Authentication` this means anyone you share a channel with can send a spoofed NodeInfo and make you send direct-messages on an incorrect public channel.
**Recommendations**:
- Keep in mind, due to NodeInfo spoof issue Direct-Messages are **very significantly less secure than a private channel** with a secure PSK.
- Do not use Direct-Messages for anything private, instead ahead of time create a new private channel and share it with the person you want to message with.
- Nodes will relay encrypted packets even if they can't decrypt it, so you only loose on some [small DM optimizations](https://github.com/meshtastic/firmware/pull/3753).
- Do not send the private channel key in direct messages or a public channel, because then anyone listening gain access.
- Use a different private channel for each person you want to have private conversations with.
## Comments
Cryptography is tricky, so we've tried to 'simply' apply standard crypto solutions to our implementation. However, the project developers are not cryptography experts.
Based on comments from reviewers (see below), here are some tips for usage of these radios, so that you may know the level of protection offered:
- It is pretty likely that the AES256 security is implemented 'correctly' and an observer will not be able to decode your messages.
- Warning: If an attacker is able to get one of the radios in their possession, they could either a) extract the channel key from that device or b) use that radio to listen to new communications.
- Warning: If an attacker is able to get the "Channel QR code/URL" that you share with others - that attacker could then be able to read any messages sent on the channel (either tomorrow or in the past - if they kept a raw copy of those broadcast packets)
The current implementation provides optional confidentiality to members of a configured network:
- Encryption is implemented in devices/nodes with network-wide encryption keys.
- Encryption is optional and is turned off when devices are in 'Ham mode'.
- There is no encryption supported in the clients (iOS, Android) to facilitate distribution as mass market software.
- Pairing from client-to-device is by:
- direct USB cable
- BT pairing
- Devices are 'promiscuous' and will pair with any near-by client. Network confidentiality requires physical protection of all nodes.
Always keep in mind [xkcd's note on encryption](https://xkcd.com/538).
- If you are a cryptography expert, please review these notes and our questions below. Can you help us by reviewing our notes below and offering advice? We will happily give as much or as little credit as you wish ;-).
- Consider our existing solution 'alpha' and probably fairly secure against a not particularly aggressive adversary (but we can't yet make a more confident statement).
### Notes for reviewers
If you are reviewing our implementation, this is a brief statement of our method.
- We do all crypto at the SubPacket (payload) level only, so that all Meshtastic nodes will route for others - even those channels which are encrypted with a different key.
- Mostly based on reading [Wikipedia](<https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_(CTR)>) and using the modes the ESP32 provides support for in hardware.
- We use AES256-CTR as a stream cypher (with zero padding on the last BLOCK) because it is well supported with hardware acceleration.
- Our AES key is 128 or 256 bits, shared as part of the 'Channel' specification.
- The node number concatenated with the packet number is used as the NONCE. This nonce will be stored in flash in the device and should essentially never repeat. If the user makes a new 'Channel' (i.e. picking a new random 256 bit key), the packet number will start at zero.
- The packet number is sent in cleartext with each packet. The node number can be derived from the "from" field of each packet. (Cleartext is acceptable because it merely provides IV for each encryption run)
- Each 16 byte BLOCK for a packet has an incrementing COUNTER. COUNTER starts at zero for the first block of each packet.
- The IV for each block is constructed by concatenating the NONCE as the upper 96 bits of the IV and the COUNTER as the bottom 32 bits. Since our packets are small counter portion will really never be higher than 32 (five bits).
### Comments from reviewer #1
This reviewer is a cryptography professional, but would like to remain anonymous. We thank them for their comments ;-):
I'm assuming that meshtastic is being used to hike in places where someone capable is trying to break it - like you were going to walk around DefCon using these. I spent about an hour reviewing the encryption, and have the following notes:
- The write-up isn't quite as clear as the code.
- The code is using AES-CTR mode correctly to ensure confidentiality.
- The comment for initNonce really covers the necessary information.
- I think the bigger encryption question is "what does the encryption need to do"? As it stands, an attacker who has yet to capture any of the devices cannot reasonably capture text or location data. An attacker who captures any device in the channel/mesh can read everything going to that device, everything stored on that device, and any other communication within the channel that they captured in encrypted form. If that capability basically matches your expectations, it is suitable for whatever adventures this was intended for, then, based on information publicly available or widely disclosed, the encryption is good. If those properties are distressing (like, device history is deliberately limited and you don't want a device captured today to endanger the information sent over the channel yesterday) we could talk about ways to achieve that (most likely synchronizing time and replacing the key with its own SHA256 every X hours, and ensuring the old key is not retained unnecessarily).
- Two other things to keep in mind are that AES-CTR does not itself provide authenticity (e.g. an attacker can flip bits in replaying data and scramble the resulting plaintext), and that the current scheme gives some hints about transmission in the size. So, if you worry about an adversary deliberately messing-up messages or knowing the length of a text message, it looks like those might be possible.
I'm guessing that the network behaves somewhat like a store-and-forward network - or, at least, that the goal is to avoid establishing a two-way connection to transmit data. I'm afraid I haven't worked with mesh networks much, but remember studying them briefly in school about ten years ago.
### Comments from @Jorropo
- The IV initialization only use 31 random bits per reboot, it then increment messages sequentially. This is not high, it makes duplicate unlikely but probable given the complete scale of the network. Thankfully IV include lower 32 bits of the MAC address which should be unique per node, so each node is it's own birthday paradox, we aren't looking for network wide birthday paradox which would be easy to hack. See [`#4031`](https://github.com/meshtastic/firmware/issues/4031).
Could be fixed.
- The lack of [integrity wasn't properly considered](https://github.com/meshtastic/firmware/issues/4030), the remote administration module implements priviliged RPC calls over AES-CTR without any MAC or AEAD.
Could be fixed.
- The AES-CTR implementation looks like it protects Confidentiality assuming IVs are not duplicated.
- The lack of Forward Secrecy is a bit worrying for a chat messenger when new users lack the paranoid and annoying key management practice that would be required for safe operation.
- IMO the clients should have a big red box the first time you open a Direct-Message indicating theses are not private and not E2E. This was not clear to me without reading the code.
- This project is completely fine for chatting with strangers, using the default key and understanding everything is public, I would not trust it with anything private without some other layer or significant reworks. For example I would consider SSH or Signal over Meshtastic safe. Yet Meshtastic does not choose to have worse crypto for bad reasons, they make the network significantly more usable over the unreliable slow LoRa backhaul it is using.

72
docs/about/overview/encryption/comments.mdx Normal file
View file

@ -0,0 +1,72 @@
---
id: comments
title: Comments on Meshtastic's Encryption
sidebar_label: Comments
sidebar_position: 2
description: "Explore community insights and expert opinions on Meshtastic's encryption, including AES256 implementation, security tips, and potential vulnerabilities."
---
This page compiles community feedback and expert reviews on Meshtastic's encryption approach. We value these insights and aim to improve our encryption implementation where feasible. Explore key details, practical tips, and understand the strengths and potential limitations of Meshtastic's AES256 encryption.
## Comments
Cryptography is tricky, so we've tried to 'simply' apply standard crypto solutions to our implementation. However, the project developers are not cryptography experts.
Based on comments from reviewers (see below), here are some tips for using these radios, so that you may know the level of protection offered:
- It is likely that the AES256 security is implemented 'correctly' and an observer will not be able to decode your messages.
- **Warning:** If an attacker is able to get one of the radios in their possession, they could either a) extract the channel key from that device, or b) use that radio to listen to new communications.
- **Warning:** If an attacker is able to get the "Channel QR code/URL" that you share with others, that attacker could then be able to read any messages sent on the channel (either tomorrow or in the past - if they kept a raw copy of those broadcast packets).
The current implementation provides optional confidentiality to members of a configured network:
- Encryption is implemented in devices/nodes with network-wide encryption keys.
- Encryption is optional and is turned off when devices are in 'Ham mode'.
- There is no encryption supported in the clients (iOS, Android) to facilitate distribution as mass-market software.
- Pairing from client-to-device is by:
- Direct USB cable
- BT pairing
- Devices are 'promiscuous' and will pair with any nearby client. Network confidentiality requires physical protection of all nodes.
Always keep in mind [xkcd's note on encryption](https://xkcd.com/538).
- If you are a cryptography expert, please review these notes and our questions below. Can you help us by reviewing our notes below and offering advice? We will happily give as much or as little credit as you wish ;-).
- Consider our existing solution 'alpha' and probably fairly secure against a not particularly aggressive adversary (but we can't yet make a more confident statement).
## Notes for reviewers
If you are reviewing our implementation, this is a brief statement of our method.
- We do all crypto at the SubPacket (payload) level only, so that all Meshtastic nodes will route for others - even those channels which are encrypted with a different key.
- Mostly based on reading [Wikipedia](<https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_(CTR)>) and using the modes the ESP32 provides support for in hardware.
- We use AES256-CTR as a stream cypher (with zero padding on the last BLOCK) because it is well supported with hardware acceleration.
- Our AES key is 128 or 256 bits, shared as part of the 'Channel' specification.
- The node number concatenated with the packet number is used as the NONCE. This nonce will be stored in flash in the device and should essentially never repeat. If the user makes a new 'Channel' (i.e. picking a new random 256 bit key), the packet number will start at zero.
- The packet number is sent in cleartext with each packet. The node number can be derived from the "from" field of each packet. (Cleartext is acceptable because it merely provides IV for each encryption run)
- Each 16 byte BLOCK for a packet has an incrementing COUNTER. COUNTER starts at zero for the first block of each packet.
- The IV for each block is constructed by concatenating the NONCE as the upper 96 bits of the IV and the COUNTER as the bottom 32 bits. Since our packets are small counter portion will really never be higher than 32 (five bits).
### Comments from reviewer #1
This reviewer is a cryptography professional, but would like to remain anonymous. We thank them for their comments ;-):
I'm assuming that meshtastic is being used to hike in places where someone capable is trying to break it - like you were going to walk around DefCon using these. I spent about an hour reviewing the encryption, and have the following notes:
- The write-up isn't quite as clear as the code.
- The code is using AES-CTR mode correctly to ensure confidentiality.
- The comment for initNonce really covers the necessary information.
- I think the bigger encryption question is "what does the encryption need to do"? As it stands, an attacker who has yet to capture any of the devices cannot reasonably capture text or location data. An attacker who captures any device in the channel/mesh can read everything going to that device, everything stored on that device, and any other communication within the channel that they captured in encrypted form. If that capability basically matches your expectations, it is suitable for whatever adventures this was intended for, then, based on information publicly available or widely disclosed, the encryption is good. If those properties are distressing (like, device history is deliberately limited and you don't want a device captured today to endanger the information sent over the channel yesterday) we could talk about ways to achieve that (most likely synchronizing time and replacing the key with its own SHA256 every X hours, and ensuring the old key is not retained unnecessarily).
- Two other things to keep in mind are that AES-CTR does not itself provide authenticity (e.g. an attacker can flip bits in replaying data and scramble the resulting plaintext), and that the current scheme gives some hints about transmission in the size. So, if you worry about an adversary deliberately messing-up messages or knowing the length of a text message, it looks like those might be possible.
I'm guessing that the network behaves somewhat like a store-and-forward network - or, at least, that the goal is to avoid establishing a two-way connection to transmit data. I'm afraid I haven't worked with mesh networks much, but remember studying them briefly in school about ten years ago.
### Comments from @Jorropo
- The IV initialization only use 31 random bits per reboot, it then increment messages sequentially. This is not high, it makes duplicate unlikely but probable given the complete scale of the network. Thankfully IV include lower 32 bits of the MAC address which should be unique per node, so each node is it's own birthday paradox, we aren't looking for network wide birthday paradox which would be easy to hack. See [`#4031`](https://github.com/meshtastic/firmware/issues/4031).
Could be fixed.
- The lack of [integrity wasn't properly considered](https://github.com/meshtastic/firmware/issues/4030), the remote administration module implements priviliged RPC calls over AES-CTR without any MAC or AEAD.
Could be fixed.
- The AES-CTR implementation looks like it protects Confidentiality assuming IVs are not duplicated.
- The lack of Forward Secrecy is a bit worrying for a chat messenger when new users lack the paranoid and annoying key management practice that would be required for safe operation.
- IMO the clients should have a big red box the first time you open a Direct-Message indicating theses are not private and not E2E. This was not clear to me without reading the code.
- This project is completely fine for chatting with strangers, using the default key and understanding everything is public, I would not trust it with anything private without some other layer or significant reworks. For example I would consider SSH or Signal over Meshtastic safe. Yet Meshtastic does not choose to have worse crypto for bad reasons, they make the network significantly more usable over the unreliable slow LoRa backhaul it is using.

115
docs/about/overview/encryption/index.mdx Normal file
View file

@ -0,0 +1,115 @@
---
id: encryption
title: Meshtastic Encryption
sidebar_label: Encryption
slug: /overview/encryption
sidebar_position: 3
description: "Understand Meshtastic's encryption: optional network-wide AES256 security for off-grid communication, ensuring confidentiality against passive eavesdropping."
---
## Explanation
Meshtastic provides AES256-CTR encryption for the payload of each packet when sending via LoRa, with a different key for each [channel](/docs/configuration/radio/channels/). The [packet header](/docs/overview/mesh-algo/#layer-1-unreliable-zero-hop-messaging) is always sent unencrypted, which allows nodes to relay packets they can't decrypt as well. One can disable this by setting a different [rebroadcast mode](/docs/configuration/radio/device#rebroadcast-mode).
By default, you have one primary channel, which is encrypted with a simple known key ("AQ=="), so to use proper encryption, you **must change** this key first, or create a new channel and share it with the ones you want to communicate with. However, if you don't have the default key, it means you will not be able to communicate with devices that don't have your key.
Direct messages to a specific node are now encrypted using Public Key Cryptography (PKC). Each node is equipped with a unique public/private key pair, and direct messages are encrypted with the recipient's public key. This ensures that only the recipient can decrypt the message using their private key. Additionally, messages are signed with the sender's private key, allowing the recipient to verify the sender's identity and ensuring the message's integrity.
All periodic broadcasts (position, telemetry, traceroutes, etc.) the device sends out itself are sent over the primary channel and thus encrypted with that key.
The device will decrypt the payload before sending it to a client app via BLE, serial, Wi-Fi/Ethernet. For MQTT, you can [specify](/docs/configuration/module/mqtt#encryption-enabled) whether you want to send an encrypted or unencrypted payload.
## Is it as secure as Wi-Fi WPA3, HTTPS TLS1.3, or Signal?
**No**.
[WPA3](https://en.wikipedia.org/wiki/WPA3), [TLS1.3](https://en.wikipedia.org/wiki/TLS1.3), [Signal](https://en.wikipedia.org/wiki/Signal_Protocol), and Meshtastic can all use AES256. Yet AES is one of the many cogs required in a modern encryption system. Below are the main features "missing" in Meshtastic.
### Perfect-Forward-Secrecy
[**P**erfect-**F**orward-**S**ecrecy, also known as **PFS**](https://en.wikipedia.org/wiki/Forward_secrecy), means _previous_ communications and more generally anything _passively captured_ cannot be decrypted **_even when the key is compromised_**.
This means Meshtastic is vulnerable to [**« Harvest now, Decrypt later »**](https://en.wikipedia.org/wiki/Harvest_now,_decrypt_later) attacks. **This attack itself is not enough to decrypt messages**; it relies on another failure leaking the channel key, such as:
- Accidentally sharing the channel key with the wrong person.
- One of your nodes being stolen.
- Any unknown bug revealing the channel key to an attacker.
Other protocols, such as _misconfigured TLS1.2_, are far more impacted by Harvest now, Decrypt later attacks because their keys will be broken by near-future Quantum-Computers, yet they do not provide PFS.
Meshtastic's AES256 encryption is considered quantum-resistant[^1], but the public/private key exchange for DMs is not, as current quantum-resistant cryptography schemes don't fit in LoRa packets or our IoT hardware; realistic attack vectors include accidental mishandling of channel keys, nodes being lost, and potential future quantum attacks on DM key exchanges.
[^1]: On the Quantum-Resistance of AES256, see [this stackoverflow question, containing a bit of debate and two good answers](https://crypto.stackexchange.com/q/6712) and the [NIST's Post-Quantum FAQ](https://csrc.nist.gov/projects/post-quantum-cryptography/faqs) section "To protect against the threat of quantum computers, should we double the key length for AES now? (added 11/18/18)"
#### Recommendations for users using private channels
- **Do not configure private channels on unattended nodes**. Nodes will relay Meshtastic traffic even if they are not able to decrypt it. Your unattended routers should not have the private PSK configured as it is easy to gain physical access and extract the channel key.
- Keep in mind that everything sent on a channel can be stored and decrypted later by anyone who gains access to the key, even if you locally delete the messages.
- Change your Channel Keys from time to time.
#### Changes since 2.5.0 Firmware release
- Direct Messages are now protected with PKC when messaging between devices on v2.5.0 or newer and key exchange has taken place, messaging to legacy 2.4.3 or older firmware versions are not protected.
- Admin Messages between two v2.5.0 or newer nodes are now protected and additonal relay attack protection in place.
### Integrity
Integrity means ensuring messages cannot be modified without the key.
Meshtastic does not verify the integrity of channel messages to check if they have been tampered with (see [issue #4030](https://github.com/meshtastic/firmware/issues/4030) for details).
#### Recommendations
- Keep in mind that by applying a known plaintext attack, anyone _could_ send messages on a channel even if the channel key is private and secure.
- For developers of third-party applications integrating Meshtastic, include a cryptographic MAC over the message content and PSK. We are also considering an [AEAD secured channel mode which would provide this natively](https://github.com/meshtastic/firmware/issues/4030).
#### Changes since 2.5.0 Firmware release
- Message integrity is checked for Direct Messages or Admin Control when communication is between v2.5.0 or newer firmware.
### Authentication
Authentication means nodes say who they are on the network. Meshtastic does not implement this, so it is trivial to impersonate anyone else if you have access to the channel key
This is because node IDs are based on hardware [MAC address](https://en.wikipedia.org/wiki/MAC_address), which are hardcoded by the manufacturer.
Some other networks like [Yggdrasil](https://yggdrasil-network.github.io/), [cjdns](https://github.com/cjdelisle/cjdns), or [libp2p](https://libp2p.io/) use [public/private key pairs](https://en.wikipedia.org/wiki/Public-key_cryptography), and the Public Key becomes the Node Identity. This makes all messages bigger and/or requires an interactive handshake process.
#### Recommendations
- Keep in mind that the sender field is indicative, and anyone with access to the channel key can trivially lie.
#### Changes since 2.5.0 Firmware release
- The above now only relates to group chats/channels as DM's are protected when messaging between devices on 2.5 or newer, messaging to legacy 2.4 or older devices are not afforded this addition authentication.
## Direct Messages
Direct Messages (DMs) are now implemented using Public Key Cryptography (PKC). This provides a significant upgrade in security compared to the previous channel-based encryption:
- **Message Encryption:** Each DM is encrypted using the recipient's public key, ensuring that only the recipient can decrypt the message with their private key.
- **Digital Signatures:** Messages are signed with the sender's private key, allowing the recipient to verify the sender's identity and ensuring the integrity of the message.
### Prior to 2.5.0 Firmware Release
Previously, DMs were implemented as channel messages with a `to` protobuf field set. This meant anyone in the channel could read all your direct messages. With PKC, this issue is resolved, as only the intended recipient can decrypt and read the message.
### Recommendations
- While PKC significantly enhances the security of DMs, it's still advisable to avoid sharing sensitive information in direct messages without proper verification of the recipient's public key.
## Admin Messages
Admin Messages/Control are now protected by enhanced security features, making sure that critical operations within the network are more secure than ever before.
- **Stronger Encryption:** Admin Messages now use advanced encryption methods to ensure that only the intended recipients can access and read them.
- **Session IDs:** Each administrative session is assigned a unique Session ID, which helps prevent unauthorized access and ensures that messages are not tampered with or replayed.
### Prior to 2.5.0 Firmware Release
Previously, admin messages were not as secure, but with these updates, they are now much better protected against potential attacks and replay attacks.
### Recommendations
- Always ensure that your devices are using the latest firmware to benefit from these improved security features.
- Regularly monitor your network for any unusual activity to maintain a high level of security.

30
docs/about/overview/radio-settings.mdx
View file

@ -7,7 +7,7 @@ sidebar_position: 1
description: "Maximize your Meshtastic device's potential with detailed radio settings instructions, including frequency bands, data rates, and encryption options."
---
import {FrequencyCalculator} from "/src/components/tools/FrequencyCalculator";
import { FrequencyCalculator } from "/src/components/tools/FrequencyCalculator";
:::info
Meshtastic is **not** LoRaWAN, Helium or TTN (TheThingsNetwork). Meshtastic uses the full spectrum frequency range designated to LoRa technology per region. This allows for several hundred possible frequency channels in the US region alone.
@ -79,16 +79,17 @@ Various data-rate options are available when configuring a frequency slot and ar
We have eight LoRa radio presets. These are the most common settings and have been proven to work well:
| Channel setting | Alt Channel Name | Data-Rate | SF / Symbols | Coding Rate | Bandwidth | Link Budget |
| :--------------------: | :--------------: | :-----------------: | :----------: | :---------: | :-------: | :---------: |
| Short Range / Fast| Short Fast| 10.94 kbps| 7 / 128| 4/5| 250| 143dB|
| Short Range / Slow| Short Slow| 6.25 kbps| 8 / 256| 4/5| 250| 145.5dB|
| Medium Range / Fast| Medium Fast| 3.52 kbps| 9 / 512| 4/5| 250| 148dB|
| Medium Range / Slow| Medium Slow| 1.95 kbps| 10 / 1024| 4/5| 250| 150.5dB|
| Long Range / Fast| Long Fast| 1.07 kbps| 11 / 2048| 4/5| 250| 153dB|
| Long Range / Moderate| Long Moderate| 0.34 kbps| 11 / 2048| 4/8| 125| 156dB|
| Long Range / Slow| Long Slow| 0.18 kbps| 12 / 4096| 4/8| 125| 158.5dB|
| Very Long Range / Slow| Very Long Slow| 0.09 kbps| 12 / 4096| 4/8| 62.5| 161.5dB|
| Channel setting | Alt Channel Name | Data-Rate | SF / Symbols | Coding Rate | Bandwidth | Link Budget |
| :--------------------: | :--------------: | :--------: | :----------: | :---------: | :-------: | :---------: |
| Short Range / Turbo | Short Turbo | 21.88 kbps | 7 / 128 | 4/5 | 500[^1] | 140dB |
| Short Range / Fast | Short Fast | 10.94 kbps | 7 / 128 | 4/5 | 250 | 143dB |
| Short Range / Slow | Short Slow | 6.25 kbps | 8 / 256 | 4/5 | 250 | 145.5dB |
| Medium Range / Fast | Medium Fast | 3.52 kbps | 9 / 512 | 4/5 | 250 | 148dB |
| Medium Range / Slow | Medium Slow | 1.95 kbps | 10 / 1024 | 4/5 | 250 | 150.5dB |
| Long Range / Fast | Long Fast | 1.07 kbps | 11 / 2048 | 4/5 | 250 | 153dB |
| Long Range / Moderate | Long Moderate | 0.34 kbps | 11 / 2048 | 4/8 | 125 | 156dB |
| Long Range / Slow | Long Slow | 0.18 kbps | 12 / 4096 | 4/8 | 125 | 158.5dB |
| Very Long Range / Slow | Very Long Slow | 0.09 kbps | 12 / 4096 | 4/8 | 62.5 | 161.5dB |
:::note
The link budget used by these calculations assumes a transmit power of 22dBm and an antenna with 0dB gain. Adjust your link budget assumptions based on your actual devices. Data-rate in this table is the theoretical max but doesn't account for packet headers, hops and re-transmissions. Calculations based on data from the official [Semtech LoRa calculator](https://www.semtech.com/design-support/lora-calculator).
@ -96,7 +97,6 @@ The link budget used by these calculations assumes a transmit power of 22dBm and
![link budget vs data rate plot](/img/about/link-budget-vs-data-rate.webp)
### Custom Settings
Custom settings can be applied by using [supported software](/docs/software).
@ -120,8 +120,10 @@ Some example settings:
The link budget used by these calculations assumes a transmit power of 17dBm and an antenna with 0dB gain. Adjust your link budget assumptions based on your actual devices.
These frequency slot settings may not have been tested. Use at your own discretion. Share on https://meshtastic.discourse.group with your successes or failure.
These frequency slot settings may not have been tested. Use at your own discretion. Share on the [Meshtastic Discussions page](https://github.com/orgs/meshtastic/discussions) with your successes or failure.
## Cryptography
The pre-shared key (PSK) used by the devices can be an AES128 or AES256 sequence. Alternatively, encryption can be turned off, which may be useful if you are operating under a Ham Radio license.
The pre-shared key (PSK) used by the devices can be an AES128 or AES256 sequence. Alternatively, encryption can be turned off, which may be useful if you are operating under a Ham Radio license.
[^1]: Short Turbo is the fastest preset and the only one with 500kHz bandwidth. It is not legal to use in all regions due to this wider bandwidth.

53
docs/about/overview/range-test.mdx
View file

@ -19,9 +19,46 @@ values={[
<TabItem value="ground">
#### Ground
#### Current Ground Record: 331km
##### Current Ground Record: 254km
- **Range:** 331km (205 miles)
- **Record Holders:** _MartinR7_ & _alleg_
- **Source:** [reddit](https://www.reddit.com/r/meshtastic/comments/1fnduwo/mountain_to_mountain_331_km/)
<h5 id="modem-settings-331">Modem Settings</h5>
Default Very Long Slow
- **Frequency:** 868MHz
- **Bandwidth:** 62.5
- **Spread Factor:** 12
- **Coding Rate:** 4/8
<h5 id="node-a-331">Node A</h5>
- **Device:** [RAK4631 Core](/docs/hardware/devices/rak-wireless/wisblock/core-module/?rakcore=RAK4631)+[RAK19003](/docs/hardware/devices/rak-wireless/wisblock/base-board/?rakbase=RAK19003)+[RAK1906](/docs/hardware/devices/rak-wireless/wisblock/peripherals/?rakmodules=Sensors#rak1906-environment-sensor)+[INA219](/docs/configuration/module/telemetry/#currently-supported-sensor-types)
- **Firmware Version:** 2.3.6
- **Antenna:** 55cm collinear 868mhz (AliExpress)
<h5 id="node-b-331">Node B</h5>
- **Device:** [RAK4631 Core](/docs/hardware/devices/rak-wireless/wisblock/core-module/?rakcore=RAK4631)+[RAK19003](/docs/hardware/devices/rak-wireless/wisblock/base-board/?rakbase=RAK19003)+[RAK1901](/docs/hardware/devices/rak-wireless/wisblock/peripherals/?rakmodules=Sensors#rak1901-temperature-and-humidity-sensor)
- **Firmware Version:** 2.4.2
- **Antenna:** RAKARJ17
<img src="/img/records/MartinR7-XARC.webp" alt="Node A" />
<img src="/img/records/MartinR7-Sneznik.webp" alt="Node B" />
<img src="/img/records/MartinR7-map.webp" alt="Map" />
<img src="/img/records/MartinR7-map2.webp" alt="Map2" />
<img src="/img/records/MartinR7-path.webp" alt="Path" />
<img src="/img/records/MartinR7-message-trace.webp" alt="Trace" />
#### Previous Ground Record: 254km
- **Range:** 254km (158 miles)
- **Record Holders:** _kboxlabs_
@ -54,7 +91,7 @@ Default Long_Fast
<img src="/img/records/kboxlabs_map.webp" alt="Geographic Locations" />
##### Previous Record 166km
#### Previous Record 166km
- **Range:** 166km (103 miles)
- **Record Holder:** _PuzzledPancake_
@ -79,11 +116,11 @@ Default Long_Fast
- **Firmware Version:** 1.2
- **Antenna:** [868MHz Vertical 6dBi](https://ivent.co.nz/product/category/1000/868mhz%20vertical%206dbi%20antenna/38606)
![Topographical Map](https://canada1.discourse-cdn.com/free1/uploads/meshtastic/optimized/2X/a/a0a26e4d40a5b9ccba9185eb70e2eaf66f0b0587_2_1380x888.jpeg)
![Topographical Map](/img/records/topographical_map.webp)
![Node A](https://canada1.discourse-cdn.com/free1/uploads/meshtastic/optimized/2X/9/99ec4bcc18b21f4e95ac1bcc0592b608c9c4f567_2_1332x1000.jpeg)
![Node A](/img/records/node_a.webp)
![Node B](https://canada1.discourse-cdn.com/free1/uploads/meshtastic/optimized/2X/1/1c8bd5fc41f7bab925404b657a9c481882de9313_2_1332x1000.jpeg)
![Node B](/img/records/node_b.webp)
<h5>Resources Used</h5>- http://www.heywhatsthat.com
@ -91,9 +128,7 @@ Default Long_Fast
<TabItem value="air">
#### Air
##### Current Air Record: 206km
#### Current Air Record: 206km
- **Range:** 206km (128 miles)
- **Record Holders:** _StarWatcher, CVR, rook, kboxlabs_

12
docs/blocks/_position-precision-bits.mdx Normal file
View file

@ -0,0 +1,12 @@
| Precision bits | Metric | Imperial |
| :------------: | :-----: | :--------: |
| 10 | 23.3 km | 14.5 miles |
| 11 | 11.7 km | 7.3 miles |
| 12 | 5.8 km | 3.6 miles |
| 13 | 2.9 km | 1.8 miles |
| 14 | 1.5 km | 4787 feet |
| 15 | 729 m | 2392 feet |
| 16 | 364 m | 1194 feet |
| 17 | 182 m | 597 feet |
| 18 | 91 m | 299 feet |
| 19 | 45 m | 148 feet |

12
docs/blocks/_position-precision.mdx Normal file
View file

@ -0,0 +1,12 @@
| Metric | Imperial |
| :-----: | :--------: |
| 23.3 km | 14.5 miles |
| 11.7 km | 7.3 miles |
| 5.8 km | 3.6 miles |
| 2.9 km | 1.8 miles |
| 1.5 km | 4787 feet |
| 729 m | 2392 feet |
| 364 m | 1194 feet |
| 182 m | 597 feet |
| 91 m | 299 feet |
| 45 m | 148 feet |

48
docs/community/local-groups.mdx
View file

@ -30,6 +30,12 @@ us on [Discord](https://discord.com/invite/ktMAKGBnBs) to add your group.
- [Meshtastic User Group Tasmania](https://www.facebook.com/groups/1556630645195649)
## Bulgaria
### Burgas
- [Burgas Mesh](https://discord.gg/5RKeFDPw)
## Canada
### Alberta
@ -66,6 +72,7 @@ us on [Discord](https://discord.com/invite/ktMAKGBnBs) to add your group.
### Ontario
- [Mesht Ontario](https://t.me/meshtOnt)
- [Greater Ottawa Meshtastic Enthusiasts Discord](https://discord.gg/njcQ4BnKDU)
### Prince Edward Island
@ -87,6 +94,12 @@ us on [Discord](https://discord.com/invite/ktMAKGBnBs) to add your group.
- [Mesh Finland Discord](https://discord.com/invite/GHnaVAjqed)
- [Mesh Finland Website](https://mesh-finland.github.io)
- [MeshAbout](https://www.meshabout.fi/)
## France
- [Collectif Meshtastic France](https://www.facebook.com/groups/meshtastic.france)
- [Réseau Gaulix - Telegram](https://t.me/+bkCEaiI-i-Q2ZTBk)
## Germany
@ -104,24 +117,45 @@ us on [Discord](https://discord.com/invite/ktMAKGBnBs) to add your group.
## Italy
- [Meshtastic Italia Community](https://t.me/meshtastic_italia_community)
- [Mesh_ITA Discord Server](https://discord.gg/ETFmtyzbFT)
## Japan
- [Meshtastic Japan Community](https://www.facebook.com/share/g/BQCGxZhw9SxFQja8/?mibextid=K35XfP)
## Lithuania
- [Meshtastic Lietuva](https://www.facebook.com/groups/1122509422249414)
- [LithMesh Signal Group](https://signal.group/#CjQKIBScbOkXSG2bkFh_omdxjOM-XqYIU4eERDmGEDrm3jjmEhDyZhh-EeCLSfjfV-DoPvEQ)
## Mexico
- [Meshtastic Mexico Community](https://radioaficionados.mx/meshtastic)
## Netherlands, The
- [Meshtastic Netherlands Telegram](https://t.me/meshtastic_nl)
- [MeshNet Meshtastic Community](https://www.meshnet.nl/)
## New Zealand
- [New Zealand Meshtastic Community Discord](https://discord.gg/xb9bBZJUpz)
## Poland
- [Meshtastic Poland Matrix Space](https://matrix.to/#/#meshtasticpl:matrix.org)
## Slovenia
- [MeshNet.si](https://meshnet.si)
- [Slovenian Amature Radio Discord](https://discord.gg/uHDDE734DD)
## Spain
- [Meshtastic Spanish Community](https://t.me/meshtastic_esp)
## Taiwan
- [Meshtastic Taiwan Community 臺灣鏈網 - Facebook](https://www.facebook.com/groups/413628121046386)
@ -201,9 +235,14 @@ us on [Discord](https://discord.com/invite/ktMAKGBnBs) to add your group.
- [Albuquerque Mesh](https://www.abqm.net)
### North Carolina
- [NCMesh](https://ncmesh.net)
### Ohio
- [Cincy Mesh](https://www.cincymesh.org)
- [Dayton Mesh](https://daytonmesh.org/)
### Oklahoma
@ -223,7 +262,16 @@ us on [Discord](https://discord.com/invite/ktMAKGBnBs) to add your group.
- [Austin Mesh](https://austinmesh.org/)
- [Cypress, Texas Meshtastic Club](https://discord.gg/KzuwNRwE6q)
- [DFW / North Texas Mesh](https://discord.gg/jyzYRTtyMD)
### Virginia
- [MadisonMesh](https://madisonmesh.com/)
### Wisconsin
- [Meshconsin](https://meshconsin.org)
### Washington
- [Puget Mesh](https://PugetMesh.org)

5
docs/community/software/index.mdx
View file

@ -9,10 +9,9 @@ The Meshtastic ecosystem is highly extensible, and a number of community project
Current community projects:
- [Meshtasticator (Simulator)](/docs/community/software/community-meshtasticator) - Meshtasticator is a discrete-event and interactive simulator that mimics the radio section of the device software.
- [Meshtastic Web API](/docs/community/software/meshtastic-web-api) - Meshtastic Web API provides a RESTful interface to interact with a Meshtastic node via a serial connection.
- [Mesh-metrics](/docs/community/software/community-mesh-metrics) - Meshtastic repeater metrics scraper using meshtastic-cli to be ingested by node_exporter for use in Prometheus or Victoria Metrics Time series DB with a Grafana dashboard and sample alerting rules.
- [Node-RED Messages Node](/docs/community/software/community-node-red-messages) - Node-RED node to send and receive packets / text messages from a device connected via HTTP.
- [Node-RED Messages Node](/docs/community/software/community-node-red-messages) - Node-RED node to send and receive packets / text messages from a device connected via HTTP.
- [MQTT Connect for Meshtastic](https://github.com/pdxlocations/MQTT-Connect-for-Meshtastic) - A nodeless python client for communicating with Meshtastic devices over MQTT.
Support for these projects should be sought from their respective authors.

16
docs/community/software/meshtasticator.mdx
View file

@ -1,16 +0,0 @@
---
id: community-meshtasticator
title: Meshtasticator
sidebar_label: Meshtasticator (Simulator)
sidebar_position: 1
---
:::note
This is a community project maintained by @GUVWAF.
Development can be followed on [GitHub](https://github.com/GUVWAF/Meshtasticator).
Support should be sought from the respective authors.
:::
Meshtasticator is a discrete-event and interactive simulator that mimics the radio section of the device software and can be used to assess the performance of your scenario, or the scalability of the protocol. Meshtasticator was created and is maintained by GUVWAF and more information on its use and setup can be found on the [Meshtasticator Github page](https://github.com/GUVWAF/Meshtasticator)

43
docs/configuration/module/mqtt.mdx
View file

@ -10,11 +10,10 @@ import TabItem from "@theme/TabItem";
If your device is connected to Internet via wifi or ethernet, you can enable it to forward packets along to an MQTT server. This allows users on the local mesh to communicate with users on the internet. One or more channels must also be enabled as uplink and/or downlink for packets to be transmitted from and/or to your mesh (See [channels](/docs/configuration/radio/channels#downlink-enabled)). Without these settings enabled, the node will still connect to the MQTT server but only send status messages.
The MQTT module config options are: Enabled, Server Address, Username, Password, Encryption Enabled, JSON Enabled, TLS Enabled, Root Topic, Client Proxy Enabled, Map Reporting Enabled (with Position Precision and Publish Interval). MQTT Module config uses an admin message sending a `ConfigModule.MQTT` protobuf.
The MQTT module config options are: Enabled, Server Address, Username, Password, Encryption Enabled, JSON Enabled, TLS Enabled, Root Topic, Client Proxy Enabled, Map Reporting Enabled (with Position Precision and Publish Interval), and Okay to MQTT. MQTT Module config uses an admin message sending a `ConfigModule.MQTT` protobuf.
## Settings
## MQTT Module Config Values
### Enabled
@ -56,27 +55,32 @@ If true, we attempt to establish a secure connection using TLS.
The root topic to use for MQTT messages. This is useful if you want to use a single MQTT server for multiple meshtastic networks and separate them via ACLs.
### Client Proxy Enabled
If true, let the device use the client's (e.g. your phone's) network connection to connect to the MQTT server. If false, it uses the device's network connection which you have to enable via the [network settings](/docs/configuration/radio/network).
### Map Reporting Enabled
Available from firmware version 2.3.2 on.
If true, your node will periodically send an unencrypted map report to the MQTT server to be displayed by online maps that support this packet. This report includes the following information:
- The node's long and short name and ID;
- The node's position (with configurable precision) and altitude;
- The node's hardware model and [role](/docs/configuration/radio/device/#roles);
- The node's firmware version;
- The node's LoRa region, modem preset and primary channel name;
- The node's LoRa region, modem preset and primary channel name;
- Whether the node can be reached on the default channel with known key;
- Number of local online nodes (heard in the last 2 hours, excluding those heard via MQTT).
#### Map Report Position Precision
The precision to use for the position in the map report. Defaults to a maximum deviation of around 1459m.
#### Map Report Publish Interval
How often we should publish the map report to the MQTT server in seconds. Defaults to 900 seconds (15 minutes).
## MQTT Module Config Client Availability
<Tabs
groupId="settings"
defaultValue="apple"
@ -121,18 +125,18 @@ The following configuration options are available in the Python CLI:
:::
| Setting | Acceptable Values | Default |
| :--------------------------: | :---------------: | :-----------------: |
| mqtt.enabled | `true`, `false` | `false` |
| mqtt.address | `string` |`mqtt.meshtastic.org`|
| mqtt.username | `string` | `meshdev` |
| mqtt.password | `string` | `large4cats` |
| mqtt.encryption_enabled | `true`, `false` | `false` |
| mqtt.json_enabled | `true`, `false` | `false` |
| mqtt.tls_enabled | `true`, `false` | `false` |
| mqtt.root | `string` | |
| mqtt.proxy_to_client_enabled | `true`, `false` | `false` |
| mqtt.map_reporting_enabled | `true`, `false` | `false` |
| Setting | Acceptable Values | Default |
| :--------------------------: | :---------------: | :-------------------: |
| mqtt.enabled | `true`, `false` | `false` |
| mqtt.address | `string` | `mqtt.meshtastic.org` |
| mqtt.username | `string` | `meshdev` |
| mqtt.password | `string` | `large4cats` |
| mqtt.encryption_enabled | `true`, `false` | `false` |
| mqtt.json_enabled | `true`, `false` | `false` |
| mqtt.tls_enabled | `true`, `false` | `false` |
| mqtt.root | `string` | |
| mqtt.proxy_to_client_enabled | `true`, `false` | `false` |
| mqtt.map_reporting_enabled | `true`, `false` | `false` |
:::tip
@ -191,7 +195,7 @@ Navigate to: Vertical Ellipsis (3 dots top right) > Radio configuration > MQTT:
[![MQTT Settings](/img/modules/mqtt/android_mqtt_encryption_sm.webp)](/img/modules/mqtt/android_mqtt_encryption.webp)
*Optional:* To use your phone's internet connection to send and receive packets over the web, also enable the slider for **MQTT Client Proxy** and skip the Configure Network Settings step below.
_Optional:_ To use your phone's internet connection to send and receive packets over the web, also enable the slider for **MQTT Client Proxy** and skip the Configure Network Settings step below.
[![Client Proxy](/img/modules/mqtt/android_mqtt_proxy_sm.webp)](/img/modules/mqtt/android_mqtt_proxy_encryption.webp)
@ -219,7 +223,7 @@ Navigate to Settings > MQTT: Turn on the slider for MQTT enabled and tap **Save*
[![MQTT Settings 1](/img/modules/mqtt/apple_mqtt_1_encryption_sm.webp)](/img/modules/mqtt/apple_mqtt_1_encryption.webp)
[![MQTT Settings 2](/img/modules/mqtt/apple_mqtt_2_sm.webp)](/img/modules/mqtt/apple_mqtt_2.webp)
*Optional:* To use your phone's internet connection to send and receive packets over the web, also enable the slider for **MQTT Client Proxy** and skip the Configure Network Settings step below.
_Optional:_ To use your phone's internet connection to send and receive packets over the web, also enable the slider for **MQTT Client Proxy** and skip the Configure Network Settings step below.
[![Client Proxy](/img/modules/mqtt/apple_mqtt_1_proxy_sm.webp)](/img/modules/mqtt/apple_mqtt_1_proxy_encryption.webp)
@ -254,6 +258,7 @@ meshtastic --ch-set downlink_enabled true --ch-index 0
```
or chained together:
```shell
meshtastic --ch-set uplink_enabled true --ch-index 0 --ch-set downlink_enabled true --ch-index 0
```
@ -267,6 +272,7 @@ meshtastic --set network.wifi_psk yourpassword
```
or chained together:
```shell
meshtastic --set network.wifi_enabled true --set network.wifi_ssid "your network" --set network.wifi_psk yourpassword
```
@ -282,7 +288,7 @@ Navigate to Config > Module Config > MQTT - Turn on the slider for MQTT enabled
[![MQTT Settings](/img/modules/mqtt/web_mqtt_encryption_sm.webp)](/img/modules/mqtt/web_mqtt_encryption.webp)
*Optional:* To use your client's internet connection to send and receive packets over the web, also enable the slider for **Proxy to Client Enabled** and skip the Configure Network Settings step below.
_Optional:_ To use your client's internet connection to send and receive packets over the web, also enable the slider for **Proxy to Client Enabled** and skip the Configure Network Settings step below.
[![Client Proxy](/img/modules/mqtt/web_mqtt_proxy_sm.webp)](/img/modules/mqtt/web_mqtt_proxy_encryption.webp)
@ -292,7 +298,6 @@ Though this option may be visible in your UI, Client Proxy is not yet functional
:::
##### 2. Enable Channel Uplink & Downlink
Navigate to Channels > Primary: Turn on the sliders for **Uplink Enabled** and **Downlink Enabled** - Click the **Save** icon.

2
docs/configuration/module/range-test.mdx
View file

@ -188,5 +188,5 @@ For an open source solution you could use [uMap](https://umap.openstreetmap.de/e
Visit [uMap](https://umap.openstreetmap.de/en/) in your preffered language.
1. Click on "Create a map"
2. Click on the "Import data"-Icon or press CRTL + I.
2. Click on the "Import data"-Icon or press CTRL + I.
3. Choose your rangetest.csv and click "Import". The dataformat is recognized and the locations are imported onto the map.

3
docs/configuration/module/remote-hardware.mdx
View file

@ -12,7 +12,8 @@ The Remote Hardware Module allows to read, write and watch GPIO pins on a remote
:::info
While configuring this module may be available in clients, setting and reading GPIO's is currently only possible using the [Meshtastic Python CLI](/docs/software/python/cli)
For firmware versions > 2.5.3, this module requires you to compile your own firmware and remove the `-DMESHTASTIC_EXCLUDE_REMOTEHARDWARE=1` build flag in `platformio.ini`.
Additionally, while configuring this module may be available in clients, setting and reading GPIO's is currently only possible using the [Meshtastic Python CLI](/docs/software/python/cli)
:::

41
docs/configuration/module/serial.mdx
View file

@ -12,9 +12,13 @@ The serial module config options are: Enabled, Echo, Mode, Receive GPIO, Transmi
This is an interface to talk to and control your Meshtastic device over a serial port. The module can be set to different [modes](#mode), each fulfilling a different use-case.
![image](https://user-images.githubusercontent.com/9000580/205529843-962c3187-8411-452c-b729-42c58b1571f5.png)
![image](/img/modules/Serial/jet.webp)
<object data="https://www.youtube.com/embed/HdOiGKBtapw?autohide=1&autoplay=0" width="100%" height="400"></object>
<object
data="https://www.youtube.com/embed/HdOiGKBtapw?autohide=1&autoplay=0"
width="100%"
height="400"
></object>
## Serial Module Config Values
@ -38,11 +42,20 @@ Available Values:
- `TEXTMSG` will allow you to send a string over the serial port to the device, which will be broadcasted as a text message to the default channel. Any text message received from the mesh will be sent to the serial port as follows: `<Short Name>: <text>`.
- `NMEA` will output a NMEA 0183 Data stream containing the internal GPS or fixed position and other node locations as Waypoints (WPL).
- `CALTOPO` will output NMEA 0183 Waypoints (WPL) every 10 seconds for all valid node locations, to be consumed by [CalTopo / SARTopo](/docs/software/integrations/caltopo.mdx).
- `WS85` will parse and compute wind speed data received over serial from the Ecowitt WS85. Transmits valuess via telemetry packet every 5 minutes. Modification of the WS85 weather sensor is required (https://hackaday.io/project/196990-meshtastic-ultrasonic-anemometer-wx-station). If option is not available in app then enable with cli command "meshtastic --set serial.mode 6"
- `WS85` will parse and compute wind speed data received over serial from the Ecowitt WS85. Transmits valuess via telemetry packet every 5 minutes. Modification of the WS85 weather sensor is required (https://hackaday.io/project/196990-meshtastic-ultrasonic-anemometer-wx-station). If option is not available in app then enable with cli command "meshtastic --set serial.mode 6"
:::tip
`PROTO` mode will show no obvious output when passively observed by a serial monitor. When testing, consider using the [Python CLI](https://github.com/meshtastic/python) with the `--listen` option, to view the stream of protobufs.
:::
### Receive GPIO Pin
Set the GPIO pin to the RXD pin you have set up.
:::tip
With the RAK4631 on the RAK19007 and some versions of the RAK19003 baseboards, the default pins are TXD1 (16) and RXD1 (15). For this device, setting [GPS Mode](/docs/configuration/radio/position/#gps-mode) to `Not_Present` is necessary. For other versions of the RAK19003 baseboard, the pins TXD0 (20) and RXD0 (19) are accessible.
:::
### Transmit GPIO Pin
Set the GPIO pin to the TXD pin you have set up.
@ -59,7 +72,7 @@ The serial baud rate.
The amount of time to wait before we consider your packet as "done".
### Override Console Serial Port
### Override Console Serial Port
If set to true, this will allow Serial Module to control (set baud rate) and use the primary USB serial bus for output. This is only useful for NMEA and CalTopo modes and may behave strangely or not work at all in other modes. Setting TX/RX pins in the Serial Module config will cause this setting to be ignored.
@ -111,18 +124,17 @@ All serial module config options are available in the python CLI. Example comman
:::
| Setting | Acceptable Values | Default |
| :------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------: |
| serial.enabled | `true`, `false` | `false` |
| serial.echo | `true`, `false` | `false` |
| serial.mode | `DEFAULT` `SIMPLE` `PROTO` `TEXTMSG`, `NMEA`, `CALTOPO` | `DEFAULT` |
| serial.rxd | GPIO Pin Number 1-39 | Default of `0` is Unset |
| serial.txd | GPIO Pin Number 1-33 | Default of `0` is Unset |
| serial.baud | `BAUD_DEFAULT` `BAUD_110` `BAUD_300` `BAUD_600` `BAUD_1200` `BAUD_2400` `BAUD_4800` `BAUD_9600` `BAUD_19200` `BAUD_38400` `BAUD_57600` `BAUD_115200` `BAUD_230400` `BAUD_460800` `BAUD_576000` `BAUD_921600` | `BAUD_DEFAULT` (38400) |
| serial.timeout | `integer` (milli seconds) | Default of `0` corresponds to 250 ms |
| Setting | Acceptable Values | Default |
| :---------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------: |
| serial.enabled | `true`, `false` | `false` |
| serial.echo | `true`, `false` | `false` |
| serial.mode | `DEFAULT` `SIMPLE` `PROTO` `TEXTMSG`, `NMEA`, `CALTOPO` | `DEFAULT` |
| serial.rxd | GPIO Pin Number 1-39 | Default of `0` is Unset |
| serial.txd | GPIO Pin Number 1-33 | Default of `0` is Unset |
| serial.baud | `BAUD_DEFAULT` `BAUD_110` `BAUD_300` `BAUD_600` `BAUD_1200` `BAUD_2400` `BAUD_4800` `BAUD_9600` `BAUD_19200` `BAUD_38400` `BAUD_57600` `BAUD_115200` `BAUD_230400` `BAUD_460800` `BAUD_576000` `BAUD_921600` | `BAUD_DEFAULT` (38400) |
| serial.timeout | `integer` (milli seconds) | Default of `0` corresponds to 250 ms |
| serial.override_console_serial_port | `true`, `false` | `false` |
:::tip
Because the device will reboot after each command is sent via CLI, it is recommended when setting multiple values in a config section that commands be chained together as one.
@ -255,6 +267,7 @@ while True:
```
#### Arduino Mini Pro BOM
- An Arduino Mini Pro with example sketch from below uploaded to it.
- T-Beam V1.1 running Meshtastic
- PIR Sensor ([Adafruit Breadboard Model](https://www.adafruit.com/product/4871))

61
docs/configuration/module/telemetry.mdx
View file

@ -2,17 +2,21 @@
id: telemetry
title: Telemetry Module Configuration
sidebar_label: Telemetry
description: This module allows sharing of Device, Environment, and Air Quality metrics from your Meshtastic device.
description: This module allows sharing of Device, Environment, Health, and Air Quality metrics from your Meshtastic device.
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The Telemetry Module provides three types of data over the mesh: Device metrics (Battery Level, Voltage, Channel Utilization and Airtime) from your Meshtastic device, Environment Metrics from attached I2C sensors, and Air Quality Metrics from attached I2C particle sensors.
The Telemetry Module provides four types of data over the mesh: Device metrics (Battery Level, Voltage, Channel Utilization and Airtime) from your Meshtastic device, Environment Metrics, Air Quality Metrics, and Health metrics (Heart rate, Oxygen Saturation and body temperature).
Supported sensors connected to the I2C bus of the device will be automatically detected at startup. Environment Telemetry and Air Quality must be enabled for them to be instrumented and their readings sent over the mesh.
Supported sensors connected to the I2C bus of the device will be automatically detected at startup. The Environment Telemetry, Air Quality, and Health Telemetry modules must be enabled for them to be instrumented and their readings sent over the mesh.
<object data="https://www.youtube.com/embed/6jj1s-fsPlc?autohide=1&autoplay=0" width="100%" height="400"></object>
<object
data="https://www.youtube.com/embed/6jj1s-fsPlc?autohide=1&autoplay=0"
width="100%"
height="400"
></object>
### Currently Supported Sensor Types
@ -22,7 +26,7 @@ Supported sensors connected to the I2C bus of the device will be automatically d
| BMP180 | 0x76, 0x77 | Temperature and barometric pressure |
| BMP280 | 0x76, 0x77 | Temperature and barometric pressure |
| BME280 | 0x76, 0x77 | Temperature, barometric pressure and humidity |
| BME680 | 0x76, 0x77 | Temperature, barometric pressure, humidity and air resistance |
| BME68x | 0x76, 0x77 | Temperature, barometric pressure, humidity and air resistance |
| MCP9808 | 0x18 | Temperature |
| INA260 | 0x40, 0x41, 0x43 | Current and Voltage |
| INA219 | 0x40, 0x41, 0x43 | Current and Voltage |
@ -31,8 +35,9 @@ Supported sensors connected to the I2C bus of the device will be automatically d
| SHTC3 | 0x70 | Temperature and humidity |
| SHT31 | 0x44 | Temperature and humidity |
| PMSA003I| 0x12 | Concentration units by size and particle counts by size |
| PMSA003I| 0x12 | Concentration units by size and particle counts by size |
| DFROBOT_LARK | 0x42 | Temperature, barometric pressure, humidity, wind direction, wind speed |
| MAX30102 | 0x57 | Heart Rate, Oxygen Saturation, and body temperature |
| MLX90614 | 0x5A | Body temperature |
## Module Config Values
@ -50,7 +55,7 @@ Default is `1800` seconds (30 minutes).
How often we should send Device Metrics over the mesh.
Default is `1800` seconds (30 minutes).
Default is `1800` seconds (30 minutes).
Device Metrics to a connected client app will always be sent once per minute, regardless of this setting.
@ -78,6 +83,28 @@ This option is used to configure the interval (in seconds) that should be used t
Default is `1800` seconds (30 minutes).
### Power Metrics Enabled
This option is used to enable/disable the sending of power telemetry as gathered by an attached supported voltage/current sensor. Note that this does not need to be enabled to monitor the voltage of the battery.
Default is `false`.
### Power Metrics Interval
This option is used to configure the interval (in seconds) that should be used to send power metrics from an attached supported sensor over the mesh network.
### Health Telemetry Enabled
This option is used to enable/disable the sending of health data from an attached supported sensor over the mesh network.
Default is `false`.
### Health Telemetry Interval
This option is used to configure the interval (in seconds) that should be used to send health data from an attached supported sensor over the mesh network.
Default is `1800` seconds (30 minutes).
## Telemetry Config Client Availability
<Tabs
@ -125,15 +152,21 @@ All telemetry module config options are available in the python CLI. Example com
## Settings
| Setting | Acceptable Values | Default |
| :---------------------------------------: | :-----------------: | :---------------------------------------: |
| Setting | Acceptable Values | Default |
| :---------------------------------------: | :-----------------: | :----------------------------------------: |
| telemetry.device_update_interval | `integer` (seconds) | Default `0` is 30 minutes(`1800` seconds). |
| telemetry.environment_display_fahrenheit | `true`, `false` | `false` |
| telemetry.environment_measurement_enabled | `true`, `false` | `false` |
| telemetry.environment_screen_enabled | `true`, `false` | `false` |
| telemetry.environment_display_fahrenheit | `true`, `false` | `false` |
| telemetry.environment_measurement_enabled | `true`, `false` | `false` |
| telemetry.environment_screen_enabled | `true`, `false` | `false` |
| telemetry.environment_update_interval | `integer` (seconds) | Default `0` is 30 minutes(`1800` seconds). |
| telemetry.air_quality_enabled | `true`, `false` | `false` |
| telemetry.air_quality_interval | `integer` (seconds) | Default `0` is 30 minutes(`1800` seconds). |
| telemetry.air_quality_enabled | `true`, `false` | `false` |
| telemetry.air_quality_interval | `integer` (seconds) | Default `0` is 30 minutes(`1800` seconds). |
| telemetry.power_measurement_enabled | `true`, `false` | `false` |
| telemetry.power_update_interval | `integer` (seconds) | Default `0` is 30 minutes(`1800` seconds). |
| telemetry.health_measurement_enabled | `true`, `false` | `false` |
| telemetry.health_update_interval | `integer` (seconds) | Default `0` is 30 minutes(`1800` seconds). |
| telemetry.health_screen_enabled | `true`, `false` | `false` |
:::tip

17
docs/configuration/radio/channels.mdx
View file

@ -7,6 +7,7 @@ description: Understand how to configure channels on your Meshtastic device, inc
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import PositionPrecisionBits from "@site/docs/blocks/_position-precision-bits.mdx";
The Channels config options are: Index, Roles, and Settings. Channel config uses an admin message sending a `Channel` protobuf which also consists of a `ChannelSettings` or `ModuleSettings` protobuf.
@ -117,13 +118,9 @@ The `position_precision` value is an integer between 0 and 32:
- A value of 0 means that location data is never sent over the given channel.
- A value of 32 means that location data is sent with full precision.
- Values in between indicate the number of bits of precision to be sent.
- Values in between indicate the number of bits of precision to be sent, which correspond to a position precision from the table below.
Some useful values and their approximate precisions:
- 11: Large region, around ±11 kilometers
- 13: City-sized region, around ±3 kilometers
- 16: Neighborhood-level precision, around ±350 meters
<PositionPrecisionBits />
The client applications have implemented different levels of precision giving the user a practical range to choose from. Setting across the full range of integers can be done via the Python CLI. See [Setting Position Precision](/docs/configuration/radio/channels/#setting-position-precision) for examples on setting different levels of precision using CLI.
@ -158,14 +155,14 @@ See [Android App Usage](/docs/software/android/usage#setup-a-channel) for more f
[![Channel Editor](/img/android/android-channel-edit-sm.webp)](/img/android/android-channel-edit.webp)
Tap the Channel Name (or the pen icon) to access the Channel Menu:
Tap "Edit" to access the Channel Menu:
1. Add, remove, or modify secondary channels
2. Create or modify encryption keys
3. Enable uplink and downlink for individual channels
4. Set the position precision value
4. Position enabled
5. Precise location (if position is enabled)
6. Position precision (if precise location is disabled)
</TabItem>

43
docs/configuration/radio/device.mdx
View file

@ -79,24 +79,12 @@ This setting defines the device's behavior for how messages are rebroadcasted.
| `LOCAL_ONLY` | LOCAL_ONLY - Ignores observed messages from foreign meshes that are open or those which it cannot decrypt. Only rebroadcasts message on the nodes local primary / secondary channels. |
| `KNOWN_ONLY` | KNOWN_ONLY - Ignores observed messages from foreign meshes like LOCAL_ONLY, but takes it a step further by also ignoring messages from nodenums not in the node's known list (NodeDB). |
## Serial Console
Acceptable values: `true` or `false`
Disabling this will disable the SerialConsole by not initializing the StreamAPI.
## TZDEF (Timezone Definition)
The `tzdef` setting allows the local offset to be defined for the device. It uses the TZ Database format to display the correct local time on the device display and in its logs.
To set the timezone, use the POSIX TZ Database string for the relevant region. Here is a list of [supported timezones](https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv). For example, if your region is `America/Los_Angeles`, you would input `PST8PDT,M3.2.0,M11.1.0` as the timezone.
## Debug Log
Acceptable values: `true` or `false`
By default we turn off logging as soon as an API client connects. Set this to true to leave the debug log outputting even when API is active.
## GPIO for user button
This is the GPIO pin number that will be used for the user button, if your device does not come with a predefined user button.
@ -113,10 +101,6 @@ This is the number of seconds between NodeInfo message (containing i.a. long and
This option will enable a double tap, when a supported accelerometer is attached to the device, to be treated as a button press.
## Managed Mode
Enabling Managed mode will restrict access to all radio configurations via client applications. Radio configurations will only be accessible through the Admin channel. To avoid being locked out, make sure the Admin channel is working properly before enabling it.
## Device Config Client Availability
<Tabs
@ -161,24 +145,21 @@ All device config options are available in the python CLI. Example commands are
:::
| Setting | Acceptable Values | Default |
| --------------------------------- | ----------------------------------------------------------------------------------- | ----------------- |
| device.debug_log_enabled | `true`, `false` | `false` |
| Setting | Acceptable Values | Default |
| --------------------------------- | ------------------------------------------------------------------ | ----------------- |
| device.role | `CLIENT`, `CLIENT_MUTE`, `ROUTER`, `REPEATER`, `TRACKER`, `SENSOR` | `CLIENT` |
| device.rebroadcast_mode | `ALL`, `ALL_SKIP_DECODING`, `LOCAL_ONLY` | `ALL` |
| device.serial_enabled | `true`, `false` | `true` |
| device.button_gpio | `0` - `34` | `0` |
| device.buzzer_gpio | `0` - `34` | `0` |
| device.node_info_broadcast_secs | `3600` - `UINT MAX` | `10800` (3 hours) |
| device.double_tap_as_button_press | `false`, `true` | `false` |
| device.is_managed | `false`, `true` | `false` |
| device.rebroadcast_mode | `ALL`, `ALL_SKIP_DECODING`, `LOCAL_ONLY` | `ALL` |
| device.button_gpio | `0` - `34` | `0` |
| device.buzzer_gpio | `0` - `34` | `0` |
| device.node_info_broadcast_secs | `3600` - `UINT MAX` | `10800` (3 hours) |
| device.double_tap_as_button_press | `false`, `true` | `false` |
:::tip
Because the device will reboot after each command is sent via CLI, it is recommended when setting multiple values in a config section that commands be chained together as one.
```shell title="Example:"
meshtastic --set device.role CLIENT --set device.debug_log_enabled true
meshtastic --set device.role CLIENT --set device.tzdef UTC0
```
:::
@ -187,18 +168,10 @@ meshtastic --set device.role CLIENT --set device.debug_log_enabled true
meshtastic --set device.role CLIENT
```
```shell title="Disable serial console"
meshtastic --set device.serial_enabled false
```
```shell title="Set tzdef"
meshtastic --set device.tzdef UTC0
```
```shell title="Enable debug logging"
meshtastic --set device.debug_log_enabled true
```
</TabItem>
<TabItem value="web">

47
docs/configuration/radio/lora.mdx
View file

@ -38,7 +38,9 @@ The presets are designed to provide further options for optimizing either speed
The Presets available are as follows, and follow a linear pattern of Fastest \<\-\-\> Slowest, and Shortest \<\-\-\> Longest range:
1. `SHORT_FAST` (Fastest, highest bandwidth, lowest airtime, shortest range)
1. `SHORT_TURBO` (Fastest, highest bandwidth, lowest airtime, shortest range. It is not legal to use in all regions due to it's 500kHz bandwidth.)
1. `SHORT_FAST`
2. `SHORT_SLOW`
@ -113,6 +115,14 @@ For testing it is useful sometimes to force a node to never listen to particular
Setting this to option to 'true' means the device will ignore any messages it receives via LoRa that came via MQTT somewhere along the path towards the device. Note this only works when your device and the MQTT node are running at least firmware version 2.2.19.
### OK to MQTT
Acceptable values: `true`, `false`
Default is `false`. When set to `true`, this configuration indicates that the user approves their packets to be uploaded to MQTT. If set to `false`, nodes receiving your packets are requested not to forward packets to MQTT. This configuration only applies to Channels configured with the `defaultpsk` and `eventpsk` keys set in the Meshtastic Firmware; Channels with custom keys ignore this setting.
**Important:** This is not a cryptographic solution but a polite request that is enforced in the official firmware.
### Override Duty Cycle Limit
Setting this option to 'true' means the device will ignore the hourly duty cycle limit in Europe. This means that you might violate regulations if the device transmits too much. By default, this option is set to 'false,' which means the device will stop sending data when it reaches the hourly limit and will start again when it is allowed to do so.
@ -169,23 +179,24 @@ LoRa config commands are available in the python CLI. Example commands are below
:::
| Setting | Acceptable Values | Default |
|:---------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------:|:----------------------------:|
| lora.modem_preset | `LONG_FAST`, `LONG_SLOW`, `VERY_LONG_SLOW`, `MEDIUM_SLOW`, `MEDIUM_FAST`, `SHORT_SLOW`, `SHORT_FAST` | `LONG_FAST`, `LONG_MODERATE` |
| lora.use_preset | `false`, `true` | `false` |
| lora.region | `UNSET`, `US`, `EU_433`, `EU_868`, `CN`, `JP`, `ANZ`, `KR`, `TW`, `RU` ,`IN`, `NZ_865`, `TH`, `LORA_24`, `UA_433`, `UA_868`, `MY_433`, `MY_919`, `SG_923` | `UNSET` |
| lora.bandwidth | `31`, `62`, `125`, `250`, `500` | `250` |
| lora.spread_factor | `7`, `8`, `9`, `10`, `11`, `12` | `12` |
| lora.coding_rate | `5`, `6`, `7`, `8` | `8` |
| lora.frequency_offset | `0` to `1000000` | `0` |
| lora.hop_limit | `1`,`2`,`3`,`4`,`5`,`6`,`7` | `3` |
| lora.tx_power | `0` to `30` | `0` |
| lora.tx_enabled | `false`, `true` | `true` |
| lora.channel_num | `0`, `1` to `NUM_CHANNELS` | `0` |
| lora.ignore_mqtt | `false`, `true` | `false` |
| lora.override_duty_cycle | `false`, `true` | `false` |
| lora.sx126x_rx_boosted_gain | `false`, `true` | `false` |
| lora.override_frequency | Any supported frequency the LoRA radio is capable of. Please respect local rules and regulations | `0` |
| Setting | Acceptable Values | Default |
|:---------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------:|:-----------:|
| lora.modem_preset | `LONG_FAST`, `LONG_SLOW`, `VERY_LONG_SLOW`, `MEDIUM_SLOW`, `MEDIUM_FAST`, `SHORT_SLOW`, `SHORT_FAST`, `SHORT_TURBO` | `LONG_FAST` |
| lora.use_preset | `false`, `true` | `false` |
| lora.region | `UNSET`, `US`, `EU_433`, `EU_868`, `CN`, `JP`, `ANZ`, `KR`, `TW`, `RU` ,`IN`, `NZ_865`, `TH`, `LORA_24`, `UA_433`, `UA_868`, `MY_433`, `MY_919`, `SG_923` | `UNSET` |
| lora.bandwidth | `31`, `62`, `125`, `250`, `500` | `250` |
| lora.spread_factor | `7`, `8`, `9`, `10`, `11`, `12` | `12` |
| lora.coding_rate | `5`, `6`, `7`, `8` | `8` |
| lora.frequency_offset | `0` to `1000000` | `0` |
| lora.hop_limit | `1`,`2`,`3`,`4`,`5`,`6`,`7` | `3` |
| lora.tx_power | `0` to `30` | `0` |
| lora.tx_enabled | `false`, `true` | `true` |
| lora.channel_num | `0`, `1` to `NUM_CHANNELS` | `0` |
| lora.ignore_mqtt | `false`, `true` | `false` |
| lora.config_ok_to_mqtt | `true`, `false` | `false` |
| lora.override_duty_cycle | `false`, `true` | `false` |
| lora.sx126x_rx_boosted_gain | `false`, `true` | `false` |
| lora.override_frequency | Any supported frequency the LoRA radio is capable of. Please respect local rules and regulations | `0` |
:::tip

2
docs/configuration/radio/position.mdx
View file

@ -155,7 +155,7 @@ meshtastic --set position.fixed_position true --setlat 37.8651 --setlon -119.538
:::
```shell title="Set GPS update interval (Default of 0 is 30 seconds)"
```shell title="Set GPS update interval (Default of 0 is 2 Minutes)"
meshtastic --set position.gps_update_interval 0
meshtastic --set position.gps_update_interval 45
```

127
docs/configuration/radio/security.mdx Normal file
View file

@ -0,0 +1,127 @@
---
id: security
title: Security Configuration
sidebar_label: Security
description: This section covers security options for the device such public key, privaate key, and admin key
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The security config options are: Public Key, Private Key, Admin Key, Is Managed, Serial Console, Debug Logs, and Admin Channel.
## Security Config Values
### Public Key
Acceptable values: `bytes`
The public key of the device, shared with other nodes on the mesh to allow them to compute a shared secret key for secure communication.
### Private Key
Acceptable values: `bytes`
The private key of the device, used to create a shared key with a remote device for secure communication.**This key should be kept confidential.**
### Admin Key
Acceptable values: `repeated bytes`
The public key(s) authorized to send administrative messages to this node. Only messages signed by these keys will be accepted for administrative control.
### Managed Mode
Acceptable values: `true` or `false`
Enabling Managed Mode restricts access to all radio configurations via client applications. Radio configurations will only be accessible through the Admin channel. Ensure the Admin channel is functioning properly before enabling this mode to avoid being locked out.
### Serial Console
Acceptable values: `true` or `false`
Disabling this will prevent the Serial Console from initializing the Stream API.
### Debug Log
Acceptable values: `true` or `false`
By default, logging is disabled when an API client connects to keep the shared serial link quiet. Set this to true to continue outputting live debug logs over serial or Bluetooth when the API is active.
### Admin Channel Enabled
Acceptable values: `true` or `false`
Allows incoming device control over the insecure legacy admin channel. Enabling this option permits control messages to be received through the older, less secure admin channel.
## Device Config Client Availability
<Tabs
groupId="settings"
defaultValue="apple"
values={[
{label: 'Android', value: 'android'},
{label: 'Apple', value: 'apple'},
{label: 'CLI', value: 'cli'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="android">
#### Android
All Security config options are available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Security**
</TabItem>
<TabItem value="apple">
#### Apple
All Security config options are available on iOS, iPadOS and macOS at Settings > Radio Configuration > Security.
</TabItem>
<TabItem value="cli">
#### CLI
All Security config options are available in the python CLI. Example commands are below:
| Setting | Acceptable Values | Default |
| ------------------------------ | ----------------- | ------- |
| security.public_key | `bytes` | `None` |
| security.private_key | `bytes` | `None` |
| security.admin_key | `repeated bytes` | `None` |
| security.is_managed | `true`, `false` | `false` |
| security.serial_enabled | `true`, `false` | `true` |
| security.debug_log_api_enabled | `true`, `false` | `false` |
| security.admin_channel_enabled | `true`, `false` | `false` |
:::tip
Because the device may reboot after each command is sent via CLI, it is recommended when setting multiple values in a config section that commands be chained together as one.
```shell title="Example:"
meshtastic --set security.is_managed false --set device.debug_log_api_enabled true
```
:::
```shell title="Disable serial console"
meshtastic --set security.serial_enabled false
```
```shell title="Enable debug logging"
meshtastic --set security.debug_log_api_enabled true
```
</TabItem>
<TabItem value="web">
#### Web
All Security config options are available in the Web client.
</TabItem>
</Tabs>

4
docs/configuration/region-by-country.mdx
View file

@ -143,8 +143,8 @@ If you'd like to contribute information for your country, click the "Edit this p
| ----------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Serbia | EU_868<br />EU_433 | |
| Singapore | SG_923 | [IMDA Regulations](https://www.imda.gov.sg/-/media/imda/files/regulation-licensing-and-consultations/ict-standards/telecommunication-standards/radio-comms/imdatssrd.pdf) |
| Slowakia | EU_868<br />EU_433 | |
| Slowenia | EU_868<br />EU_433 | |
| Slovakia | EU_868<br />EU_433 | [Slovak regulations](https://eur-lex.europa.eu/legal-content/SK/TXT/PDF/?uri=CELEX:32022D0180) |
| Slovenia | EU_868<br />EU_433 | |
| Spain | EU_868<br />EU_433 | |
| Sweden | EU_868<br />EU_433 | |
| Switzerland | EU_868<br />EU_433 | |

2
docs/configuration/tips.mdx
View file

@ -35,7 +35,7 @@ Remember: A network of `CLIENT` nodes with a small number of well-placed `ROUTER
## (Not) Sharing Your Location
Telemetry is shared over your [PRIMARY channel](/docs/configuration/radio/channels#role). This means that if your node has acquired GPS coordinates from an integrated GPS chip, or from your mobile device, your coordinates will be sent to the mesh over this channel, using it's defined encryption (if any).
Telemetry is shared over your [PRIMARY channel](/docs/configuration/radio/channels#role). This means that if your node has acquired GPS coordinates from an integrated GPS chip, or from your mobile device, your coordinates will be sent to the mesh over this channel, using its defined encryption (if any).
By default the PRIMARY channel's name is LongFast with the encryption key "AQ==" (Base64 equivalent of Hex 0x01). If this is left unchanged, your location will be shared with all nodes in range that are also using the default channel.

13
docs/development/android.mdx
View file

@ -10,15 +10,22 @@ sidebar_position: 1
If you would like to develop this application we'd love your help! These build instructions are brief and should be improved, please send a PR if you can.
1. Use Android Studio to build/debug
2. Use `git submodule update --init --recursive` to pull in the various sub-modules we depend on.
3. There are a few config files which you'll need to copy from templates included in the project. Run the following commands to do so:
2. Clone the repository and after successful cloning, change the working directory to Meshtastic-Android/
```shell
git clone https://github.com/meshtastic/Meshtastic-Android.git && cd Meshtastic-Android/
```
3. Pull in the various sub-modules we depend on.
```shell
git submodule update --init --recursive
```
4. There are a few config files which you'll need to copy from templates included in the project. Run the following commands to do so:
```shell
rm ./app/google-services.json
cp ./app/google-services-example.json ./app/google-services.json
rm ./app/src/main/res/values/curfirmwareversion.xml
cp ./app/special/curfirmwareversion.xml ./app/src/main/res/values/
```
4. Now you should be able to select "Run / Run" in the IDE and it will happily start running on your phone or the emulator.
5. Now you should be able to select "Run / Run" in the IDE and it will happily start running on your phone or the emulator.
:::note
The emulators don't support Bluetooth, so some features can not be used in that environment.

28
docs/development/device/error-codes.mdx
View file

@ -11,16 +11,18 @@ The device might report these fault codes on the screen, but it will also be out
This table is derived from the [protobufs](https://buf.build/meshtastic/protobufs/docs/main:meshtastic#meshtastic.CriticalErrorCode)
:::
| Name | Number | Description |
| :-----------------: | :----: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| TxWatchdog | 1 | A software bug was detected while trying to send LoRa |
| SleepEnterWait | 2 | A software bug was detected on entry to sleep |
| NoRadio | 3 | No LoRa radio hardware could be found |
| Unspecified | 4 | Not normally used |
| UBloxInitFailed | 5 | We failed while configuring a UBlox GPS |
| NoAXP192 | 6 | This board was expected to have a power management chip and it is missing or broken |
| InvalidRadioSetting | 7 | The channel tried to set a radio setting which is not supported by this chipset, radio comms settings are now undefined |
| TransmitFailed | 8 | Radio transmit hardware failure. We sent data to the radio chip, but it did not reply with an interrupt |
| Brownout | 9 | We detected that the main CPU voltage dropped below the minimum acceptable value |
| SX1262Failure | 10 | Selftest of SX1262 radio chip failed |
| RadioSpiBug | 11 | A (likely software but possibly hardware) failure was detected while trying to send packets. If this occurs on your board, please post in the forum so that we can ask you to collect some information to allow fixing this bug |
| Name | Number | Description |
| :--------------------------: | :----: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| TxWatchdog | 1 | A software bug was detected while trying to send LoRa. |
| SleepEnterWait | 2 | A software bug was detected on entry to sleep. |
| NoRadio | 3 | No LoRa radio hardware could be found. |
| Unspecified | 4 | Not normally used. |
| UBloxInitFailed | 5 | Failed while configuring a UBlox GPS. |
| NoAXP192 | 6 | This board was expected to have a power management chip, but it is missing or broken. |
| InvalidRadioSetting | 7 | The channel tried to set a radio setting not supported by this chipset; radio communication settings are now undefined. |
| TransmitFailed | 8 | Radio transmit hardware failure. Data was sent to the radio chip, but it did not respond with an interrupt. |
| Brownout | 9 | Main CPU voltage dropped below the minimum acceptable value. |
| SX1262Failure | 10 | Self-test of the SX1262 radio chip failed. |
| RadioSpiBug | 11 | A failure (likely software, possibly hardware) was detected while sending packets. If this occurs on your board, please post in the forum to help us collect information to fix this bug. |
| FlashCorruptionRecoverable | 12 | Corruption was detected on the flash filesystem, but it was repaired. |
| FlashCorruptionUnrecoverable | 13 | Corruption was detected on the flash filesystem, and it could not be repaired. _Note: Your node will likely need reconfiguration upon the next reboot (e.g., loss of region code)._ |

78
docs/development/reference/encryption-technical.mdx Normal file
View file

@ -0,0 +1,78 @@
---
id: encryption-technical
title: Updated Security Implementation
sidebar_label: Encryption Technical
sidebar_position: 5
description: Technical Overview of Encryption Employed with Meshtastic from Firmware 2.5.0 Onwards
---
## PSK for Channels, PKC for Direct Messages and Admin Messages
Up to version 2.4.x of the firmware, Meshtastic relied entirely on Pre-Shared Key (PSK) cryptography for all messaging. Starting with firmware version 2.5.0, Meshtastic introduced Public Key Cryptography (PKC) for Direct Messages (DMs) and added Session IDs for Admin Messages. Together, these enhancements bring the security architecture of Meshtastic to a new level of robustness.
Below is a detailed overview of how PSK, PKC, and Session IDs are integrated into your system to secure Channels, Direct Messages, and Admin Messages.
### 1. Chat Channels Using PSK
- **PSK Overview:**
- Chat Channels continue to utilize a PSK for encrypting communications.
- All participants share the same PSK for their Channels, which is used for both encryption and decryption within the channel.
- **Security Considerations:**
- **Confidentiality:** Only participants with the correct PSK can access messages within the Chat Channel.
- **Key Management:** Secure distribution and regular rotation of the PSK are essential to maintaining the channel's security.
### 2. DMs Now Using PKC
- **PKC Implementation for DMs:**
- **Public/Private Key Pairs:** Each node is equipped with a unique public/private key pair. The private key is securely stored on the node, and the public key is shared with other nodes, allowing for secure, authenticated communication.
- **Encryption and Signature:**
- **Encryption:** DMs are encrypted using the recipient’s public key, ensuring only the recipient with the corresponding private key can decrypt the message.
- **Digital Signatures:** DMs are signed with the sender’s private key before encryption, allowing the recipient to verify the sender’s identity and the message’s integrity using the sender’s public key.
- **Security Enhancements with PKC:**
- **Message Confidentiality and Integrity:** With PKC, each DM is encrypted and signed, ensuring that only the intended recipient can read the message, and verifying that it has not been tampered with.
### 3. Admin Messages: Enhanced Security with PKC and Session IDs
- **Key Exchange with DH Curve25519:**
- **Initial Key Exchange Setup:**
- **Key Generation:** A Diffie-Hellman (DH) key exchange occurs using Curve25519 upon first communication between nodes. This generates a shared secret for establishing a symmetric encryption key.
- **Hardware Support:** Curve25519 is supported in hardware, ensuring efficient and secure key exchanges.
- **Shared Secret:** The derived shared secret is used for all subsequent communications between the nodes.
- **Use of Shared Secret for Encryption:**
- **Symmetric Encryption:** Following the key exchange, messages are encrypted and decrypted using the shared secret with symmetric encryption algorithms like AES-CTR or AES-CCM.
- **Efficiency:** Symmetric encryption, especially when based on a secure DH exchange, balances security and performance, making it ideal for real-time applications.
- **Session ID for Admin Messages:**
- **Session ID Usage:** Session IDs are generated for each admin session and used as an additional value inside the encrypted packet. This ensures that each session is secure and unique.
- **Session Duration:** The session ID is valid only for a short duration (e.g., 300 seconds) and is discarded once the session ends or after the next control message is sent.
- **Security Enhancements with PKC and Session ID:**
- **Replay Attack Mitigation:** By utilizing session IDs, replay attacks are effectively mitigated. Old session IDs cannot be reused, ensuring that intercepted packets are invalidated.
- **Isolated Impact:** The use of session IDs confines any issues related to session management to admin messages, without affecting broader communication functions like DMs or Chat Channels.
### 4. Overall Security Architecture
- **Integration of PKC with Existing Systems:**
- **Direct Messages:** PKC enhances the security of DMs by providing encryption, authentication, and integrity through the use of asymmetric encryption and digital signatures.
- **Admin Messages:** The combination of PKC and session IDs secures admin-related operations, providing an additional layer of protection for critical functions.
- **Use of PSK with Existing Systems:**
- **Channels:** PSKs continue to be used for group communication, ensuring secure message exchanges within the channel.
- **Scalability and Performance:**
- **Efficient Use of Resources:** PKC for DMs leverages asymmetric encryption for secure communication, while PSKs for Chat Channels and session IDs for admin messages optimize resource consumption on the platform.
- **Memory Management:** The selective use of PKC, PSKs, and session IDs ensures that memory and computational resources are effectively managed, allowing the system to scale while maintaining high security.
## Conclusion
PSKs and the expanded use of PKC and session IDs across different MCU architectures—ESP32, nRF52, and ARM—demonstrates a tailored approach to security that balances performance, power consumption, and memory management. Each architecture's strengths are leveraged to ensure that secure communications are maintained without compromising the efficiency or scalability of the system. This approach provides robust security for a wide range of applications, from low-power wearable devices to more powerful, feature-rich systems.

23
docs/getting-started/flashing-firmware/esp32/cli-script.mdx
View file

@ -189,20 +189,33 @@ MAC: 24:6f:28:b5:36:71
Hard resetting via RTS pin...
```
### Navigate to Firmware
### Download Firmware
`cd` into the directory where you unzipped the latest release. For example:
1. Head to the [Meshtastic Downloads Page](/downloads) to download the latest firmware.
2. Scroll down to the **Firmware** section and select one of the following, depending on your preferences:
- **Download Stable**: For stable, well-tested releases.
- **Download Alpha**: For newer, experimental releases with the latest features.
3. Once redirected to the GitHub release page, scroll down to the "Assets" section and expand it. Identify the correct firmware for your device by its architecture (e.g., `firmware-esp32s3` for ESP32-S3-based devices like the Heltec V3).
4. Download the file and take note of the download location on your system (usually in your `~/Downloads` folder).
### Navigate to Firmware Directory
1. Open a terminal and navigate (`cd`) to the directory where your firmware was downloaded. The folder name typically matches the architecture and firmware version from the zip file. For example:
```shell title="Example"
cd ~/Downloads/firmware/
cd ~/Downloads/firmware-esp32s3-X.X.X.xxxxxxx/
```
:::note
Make sure to replace `esp32s3` and the version number with those corresponding to the file you downloaded.
:::
### Install/Update Firmware
Install or Update the device that you have by using the following commands according to your operating system:
Now, proceed with the instructions below for your operating system to install or update the firmware for your specific board:
:::caution
Be very careful to install the correct firmware file for your board. In particular, the popular 'T-BEAM' radio from TTGO is not called 'TTGO-Lora' (that is a different board). So don't install the 'TTGO-Lora' build on a TBEAM, it won't work correctly. If you flash the incorrect device firmware, it may appear to successfully complete, yet the device will usually become unresponsive, displaying a blank screen (if equipped). Attempt to flash the correct version. Please note, while these devices are quite resilient and damage is not always likely, there is a possibility of onboard radio and peripheral damage due to incorrect GPIO pin direction.
Be very careful to install the correct firmware file for your board. In particular, the popular 'T-BEAM' radio from TTGO is not called 'TTGO-Lora' (that is a different board). So don't install the 'TTGO-Lora' build on a TBEAM, it won't work correctly. If you flash the incorrect device firmware, it may appear to successfully complete, yet the device will usually become unresponsive, displaying a blank screen (if equipped). Attempt to flash the correct version. Please note, while these devices are quite resilient and damage is not always likely, there is a possibility of onboard radio and peripheral damage due to incorrect GPIO pin direction
:::
<Tabs

4
docs/getting-started/flashing-firmware/esp32/index.mdx
View file

@ -7,12 +7,12 @@ description: Instructions to flash Meshtastic firmware to an ESP32 chipset devic
---
:::info
The recommended method for firmware flashing is the [Web-Based Installer.](https://flasher.meshtastic.org)
The recommended method for firmware flashing is the [Web Flasher.](https://flasher.meshtastic.org)
:::
## Flashing Method for ESP32 Devices
1. The [Web-Based Installer](/docs/getting-started/flashing-firmware/esp32/web-flasher.mdx) requires either Chrome or Edge browsers but is an excellent choice for quickly flashing devices. **This method is highly recommended for firmware flashing, especially for new users of the project, as it is easy to use.**
1. The [Web Flasher](/docs/getting-started/flashing-firmware/esp32/web-flasher.mdx) requires either Chrome or Edge browsers but is an excellent choice for quickly flashing devices. **This method is highly recommended for firmware flashing, especially for new users of the project, as it is easy to use.**
2. The [CLI Script](/docs/getting-started/flashing-firmware/esp32/cli-script) is considered the "manual process" for flashing firmware.
3. Flashing your device using an [external serial adapter](/docs/getting-started/flashing-firmware/esp32/external-serial-adapter) should only be attempted as a last resort if no other method has been successful.

2
docs/getting-started/flashing-firmware/nrf52/update-booloader.mdx
View file

@ -63,7 +63,7 @@ pip install adafruit-nrfutil
4. In the terminal or command prompt, navigate to the directory where you downloaded the bootloader zip package and execute the following command, replacing /dev/ttyACM0 with the correct port for your device (Windows users might use COMx):
```bash
adafruit-nrfutil --verbose dfu serial --package <downloaded file>.zip -p /dev/ttyACM0 -b 115200 --singlebank --touch 1200
adafruit-nrfutil --singlebank --touch 1200 --verbose dfu serial --package <downloaded file>.zip -p /dev/ttyACM0 -b 115200
```
5. Once the process finishes, the update is complete. Your device is now running the latest bootloader version and you can proceed with [flashing the firmware](/docs/getting-started/flashing-firmware/nrf52/drag-n-drop/).

4
docs/hardware/antennas/testing.mdx
View file

@ -88,6 +88,4 @@ In summary - wavelengths in Europe fair well in plain sight, curve over not-so-t
## Discussion
To comment on / join in antenna range [Meshtastic discourse](https://meshtastic.discourse.group/t/antenna-improved-range/227/35?u=sens8tion)
There, you will also find reference to Meshtastic range achievements and aerial recommendations. (Note we've stopped short of making specific supplier aerial recommendations in this wiki.)
For further insights, join the conversation on antenna range and performance at [Meshtastic Discussions on GitHub.](https://github.com/orgs/meshtastic/discussions)

3
docs/hardware/devices/heltec-automation/index.mdx
View file

@ -14,7 +14,8 @@ Inexpensive basic ESP32-based boards.
| [LoRa32 V2.1](./lora32/?heltec=v2.1) | ESP32 | SX127x | 2.4GHz b/g/n | 4.2 | NO |
| [LoRa32 V3/3.1](./lora32/?heltec=v23) | ESP32-S3FN8 | SX1262 | 2.4GHz b/g/n | 5.0 | NO |
| [Wireless Stick Lite V3](./lora32/?heltec=Wireless+Stick+Lite+V3) | ESP32-S3FN8 | SX1262 | 2.4GHz b/g/n | 5.0 | NO |
| [Wireless Tracker](./lora32/?heltec=tracker) | ESP32-S3FN8 | SX1262 | 2.4GHz b/g/n | 5.0 | YES |
| [Wireless Tracker v1.0](./lora32/?heltec=tracker-v1.0) | ESP32-S3FN8 | SX1262 | 2.4GHz b/g/n | 5.0 | YES |
| [Wireless Tracker v1.1](./lora32/?heltec=tracker-v1.1) | ESP32-S3FN8 | SX1262 | 2.4GHz b/g/n | 5.0 | YES |
| [Wireless Paper](./lora32/?heltec=paper) | ESP32-S3FN8 | SX1262 | 2.4GHz b/g/n | 5.0 | NO |
## [Plug & Play Sensors](./sensor/)

82
docs/hardware/devices/heltec-automation/lora32/index.mdx
View file

@ -16,7 +16,8 @@ values={[
{label: 'LoRa32 V2.1', value: 'v2.1'},
{label: 'LoRa32 V3/V3.1', value:'v3'},
{label: 'Wireless Stick Lite V3', value:'Wireless Stick Lite V3'},
{label: 'Wireless Tracker', value: 'tracker'},
{label: 'Wireless Tracker v1.0', value: 'tracker-v1.0'},
{label: 'Wireless Tracker v1.1', value: 'tracker-v1.1'},
{label: 'Wireless Paper v1.0', value: 'paper-v1.0'},
{label: 'Wireless Paper v1.1', value: 'paper-v1.1'}
]}>
@ -57,10 +58,15 @@ Not recommended because of design issues! Support is being phased out. Use V3 in
## V3/V3.1
:::info
::::info
This device may have issues charging a connected battery if utilizing a USB-C to USB-C cable. It's recommended to use a USB-A to USB-C cable.
:::caution
Be careful when interacting with the USB-C port. This device does not have ESD protection for the CP2102 USB to UART bridge chip.
:::
::::
- **MCU:**
- ESP32-S3FN8 (WiFi & Bluetooth)
- **LoRa Transceiver:**
@ -108,7 +114,7 @@ Image Source: [Heltec](<https://resource.heltec.cn/download/WiFi_LoRa32_V3/HTIT-
- [Rokland](https://store.rokland.com/collections/heltec-products/products/heltec-wifi-lora-32v3)
- International
- [Heltec](https://heltec.org/project/wifi-lora-32-v3/)
- [AliExpress](https://www.aliexpress.us/item/3256805256690400.html)
- [AliExpress](https://www.aliexpress.us/item/3256807466584635.html)
</TabItem>
@ -161,13 +167,77 @@ Image Source: [Heltec](https://resource.heltec.cn/download/Wireless_Stick_Lite_V
- [Rokland](https://store.rokland.com/collections/heltec-products/products/heltec-wireless-stick-litev3-902-928-mhz)
- International
- [Heltec](https://heltec.org/project/wireless-stick-lite-v2/)
- [AliExpress](https://www.aliexpress.us/item/3256805256996507.html)
- [AliExpress](https://www.aliexpress.us/item/3256807466584635.html)
</TabItem>
<TabItem value="tracker">
<TabItem value="tracker-v1.0">
## Wireless Tracker
## Wireless Tracker v1.0
:::info
This device may have issues charging a connected battery if utilizing a USB-C to USB-C cable. It's recommended to use a USB-A to USB-C cable.
:::
- **MCU:**
- ESP32-S3FN8 (WiFi & Bluetooth)
- **LoRa Transceiver:**
- Semtech SX1262
- **Frequency Options:**
- 470 - 510 MHz
- 863 - 870 MHz
- 902 - 928 MHz
- **Connectors:**
- USB-C
- Antenna:
- Dedicated 2.4 GHz metal spring antenna for WiFi/Bluetooth
- U.FL/IPEX antenna connector for LoRa and GNSS
### Features
- Onboard 0.96-inch LCD display
- User and Reset Buttons
### Flashing
To flash ESP32-S3 devices like the Wireless Tracker, you typically need to place them in Espressif's firmware download mode. Use the "1200bps reset" button in the web flasher to do this. If this method does not work for any reason, you can follow the manual process below.
:::warning
Do not proceed unless an antenna is connected to avoid possible damage to the device's radio.
:::
The following process will manually place the device into the Espressif Firmware Download mode:
1. Unplug the device.
2. Press and hold the USER button.
3. Plug device in.
4. After 2-3 seconds, release the USER button.
With the device now in the Espressif Firmware Download mode, you can proceed with flashing using one of the supported flashing methods. It's generally recommended to use the [Web Flasher](https://flasher.meshtastic.org/). You can select "Heltec Wireless Tracker" from the device drop-down.
### Pin Map
![HT-Tracker_V1 Pin Map](/img/hardware/HT-Tracker_V1_Pin_Map.webp)
Image Source: [Heltec](https://heltec.org/project/wireless-tracker/)
### Resources
- Firmware file: `firmware-heltec-wireless-tracker-V1-0-X.X.X.xxxxxxx.bin`
- Purchase Links:
:::note
Heltec revised the Wireless Tracker schematics and released a V1.1, most devices being sold are now [V1.1.](/docs/hardware/devices/heltec-automation/lora32/?heltec=tracker-v1.1#resources-4)
:::
</TabItem>
<TabItem value="tracker-v1.1">
## Wireless Tracker v1.1
:::info
This device may have issues charging a connected battery if utilizing a USB-C to USB-C cable. It's recommended to use a USB-A to USB-C cable.

88
docs/hardware/devices/heltec-automation/lora32/peripherals.mdx
View file

@ -14,8 +14,6 @@ queryString="heltecESP32V3"
defaultValue="GPS"
values={[
{label: 'GPS Module', value: 'GPS'},
{label: 'Keyboard', value: 'Keyboard'},
{label: 'Buzzer', value: 'Buzzer'},
]}>
<TabItem value="GPS">
@ -23,10 +21,9 @@ values={[
### Introduction
This informational guide outlines the process of enhancing the Heltec ESP32 V3 board by integrating the GT-U7 GPS Module. The addition of this module provides precise GPS capabilities and a real-time clock (RTC), eliminating the need for WiFi or a smartphone for time tracking. This enhancement is particularly beneficial for the mesh, where tracking the duration since the last seen device is crucial.
However, it's important to note that the GPS module increases the power demand of your node. We'll address this by detailing how to incorporate a switch or an NPN 2N2222 transistor into your setup. This enables firmware-controlled power management, conserving battery life without sacrificing functionality.
This guide outlines the process of enhancing the Heltec ESP32 V3 board by integrating a GT-U7 GPS Module, although almost any supported GNSS module can be integrated in the same way. The addition of this module provides precise GPS capabilities and a real-time clock (RTC), eliminating the need for WiFi or a smartphone for time tracking. This enhancement is particularly beneficial for the mesh, where tracking the duration since the last seen device is crucial.
It is important to note that the GPS module increases the power demand of the node. This guide details the incorporation of a switch or an NPN 2N2222 transistor to enable firmware-controlled power management, conserving battery life without compromising functionality.
However, it's important to note that the GPS module increases the power demand of the node. This guide helps to address this by detailing how to incorporate a switch or an N-channel MOSFET into the setup. This enables additional firmware-controlled power management, conserving more battery life than the soft-sleep option without sacrificing functionality.
### Benefits
@ -35,35 +32,72 @@ It is important to note that the GPS module increases the power demand of the no
### Power Consumption Considerations
The GT-U7 module is known for its high power consumption, which can potentially shorten the battery lifespan of the node. To mitigate this, two approaches are recommended:
The GT-U7 module is known for its high power consumption, which can potentially shorten the battery lifespan of the node. To mitigate this, three approaches are recommended:
- **Manual Switch**: A simple on/off switch for the GPS module, allowing for manual power management.
- **NPN 2N2222 Transistor**: Facilitates automatic power control through the firmware, enabling the device to turn off the GPS module based on specific conditions or after a set period.
- **Through-hole MOSFET**: Facilitates automatic power control through the firmware, enabling the device to turn off the GPS module based on specific conditions or after a set period.
- **SMD MOSFET**: As above, but in a smaller volume and space envelope and with a marginally lower power consumption when in use.
### Notes on previous versions of these instructions
Previous versions of these instructions specified using a 2N2222a power transistor to control the power. In addition, it showed the transistor being used to control the power from the "high side" (i.e. between the Heltec Vcc and the GPS Vin). While this method will work for some boards, it is not ideal to use an NPN transistor to switch the "high side" of the load like this.
The current version of the guide now instructs using either a surface mount or through-hole MOSFET to switch the ground ("low side") of the GPS module. This allows the MOSFET to operate in the fully saturated condition, and MOSFETs will have a lower power consumption themselves than a power transistor. As the ground for the two parts will now be isolated, it is important that no parts of the GPS module, the antenna or any shielding shell are able to contact the ground for the Heltec board.
The essential connections for the NPN MOSFET are shown in the schematic below.
![Heltec_ESP32V3_N-Mosfet_Schematic](/img/hardware/heltec/Heltec_ESP32V3_N-Mosfet_Schematic.webp)
### Materials Needed
- Heltec ESP32 V3 board
- GT-U7 GPS Module
- NPN 2N2222 Transistor
- (Optional) Through-hole MOSFET (note: these are harder to find in small packages than SMD MOSFETS, but any that can operate on 3.3V will be suitable, e.g. 2N7000, BS170)
- (Optional) Surface Mount MOSFET (note: any suitable N-channel MOSFET can be used, e.g. SI2312, AO3400a, 2N7002)
- Wires and soldering equipment
- (Optional) Switch for manual power control
### Instructions
### Instructions (Through-Hole MOSFET)
1. Solder a cable from the TXD slot on the GPS module to GPIO 48 on Heltec board. (You may choose your own GPIO pin)
2. Solder a cable from the RXD slot on the GPS module to GPIO 47 on Heltec board. (You may choose your own GPIO pin)
3. Solder a cable from the GND slot on the GPS module to GND pin on Heltec board.
4. Solder a cable from left leg of NPN 2N2222 Transistor to VCC skit on GPS module.
5. Solder a cable from Right leg of NPN 2N2222 Transistor to 3V/5V pin on Heltec board.
6. Solder a cable from Middle leg of NPN 2N2222 Transistor to GPIO 48 of Heltec board. (You may choose your own GPIO pin)
Note: these instructions assume a 2N7000 MOSFET is used. For other parts, always check the data sheet!
1. Solder a wire from the TXD pin on the GPS module to GPIO 48 on Heltec board. (Another GPIO pin may be chosen)
2. Solder a wire from the RXD pin on the GPS module to GPIO 47 on Heltec board. (Another GPIO pin may be chosen)
3. Solder a wire from the VCC pin on the GPS module to 3V/5V pin pin on Heltec board.
4. Solder a wire from Right leg (lead 3, Drain) of NPN MOSFET to GND on GPS module.
5. Solder a wire from Left leg (lead 1, Source) of NPN MOSFET to GND on Heltec board.
6. Solder a wire from Middle leg (lead 2, Gate) of NPN MOSFET to GPIO 48 of Heltec board. (Another GPIO pin may be chosen)
7. Go to Meshtastic app > Radio Configurations > Position
8. Set GPS_RX_PIN to 48 (This will communicate to the TXD slot on the GPS)
9. Set GPS_TX_PIN to 47 (This will communicate to the RXD slot on the GPS)
8. Set GPS_RX_PIN to 48 (This will communicate to the TXD pin on the GPS)
9. Set GPS_TX_PIN to 47 (This will communicate to the RXD pin on the GPS)
10. Set PIN_GPS_EN to 46 (This will allow the meshtastic firmware to turn off the power on the GPS board with the user button of the Heltec Board by pressing it 3 times)
### Wiring Diagram
### Wiring Diagram - Through-Hole
![HeltecESP32V3-gps-module](/img/hardware/HeltecESP32V3-gps-module.webp)
![HeltecESP32V3-gps-module](/img/hardware/heltec/Heltec_ESP32V3_GPS_module_low-side.webp)
### Instructions (Surface Mount MOSFET)
Note: these instructions assume an SI2312 MOSFET is used. For other parts, always check the data sheet!
1. Solder a wire from the TXD pin on the GPS module to GPIO 48 on Heltec board. (Another GPIO pin may be chosen)
2. Solder a wire from the RXD pin on the GPS module to GPIO 47 on Heltec board. (Another GPIO pin may be chosen)
3. Solder a wire from the GND pin on the GPS module to middle pin of the SI 2312 MOSFET
4. Solder a wire from the VCC pin of the GPS module to o 3V/5V pin on Heltec board.
5. Solder a wire from Left leg of SI2312 MOSFET to GPIO 46 on the Heltec board.
6. Solder a wire from Right leg of SI2312 MOSFET to the empty solder spot on the heltec board (see pictures).
7. Go to Meshtastic app > Radio Configurations > Position
8. Set GPS_RX_PIN to 48 (This will communicate to the TXD pin on the GPS)
9. Set GPS_TX_PIN to 47 (This will communicate to the RXD pin on the GPS)
10. Set PIN_GPS_EN to 46 (This will allow the meshtastic firmware to turn off the power on the GPS board with the user button of the Heltec Board by pressing it 3 times)
11. Ensure that the ground on the GPS module does not contact the ground of the Heltec board, or any other component linked to the Heltec ground. This includes antenna covers, battery connectors, etc. Failure to ensure they are separated may lead to the MOSFET being bypassed.
### Photographs and Diagrams - SMD
![HeltecESP32V3-gps-module](/img/hardware/heltec/Heltec_ESP32V3_SMDMosfetDiagram.webp)
![HeltecESP32V3-gps-module](/img/hardware/heltec/Heltec_ESP32V3_SMDMosfetInPlace.webp)
![HeltecESP32V3-gps-module](/img/hardware/heltec/Heltec_ESP32V3_SMDMOSFET_GPSInPlace.webp)
### Troubleshooting Tips
@ -75,21 +109,7 @@ If the location is not accurate, walk around to allow the GPS to properly lock o
### Conclusion
By following this guide, you can enhance your Heltec ESP32 V3 board with valuable GPS capabilities and an RTC, while effectively managing power consumption. Whether for a hobby project or a more serious application, these additions significantly expand the potential of your device.
</TabItem>
<TabItem value="Keyboard">
## Keyboard
Coming Soon
</TabItem>
<TabItem value="Buzzer">
## Buzzer
Coming Soon
By following this guide, the Heltec ESP32 V3 board can be enhanced with valuable GPS capabilities and an RTC, while effectively managing power consumption. Whether for a hobby project or a more serious application, these additions significantly expand the potential of the device.
</TabItem>
</Tabs>

2
docs/hardware/devices/heltec-automation/sensor/index.mdx
View file

@ -38,7 +38,7 @@ values={[
:::info
Capsule Sensor V3 uses WirelessBoot mode to upload firmware, exchange information, and print logs through WiFi.
That is, whether you update the firmware locally or via the Web, You need to get the device into WirelssBoot state first.
That is, whether you update the firmware locally or via the Web, You need to get the device into WirelessBoot state first.
:::
Refer to this link for how to upload firmware for Capsule Sensor V3: [**Wireless Boot**](https://docs.heltec.org/en/node/esp32/capsule_sensor_v3/wireless_boot.html#).

20
docs/hardware/devices/index.mdx
View file

@ -126,7 +126,8 @@ Inexpensive basic ESP32-based boards.
| [LoRa32 V2.1](./heltec-automation/lora32/?heltec=v2.1) | ESP32 | SX127x | 2.4GHz b/g/n | 4.2 | NO |
| [LoRa32 V3/3.1](./heltec-automation/lora32/?heltec=v23) | ESP32-S3FN8 | SX1262 | 2.4GHz b/g/n | 5.0 | NO |
| [Wireless Stick Lite V3](./heltec-automation/lora32/?heltec=Wireless+Stick+Lite+V3) | ESP32-S3FN8 | SX1262 | 2.4GHz b/g/n | 5.0 | NO |
| [Wireless Tracker](./heltec-automation/lora32/?heltec=tracker) | ESP32-S3FN8 | SX1262 | 2.4GHz b/g/n | 5.0 | YES |
| [Wireless Tracker v1.0](./heltec-automation/lora32/?heltec=tracker-v1.0) | ESP32-S3FN8 | SX1262 | 2.4GHz b/g/n | 5.0 | YES |
| [Wireless Tracker v1.1](./heltec-automation/lora32/?heltec=tracker-v1.1) | ESP32-S3FN8 | SX1262 | 2.4GHz b/g/n | 5.0 | YES |
| [Wireless Paper](./heltec-automation/lora32/?heltec=paper) | ESP32-S3FN8 | SX1262 | 2.4GHz b/g/n | 5.0 | NO |
### [Plug & Play Sensors](./heltec-automation/sensor/)
@ -189,6 +190,8 @@ Meshtastic offers support for Raspberry Pi devices through our Linux native plat
### SenseCap
The SenseCAP product line offers a comprehensive range of solutions for both hobbyists and industrial users, featuring the T1000-E card tracker, an IP65-rated, ready-to-go Meshtastic device, and the Indicator with a 4-inch touchscreen driven by ESP32-S3 and RP2040 Dual-MCU, coming soon.
| Name | MCU | Radio | WiFi | BT | GPS |
| ------------------------------------------------------------- | ------------- | ------ | ---- | --- | --- |
| [Card Tracker T1000-E](./seeed-studio/sensecap/card-tracker/) | nRF52840 | LR1110 | NO | 5.1 | YES |
@ -219,6 +222,15 @@ All-in-one development device with LoRa, WiFi, BT, touchscreen, accelerometer, g
| :------------------- | :--------------- | :----- | :--: | :-: | :-: |
| [unPhone](./unPhone) | ESP32-S3-WROOM-1 | RF950W | YES | 5.0 | NO |
### [Seeed Wio-WM1110](./seeed-studio/wm1110)
nRF52840-based development boards with GPS, and multiple ports to attach sensors.
| Name | MCU | Radio | WiFi | BT | GPS |
| :------------------------------------------------------------------------ | :------- | :----- | :--: | :-: | :-: |
| [Seeed Wio-WM1110 Dev Kit](./seeed-studio/wm1110?wm1110=wio-sdk-wm1110) | nRF52840 | LR1110 | YES | 5.3 | YES |
| [Seeed Wio Tracker 1110](./seeed-studio/wm1110?wm1110=wio-tracker-wm1110) | nRF52840 | LR1110 | YES | 5.3 | YES |
## [Chatter](./chatter)
DIY kit with ESP32, LoRa chip, and optional GPS. Designed for STEM education.
@ -226,3 +238,9 @@ DIY kit with ESP32, LoRa chip, and optional GPS. Designed for STEM education.
| Name | MCU | Radio | WiFi | BT | GPS |
| :------------------- | :---- | :----- | :--: | :-: | :-: |
| [Chatter](./chatter) | ESP32 | LLCC68 | YES | 4.2 | No |
### Radio Master
| Name | MCU | Radio | WiFi | BT | GPS |
| :-------------------- | :--------------- | :----- | :--: | :-: | :-: |
| Bandit Nano ExpressLRS 900 | ESP32 | SX1276 + SKY66122 PA/LNA +30db TX, +16db RX ) | ? | YES | NO |

2
docs/hardware/devices/lilygo/lora/index.mdx
View file

@ -226,7 +226,7 @@ Early versions of these boards contained the wrong component in the LiPo battery
- ESP32-S3 (WiFi & Bluetooth)
- **LoRa Transceiver**
- Semtech SX1262
- Semtech 1276
- Semtech SX1276
- Semtech SX1280 with PA (Region LORA_24 worldwide use)
- **Frequency options**
- 868 MHz

42
docs/hardware/devices/lilygo/tbeam/buttons.mdx
View file

@ -5,6 +5,19 @@ sidebar_label: Buttons
sidebar_position: 1
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
<Tabs
groupId="t-beam buttons"
queryString="t-beam"
defaultValue="t-beam"
values={[
{label: 'T-Beam', value: 't-beam'},
{label: 'T-Beam Supreme', value:'t-beam-supreme'},
]}>
<TabItem value="t-beam">
## Functionality
- **Power Button (left):**
@ -23,3 +36,32 @@ sidebar_position: 1
width="200"
align="center-right"
/>
</TabItem>
<TabItem value = "t-beam-supreme">
:::info
Be aware that the button layout differs on the T-Beam Supreme model.
:::
## Functionality
- **Power Button (middle):**
- **Long press:** Powers the device on or off.
- **Reset Button (right):**
- **Single press:** Resets the device.
- **User/Program Button (left):**
- **Long press:** Will signal the device to shutdown after 5 seconds.
- **Single press:** Changes the information page displayed on the device's screen.
- **Double press:** Sends an adhoc ping of the device's position to the network.
- **Triple press:** Disables the device's GPS. Repeat to re-enable. (_This will be indicated on both information screen pages on the device's display as shown below_)
<img src="/img/hardware/GPS-disabled.webp" width="200" align="center-left" />
<img
src="/img/hardware/GPS-disabled-by-button.webp"
width="200"
align="center-right"
/>
</TabItem>
</Tabs>

165
docs/hardware/devices/rak-wireless/wisblock/base-boards.mdx
View file

@ -37,17 +37,33 @@ The RAK5005-O is no longer in production. It is recommended to use the RAK19007
- (x1) Reset Button
- It may be possible to add a user button using the [13002 IO module](https://store.rakwireless.com/collections/wisblock-interface/products/adapter-module-rak13002).
- **Connectors**
- Connector for 3.7v LiPo battery (with charge controller)
- Connector for 5v solar panel (max 5.5v)
- I<sup>2</sup>C, UART, GPIOs and analog input accessible with solder contacts
- Micro USB port for debugging and power
- JST PHR-2 connector for 3.7v LiPo battery (with charge controller)
- JST-ZHR-2 connector for 5v solar panel (max 5.5v)
- I<sup>2</sup>C, UART, GPIOs and analog input accessible with solder contacts
- Micro USB port for debugging and power
- **Screen Support**
- OLED screen support (OLED screen sold separately)
- OLED screen support (OLED screen sold separately)
:::note
The RAK5005 (without the -O) is not compatible.
:::
### Connectors Diagram
<img
alt="RAK19001-O Connectors"
src="/img/hardware/rak5005-0_connectors.web"
style={{ zoom: "50%" }}
/>
### Voltages
- JST PHR-2 connector for 3.7v LiPo battery.
- Charge controller max charge rate is 500mAh.
- Minimum input voltage for charging is 3.3v, maximum 4.3v.
- JST ZHR-2 connector for 5v solar panel.
- Minimum input voltage to charge is 4.4v, maximum 5.5v.
Further information on the RAK5005-O can be found on the [RAK Documentation Center](https://docs.rakwireless.com/Product-Categories/WisBlock/RAK5005-O/Overview/#product-description).
<img
@ -63,23 +79,39 @@ Further information on the RAK5005-O can be found on the [RAK Documentation Cent
## RAK19007
- [RAK19007](https://store.rakwireless.com/products/rak19007-wisblock-base-board-2nd-gen) - WisBlock Base Board (2nd Generation, an upgrade to the RAK5005-O)
- **Slots**
- (x1) Core Module slot
- (x1) WisBlock IO Module slot
- (x4) WisBlock Sensor Module slots
- **Buttons**
- (x1) Reset Button
- To add a user button, you can utilize the AIN1 pin, which is exposed as pin 31 in the firmware.
- **Connectors**
- Connector for 3.7v LiPo battery (with charge controller)
- Connector for 5v solar panel (max 5.5v)
- I<sup>2</sup>C, UART, BOOT and GPIOs accessible with solder contacts
- USB-C port for debugging and power
- **Screen Support**
- OLED screen support (OLED screen sold separately)
- **Slots**
- (x1) Core Module slot
- (x1) WisBlock IO Module slot
- (x4) WisBlock Sensor Module slots
- **Buttons**
- (x1) Reset Button
- To add a user button, you can utilize the AIN1 pin, which is exposed as pin 31 in the firmware.
- **Connectors**
- JST PHR-2 connector for 3.7v LiPo battery.
- JST ZHR-2 connector for 5v solar panel.
- I<sup>2</sup>C, UART, BOOT and GPIOs accessible with solder contacts
- USB-C port for debugging and power
- **Screen Support**
- OLED screen support (OLED screen sold separately)
Further information on the RAK19007 can be found on the [RAK Documentation Center](https://docs.rakwireless.com/Product-Categories/WisBlock/RAK19007/Overview/#product-description).
### Connectors Diagram
<img
alt="RAK19007 Connectors"
src="/img/hardware/rak19007_connectors.webp"
style={{ zoom: "50%" }}
/>
### Voltages
- JST PHR-2 connector for 3.7v LiPo battery.
- Charge controller max charge rate is 350mAh.
- Minimum input voltage for charging is 3.3v, maximum 4.3v.
- JST ZHR-2 connector for 5v solar panel.
- Minimum input voltage to charge is 4.4v, maximum 5.5v.
### Resources
- Purchase Links:
@ -96,22 +128,38 @@ Further information on the RAK19007 can be found on the [RAK Documentation Cente
## RAK19003
- [RAK19003](https://store.rakwireless.com/products/wisblock-base-board-rak19003) - WisBlock's Mini Base Board.
- **Slots**
- (x1) Core Module slot
- (x2) WisBlock Sensor Module slots
- **Buttons**
- (x1) Reset Button
- There is a 3rd party sensor module that breaks out the user button, available [here](https://www.etsy.com/de/listing/1254963521/mini-io-expansion-board-for-rak-wireless).
- **Connectors**
- Connector for 3.7v LiPo battery (with charge controller)
- Connector for 5v solar panel (max 5.5v)
- I<sup>2</sup>C, UART and BOOT headers accessible with solder contacts
- USB-C port for debugging and power
- **Screen Support**
- OLED screen support (OLED screen sold separately)
- **Slots**
- (x1) Core Module slot
- (x2) WisBlock Sensor Module slots
- **Buttons**
- (x1) Reset Button
- There is a 3rd party sensor module that breaks out the user button, available [here](https://www.etsy.com/de/listing/1254963521/mini-io-expansion-board-for-rak-wireless).
- **Connectors**
- JST PHR-2 connector for 3.7v LiPo battery.
- JST ZHR-2 connector for 5v solar panel.
- I<sup>2</sup>C, UART and BOOT headers accessible with solder contacts
- USB-C port for debugging and power
- **Screen Support**
- OLED screen support (OLED screen sold separately)
Further information on the RAK19003 can be found on the [RAK Documentation Center](https://docs.rakwireless.com/Product-Categories/WisBlock/RAK19003/Overview/#product-description)
### Connectors Diagram
<img
alt="RAK19003 Connectors"
src="/img/hardware/rak19003_connectors.webp"
style={{ zoom: "50%" }}
/>
### Voltages
- JST PHR-2 connector for 3.7v LiPo battery.
- Charge controller max charge rate is 350mAh.
- Minimum input voltage for charging is 3.3v, maximum 4.3v.
- JST ZHR-2 connector for 5v solar panel.
- Minimum input voltage to charge is 4.4v, maximum 5.5v.
### Resources
- Purchase Links:
@ -132,26 +180,45 @@ Further information on the RAK19003 can be found on the [RAK Documentation Cente
## RAK19001
- [RAK19001](https://store.rakwireless.com/products/rak19001-wisblock-dual-io-base-board) - WisBlock's Dual IO Base Board.
- **Slots**
- (x1) Core Module slot
- (x2) WisBlock IO Module slot
- (x6) WisBlock Sensor Module slots
- **Buttons**
- (x1) Reset Button
- (x1) User-defined push button switch
- (x1) Battery selector switch
- On this board the PIN for user button (IO5) is available as a solder contact on the upper header row.
- **Connectors**
- Connector for 3.7v LiPo battery (with charge controller)
- Connector for 5v solar panel (max 5.5v)
- Separate connector for non-rechargeable batteries
- I<sup>2</sup>C, SPI, UART, BOOT and GPIOs accessible with solder contacts
- USB-C port for debugging and power
- **Screen Support**
- OLED screen support (OLED screen sold separately)
- **Slots**
- (x1) Core Module slot
- (x2) WisBlock IO Module slot
- (x6) WisBlock Sensor Module slots
- **Buttons**
- (x1) Reset Button
- (x1) User-defined push button switch
- (x1) Battery selector switch
- On this board the PIN for user button (IO5) is available as a solder contact on the upper header row.
- **Connectors**
- JST PHR-2 connector for 3.7v LiPo battery (with charge controller)
- JST ZHR-2 connector for 5v solar panel (max 5.5v)
- Separate FGH20005-S02M2W1B connector for non-rechargeable batteries
- I<sup>2</sup>C, SPI, UART, BOOT and GPIOs accessible with solder contacts
- USB-C port for debugging and power
- **Screen Support**
- OLED screen support (OLED screen sold separately)
Further information on the RAK19001 can be found on the [RAK Documentation Center](https://docs.rakwireless.com/Product-Categories/WisBlock/RAK19001/Overview/#product-description).
### Connectors Diagram
<img
alt="RAK19001 Connectors"
src="/img/hardware/rak19001_connectors.webp"
style={{ zoom: "50%" }}
/>
### Voltages
- JST PHR-2 connector for 3.7v LiPo battery.
- Charge controller max charge rate is 500mAh.
- Minimum input voltage for charging is 3.3v, maximum 4.3v.
- JST ZHR-2 connector for 5v solar panel.
- Minimum input voltage to charge is 4.4v, maximum 5.5v.
- FGH20005-S02M2W1B connector for non-rechargable battery.
- Minimum required is 3.3v, typical 3.7v, maximum 5.5v.
- Active battery is selected with the battery selector switch.
### Resources
- Purchase Links:

5
docs/hardware/devices/seeed-studio/index.mdx
View file

@ -7,13 +7,16 @@ sidebar_position: 6
Seeed Studio is a tech company focused on Edge AI and IoT. With the mission of "making technology accessible for all", Seeed Studio has been embracing open source since DAY 1. Seeed works closely with the Meshtastic community to bring easy-to-use, affordable products to community members. By listening to the voices, communicating and collaborating closely with innovators in this community, iterations of products and new services are brought to life.
### SenseCap
### [SenseCap](./sensecap/)
The SenseCAP product line offers a comprehensive range of solutions for both hobbyists and industrial users, featuring the T1000-E card tracker, an IP65-rated, ready-to-go Meshtastic device, and the Indicator with a 4-inch touchscreen driven by ESP32-S3 and RP2040 Dual-MCU, coming soon.
| Name | MCU | Radio | WiFi | BT | GPS |
| ------------------------------------------------ | ------------- | ------ | ---- | --- | --- |
| [Card Tracker T1000-E](./sensecap/card-tracker/) | nRF52840 | LR1110 | NO | 5.1 | YES |
| [SenseCAP Indicator](#) (coming soon) | ESP32, RP2040 | - | - | - | - |
### [Wio-WM1110](./wm1110)
nRF52840-based development boards with GPS, and multiple ports to attach sensors.

7
docs/hardware/devices/seeed-studio/sensecap/card-tracker.mdx
View file

@ -10,7 +10,7 @@ SenseCAP T1000-E is a high-performance tracker designed for Meshtastic. As small
### Specifications
- **MCU**
- Nordic nRF52840 (WiFi & Bluetooth)
- Nordic nRF52840 (supports Bluetooth)
- **LoRa Transceiver**
- Semtech LR1110
- **Frequency options**
@ -34,8 +34,9 @@ SenseCAP T1000-E is a high-performance tracker designed for Meshtastic. As small
- Purchase Links:
- International
- [Seeed Studio](https://www.seeedstudio.com/SenseCAP-Card-Tracker-T1000-E-for-Meshtastic-p-5913.html)
- [User Guide](https://wiki.seeedstudio.com/sensecap_t1000_e/)
#### Images
![SenseCAP Card Tracker T1000-E for Meshtastic](/img/hardware/seeed/card_tracker.webp)
![SenseCAP Card Tracker T1000-E Dimensions](/img/hardware/seeed/T1000-E.webp)
![SenseCAP Card Tracker T1000-E for Meshtastic](/img/hardware/seeed/t1000-e-meshtastic.webp)
![SenseCAP Card Tracker T1000-E Dimensions](/img/hardware/seeed/t1000-e-hardware.webp)

2
docs/hardware/devices/seeed-studio/wm1110/index.mdx
View file

@ -70,7 +70,7 @@ The LR1110 GNSS functionality does not yet work. Seeed recommends at Grove - GPS
## Wio Tracker 1110 Dev Kit for Meshtastic
- **MCU**
- Nordic nRF52840 (WiFi & Bluetooth)
- Nordic nRF52840 (BLE 5.3)
- **LoRa Transceiver**
- Semtech LR1110
- **Frequency options**

2
docs/legal/licensing-and-trademark.mdx
View file

@ -154,6 +154,8 @@ The following uses of the Meshtastic Trademarks are not approved under any fores
These guidelines (except for trademark licenses executed for non software goods) may be amended from time to time at the discretion of Meshtastic and such changes will be effective ten (10) days after the changes are posted. Meshtastic may provide you with notice of such changes, but need not do so. You are responsible for checking this site for any changes.
In the past, community members have inquired whether it is permissible to use the Meshtastic Trademarks, including the term "Meshtastic" in software product names. You **may not** use any of Meshtastic Trademarks in either the primary or secondary branding of any third party product or service names. For example, you may not name a product either "BigCo Project Thing", "BigCo distribution of Project", or any similar kind of name where Project is any Meshtastic mark or project name.
## Proper Trademark Use
One of the purposes of Meshtastic is to encourage the use of Meshtastic software to enable the public to come to trust the use of Meshtastic Trademarks. To achieve this purpose it is important that Meshtastic can quickly be identified. Meshtastic has chosen the Meshtastic Logo to identify such software and is granting usage rights in the Meshtastic Logo (and the other Meshtastic Trademarks) as previously described in this document in order to assure widespread availability.

2
docs/legal/privacy.mdx
View file

@ -14,6 +14,6 @@ If you opt-in to analytics on the Android app (thank you - that helps us know wh
The search engine for this website is provided by Algolia, please see their [privacy policy](https://www.algolia.com/policies/privacy) for details of what information they collect.
This is an open-source project run by hobbyists, and we try to be completely transparent. If you have questions on this policy, please [post on the forum](https://meshtastic.discourse.group/), and we'll reply/clarify/correct.
This is an open-source project run by hobbyists, and we try to be completely transparent. If you have questions on this policy, please [post on the Meshtastic Discussions page](https://github.com/orgs/meshtastic/discussions), and we'll reply/clarify/correct.
Keep being awesome!

4
docs/software/android/installation.mdx
View file

@ -41,8 +41,6 @@ The minimum Android version is 5.0 (Lollipop 2014, first BLE support), however A
There is a Play Store [testing program](https://play.google.com/apps/testing/com.geeksville.mesh) with the latest cutting edge changes, though this may come with extra bugs.
It is recommended that you follow the [Meshtastic Discourse Alpha Testers](https://meshtastic.discourse.group/c/development/alpha-testers) channel if you decide to join.
_Google Play and the Google Play logo are trademarks of Google LLC._
### Install by Sideloading
@ -73,4 +71,4 @@ If you do sideload, you may have to give your browser permissions to run a packa
Obtainium allows you to install and update Open-Source Apps directly from their releases pages, and receive notifications when new releases are made available.
\*Alpha releases include the latest cutting edge changes which may come with extra bugs. It is recommended that you follow the [Meshtastic Discourse Alpha Testers](https://meshtastic.discourse.group/c/development/alpha-testers) channel if you decide to use these versions.
\*Alpha releases include the latest cutting edge changes which may come with extra bugs. It is recommended that you follow the Meshtastic Alpha Testers Channel on [Discord](https://discord.com/invite/ktMAKGBnBs) if you decide to use these versions.

141
docs/software/android/usage.mdx
View file

@ -5,6 +5,11 @@ sidebar_label: Usage
sidebar_position: 2
---
import PositionPrecision from "@site/docs/blocks/_position-precision.mdx";
import Link from "@docusaurus/Link";
import ThemedImage from "@theme/ThemedImage";
import useBaseUrl from "@docusaurus/useBaseUrl";
## Introduction
The Meshtastic Android app handles the communication and can show the location of everyone in your private group. Each member of your private mesh can see the location and distance of members and text messages sent to your group chat.
@ -35,22 +40,54 @@ To find devices to connect via Bluetooth click the "+" button on the bottom righ
The cloud icon at the top right corner indicates if you are connected to a device. This currently has three states:
![Not connected](/img/android/android-cloud-cross.webp) Cloud with a slash through it: No device connected to the application.
<center>
<ThemedImage
alt="Not connected"
className="max-h-14"
sources={{
light: useBaseUrl("/img/android/android-no-ack_lt.webp"),
dark: useBaseUrl("/img/android/android-no-ack_dk.webp"),
}}
/>
</center>
Cloud with a slash through it: No device connected to the application.
![Connected](/img/android/android-cloud-tick.webp) Cloud with a tick in it: Device connected to the application.
<center>
<ThemedImage
alt="Connected"
className="max-h-14"
sources={{
light: useBaseUrl("/img/android/android-imp-ack_lt.webp"),
dark: useBaseUrl("/img/android/android-imp-ack_dk.webp"),
}}
/>
</center>
Cloud with a check in it: Device connected to the application.
![Sleeping](/img/android/android-cloud-up.webp) Cloud with an up arrow in it: Device is connected, but currently sleeping or out of range.
<center>
<ThemedImage
alt="Sleeping"
className="max-h-14"
sources={{
light: useBaseUrl("/img/android/android-waiting_lt.webp"),
dark: useBaseUrl("/img/android/android-waiting_dk.webp"),
}}
/>
</center>
Cloud with an up arrow in it: Device is connected, but currently sleeping or out
of range.
## Common tasks
### Set your region
In order to start communicating with your mesh, you must select a region. This setting controls which frequency range your device uses and should be set according to your location. See [Region Settings](https://meshtastic.org/docs/getting-started/initial-config#set-regional-settings) for a list of region codes and their meanings.
- Tap on the "Region" dropdown in the top-right corner and make the appropriate selection.
### Change your name
Edit the "Your name", e.g. to be "Mike Bird". This is the name that other people will see, so make it unique within your group. The initials e.g. "MB" should also be unique and will be used to identify you in the message history and on the device screens. Initials, or "short name", can be customized in the Radio configuration - User settings. The four characters displayed after your initials cannot be changed. These are the last four hex digits of the device MAC address. Devices with unset names will display these four characters as the device short name.
Edit the "Your name", e.g. to be "Mike Bird". This is the name that other people will see, so make it unique within your group. The initials e.g. "MB" should also be unique and will be used to identify you in the message history and on the device screens. Initials, or "short name", can be customized in the Radio configuration - User settings. The four characters displayed after your initials cannot be changed. These are the last four hex digits of the device MAC address. Devices with unset names will display these four characters as the device short name.
[![Changing device name](/img/android/android-settings-mike-sm.webp)](/img/android/android-settings-mike.webp)
@ -72,7 +109,7 @@ You will see a warning because changing the Channel will break communications wi
[![Do you want to change the channel?](/img/android/android-new-channel-sm.webp)](/img/android/android-new-channel.webp)
The app will generate a new QR code on the screen. This encodes the channel details and a random 256-bit key for sharing with the new group. You can share the QR code with other Meshtastic users, or use the Share button and share the link via chat message, SMS, or email. The link is a very long code, for example: https://www.meshtastic.org/d/#CgUYAyIBAQ
The app will generate a new QR code on the screen. This encodes the channel details and a random 256-bit key for sharing with the new group. You can share the QR code with other Meshtastic users, or use the Share button and share the link via chat message, SMS, or email. The link is a very long code, for example: https://www.meshtastic.org/d/#CgUYAyIBAQ
### Join a channel
@ -83,10 +120,11 @@ The app will generate a new QR code on the screen. This encodes the channel det
2. If the channel is shared from a file or link using the `Share` button, you can click on the file or link and you need to choose "Open with Meshtastic".
:::info If a QR or URL opens a webpage instead of the APP or "Open with Meshtastic" is not an option:
1. Go to Android Settings > Apps > Default apps > Meshtastic > Opening links
2. Make sure you have in "links/web address": www.meshtastic.org
3. If you see the option "Open the supported links", make sure it is enabled.
:::
:::
[![Accept new channel](/img/android/android-accept-channel-c.webp)](/img/android/android-accept-channel.webp)
@ -104,16 +142,18 @@ You can test changing channels with the QR code shown below.
### Adjust a channel
You can change the following settings by tapping on the name of an existing channel:
1. MQTT Uplink
2. MQTT Downlink
3. Position precision value
3. Position enabled
4. Precise location (if position is enabled)
5. Position precision (if precise location is disabled)
#### Position Precision
The precision levels currently used in the app correspond to the following values:
- HIGH_PRECISION (32), full precision
- MED_PRECISION (16), around ±350 meters
- LOW_PRECISION (11), around ±11 kilometers
- DISABLED (0), location data is never sent over the given channel
The precision levels currently used in the app correspond the values in the table below. These can be thought of as the radius of a circle around a point (not your current location) which you are within.
<PositionPrecision />
### Send a message
@ -126,17 +166,76 @@ The message window operates like most messaging apps. Note that your primary cha
With LoRa (or any radio) there is some uncertainty that the message has been received, so there is a confirmation built-in to the protocol. There are small icons shown to the right of the messages you send:
- Cloud with an up arrow: the message is queued in the app, waiting to be handed to the device.
- Cloud only: the device received the message from the app, and it has been sent and transmitted via LoRa.
- Cloud with a check mark: received at least one node's acknowledgement response. Confirmations could be from any one device.
- Person with a check mark - The intended recipient node of your direct message acknowledged the message.
- Cloud crossed out: the initial sender did not receive any confirmation within a certain timeout.
<center>
<ThemedImage
alt="cloud up"
className="max-h-18"
sources={{
light: useBaseUrl("/img/android/android-waiting_lt.webp"),
dark: useBaseUrl("/img/android/android-waiting_dk.webp"),
}}
/>
</center>
Cloud with an up arrow: the message is queued in the app, waiting to be handed
to the device.
<center>
<ThemedImage
alt="cloud only"
className="max-h-18"
sources={{
light: useBaseUrl("/img/android/android-sent_lt.webp"),
dark: useBaseUrl("/img/android/android-sent_dk.webp"),
}}
/>
</center>
- Cloud only: the device received the message from the app, and it has been sent
and transmitted via LoRa.
<center>
<ThemedImage
alt="Cloud with a check mark"
className="max-h-18"
sources={{
light: useBaseUrl("/img/android/android-imp-ack_lt.webp"),
dark: useBaseUrl("/img/android/android-imp-ack_dk.webp"),
}}
/>
</center>
- Cloud with a check mark: received at least one node's acknowledgement
response. Confirmations could be from any one device.
<center>
<ThemedImage
alt="Person with a check mark"
className="max-h-18"
sources={{
light: useBaseUrl("/img/android/android-DM-ack_lt.webp"),
dark: useBaseUrl("/img/android/android-DM-ack_dk.webp"),
}}
/>
</center>
- Person with a check mark - The intended recipient node of your direct message
acknowledged the message.
<center>
<ThemedImage
alt="Cloud crossed out"
className="max-h-18"
sources={{
light: useBaseUrl("/img/android/android-no-ack_lt.webp"),
dark: useBaseUrl("/img/android/android-no-ack_dk.webp"),
}}
/>
</center>
- Cloud crossed out: the initial sender did not receive any confirmation within
a certain timeout.
By default there is no long-term store-and-forward of messages, so messages not received during transmission are lost.
### View your network
[![Local Meshtastic network](/img/android/android-nodes-sm.webp)](/img/android/android-nodes.webp)
![[Local Meshtastic network](/img/android/android-nodes-sm.webp)](/img/android/android-nodes.webp)
The network list shows all the users (devices) that have connected to the same Channel. For each entry, it shows the last time they were active, their location and distance (when available), and their last known power status. In the example above, Monkey is the local user, Rabbit was last heard from 10 minutes ago and is 50m away, and Panda was last heard 11 minutes ago and 5m away.
@ -151,7 +250,6 @@ The network list shows all the users (devices) that have connected to the same C
The Map tab will show a local map with an icon for each active mesh node that has a known position. The users names are shown above the icon.
[![Map Layers](/img/android/android-map-layers-c.webp)](/img/android/android-map-layers.webp)
- Clicking the layers icon in the top-right will allow you to select the map type.
@ -160,7 +258,7 @@ The Map tab will show a local map with an icon for each active mesh node that ha
[![Download offline maps](/img/android/android-map-download-c.webp)](/img/android/android-map-download.webp)
- Some map types allow downloading for offline use. If offline maps are available for your selected map type, a download icon will appear in the bottom-right corner of the map. Tap this icon and choose the option to Download Region, then select the area you wish to download.
- Some map types allow downloading for offline use. If offline maps are available for your selected map type, a download icon will appear in the bottom-right corner of the map. Tap this icon and choose the option to Download Region, then select the area you wish to download.
## Configuration options
@ -179,6 +277,7 @@ The debug panel allows you to see all packets sent between the application and t
[![Meshtastic configuration options](/img/android/android-radio-configuration-c.webp)](/img/android/android-radio-configuration.webp)
Radio Configuration opens a list of all radio and module configuration settings.
- See [Radio Config](/docs/configuration/radio) for radio settings.
- See [Module Config](/docs/configuration/module) for module settings.
- At the end of this list are buttons for Reboot, Shutdown, Factory reset, and NodeDB reset.
@ -207,7 +306,7 @@ Opens the introduction slideshow.
[![Quick Chat](/img/android/android-quick-chat-sm.webp)](/img/android/android-quick-chat.webp)
Brings up an editor to create and edit quick response messages. These will appear as buttons in the chat window. Messages have the option to send instantly, or be appended to your message and sent manually.
Brings up an editor to create and edit quick response messages. These will appear as buttons in the chat window. Messages have the option to send instantly, or be appended to your message and sent manually.
### About

16
docs/software/apple/translate.mdx
View file

@ -7,12 +7,14 @@ sidebar_position: 3
## How to Contribute
Contributing translations to the Meshtastic Apple app helps make the project accessible to a wider audience. Follow these steps to add translations for a new language:
Contributing translations to the Meshtastic Apple app helps make the project accessible to a wider audience. The Meshtastic Apple app uses [string catalogs](https://developer.apple.com/documentation/xcode/localizing-and-varying-text-with-a-string-catalog) in Xcode to manage translations.
1. **Fork the Repository**: Start by forking the [Meshtastic-Apple repository](<https://github.com/meshtastic/Meshtastic-Apple/tree/main>) to your GitHub account.
2. **Create a Language Folder**: In your forked repository, create a new folder for your language using the language code followed by `.lproj`. For example, for German, create a folder named `de.lproj`.
3. **Copy the Localizable.strings File**: Navigate to the [English strings folder](<https://github.com/meshtastic/Meshtastic-Apple/blob/main/en.lproj/Localizable.strings>) and copy the `Localizable.strings` file. Paste this file into the folder you created in the previous step.
4. **Translate the Strings**: Open the `Localizable.strings` file in your language folder and translate the English strings into your language. Be sure to maintain the format of the file.
5. **Create a Pull Request**: Once you've completed the translation, create a new pull request from your forked repository to the main Meshtastic-Apple repository. Title the pull request appropriately (e.g., "Add German Translation") and describe the changes you've made.
If you would like to update the translations for a locale or add a new language, follow these steps.
Your contribution will be reviewed, and upon approval, your translation will be included in the next release of the Meshtastic Apple app. Thank you for helping expand the reach of Meshtastic!
1. Start by forking the [Meshtastic-Apple repository](<https://github.com/meshtastic/Meshtastic-Apple/tree/main>) to your GitHub account.
2. Clone the project and open the `Meshtastic.xcworkspace`
3. Select the `Localizable.xcstrings` file in the project navigator.
4. Follow the steps outlined [here](https://developer.apple.com/documentation/xcode/localizing-and-varying-text-with-a-string-catalog) for adding or updating translations.
5. Create a PR on the project with your changes.
Your contribution will be reviewed, and upon approval, your translation will be included in the next release of the Meshtastic Apple app. Thank you for helping expand the reach of Meshtastic!

30
docs/software/integrations/mqtt/home-assistant.mdx
View file

@ -44,7 +44,7 @@ sensor:
- name: "Node 1 Battery Voltage"
unique_id: "node_1__battery_voltage"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_topic: "msh/US/2/json/LongFast/!67ea9400"
state_class: measurement
value_template: >-
{% if value_json.from == 4038675309 and
@ -60,7 +60,7 @@ sensor:
- name: "Node 1 Battery Percent"
unique_id: "node_1_battery_percent"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_topic: "msh/US/2/json/LongFast/!67ea9400"
state_class: measurement
value_template: >-
{% if value_json.from == 4038675309 and value_json.payload.battery_level is defined %}
@ -73,7 +73,7 @@ sensor:
- name: "Node 1 ChUtil"
unique_id: "node_1_chutil"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_topic: "msh/US/2/json/LongFast/!67ea9400"
state_class: measurement
value_template: >-
{% if value_json.from == 4038675309 and value_json.payload.channel_utilization is defined %}
@ -85,7 +85,7 @@ sensor:
- name: "Node 1 AirUtilTX"
unique_id: "node_1_airutiltx"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_topic: "msh/US/2/json/LongFast/!67ea9400"
state_class: measurement
value_template: >-
{% if value_json.from == 4038675309 and value_json.payload.air_util_tx is defined %}
@ -104,7 +104,7 @@ sensor:
- name: "Node 1 Temperature"
unique_id: "node_1_temperature"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_topic: "msh/US/2/json/LongFast/!67ea9400"
state_class: measurement
value_template: >-
{% if value_json.from == 4038675309 and value_json.payload.temperature is defined %}
@ -113,7 +113,7 @@ sensor:
{{ this.state }}
{% endif %}
device_class: "temperature"
unit_of_measurement: "F"
unit_of_measurement: "°F"
# With device_class: "temperature" set, make sure to use the configured unit for temperature in your HA instance.
# If you don't, then non-temperature messages will change the value of this sensor by reinterpreting the current state with the wrong unit, unless you account for it.
# For Celsius use: {{ (value_json.payload.temperature | float) | round(1) }}
@ -121,7 +121,7 @@ sensor:
- name: "Node 1 Humidity"
unique_id: "node_1_humidity"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_topic: "msh/US/2/json/LongFast/!67ea9400"
state_class: measurement
value_template: >-
{% if value_json.from == 4038675309 and value_json.payload.relative_humidity is defined %}
@ -134,7 +134,7 @@ sensor:
- name: "Node 1 Pressure"
unique_id: "node_1_pressure"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_topic: "msh/US/2/json/LongFast/!67ea9400"
state_class: measurement
value_template: >-
{% if value_json.from == 4038675309 and value_json.payload.barometric_pressure is defined %}
@ -149,7 +149,7 @@ sensor:
- name: "Node 1 Gas Resistance"
unique_id: "node_1_gas_resistance"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_topic: "msh/US/2/json/LongFast/!67ea9400"
state_class: measurement
value_template: >-
{% if value_json.from == 4038675309 and value_json.payload.gas_resistance is defined %}
@ -167,7 +167,7 @@ sensor:
```yaml
- name: "Node 1 Messages"
unique_id: "node_1_messages"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_topic: "msh/US/2/json/LongFast/!67ea9400"
value_template: >-
{% if value_json.from == 4038675309 and value_json.payload.text is defined %}
{{ value_json.payload.text }}
@ -187,7 +187,7 @@ alias: Update Node 1 location
description: Update Meshtastic node when corresponding MQTT messages are seen.
trigger:
- platform: mqtt
topic: msh/2/json/LongFast/!67ea9400
topic: msh/US/2/json/LongFast/!67ea9400
payload: "on"
value_template: |-
{% if value_json.from == 4038675309 and
@ -216,7 +216,7 @@ Home Assistant entities can be created for any data type that is published to MQ
### Configure With Your Topic & Node ID's
- In every entity, replace `msh/2/json/LongFast/!67ea9400` with the topic your node publishes to. In this example, `!67ea9400` refers to the node that has mqtt enabled on the mesh and is publishing to the broker.
- In every entity, replace `msh/US/2/json/LongFast/!67ea9400` with the topic your node publishes to. In this example, `!67ea9400` refers to the node that has mqtt enabled on the mesh and is publishing to the broker.
- In every entity replace `4038675309` with the node number of the radio you wish to monitor. In this example `4038675309` is the node on the mesh with environment sensors and telemetry that I wish to observe. Node numbers can be found by monitoring the output in MQTT Explorer, listening with the MQTT addon or by using the Python CLI with `meshtastic --info`.
@ -227,7 +227,7 @@ Copy and paste these entities then change `name`, `unique_id`, `from`, and `stat
```yaml
- name: "Node 2 Messages"
unique_id: "node_2_messages"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_topic: "msh/US/2/json/LongFast/!67ea9400"
value_template: >-
{% if value_json.from == 695318008 and value_json.payload.text is defined %}
{{ value_json.payload.text }}
@ -279,7 +279,7 @@ Add the following code to your automations.yaml file. Be sure to modify the `to
description: any message with an @Tropho will send to mobile device
trigger:
- platform: mqtt
topic: msh/2/json/LongFast/!67ea9400
topic: msh/US/2/json/LongFast/!67ea9400
condition:
- condition: template
value_template: "{{ trigger.payload_json.payload.text | regex_search('@Tropho') }}"
@ -336,7 +336,7 @@ This automation will check the send box for changes. After typing a message, ei
data:
qos: 0
retain: false
topic: msh/2/json/mqtt/!67ea9400
topic: msh/US/2/json/mqtt/!67ea9400
payload: >-
{"from":1743426560,"type":"sendtext","payload":"{{
states('input_text.meshtastic_send_box') }}"}

71
docs/software/integrations/mqtt/index.mdx
View file

@ -6,21 +6,43 @@ sidebar_position: 6
description: Bridging mesh networks over the internet and integrating Meshtastic protocols with popular technologies such as Home Assistant, Node Red, and Adafruit IO.
---
## Bridging networks
## Public MQTT Server
![Common MQTT Layout](/img/software/mqtt/mqtt.webp)
Meshtastic networks in different locations beyond the reach of LoRa can be easily bridged together using MQTT. The simplest option is to connect your mesh to the official Meshtastic MQTT broker. This makes your devices appear on the world map, and provides a copy of your mesh traffic, translated into JSON. All you have to do to join the public MQTT server is to Enable MQTT and set Uplink and Downlink on the channels that you want to share over MQTT. The default device configuration using the public MQTT Server is encrypted.
The Meshtastic project provides a public MQTT service that users can connect to, with certain restrictions in place to ensure network stability. This service allows Meshtastic devices to bridge over the internet, providing global connectivity for remote networks.
You can also specify your own private MQTT broker to bridge mesh networks together, via the internet (or just a local IP network).
For instructions on connecting to the public MQTT server, please refer to [Connect to the Default Public Server](/docs/configuration/module/mqtt/#connect-to-the-default-public-server).
You can find the settings available for MQTT [here](/docs/configuration/module/mqtt).
### Restrictions on the Public MQTT Server
:::important
When MQTT is turned on, you are potentially broadcasting your entire mesh's traffic onto the public internet. This includes messages and position information.
To maintain optimal performance and protect LoRa meshes, traffic restrictions are currently applied to the public MQTT server.
The default channel (LongFast) on the public MQTT server usually has a lot of traffic. Your device may get overloaded and may no longer function properly anymore. It is recommended to use a different channel or to use your own MQTT server if you experience issues.
:::
#### Zero-Hop Policy
Traffic from the public MQTT server does not fully propagate through local mesh networks. Directly connected nodes will receive the data, but due to the zero-hop policy, it will not spread further to other nodes within the local mesh network.
#### Optimized Traffic Filtering
Only specific portnums are prioritized for transmission over the public MQTT server when using the default PSK:
- NodeinfoApp
- TextMessageCompressedApp
- TextMessageApp
- PositionApp
- TelemetryApp
- MapReportApp
- RoutingApp
#### Location Precision Filtering
On the default PSK, the public server also limits the precision of location data to help protect user privacy. Only position packets containing imprecise location data (10-16 bits) are shared on the topic, ensuring that precise location details are not exposed. For more information on how location precision works, see the [Position Precision](https://meshtastic.org/docs/configuration/radio/channels/#position-precision) section.
This filtering focuses network resources on critical traffic, improving overall performance and reducing unnecessary data flow. Since these restrictions are applied at the network level, no firmware updates are required. As Meshtastic networks continue to grow, further traffic reduction measures may become necessary to manage network load and maintain reliable performance across all channels.
### Using Private Brokers
It is not recommended to use the default key (PSK) on a private broker. Doing so potentially allows security vulnerabilities and can flood the mesh with traffic, as private brokers do not enforce the zero-hop policy needed for public channels. Private brokers are intended for use with private channels, where custom PSKs provide secure, isolated communication.
## Software Integrations
@ -30,19 +52,17 @@ When MQTT is enabled, the Meshtastic device simply uplinks and/or downlinks ever
### MQTT [Topics](https://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices)
If no specific [root topic](/docs/configuration/module/mqtt#root-topic) is configured, the default root topic will be `msh/`.
Each device that is connected to MQTT will publish its MQTT state (`online`/`offline`) to:
If no specific [root topic](/docs/configuration/module/mqtt#root-topic) is configured, the default root topic will be `msh/REGION`.
`msh/2/stat/USERID`, where `USERID` is the node ID of the gateway device (the one connected to MQTT).
For each channel where uplink and/or downlink is enabled, two other topics might be used:
For each channel where uplink and/or downlink is enabled, two topics might be used:
#### Protobufs topic
A gateway node will uplink and/or downlink raw ([protobuf](https://developers.google.com/protocol-buffers)) MeshPackets to the topic:
`msh/2/e/CHANNELNAME/USERID`, where `CHANNELNAME` is the name of the channel (firmware versions prior to 2.3.0 will publish to a topic with `/c/` in the place of `/e/`).
`msh/REGION/2/e/CHANNELNAME/USERID`, where `CHANNELNAME` is the name of the channel (firmware versions prior to 2.3.0 will publish to a topic with `/c/` in the place of `/e/`).
For example: `msh/2/e/LongFast/!abcd1234`
For example: `msh/US/2/e/LongFast/!abcd1234`
The payload is a raw protobuf, whose definitions for Meshtastic can be found [here](https://github.com/meshtastic/protobufs/blob/master/meshtastic). Reference guides for working with protobufs in several popular programming languages can be found [here](https://protobuf.dev/reference/). Looking at the MQTT traffic with a program like `mosquitto_sub` will tell you it's working, but you won't get much useful information out of it. For example:
@ -55,13 +75,14 @@ The payload is a raw protobuf, whose definitions for Meshtastic can be found [he
If [encryption_enabled](/docs/configuration/module/mqtt#encryption-enabled) is set to true, the payload of the MeshPacket will remain encrypted with the key for the specified channel.
#### JSON topic
:::note
JSON is not supported on the nRF52 platform.
:::
If [JSON is enabled](/docs/configuration/module/mqtt#json-enabled), packets from the following [port numbers](/docs/development/firmware/portnum) are serialized to JSON: `TEXT_MESSAGE_APP`, `TELEMETRY_APP`, `NODEINFO_APP`, `POSITION_APP`, `WAYPOINT_APP`, `NEIGHBORINFO_APP`, `TRACEROUTE_APP`, `DETECTION_SENSOR_APP`, `PAXCOUNTER_APP` and `REMOTE_HARDWARE_APP`. These are then forwarded to the topic:
`msh/2/json/CHANNELNAME/USERID`.
`msh/US/2/json/CHANNELNAME/USERID`.
An example of a received `NODEINFO_APP` message:
@ -85,7 +106,7 @@ An example of a received `NODEINFO_APP` message:
The meaning of these fields is as follows:
- "`id`" is the unique ID for this message.
- "`id`" is the unique ID for this message.
- "`channel`" is the channel index this message was received on.
- "`from`" is the unique decimal-equivalent Node ID of the node on the mesh that sent this message. (The hexadecimal value `7efeee00` represented by an integer in decimal is `2130636288`).
- "`id`" inside the payload of a `NODEINFO_APP` message is the hexadecimal Node ID (sometimes called User ID) of the node that sent it.
@ -94,18 +115,18 @@ The meaning of these fields is as follows:
- "`shortname`" is the short name of the device that sent the `NODEINFO_APP` message.
- "`sender`" is the hexadecimal Node ID of the gateway device, which is in this case the same node that sent the `NODEINFO_APP` message.
- "`timestamp`" is the Unix Epoch when the message was received, represented as an integer in decimal.
- "`to`" is the decimal-equivalent Node ID of the destination of the message. In this case, "-1" means it was a broadcast message (this is the decimal integer representation of `0xFFFFFFFF`).
- "`to`" is the decimal-equivalent Node ID of the destination of the message. In this case, "-1" means it was a broadcast message (this is the decimal integer representation of `0xFFFFFFFF`).
- "`type`" is the type of the message, in this case it was a `NODEINFO_APP` message.
The `from` field can thus be used as a stable identifier for a specific node. Note that in firmware prior to 2.2.0, this is a signed value in JSON, while in firmware 2.2.0 and higher, the JSON values are unsigned.
The `from` field can thus be used as a stable identifier for a specific node. Note that in firmware prior to 2.2.0, this is a signed value in JSON, while in firmware 2.2.0 and higher, the JSON values are unsigned.
If the message received contains valid JSON in the payload, the JSON is deserialized and added as a JSON object rather than a string containing the serialized JSON.
#### JSON downlink to instruct a node to send a message
You can also send a JSON message to the topic `msh/2/json/mqtt/` to instruct a gateway node to send a message to the mesh.
To make this work, ensure that your node has a Meshtastic channel configured called "mqtt". Enable Downlink. The PSK can be random and doesn't matter. This channel allows the node to listen to messages on the `msh/2/json/mqtt/` topic.
You can also send a JSON message to the topic `msh/US/2/json/mqtt/` to instruct a gateway node to send a message to the mesh.
To make this work, ensure that your node has a Meshtastic channel configured called "mqtt". Enable Downlink. The PSK can be random and doesn't matter. This channel allows the node to listen to messages on the `msh/US/2/json/mqtt/` topic.
Reboot your device after creating this channel.
@ -150,12 +171,6 @@ Gateway nodes (via code running in the phone) will contain two tables to whiteli
Since multiple gateway nodes might be connected to a single mesh, it is possible that duplicate messages will be published on any particular topic. Therefore, subscribers to these topics should
deduplicate if needed by using the packet ID of each message.
### Optional web services
#### Public MQTT broker service
An existing public [MQTT broker](https://mosquitto.org) will be the default for this service, but clients can use any MQTT broker they choose.
## Examples
- [Using mosquitto on a mac](/docs/software/integrations/mqtt/mosquitto.mdx)

48
docs/software/integrations/mqtt/nodered.mdx
View file

@ -7,31 +7,30 @@ sidebar_position: 3
## Using MQTT with Node-RED
Node-RED is a free cross-platform programming tool for wiring together hardware, APIs, and online services developed originally by IBM for IOT. It is widely used for home automation by many non-professional programmers and runs well on Pi's. Node-RED has many plug-in modules written by the community.
Node-RED is a free cross-platform programming tool for wiring together hardware, APIs, and online services developed originally by IBM for IOT. It is widely used for home automation by many non-professional programmers and runs well on Pi's. Node-RED has many plug-in modules written by the community.
I will use this platform as a practical example on how to interface with the MQTT features of Meshtastic. Everything can be done from GUI's without using command line.
### Enabling MQTT
Use http://client.meshtastic.org/ , the python CLI, or an Apple or Android app to connect to your device and adjust these settings.
1. Settings--> Radio Config--> Network
1. Settings--> Radio Config--> Network
- On the node that will act as the gateway between the mesh and MQTT enable a network connection (i.e. Wifi, Ethernet).
- Save
- On the node that will act as the gateway between the mesh and MQTT enable a network connection (i.e. Wifi, Ethernet).
- Save
2. Settings--> Module Config--> MQTT config
2. Settings--> Module Config--> MQTT config
- Configure the MQTT gateway's network configuration.
- Verify Encryption Enabled is OFF.
- (optional) Turn JSON Output Enabled ON.
- Save
3. Channel Editor
- Go to Channel Editor and enable Uplink and Downlink on the channels you wish to publish to MQTT.
- Save
- Save
### Using Node-RED with Meshtastic
There are three common approaches:
1. Using JSON-encoded messages
@ -39,6 +38,7 @@ There are three common approaches:
3. Using protobuf-encoded messages with a protobuf decode node and the Meshtastic protobuf definitions
The JSON output only publishes the following subset of the messages on a Meshtastic network:
- Text Message
- Telemetry
- Device Metrics
@ -54,11 +54,12 @@ The JSON output only publishes the following subset of the messages on a Meshtas
> Protobufs are mesh native.
#### 1. Using JSON-encoded messages
:::note
:::note
JSON is not supported on the nRF52 platform.
:::
Make sure that option *JSON Output Enabled* is set in MQTT module options and you have a channel called "mqtt".
Make sure that option _JSON Output Enabled_ is set in MQTT module options and you have a channel called "mqtt".
Below is a valid JSON envelope for information sent by MQTT to a device for broadcast onto the mesh. The `to` field is optional and can be omitted for broadcast. The `channel` field is also optional and can be omitted to send to the primary channel.
@ -71,7 +72,9 @@ Below is a valid JSON envelope for information sent by MQTT to a device for broa
"payload": text or a json object go here
}
```
#### 2. Using protobuf-encoded messages with the Meshtastic decode node
Install Node-Red plug-in:
https://flows.nodered.org/node/@meshtastic/node-red-contrib-meshtastic
@ -80,10 +83,9 @@ More info is in the plug-in source repository.
There is an example flow using this mechanism available
https://github.com/scruplelesswizard/meshtastic-node-red
#### 3. Using protobuf-encoded messages with a protobuf decode node and the Meshtastic protobuf definitions
If you don't want to depend on JSON decoding on the device, you can decode the protobuf messages off-device. To do that you will need to get the .proto files from https://github.com/meshtastic/protobufs. They function as a schema and are required for decoding in Node-RED. Save the files where the node-RED application can access them and note the file path of the "mqtt.proto" file.
If you don't want to depend on JSON decoding on the device, you can decode the protobuf messages off-device. To do that you will need to get the .proto files from https://github.com/meshtastic/protobufs. They function as a schema and are required for decoding in Node-RED. Save the files where the node-RED application can access them and note the file path of the "mqtt.proto" file.
Install Node-RED plug-ins to your Node-RED application for an embedded MQTT server and a protobuf decoder.
https://flows.nodered.org/node/node-red-contrib-aedes
@ -91,20 +93,20 @@ https://flows.nodered.org/node/node-red-contrib-protobuf
Drag, drop, and wire the nodes like this. For this example, I ran Node-RED on a Windows machine. Note that file paths might be specified differently on different platforms. MQTT server wild cards are usually the same. A "+" is a single level wildcard for a specific topic level. A "#" is a multiple level wildcard that can be used at the end of a topic filter. The debug messages shown are what happens when the inject button sends a JSON message with a topic designed to be picked up by the specified Meshtastic device and then having it rebroadcast the message.
[<img src="/documents/mqtt/NodeRedTwo.jpg" style={{zoom:'50%'}} />](/documents/mqtt/NodeRedTwo.jpg)
[<img src="/documents/mqtt/NodeRedThree.jpg" style={{zoom:'50%'}} />](/documents/mqtt/NodeRedThree.jpg)
[<img src="/documents/mqtt/NR_nodes.jpg" style={{zoom:'50%'}} />](/documents/mqtt/NR_nodes.jpg)
[<img src="/documents/mqtt/NodeRedTwo.webp" style={{zoom:'50%'}} />](/documents/mqtt/NodeRedTwo.webp)
[<img src="/documents/mqtt/NodeRedThree.webp" style={{zoom:'50%'}} />](/documents/mqtt/NodeRedThree.webp)
[<img src="/documents/mqtt/NR_nodes.webp" style={{zoom:'50%'}} />](/documents/mqtt/NR_nodes.webp)
The aedes broker must be set up on the same flow as the other nodes. By activating the Publish debug node, you can see all the published messages.
[<img src="/documents/mqtt/Broker1.jpg" style={{zoom:'50%'}} />](/documents/mqtt/Broker1.jpg)
[<img src="/documents/mqtt/Broker1.webp" style={{zoom:'50%'}} />](/documents/mqtt/Broker1.webp)
Receiving a json mqtt message is very simple.
[<img src="/documents/mqtt/Consume.jpg" style={{zoom:'50%'}} />](/documents/mqtt/Consume.jpg)
[<img src="/documents/mqtt/Consume.webp" style={{zoom:'50%'}} />](/documents/mqtt/Consume.webp)
Injecting a json message to be sent by a device is also very simple. You do need the correct envelope.
[<img src="/documents/mqtt/Inject.jpg" style={{zoom:'50%'}} />](/documents/mqtt/Inject.jpg)
[<img src="/documents/mqtt/Inject.webp" style={{zoom:'50%'}} />](/documents/mqtt/Inject.webp)
Forwarding a text message from one device, through a broker, to another broker/device/channel would look like this.
[<img src="/documents/mqtt/Forward.jpg" style={{zoom:'50%'}} />](/documents/mqtt/Forward.jpg)
[<img src="/documents/mqtt/Forward.webp" style={{zoom:'50%'}} />](/documents/mqtt/Forward.webp)
If you want to decode text and position messages without json, it gets complicated:
[<img src="/documents/mqtt/DecodeNewest.jpg" style={{zoom:'50%'}} />](/documents/mqtt/DecodeNewest.jpg)
[<img src="/documents/mqtt/DecodeNewest.webp" style={{zoom:'50%'}} />](/documents/mqtt/DecodeNewest.webp)
If you are interested in my flow for this it is here:
```json
@ -669,10 +671,10 @@ If you are interested in my flow for this it is here:
(documents/mqtt/Flow.txt)
Node-red can rapidly (minutes vs days) put together some pretty impressive output when paired with meshtastic. Here is the output of that flow geofencing and mapping via mqtt data.
[<img src="/documents/mqtt/Mapping.jpg" style={{zoom:'50%'}} />](/documents/mqtt/Mapping.jpg)
[<img src="/documents/mqtt/Mapping.webp" style={{zoom:'50%'}} />](/documents/mqtt/Mapping.webp)
Advanced use, such as encoding Position and sending it to a device via MQTT without using JSON can get a little complicated. An example of how it can be done is below.
[<img src="/documents/mqtt/EncodingPosition.jpg" style={{zoom:'50%'}} />](/documents/mqtt/EncodingPosition.jpg)
[<img src="/documents/mqtt/EncodingPosition.webp" style={{zoom:'50%'}} />](/documents/mqtt/EncodingPosition.webp)
The flow is:
```json
@ -1001,4 +1003,4 @@ Sending a position to a device for broadcast to the mesh is much easier with JSO
```
An example of doing this in node-red:
[<img src="/documents/mqtt/PosJSON.jpg" style={{zoom:'50%'}} />](/documents/mqtt/PosJSON.jpg)
[<img src="/documents/mqtt/PosJSON.webp" style={{zoom:'50%'}} />](/documents/mqtt/PosJSON.webp)

90
docs/software/meshtasticator/discrete-event-sim.mdx Normal file
View file

@ -0,0 +1,90 @@
---
id: discrete-event-sim
title: Discrete Event Simulator Usage Guide
sidebar_label: Discrete Event Simulator
sidebar_position: 1
description: A usage guide for simulating radio communications with configurable parameters and node behaviors.
---
The discrete-event simulator mimics the radio section of the device software. It is currently based on Meshtastic 2.1.
## Usage
Please `git clone` or download this repository, navigate to the Meshtasticator folder (optionally create a virtual environment), and install the necessary requirements using:
`pip install -r requirements.txt`
To start one simulation with the default configurations, run:
`python3 loraMesh.py [nr_nodes]`
If no argument is given, you first have to place the nodes on a plot. After you place a node, you can optionally set the node as a Router, change its hop limit, height (elevation), and antenna gain. These settings will automatically save when you place a new node or when you start the simulation.
![Config Node](/img/software/meshtasticator/configNode.webp)
If the number of nodes is given, it will randomly place nodes in the area. It ensures that each node can reach at least one other node. Furthermore, all nodes are placed at a configurable minimum distance (MINDIST) from each other.
If you placed the nodes yourself, after a simulation the number of nodes, their coordinates, and configuration are automatically saved, and you can rerun the scenario with:
`python3 loraMesh.py --from-file`
If you want to change any of the configurations, adapt the file _out/nodeConfig.yaml_ before running it with the above command.
For running multiple repetitions of simulations for a set of parameters, e.g., the number of nodes, run:
`python3 batchSim.py`
After the simulations are done, it plots relevant metrics obtained from the simulations. It saves these metrics in _/out/report/_ for analysis later on. See _plotExample.py_ for an example Python script to plot the results.
To simulate different parameters, you will have to change the _batchSim.py_ script yourself.
## Custom configurations
Here we list some of the configurations, which you can change to model your scenario in _/lib/config.py_. These apply to all nodes, except those that you configure per node when using the plot.
### Modem
The LoRa modem ([see Meshtastic radio settings](/docs/overview/radio-settings#predefined-channels)) that is used, as defined below:
| Modem | Name | Bandwidth (kHz) | Coding rate | Spreading Factor | Data rate (kbps) |
| ----- | -------------- | --------------- | ----------- | ---------------- | ---------------- |
| 0 | Short Fast | 250 | 4/8 | 7 | 6.8 |
| 1 | Short Slow | 250 | 4/8 | 8 | 3.9 |
| 2 | Mid Fast | 250 | 4/8 | 9 | 2.2 |
| 3 | Mid Slow | 250 | 4/8 | 10 | 1.2 |
| 4 | Long Fast | 250 | 4/8 | 11 | 0.67 |
| 5 | Long Moderate | 125 | 4/8 | 11 | 0.335 |
| 6 | Long Slow | 125 | 4/8 | 12 | 0.18 |
| 7 | Very Long Slow | 62.5 | 4/8 | 12 | 0.09 |
### Period
Mean period (in ms) with which the nodes generate a new message following an exponential distribution. For example, if you set it to 300s, each node will generate a message on average once every five minutes.
### Packet length
Payload size of each generated message in bytes. For a position packet, it will be around 40 bytes.
### Model
This feature refers to the path loss model, i.e., what the simulator uses to calculate how well a signal will propagate. Note that this is only a rough estimation of the physical environment and will not be 100% accurate, as it depends on a lot of factors. The implemented path loss models are:
- `0` set the log-distance model
- `1` set the Okumura-Hata for small and medium-size cities model
- `2` set the Okumura-Hata for metropolitan areas
- `3` set the Okumura-Hata for suburban environments
- `4` set the Okumura-Hata for rural areas
- `5` set the 3GPP for suburban macro-cell
- `6` set the 3GPP for metropolitan macro-cell
### Broadcasts or direct messages (DMs)
By default, _DMs_ is set to False, meaning it will send broadcast messages only. If you set it to True, each node will only send DMs to a random other node in the network.
## Explanation
A discrete-event simulator jumps from event to event over time, where an event is a change in the state of the system. It is therefore well-suited for simulating communication networks.
For every node in the simulation, an instance is created that mimics the [Meshtastic logic](/docs/overview/mesh-algo). Each node runs three processes in parallel: _generateMessage_, _transmit_, and _receive_. The first creates an event by constructing a new message with a unique sequence number at a random time, taken from an exponential distribution. For now, each generated message is of the same payload size. The second and third processes model the actual transmitting and receiving behavior, respectively.
The model of the LoRa physical (PHY) layer is in _/lib/phy.py_. Depending on the modem used, it calculates what the airtime of a packet is. The PHY layer uses a configurable path loss model to estimate whether nodes at a specific distance can sense each other's packets. Furthermore, it determines whether two packets collide, which depends on the frequency, spreading factor, received time, and received power of the two packets.
The routing behavior is implemented in each of the processes of the node. Inside _generateMessage_, reliable retransmissions are handled if no implicit acknowledgment is received. A MeshPacket (defined in _/lib/packet.py_) is created to transfer the message. Note that there may be multiple packets created containing the same message, due to retransmissions and rebroadcasting. In _receive_, it is decided what to do on reception of a packet. A packet is flooded if its hop limit is not zero and no rebroadcast of this packet was heard before. In _transmit_, delays of the Medium Access Control (MAC) layer are called from _/lib/mac.py_. The MAC uses a listen-before-talk mechanism, including introducing (random or SNR-based) delays before transmitting a packet. When a packet is ready to be transferred over the air, it is first checked whether in the meantime still no acknowledgment was received; otherwise, the transmission is canceled.
The actual communication between processes of different nodes is handled by a BroadcastPipe of [Simpy](https://simpy.readthedocs.io/en/latest/examples/process_communication.html). This ensures that a packet transmitted by one node creates events (one at the start of a packet and one at the end) at the receiving nodes.

58
docs/software/meshtasticator/index.mdx Normal file
View file

@ -0,0 +1,58 @@
---
id: meshtasticator
title: Meshtasticator
sidebar_label: Meshtasticator (Simulator)
sidebar_position: 5
description: Overview of Meshtasticator simulator for evaluating performance and scalability of the Meshtastic protocol using discrete-event and interactive simulations.
---
import ReactPlayer from "react-player";
**Meshtasticator** is a discrete-event and interactive simulator that replicates the radio section of the device software. It helps evaluate the performance of various scenarios and the scalability of the protocol. The **Meshtasticator** simulator can be found on [Github](https://github.com/meshtastic/meshtasticator).
## Discrete-Event Simulator
The discrete-event simulator models the radio section of the device software to analyze its behavior. It can assess the performance of specific scenarios and the scalability of the protocol.
### Getting Started
For step-by-step instructions on how to use the discrete-event simulator, see the [discrete-event simulator usage guide](./discrete-event-sim).
### Simulation Insights
After each simulation, the tool plots node placements and schedules the timing for overlapping messages sent during the simulation.
![Placement Schedule](/img/software/meshtasticator/placement_schedule.webp)
The simulator allows network analysis using different parameter sets. For example, below are the results of 100 simulations, each lasting 200 seconds, with varying hop limits and node counts. As expected, the average number of nodes reached per message increases with a higher hop limit.
![Reachability Hops](/img/software/meshtasticator/reachability_hops.webp)
However, this improvement comes with a trade-off in **usefulness**—the proportion of received packets containing new (non-duplicate) messages decreases as rebroadcasting increases.
![Usefulness Hops](/img/software/meshtasticator/usefulness_hops.webp)
## Interactive Simulator
The interactive simulator leverages the [Linux-native Meshtastic application](https://meshtastic.org/docs/software/linux-native), i.e., the real device software, while emulating some hardware components, including the LoRa chip. It can also run on Windows or macOS using Docker.
### Setup Instructions
To get started with the interactive simulator, see the [interactive simulator usage guide](./interactive-sim).
### Debugging and Visualization
This simulator facilitates debugging multiple communicating nodes without needing physical devices.
<div style={{ maxWidth: "800px", margin: "auto" }}>
<ReactPlayer
url="/img/software/meshtasticator/interactive-sim-video.mp4"
controls
width="100%"
height="400px"
/>
</div>
Additionally, because the simulator has an 'oracle view' of the network, it provides insights into the routes taken by messages.
![Route Plot](/img/software/meshtasticator/route_plot.webp)

129
docs/software/meshtasticator/interactive-sim.mdx Normal file
View file

@ -0,0 +1,129 @@
---
id: interactive-sim
title: Interactive Simulator Usage Guide
sidebar_label: Interactive Event Simulator
sidebar_position: 2
description: A usage guide for simulating multiple Meshtastic instances with TCP-based communication and configurable pathloss models.
---
The Python script _`interactiveSim.py`_ uses the [Linux native application of Meshtastic](https://meshtastic.org/docs/software/linux-native) to simulate multiple instances of the device software. These instances communicate using TCP via the script, simulating the LoRa chip. The simulator forwards messages from the sender to all nodes within range, based on their simulated positions and the selected pathloss model (see [Pathloss Model](#pathloss-model)). **Note:** Packet collisions are not yet simulated.
## Usage
1. Clone or download the repository and navigate to the Meshtasticator folder.
2. (Optional) Create a virtual environment.
3. Install dependencies:
```bash
pip install -r requirements.txt
```
The simulator runs the Linux native application of Meshtastic firmware. You can use either [PlatformIO](https://meshtastic.org/docs/development/firmware/build) or [Docker](https://meshtastic.org/docs/software/linux-native#usage-with-docker) to run the firmware:
### Using PlatformIO
Select 'native' and click 'build.' Locate the generated binary file, likely in _`firmware/.pio/build/native/`_.
Copy the `program` file to the directory where you'll run the Python script, or provide the path as an argument with `-p`:
```bash
python3 interactiveSim.py 3 -p /home/User/Meshtastic-device/.pio/build/native/program
```
### Using Docker
The simulator pulls a Docker image that builds the latest Meshtastic firmware.
Ensure the Docker SDK for Python is installed:
```bash
pip3 install docker
```
Make sure the Docker daemon or Desktop app is running. Use the `-d` argument to launch the simulator:
```bash
python3 interactiveSim.py 3 -d
```
## Running the Simulator
To run the interactive simulator:
```bash
python3 interactiveSim.py [nrNodes] [-p <full-path-to-program>]
```
- **`nrNodes`** (optional): Number of instances to launch. Each instance opens a terminal and a TCP port (starting at 4403).
- If you provide the number of nodes, they will be randomly placed; otherwise, you can manually place nodes on a plot.
- After placing nodes, you can configure their [role](https://meshtastic.org/docs/settings/config/device#role), `hopLimit`, height (elevation), and antenna gain. Configurations are saved automatically.
![Config Note](/img/software/meshtasticator/configNode.webp)
## Commands During Simulation
Once the simulation starts, you can issue commands (or use a predefined [script](#usage-with-script)) to send messages between nodes. Use `plot` to visualize message routes and airtime statistics:
- Enter a message ID to see its route.
- Hover over arcs for information and click to remove the overlay.
- Two graphs display channel utilization (one-minute window) and airtime usage (hourly window) for each node.
![Route Plot 2](/img/software/meshtasticator/route_plot-2.webp)
## List of Commands
- **`broadcast <fromNode> <txt>`**: Send a broadcast from node _fromNode_ with text _txt_.
- **`DM <fromNode> <toNode> <txt>`**: Send a Direct Message from node _fromNode_ to node _toNode_ with text _txt_.
- **`traceroute <fromNode> <toNode>`**: Send a traceroute request from node _fromNode_ to node _toNode_.
- **`reqPos <fromNode> <toNode>`**: Send a position request from node _fromNode_ to node _toNode_.
- **`ping <fromNode> <toNode>`**: Send ping from node _fromNode_ to node _toNode_.
- **`remove <id>`**: Remove node _id_ from the current simulation.
- **`nodes <id0> [id1, etc.]`**: Show the node list as seen by node(s) _id0_, _id1_, etc.
- **`plot`**: Plot the routes of messages sent and airtime statistics.
- **`exit`**: Exit the simulator without plotting routes.
## Usage with Script
Modify the `try` clause in _`interactiveSim.py`_ to predefine messages. Run the simulator with the `-s` argument:
```bash
python3 interactiveSim.py 3 -s
```
- After nodes exchange NodeInfo, they will begin sending messages.
- Close the simulation manually with `Ctrl+C` or wait for the timeout.
## Tips and Tricks
1. **Speeding Up NodeInfo Exchange:**
Disable certain modules by removing `new NodeInfoModule()` from _`src/modules/Modules.cpp`_ in the firmware.
2. **Saving and Reloading Configurations:**
After a simulation, node configurations are saved. You can rerun the same scenario with:
```bash
python3 interactiveSim.py --from-file
```
Modify the _`out/nodeConfig.yaml`_ file to adjust configurations before reloading.
3. **Using the Python CLI:**
You can call functions from the Node class via `sim.getNodeById(<id>)` in _`interactiveSim.py`_. Example:
```python
node.setURL('<YOUR_URL>')
```
## Pathloss Model
The simulator estimates signal propagation using a pathloss model. This is an approximation of the physical environment, so it may not be 100% accurate. The available models are:
- **0**: Log-distance model
- **1**: Okumura-Hata model (small/medium cities)
- **2**: Okumura-Hata model (metropolitan areas)
- **3**: Okumura-Hata model (suburban environments)
- **4**: Okumura-Hata model (rural areas)
- **5**: 3GPP model (suburban macro-cell)
- **6**: 3GPP model (metropolitan macro-cell)
You can modify the pathloss model and area configuration in _`lib/config.py`_. LoRa settings remain at their Meshtastic defaults unless customized during node placement.

2
docs/software/python-cli/index.mdx
View file

@ -541,7 +541,7 @@ meshtastic --ble-scan
### --noproto
Don't start the API, just function as a dumb serial terminal. Probably not very helpful from the command line. Used more for testing/internal needs.
Don't start the API, just function as a dumb serial terminal. Useful for debugging because it doesn't count as a client. Depends on a physically cabled serial connection. It will connect but not display information over a network (--host) or Bluetooth (--ble) connection.
```shell title="Usage"
meshtastic --noproto

16
docs/software/python-cli/installation.mdx
View file

@ -4,7 +4,7 @@ title: Meshtastic Python CLI installation
sidebar_label: Installation
slug: /software/python/cli/installation
sidebar_position: 1
description: This page offers comprehensive instructions on methods of installing the Meshtastic Python CLI across different operating systems.
description: This page offers comprehensive instructions on methods of installing the Meshtastic Python CLI across different operating systems.
---
import Tabs from "@theme/Tabs";
@ -54,7 +54,7 @@ values={[
- You should see something like:
- `ID 10c4:ea60 Silicon Labs CP210x UART Bridge` for CP210X
- `ID 1a86:55d4 QinHeng Electronics USB Single Serial` for CH9102
- If there is no seral device shown that matches the device you are using, please review our [Install Serial Drivers](/docs/getting-started/serial-drivers/) page before proceeding.
- If there is no seral device shown that matches the device you are using, please review our [Install Serial Drivers](/docs/getting-started/serial-drivers/) page before proceeding.
- Check that your computer has Python 3 installed.
@ -102,10 +102,10 @@ values={[
```shell
sudo apt install pipx && pipx install meshtastic
```
- If using `pipx` it may be necessary to update `$PATH` by running:
```shell
pipx ensurepath
```
- If using `pipx` it may be necessary to update `$PATH` by running:
```shell
pipx ensurepath
```
</TabItem>
<TabItem value="macos">
@ -210,7 +210,7 @@ When installing Python, make sure to select the option to "Add Python to PATH" o
```
:::note
Be aware that the Meshtastic CLI is not able to control the nodes over USB through termux, but you can control devices over Wifi using the `--host x.x.x.x` option with the device IP address (ESP32 or Pico W only). Wifi connection is currently under development and may not be working properly just yet. If you would like to provide feedback or test this feature, please visit our [forum](https://meshtastic.discourse.group) or join our [Discord server](https://discord.gg/ktMAKGBnBs) for more information.
Be aware that the Meshtastic CLI is not able to control the nodes over USB through termux, but you can control devices over Wifi using the `--host x.x.x.x` option with the device IP address (ESP32 or Pico W only). Wifi connection is currently under development and may not be working properly just yet. If you would like to provide feedback or test this feature, please join our [Discord server](https://discord.gg/ktMAKGBnBs) for more information.
:::
</TabItem>
@ -218,7 +218,6 @@ Be aware that the Meshtastic CLI is not able to control the nodes over USB throu
**You may need to close and re-open the CLI. The path variables may or may not update for the current session when installing.**
### Standalone Installation (Ubuntu only)
1. Download the `meshtastic_ubuntu` executable from the [Releases](https://github.com/meshtastic/Meshtastic-python/releases) page.
@ -227,6 +226,7 @@ Be aware that the Meshtastic CLI is not able to control the nodes over USB throu
```shell
chmod +x meshtastic_ubuntu && mv meshtastic_ubuntu meshtastic
```
3. To run the CLI:
```shell

13
docs/software/python-cli/usage.mdx
View file

@ -14,7 +14,7 @@ The `meshtastic` command is not run within python but is a script run from your
## Viewing Serial Output
The `--noproto` command in the Meshtastic Python CLI is used to disable the API and function merely as a "dumb serial terminal." This mode of operation allows both the API and device functionalities to remain accessible for regular use, while simultaneously providing a window into the raw serial output. This feature can be particularly useful for debugging, development, or understanding the low-level communication between devices.
The `--noproto` command in the Meshtastic Python CLI is used to disable the API and function merely as a "dumb serial terminal." This mode of operation allows both the API and device functionalities to remain accessible for regular use, while simultaneously providing a window into the raw serial output. This feature can be particularly useful for debugging, development, or understanding the low-level communication between devices. Depends on a physically cabled serial connection. It will connect but not display information over a network (--host) or Bluetooth (--ble) connection.
```shellsession title="Example Usage"
user@host % meshtastic --noproto
@ -112,12 +112,12 @@ Writing modified channels to device
Toggling `set-ham` changes your device settings in the following ways.
| Setting | `set-ham` Default | Normal Default |
| :----------: | :---------------: | :------------------------------------------------------------------------: |
| Setting | `set-ham` Default | Normal Default |
| :----------: | :---------------: | :----------------------------------------------------------------------------: |
| `IsLicensed` | `true` | See [User Config - IsLicensed](/docs/configuration/radio/user#is-licensed-ham) |
| `LongName` | _Your CallSign_ | See [User Config - LongName](/docs/configuration/radio/user#long-name) |
| `ShortName` | _Abrv CallSign_ | See [User Config - ShortName](/docs/configuration/radio/user#short-name) |
| `PSK` | `""` | See [Channel Settings - PSK](#changing-the-preshared-key) |
| `PSK` | `""` | See [Channel Settings - PSK](#changing-the-preshared-key) |
## Changing the preshared key
@ -190,6 +190,7 @@ meshtastic --ble AA11BB22-CC33-DD44-EE55-FF6677889900 --info
```shell
meshtastic --ble Meshtastic_1234 --nodes
```
#### Export device config with --export-config
```shell
@ -214,8 +215,6 @@ This is a collection of common questions and answers from our friendly forum.
### Permission denied: ‘/dev/ttyUSB0’
As previously discussed on the [forum](https://meshtastic.discourse.group/t/question-on-permission-denied-dev-ttyusb0/590/3?u=geeksville)
This indicates an OS permission problem for access by your user to the USB serial port. Typically this is fixed by the following.
```shell
@ -236,4 +235,4 @@ There is a problem with Big Sur and pyserial. The workaround is to install a new
```shell
pip3 install -U --pre pyserial
```
```

7
docs/terms/index.mdx
View file

@ -29,7 +29,7 @@ DFU
: Device Firmware Update, a state which a device is placed into for it to receive a firmware update
ESP32 | [Drivers](/docs/getting-started/serial-drivers/esp32/) | [Firmware](/docs/getting-started/flashing-firmware/esp32/)
: A chipset of microcontroller made/designed by Espressif, used by a number of devices. Higher power usage than NRF52, but often cheaper and supports WiFi if desired.
: A chipset of microcontroller made/designed by Espressif, used by a number of devices. Higher power usage than NRF52, but often cheaper and supports WiFi if desired.
Firmware | [Guide](https://meshtastic.org/docs/getting-started/flashing-firmware/)
: The low-level software programmed onto a Meshtastic device, controlling its hardware functions and enabling it to communicate within the mesh network using LoRa technology. Firmware
@ -73,9 +73,12 @@ Packet
Protobuf | [Reference](/docs/development/reference/protobufs/)
: Protocol Buffers, a method developed by Google for serializing structured data, used in Meshtastic for efficient communication protocol between devices.
PSK | [Encryption](/docs/overview/encryption/)
Pre-Shared Key (PSK) | [Encryption](/docs/overview/encryption/)
: Pre-Shared Key, a secret code or passphrase used in Meshtastic channels for encryption, ensuring that only devices with the matching PSK can communicate within that specific channel.
Public Key Cryptography (PKC) | [Encryption](/docs/overview/encryption/)
: A cryptographic method introduced in Meshtastic v2.5 for Direct Messages and Admin Messages, where each device uses a unique public and private key pair. The public key, shared with other devices, enables secure message encryption, while the private key allows only the intended recipient to decrypt and authenticate the message. This approach enhances privacy and integrity for both direct device-to-device communication and sensitive admin functions.
Repeater | [Role Definitions](/docs/configuration/radio/device/#roles)
: Infrastructure node for extending network coverage by relaying messages with minimal overhead. Not visible in Nodes list.

5
package.json
View file

@ -22,7 +22,7 @@
"@giscus/react": "^3.0.0",
"@heroicons/react": "^2.1.1",
"@mdx-js/react": "^3.0.1",
"@meshtastic/js": "2.2.23-0",
"@meshtastic/js": "2.3.7-5",
"autoprefixer": "^10.4.17",
"base64-js": "^1.5.1",
"clsx": "^2.1.0",
@ -33,13 +33,14 @@
"react-dom": "^18.2.0",
"react-icons": "^5.0.1",
"react-markdown": "^9.0.1",
"react-player": "^2.16.0",
"remark-deflist": "^1.0.0",
"swr": "^2.2.5",
"tailwindcss": "^3.4.1"
},
"devDependencies": {
"@biomejs/biome": "^1.5.3",
"@buf/meshtastic_protobufs.bufbuild_es": "1.7.2-20240216123215-6b07c41c68c9.1",
"@buf/meshtastic_protobufs.bufbuild_es": "2.0.0-20240906232734-3da561588c55.2",
"@docusaurus/module-type-aliases": "3.1.1",
"@tailwindcss/typography": "^0.5.10",
"@tsconfig/docusaurus": "^2.0.2",

5075
pnpm-lock.yaml
View file

File diff suppressed because it is too large Load diff

6
src/components/GiscusComponent/index.js
View file

@ -7,10 +7,10 @@ export default function GiscusComponent() {
return (
<Giscus
repo="meshtastic/meshtastic"
repoId="MDEwOlJlcG9zaXRvcnkzMzkzMDEyMjI="
repo="meshtastic/discussions"
repoId="R_kgDONDs6gA"
category="Blog Post Comments"
categoryId="DIC_kwDOFDlTZs4Choq7"
categoryId="DIC_kwDONDs6gM4Cjy3h"
mapping="pathname"
term="specific-term" //If you didn't select "Discussion title contains a specific term", omit.
strict="1"

7
src/components/homepage/SocialCard.tsx
View file

@ -1,27 +1,28 @@
import type React from "react";
import { FiExternalLink } from "react-icons/fi";
export interface SocialCardProps {
children: React.ReactNode;
color: string;
link: string;
isMeLink?: boolean;
}
export const SocialCard = ({
children,
color,
link,
isMeLink = false,
}: SocialCardProps): JSX.Element => {
return (
<div
className={`group relative flex h-24 w-36 min-w-max flex-shrink-0 rounded-xl shadow-xl ${color} m-2`}
className={`group relative flex h-20 w-28 min-w-max flex-shrink-0 rounded-lg shadow-lg ${color} m-1`}
>
{children}
<a
className="absolute top-0 left-0 right-0 bottom-0 hidden rounded-xl border border-accent bg-secondary bg-opacity-95 text-2xl shadow-xl group-hover:flex"
href={link}
rel="noreferrer"
rel={isMeLink ? "me noreferrer" : "noreferrer"}
target="_blank"
>
<FiExternalLink className="m-auto" />

42
src/components/tools/FrequencyCalculator.tsx
View file

@ -215,6 +215,14 @@ const modemPresets = new Map<
Protobuf.Config.Config_LoRaConfig_ModemPreset,
Modem
>([
[
Protobuf.Config.Config_LoRaConfig_ModemPreset.SHORT_TURBO,
{
bw: 500,
cr: 5,
sf: 7,
},
],
[
Protobuf.Config.Config_LoRaConfig_ModemPreset.SHORT_FAST,
{
@ -323,8 +331,9 @@ export const FrequencyCalculator = (): JSX.Element => {
return (
<div className="flex flex-col border-l-[5px] shadow-md my-4 border-accent rounded-lg p-4 bg-secondary gap-2">
<div className="flex gap-2">
<label>Modem Preset:</label>
<label htmlFor="modemPreset">Modem Preset:</label>
<select
id="modemPreset"
value={modemPreset}
onChange={(e) =>
setModemPreset(
@ -342,8 +351,9 @@ export const FrequencyCalculator = (): JSX.Element => {
</select>
</div>
<div className="flex gap-2">
<label>Region:</label>
<label htmlFor="region">Region:</label>
<select
id="region"
value={region}
onChange={(e) => setRegion(Number.parseInt(e.target.value))}
>
@ -354,15 +364,21 @@ export const FrequencyCalculator = (): JSX.Element => {
))}
</select>
</div>
<div className="flex gap-2 mb-4">
<label className="font-semibold">Number of slots:</label>
<input type="number" disabled={true} value={numChannels} />
<label htmlFor="numSlots" className="font-semibold">
Number of slots:
</label>
<input
id="numSlots"
type="number"
disabled={true}
value={numChannels}
/>
</div>
<div className="flex gap-2">
<label>Frequency Slot:</label>
<label htmlFor="frequencySlot">Frequency Slot:</label>
<select
id="frequencySlot"
value={channel}
onChange={(e) => setChannel(Number.parseInt(e.target.value))}
>
@ -373,10 +389,16 @@ export const FrequencyCalculator = (): JSX.Element => {
))}
</select>
</div>
<div className="flex gap-2">
<label className="font-semibold">Frequency of slot:</label>
<input type="number" disabled={true} value={channelFrequency} />
<label htmlFor="slotFrequency" className="font-semibold">
Frequency of slot:
</label>
<input
id="slotFrequency"
type="number"
disabled={true}
value={channelFrequency}
/>
</div>
</div>
);

2
src/css/custom.css
View file

@ -280,4 +280,4 @@ p {
.markdown img {
margin-bottom: 0;
}
}

48
src/css/faq.css
View file

@ -1,46 +1,46 @@
.accordion {
border-radius: 2px;
border: 1px solid var(--ifm-color-emphasis-200);
border-radius: 2px;
border: 1px solid var(--ifm-color-emphasis-200);
}
.accordion__item + .accordion__item {
border-top: 1px solid var(--ifm-color-emphasis-200);
border-top: 1px solid var(--ifm-color-emphasis-200);
}
.accordion__button {
background-color: var(--ifm-footer-background-color);
border: none;
cursor: pointer;
padding: calc(var(--ifm-pre-padding)/1.5);
text-align: left;
width: 100%;
background-color: var(--ifm-footer-background-color);
border: none;
cursor: pointer;
padding: calc(var(--ifm-pre-padding) / 1.5);
text-align: left;
width: 100%;
}
.accordion__button:hover {
background-color: var(--ifm-background-surface-color);
background-color: var(--ifm-background-surface-color);
}
.accordion__button:before {
border-bottom: 2px solid currentColor;
border-right: 2px solid currentColor;
content: '';
display: inline-block;
height: 10px;
margin-right: 12px;
transform: rotate(-45deg);
width: 10px;
border-bottom: 2px solid currentColor;
border-right: 2px solid currentColor;
content: "";
display: inline-block;
height: 10px;
margin-right: 12px;
transform: rotate(-45deg);
width: 10px;
}
.accordion__button[aria-expanded='true']::before,
.accordion__button[aria-selected='true']::before {
transform: rotate(45deg);
.accordion__button[aria-expanded="true"]::before,
.accordion__button[aria-selected="true"]::before {
transform: rotate(45deg);
}
[hidden] {
display: none;
display: none;
}
.accordion__panel {
background: var(--ifm-background-color);
padding: var(--ifm-pre-padding);
background: var(--ifm-background-color);
padding: var(--ifm-pre-padding);
}

10
src/pages/downloads/_components/FirmwareCard.tsx
View file

@ -16,7 +16,9 @@ export const FirmwareCard = ({
<div className="card__header flex justify-between">
<h3>{variant}</h3>
{release?.length && (
<a href={release[0].page_url}>{release[0].title}</a>
<a href={release[0].page_url}>
{release[0].title.replace("Meshtastic Firmware ", "")}
</a>
)}
</div>
<div className="card__body">
@ -29,7 +31,9 @@ export const FirmwareCard = ({
{release.slice(1, 6).map((release) => {
return (
<div key={release.id}>
<a href={release.zip_url}>{release.title}</a>
<a href={release.page_url}>
{release.title.replace("Meshtastic Firmware ", "")}
</a>
</div>
);
})}
@ -38,7 +42,7 @@ export const FirmwareCard = ({
{release?.length ? (
<>
<a
href={release[0].zip_url}
href={release[0].page_url}
className="button button--secondary button--block margin-top--sm"
>
Download {variant}

12
src/pages/downloads/index.tsx
View file

@ -38,13 +38,12 @@ const Firmware = (): JSX.Element => {
<div className="flex w-full flex-col bg-primary xl:flex-row">
<div className="card m-4 border-2 border-secondary">
<div className="card__header">
<h3>ESP32 Web Flasher</h3>
<h3>Web Flasher</h3>
</div>
<div className="card__body">
<p>
Web based installer for easy flashing with Chrome and Edge
Browser. Works with T-Beam, T-Lora, Nano-G1 and similar
boards.
Web based flasher for easy device flashing with Chrome and
Edge Browser. Works with all major device architectures.
</p>
</div>
<div className="card__footer mt-auto">
@ -52,7 +51,7 @@ const Firmware = (): JSX.Element => {
href="https://flasher.meshtastic.org/"
className="m-auto flex rounded-lg border-4 border-transparent bg-accent p-1 font-semibold text-black shadow-md hover:text-black hover:brightness-110 active:border-green-200"
>
Go to Flasher
Go to Web Flasher
<ArrowTopRightOnSquareIcon className="m-auto ml-2 h-4" />
</a>
</div>
@ -97,7 +96,8 @@ const Firmware = (): JSX.Element => {
</div>
</div>
<div className="card__body">
Available on MacOS & iOS. Requires MacOS Ventura or iOS 16+.
Available on iOS, iPadOS and macOS. The last two major OS
versions are supported.
</div>
<div className="card__footer mt-auto">
<a

52
src/pages/index.tsx
View file

@ -27,7 +27,7 @@ const SocialCards: SocialCardProps[] = [
children: (
<img
alt="twitter"
className="m-auto h-14"
className="m-auto h-10"
src="/img/homepage/Twitter-Logo-White.svg"
/>
),
@ -38,7 +38,7 @@ const SocialCards: SocialCardProps[] = [
children: (
<img
alt="facebook"
className="m-auto h-14"
className="m-auto h-10"
src="/img/homepage/f_logo_RGB-White_1024.webp"
/>
),
@ -49,7 +49,7 @@ const SocialCards: SocialCardProps[] = [
children: (
<img
alt="instagram"
className="m-auto h-14"
className="m-auto h-10"
src="/img/homepage/Instagram_Glyph_Gradient.svg"
/>
),
@ -60,19 +60,8 @@ const SocialCards: SocialCardProps[] = [
children: (
<img
alt="youtube"
className="m-auto h-16"
src="/img/homepage/YouTube-Logo-White.svg"
/>
),
},
{
color: "bg-[#ffffff]",
link: "https://meshtastic.discourse.group",
children: (
<img
alt="discourse"
className="m-auto h-12"
src="/img/homepage/Discourse-Logo-White.svg"
src="/img/homepage/YouTube-Logo-White.svg"
/>
),
},
@ -82,18 +71,30 @@ const SocialCards: SocialCardProps[] = [
children: (
<img
alt="reddit"
className="m-auto h-20"
className="m-auto h-14"
src="/img/homepage/Reddit-Logo-White.svg"
/>
),
},
{
color: "bg-[#563ACC]",
link: "https://mastodon.social/@meshtastic",
isMeLink: true,
children: (
<img
alt="mastodon"
className="m-auto h-10"
src="/img/homepage/mastodon-logo-white.svg"
/>
),
},
{
color: "bg-[#24A1DE]",
link: "https://t.me/+hmKN0xOR73ExOTU6",
children: (
<img
alt="telegram"
className="m-auto h-14"
className="m-auto h-10"
src="/img/homepage/telegram-single-path-240px.svg"
/>
),
@ -147,9 +148,14 @@ function Home() {
<main className="flex flex-col gap-4">
<div className="bg-primaryDark mx-auto flex w-full lg:w-auto flex-col gap-4 p-4 shadow-inner">
<h3 className="text-xl font-bold">Connect with us.</h3>
<div className="flex w-full overflow-x-auto">
<div className="flex w-full overflow-x-auto gap-2 flex-wrap justify-center">
{SocialCards.map((card) => (
<SocialCard key={card.link} color={card.color} link={card.link}>
<SocialCard
key={card.link}
color={card.color}
link={card.link}
isMeLink={card.isMeLink}
>
{card.children}
</SocialCard>
))}
@ -177,11 +183,7 @@ function Home() {
<li>Radio</li>
<li>Battery</li>
<li>Case</li>
<li>
Antenna (most devices include an antenna, but the quality
can be a bit of a mixed bag from some suppliers on stock
antennas)
</li>
<li>Antenna</li>
</ul>
</p>
</div>
@ -192,7 +194,7 @@ function Home() {
</div>
<div className="card__body flex justify-center">
<p>
The Meshtastic Web-Based Flasher & Clients can assist you in
The Meshtastic Web Flasher & Clients can assist you in
flashing the firmware and configuring settings.
</p>
</div>

BIN
static/documents/mqtt/Broker1.jpg
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 25 KiB

BIN
static/documents/mqtt/Broker1.webp Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 6.8 KiB

BIN
static/documents/mqtt/Consume.jpg
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 37 KiB

BIN
static/documents/mqtt/Consume.webp Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 9 KiB

BIN
static/documents/mqtt/Decode.jpg
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 129 KiB

BIN
static/documents/mqtt/Decode.webp Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 34 KiB

BIN
static/documents/mqtt/DecodeNewest.jpg
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 148 KiB

BIN
static/documents/mqtt/DecodeNewest.webp Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 40 KiB

BIN
static/documents/mqtt/EncodingPosition.jpg
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 143 KiB

BIN
static/documents/mqtt/EncodingPosition.webp Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 40 KiB

BIN
static/documents/mqtt/Forward.jpg
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 121 KiB

BIN
static/documents/mqtt/Forward.webp Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 29 KiB

BIN
static/documents/mqtt/Inject.jpg
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 36 KiB

BIN
static/documents/mqtt/Inject.webp Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 10 KiB

BIN
static/documents/mqtt/MapFlow.jpg
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 168 KiB

BIN
static/documents/mqtt/MapFlow.webp Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 45 KiB

BIN
static/documents/mqtt/Mapping.jpg
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 191 KiB

BIN
static/documents/mqtt/Mapping.webp Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 58 KiB

BIN
static/documents/mqtt/NR_nodes.jpg
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 146 KiB

BIN
static/documents/mqtt/NR_nodes.webp Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 54 KiB

BIN
static/documents/mqtt/NodeRedThree.jpg
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 415 KiB

BIN
static/documents/mqtt/NodeRedThree.webp Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 101 KiB

BIN
static/documents/mqtt/NodeRedTwo.jpg
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 409 KiB

BIN
static/documents/mqtt/NodeRedTwo.webp Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 98 KiB

BIN
static/documents/mqtt/PosJSON.jpg
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 95 KiB

BIN
static/documents/mqtt/PosJSON.webp Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 26 KiB

Some files were not shown because too many files have changed in this diff Show more