mudhorn/meshtastic
1
0
Fork 0
mirror of https://github.com/meshtastic/meshtastic.git synced 2024-12-26 06:04:22 -08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge branch 'master' into master

Browse source
This commit is contained in:
rcarteraz 2023-11-03 08:57:08 -07:00 committed by GitHub
parent 5750ded4c4 08e25f2c53
commit 3066d68e43
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
280 changed files with 9198 additions and 11071 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.npmrc Normal file
View file

@ -0,0 +1 @@
@buf:registry=https://buf.build/gen/npm/v1

10
.trunk/configs/rome.json
View file

@ -1,5 +1,5 @@
{
"$schema": "../../node_modules/rome/configuration_schema.json",
"$schema": "./node_modules/rome/configuration_schema.json",
"formatter": {
"enabled": true,
"indentStyle": "space",
@ -13,5 +13,11 @@
},
"organizeImports": {
"enabled": true
},
"files": {
"ignore": [
"node_modules",
"dist"
]
}
}
}

5
.vscode/settings.json vendored
View file

@ -3,5 +3,8 @@
"editor.defaultFormatter": "trunk.io",
"files.associations": {
"*.mdx": "markdown"
},
"[typescriptreact]": {
"editor.defaultFormatter": "rome.rome"
}
}
}

24
docs/about/contributing.mdx
View file

@ -4,14 +4,16 @@ sidebar_label: Contributing
slug: /contributing
sidebar_position: 3
---
### Volunteer Based Development
Meshtastic is a team of volunteers, and as such there is always plenty of ways to help. This project gets great contributions from people in their off hours. Those contributors work on the features they are interested in. It is a very open and welcoming developer community, and we are always looking for help to improve Meshtastic.
Meshtastic is a team of volunteers, and as such there are always plenty of ways to help. This project gets great contributions from people in their off hours. Those contributors work on the features they are interested in. It is a very open and welcoming developer community, and we are always looking for help to improve Meshtastic.
- If you're a developer, there's plenty stuff to do. Dig in!
- If you're interacting with Meshtastic radios, we could use help with testing, documenting, and providing feedback.
- If you're into Web Development, check out the different web repos.
- If you're into Kotlin and Android, check out the link to the repo below.
- If you're into Python, check out the link to the repo below
- If you're into SwiftUI, check out the link to the repo below
- If you're into Ham Radio and LoRa, then this is a great project for you!
- ... basically... we would love to have your help and feedback
@ -27,20 +29,20 @@ Most communication and interactions happen with protocol buffers. The [Meshtasti
### Device Firmware
The [firmware](https://github.com/meshtastic/firmware) is where all of the firmware development happens. This is where the code for the ESP32 and nRF52 based devices is developed. It is mainly C and C++ code. Think Arduino. It is where the first level of hardware interaction begins and ends.
The [firmware repo](https://github.com/meshtastic/firmware) is where all of the device firmware development happens. This is where the code for the ESP32 and nRF52 based devices is developed. It is mainly C and C++ code. Think Arduino. It is where the first level of hardware interaction begins and ends.
### Firmware Modules
[Modules](/docs/settings/moduleconfig) are also implemented mainly in the firmware repo above. Typically, you would add functionality in the protobufs repo and the device repo to implement module functionality. You probably also want to have some client/device use/interact with the module and that is where the Device support comes into play.
[Modules](/docs/configuration/module) extend device and mesh functionality beyond core functions. These are also implemented mainly in the firmware repo above. Typically, you would add functions in the protobufs repo and the device repo to implement module functionality. You probably also want to have some client or device, use or interact with the module. This is where Device Interface support comes into play.
### CLI Apps (Device Interface)
- **Meshtastic Python CLI** - The [meshtastic/Meshtastic-python](https://github.com/meshtastic/Meshtastic-python) repository is typically where the first device interaction takes place, but that is not a requirement. This repo has a command line utility that allows you to interact with most functionality with the devices. This python library can also be consumed for other applications.
- **Meshtastic Python CLI** - The [meshtastic/Meshtastic-python repository](https://github.com/meshtastic/Meshtastic-python) is a command line utility that allows you to interact with most of the device settings and functionality. This python library can also be consumed for other applications. See [Meshtastic Python Development](/docs/development/python/) for more details
### Web Apps (Device Interface)
- **Meshtastic Web** - The [meshtastic/web](https://github.com/meshtastic/web) repository is where the hosted web server on the ESP32 devices in Typescript is developed. See the [Web interface overview](/docs/software/web-client) for more details.
- **Meshtastic JS** - The [meshtastic/meshtastic.js](https://github.com/meshtastic/meshtastic.js) repository is a JavaScript library that provides an interface for Meshtastic devices.
- **Meshtastic Web** - The [meshtastic/web repository](https://github.com/meshtastic/web) is where the hosted web server on the ESP32 devices in Typescript is developed. See the [Web Development Overview](/docs/development/web/) for more details.
- **Meshtastic JS** - The [meshtastic/meshtastic.js](https://github.com/meshtastic/meshtastic.js) repository is a JavaScript library that provides an interface for Meshtastic devices. See [Javascript Development](/docs/development/js) for more details
@sachaw has been making tons of progress on the web app and would love help with:
@ -49,13 +51,13 @@ The [firmware](https://github.com/meshtastic/firmware) is where all of the firmw
- Chat scroll lock
- Various module support
### Mobile Apps (Device Interface)
### Mobile and Desktop Apps (Device Interface)
There are two phone apps that interact with the Meshtastic devices:
There are Android, iOS, iPadOS, and macOS apps that interact with Meshtastic devices:
- **Android App** - The [meshtastic/Meshtastic-Android](https://github.com/meshtastic/Meshtastic-Android) repository repo contains the Kotlin code for Android based interactions with Meshtastic devices. See the [Android development instructions](/docs/development/android) on how to create a development environment and build the Meshtastic Android App.
- **Apple Apps** - The iOS applications are in the process of a complete re-write in Swift and will have the new repo published soon. Note: There are a couple of earlier implementations.
- **Android App** - The [meshtastic/Meshtastic-Android](https://github.com/meshtastic/Meshtastic-Android) repository contains the Kotlin code for Android based interactions with Meshtastic devices. See the [Android development instructions](/docs/development/android) on how to create a development environment and build the Meshtastic Android App.
- **Apple Apps** - The [meshtastic/Meshtastic-Apple](https://github.com/meshtastic/Meshtastic-Apple) repository contains the SwiftUI client applications code for iPhone, iPad and Mac.
### Documentation
This website is in the [Meshtastic](https://github.com/meshtastic/meshtastic) repository.
The Meshtastic website (the one you are looking at right now) is in the [meshtastic/Meshtastic](https://github.com/meshtastic/meshtastic) repository. See [Maintaining Documentation](docs/development/docs) for more details.

33
docs/about/faq.mdx
View file

@ -45,12 +45,13 @@ Try forgetting the Bluetooth connection from the Android Bluetooth Settings menu
### What version of iOS/iPadOS/macOS does the Meshtastic App Require?
The Meshtastic App on Apple Clients require the following minimum OS versions: iOS 16, iPadOS 16, and macOS 13.
The Meshtastic App on Apple Clients require the following minimum OS versions: iOS 16.2, iPadOS 16.2, and macOS 13.
### How do I get the Apple Meshtastic App?
See [Apple Apps](/docs/software/apple/installation)
<!-- trunk-ignore(markdownlint/MD024) -->
### After a fresh firmware install, my node is not connecting via Bluetooth. What should I do?
Try forgetting the Bluetooth connection from the iOS/iPadOS/macOS System Settings. Re-pair and try again. This is a security measure and there is no workaround for it. It prevents apps and other accessories from spoofing an existing accessory by un-pairing and "re-pairing" themselves without the users' knowledge.
@ -97,28 +98,28 @@ Push the left PWR button for about 1 second.
### Where do I purchase the device hardware?
Each [supported device](/docs/hardware/devices/tbeam) has a "Purchase Link".
Each [supported device](/docs/supported-hardware) has a "Purchase Link".
### I have my hardware. How do I install the firmware and any required drivers?
[See our guide here](/docs/getting-started/flashing-firmware).
[See our guide here](/docs/getting-started).
### How do I update the firmware to the latest version?
If the device is running Meshtastic firmware, you might be able to update over-the-air like via the Android app.
Updating firmware varies with hardware. See [Flashing Firmware](/docs/getting-started/flashing-firmware).
### My device has gone to sleep. Are received messages lost?
The LoRa radio on the node is still active and will wake up the CPU when the device is sleeping. If your phone is in range, the node will relay any messages your phone may have missed. If you're in range and your device is active, messages have not been lost.
<!-- trunk-ignore(markdownlint/MD026) -->
### My device has gone to sleep and I can't send any messages.
Once the node wakes up from sleep, your phone will relay any delayed messages through your node and to the mesh network. Give it a few minutes and it'll do the right thing.
### How can I tell the device not to sleep?
- Android instructions see: [Android Usage](/docs/software/android/usage#configuration-options)
- Python CLI instructions see: [Python Usage](/docs/software/python/cli/usage#changing-settings)
See [Device Power Configuration](/docs/configuration/radio/power) options.
### I am in Europe and my device seems to stop transmitting after a while, what is going on?
@ -142,27 +143,21 @@ If you use your HAM radio license with Meshtastic, consider both the privileges
#### Privileges
- Increased Transmit Power
- Up to 1500W transmit power! [FCC Part 97.313](https://www.ecfr.gov/current/title-47/chapter-I/subchapter-D/part-97/subpart-D/section-97.313)
- Up to 10W transmit power in the United States! [47 CFR 97.313(j)](https://www.ecfr.gov/current/title-47/chapter-I/subchapter-D/part-97#p-97.313(j))
- Higher Gain Antennas
#### Restrictions
- Plain-Text Only
- On amateur radio bands, encryption is illegal. [FCC Part 97.113.C](https://www.ecfr.gov/current/title-47/chapter-I/subchapter-D/part-97/subpart-B/section-97.113)
- On amateur radio bands, encryption is illegal. [FCC Part 97.113.A.4](https://www.ecfr.gov/current/title-47/chapter-I/subchapter-D/part-97/subpart-B/section-97.113#p-97.113(a)(4))
- Lack of Privacy
- As a HAM operator, it is a requirement that you identify yourself by your call sign periodically when transmitting. Your call sign will be publicly transmitted at least once every 10 minutes at minimum. [FCC Part 97.119.A](https://www.ecfr.gov/current/title-47/chapter-I/subchapter-D/part-97/subpart-B/section-97.119)
- As a HAM operator, it is a requirement that you identify yourself by your call sign periodically when transmitting. Your call sign will be publicly transmitted at least once every 10 minutes at minimum. [FCC Part 97.119.A](https://www.ecfr.gov/current/title-47/chapter-I/subchapter-D/part-97/subpart-B/section-97.119#p-97.119(a))
### How do I set my HAM call sign?
Please see instructions for [Enabling HAM License from the Python CLI](/docs/software/python/cli/usage#ham-radio-support)
<!-- Flasher -->
## Flasher
### Why does my operating system flag Meshtastic Flasher as having malware?
The flasher contains no malware and completely passed the Microsoft malware scanning. It appears that a lot of file download services are using the Windows Defender data, so if you're seeing alerts of a detected trojan please [update your Windows Defender definitions](https://www.microsoft.com/en-us/wdsi/defenderupdates).
- 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).
### What if I'm still having issues on Windows 10?
@ -194,7 +189,7 @@ Modules are features that expand the basic device functionality and/or integrate
### What modules do we have available?
A list of available modules is available [here](/docs/settings/moduleconfig).
A list of available modules is available [here](/docs/configuration/module).
### I'd like to write a module. How do I get started?

4
docs/about/introduction.mdx
View file

@ -11,9 +11,9 @@ Meshtastic® is a project that enables you to use inexpensive LoRa radios as a l
### Features
- Long range ([_166km record by PuzzledPancake_](/docs/overview/range-tests#current-record))
- Long range ([_254km record by kboxlabs_](/docs/overview/range-tests#current-record))
- No phone required for mesh communication
- Decentralised communication - no dedicated router required
- Decentralized communication - no dedicated router required
- Encrypted communication
- Excellent battery life
- Send and receive text messages between members of the mesh

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

@ -6,33 +6,37 @@ slug: /overview/encryption
sidebar_position: 3
---
Cryptography is tricky, so we've tried to 'simply' apply standard crypto solutions to our implementation. However, the project developers are not cryptography experts. Therefore we ask two things:
- 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).
Cryptography is tricky, so we've tried to 'simply' apply standard crypto solutions to our implementation. However, the project developers are not cryptography experts.
Always keep in mind [xkcd's note on encryption](https://xkcd.com/538).
## Summary of strengths/weaknesses of our current implementation
Based on comments from reviewers (see below), here's some tips for usage of these radios. So you can know the level of protection offered:
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)
Possible future areas of work (if there is enough interest - post in our [forum](https://meshtastic.discourse.group) if you want this):
The current implementation provides optional confidentiality to members of a configured network:
1. Optionally requiring users to provide a PIN to regain access to the mesh. This could be based on: intentionally locking the device, time since last use, or any member could force all members to re-authenticate,
2. Until a device re-authenticates, any other access via BLE or USB would be blocked (this would protect against attackers who are not prepared to write custom software to extract and reverse engineer meshtastic flash memory)
3. Turning on read-back protection in the device fuse-bits (this would extend protection in #2 to block all but **extremely** advanced attacks involving chip disassembly)
4. Time limiting keys used for message transmission and automatically cycling them on a schedule. This would protect past messages from being decoded even if an attacker learns the current key.
- 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.
### Notes for reviewers
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.
- 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.
@ -53,61 +57,4 @@ I'm assuming that meshtastic is being used to hike in places where someone capab
- 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.
## Phased Proposal for the Meshtastic Security Framework
### Phase 1 - Fixed network encryption with AES-CTR
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 protextion of all nodes.
### Phase 2 - Strong device and client identity
**Phase 2 security goals:**
- Know who sent a message (strong binding of messages to a particular node and/or terminal device)
- This would be an optional feature for a message
- Optionaly enforce identity based restrictions on some actions performed at nodes and/or clients
- Optional support of strong pairing of a client to a device/node and restrict ability to manage and receive messages based on the pairing.
- The BT paring and the cryptographic paring are separate (to simplify pahse 1 deployment and testing)
- Above features should be architected to be ‘cryptographically strong’ and algorithm agile.
**Phase 2 Proposed mechanisms:**
- Proposed initial algorithms
- Ed25519 for signatures based on NaCl libraries and iOS support for Ed25519
- Clients and nodes to generate local identity Ed25519 keys
- Devices maintain knowledge of owner public key
- Devices maintain knowledge of some peers public keys and associated information (name, etc.)
- Experimental protobuf message type with
- cipher suite indicator (csi)
- wrapped data using a cipher suite identifier to indicate use of Ed25519 wrapping identified algorithms.
Wrapped data to contain any of the existing message types.
- initial ‘cipher suite’ **only** signs a message
- new signed/authenticated messages to:
- device->client: provide ownership status of device (owner is identifed by a public key)
- client->device: set owner key (must be existing device owner or owner null)
- any->all. Broadcast public key and associated info (crude initial key distribution)
### Phase 3 and 3+:
- Device/node e2e message confidentiality (1-to-1)
- NO client side encryption
- All encryption turned off for a network in 'Ham mode'
- Protect messages sent over LoRa from eavesdroppers outside of a well identified group
- multicast group key distribution / discovery (1-to-n)
- Privacy
- BT MAC layer address privatization
- Node address privatization (Use use if based on device public key and schedule based aliasing)
- Private peer discovery
- Private service announcement and discovery
- Device/node security (hardening key storage, tamper resistance, side channel protection, etc.)
- Public key pairing process for client-to-device also sets up BT (no BT pin)
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.

5
docs/about/overview/mesh-alg.mdx
View file

@ -10,6 +10,8 @@ sidebar_position: 2
The routing protocol for Meshtastic is really quite simple (and sub-optimal). If you want to test its theoretical performance, you can have a look at the [simulator](https://github.com/GUVWAF/Meshtasticator). The protocol is heavily influenced by the mesh routing algorithm used in [RadioHead](https://www.airspayce.com/mikem/arduino/RadioHead) (which was used in very early versions of this project). It has four conceptual layers.
<object data="https://www.youtube.com/embed/7v6UbC5blJU?autohide=1&autoplay=0" width="100%" height="400"></object>
### A Note About Protocol Buffers
Because we want our devices to work across various vendors and implementations, we use [Protocol Buffers](https://github.com/meshtastic/protobufs) pervasively. For purposes of this document you mostly only
@ -34,7 +36,8 @@ This layer is conventional non-reliable LoRa packet transmission. A packet gener
| 0x08 | 4 bytes | Integer | Packet Header: The sending node's unique packet ID for this packet. |
| 0x0C | 1 byte | Bits | Packet Header: Flags. See the [header flags](#packet-header-flags) for usage. |
| 0x0D | 1 byte | Bits | Packet Header: Channel hash. Used as hint for decryption for the receiver. |
| 0x0E | Max. 237 bytes (excl. protobuf overhead) | Bytes | Actual packet data. Unused bytes are not transmitted. |
| 0x0E | 2 bytes | Bytes | Packet Header: Padding for memory alignment. |
| 0x10 | Max. 237 bytes (excl. protobuf overhead) | Bytes | Actual packet data. Unused bytes are not transmitted. |
#### Packet Header Flags

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

@ -28,7 +28,7 @@ The maximum power allowed for Europe is +14 dBm ERP ([Effective Radiated Power](
The band range is from 433 to 434 MHz.
There are four channels defined with the standard radio preset `LongFast`. After factory reset the radio will be set to channel 3 with a center frequency of 433.875 MHz.
There are four channels defined with the standard radio preset `LongFast`. After factory reset the radio will be set to channel 4 with a center frequency of 433.875 MHz.
### 868 MHz
@ -36,7 +36,7 @@ The maximum power allowed for Europe is +27 dBm ERP ([Effective Radiated Power](
The band range is from 869.40 to 869.65 MHz. This is less than the 863–870 MHz range defined as SRD Band, but allows for a higher ERP and a duty cycle of 10%.
There is one channel defined with the standard radio preset `LongFast`. After factory reset the radio will be set to channel 0 with a center frequency of 869.525 MHz.
There is one channel defined with the standard radio preset `LongFast`. After factory reset the radio will be set to channel 1 with a center frequency of 869.525 MHz.
## North America Frequency Bands
@ -46,7 +46,7 @@ The maximum output power for North America is +30 dBm ERP ([Effective Radiated P
The band range is from 902 to 928 MHz.
There are 104 channels defined with the standard radio preset `LongFast`. After factory reset the radio will be set to channel 19 with a center frequency of 906.875 MHz.
There are 104 channels defined with the standard radio preset `LongFast`. After factory reset the radio will be set to channel 20 with a center frequency of 906.875 MHz.
## Data Rates
@ -54,7 +54,7 @@ There are 104 channels defined with the standard radio preset `LongFast`. After
Various data-rate options are available when configuring a channel and are inversely proportional to the theoretical range of the devices.
- **Spreading Factor** - How much we "spread" our data over time.
- **Spreading Factor (SF)** - How much we "spread" our data over time.
- Each step up in Spreading Factor doubles the airtime to transmit.
- Each step up in Spreading Factor adds about 2.5db extra link budget.
- **Bandwidth** - How big of a slice of the spectrum we use.
@ -88,11 +88,7 @@ The link budget used by these calculations assumes a transmit power of 17dBm and
### Custom Settings
You may want to select other channels for your usage. The other settings can be set by using the Python API.
```shell
meshtastic --ch-set spread_factor 10 --ch-set coding_rate 4 --ch-set bandwidth 125 --ch-index 0
```
Custom settings can be applied by using [supported software](/docs/software).
After applying the settings, you will need to restart the device. After your device is restarted, it will generate a new crypto key and you will need to share the newly generated QR Code or URL to all your other devices.
@ -113,18 +109,8 @@ 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 channel settings may have not been tested. Use at your own discretion. Share on <https://meshtastic.discourse.group> with your successes or failure.
These channel settings may not have been tested. Use at your own discretion. Share on https://meshtastic.discourse.group with your successes or failure.
## Cryptography
The pre-shared key (PSK) used by the devices can be modified.
- 0 = No crypto
- 1 = Default channel key
- 2 - 10 = The default channel key, except with 1 through 9 added to the last byte
Use of cryptography can also be modified. To disable cryptography (maybe useful if you have Ham radio license):
```shell
meshtastic --setchan psk 0
```
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.

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

@ -6,26 +6,71 @@ sidebar_label: Range Tests
sidebar_position: 4
---
## Current Record
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
<Tabs
defaultValue="ground"
values={[
{label: 'Ground to Ground', value: 'ground'},
{label: 'Ground to Air', value: 'air'},
]}>
<TabItem value="ground">
## Current Ground Record: 254km
- **Range:** 254km (158 miles)
- **Record Holders:** _kboxlabs_
- **Source:** [Meshtastic Discourse](https://meshtastic.discourse.group/t/practical-range-test-results/692/137)
<h2 id="modem-settings-254">Modem Settings</h2>
Default Long_Fast
- **Frequency:** 915MHz
- **Bandwidth:** 250
- **Spread Factor:** 11
- **Coding Rate:** 4/8
<h2 id="node-a-254">Node A</h2>
- **Device:** [RAK4631 Core](https://meshtastic.org/docs/hardware/devices/rak/core-module) with [RAK 5005-O Base Board](https://meshtastic.org/docs/hardware/devices/rak/base-board)
- **Firmware Version:** 2.1.17
- **Antenna:** 902-928MHz 5.8 dBi Slinkdsco Outdoor
<h2 id="node-b-254">Node B</h2>
- **Device:** [RAK4631 Core](https://meshtastic.org/docs/hardware/devices/rak/core-module) with [RAK 19003 Mini Base Board](https://meshtastic.org/docs/hardware/devices/rak/base-board)
- **Firmware Version:** 2.1.18
- **Antenna:** Standard LoRa 915MHz 60mm 2dBi Omnidirectional
<img src="/img/records/kboxlabs_sender.png" alt="Sending Node" />
<img src="/img/records/kboxlabs_receiver.png" alt="Receiving Node" />
<img src="/img/records/kboxlabs_map.png" alt="Geographic Locations" />
## Previous Record 166km
- **Range:** 166km (103 miles)
- **Record Holder:** _PuzzledPancake_
- **Source:** [Meshtastic Discourse](https://meshtastic.discourse.group/t/practical-range-test-results/692/44)
### Modem Settings
<h2 id="modem-settings-166">Modem Settings</h2>
- **Frequency:** 868MHz
- **Bandwidth:** 125
- **Spread Factor:** 12
- **Coding Rate:** 4/8
### Node A
<h2 id="node-a-166">Node A</h2>
- **Device:** [LILYGO TTGO T-Beam w/ SX1262](/docs/hardware/devices/tbeam)
- **Firmware Version:** 1.2
- **Antenna:** [868MHz 5dBi Antenna](https://ivent.co.nz/product/category/1000/868mhz%205dbi%20antenna%20193mm%20black%20sma%20%28m%29/38646)
### Node B
<h2 id="node-b-166">Node B</h2>
- **Device:** [LILYGO TTGO T-Beam w/ SX1262](/docs/hardware/devices/tbeam)
- **Firmware Version:** 1.2
@ -37,6 +82,42 @@ sidebar_position: 4
![Node B](https://canada1.discourse-cdn.com/free1/uploads/meshtastic/optimized/2X/1/1c8bd5fc41f7bab925404b657a9c481882de9313_2_1332x1000.jpeg)
### Resources Used
<h2>Resources Used</h2>
- http://www.heywhatsthat.com
</TabItem>
<TabItem value="air">
## Current Air Record: 206km
- **Range:** 206km (128 miles)
- **Record Holders:** _StarWatcher, CVR, rook, kboxlabs_
- **Source:** [Meshtastic Discourse](https://meshtastic.discourse.group/t/practical-range-test-results/692/130)
<h2 id="modem-settings-206">Modem Settings</h2>
Default Long_Fast
- **Frequency:** 915MHz
- **Bandwidth:** 250
- **Spread Factor:** 11
- **Coding Rate:** 4/8
<h2 id="node-a-206">Node A</h2>
- **Device:** [LILYGO TTGO T-Beam](/docs/hardware/devices/tbeam)
- **Firmware Version:** 2.1.10
- **Antenna:** Stock Antenna
<h2 id="node-b-206">Node B</h2>
- **Device:** [LILYGO TTGO T-Beam](/docs/hardware/devices/tbeam)
- **Firmware Version:** 2.1.10 (modified to place GPS in flight mode)
- **Antenna:** Stock Antenna
<img src="/img/records/Devices-Balloon.png" alt="Nodes and Balloon" />
<img src="/img/records/app-screenshots.png" alt="App Screenshots" />
</TabItem>
</Tabs>

2
docs/configuration/_category_.yml
View file

@ -4,4 +4,4 @@ position: 4
link:
type: generated-index
title: Configuration
slug: /settings
slug: /configuration

21
docs/configuration/device-config/index.mdx
View file

@ -1,21 +0,0 @@
---
id: config
title: Device Configuration
sidebar_label: Device Config
slug: /settings/config
sidebar_position: 1
---
There are several config sections in the Meshtastic firmware, these are broken out so they can be sent as small admin messages over the mesh.
| Name | Description |
| :------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| [Bluetooth](/docs/settings/config/bluetooth) | Bluetooth config options are: Enabled, Pairing Mode and Fixed PIN. |
| [Channels](/docs/settings/config/channels) | Channels config options are: Index, Role and Settings. |
| [Device](/docs/settings/config/device) | Device config options are: Device Role, Serial Output, Debug Log and Factory Reset. |
| [Display](/docs/settings/config/display) | Display config options are: Screen On Duration, Auto Carousel Interval, Always Point North, and GPS Format. |
| [LoRa](/docs/settings/config/lora) | The LoRa config options are: Region, Modem Preset, Max Hops, Transmit Power, Bandwidth, Spread Factor, Coding Rate, Frequency Offset, Transmit Disabled and Ignore Incoming Array. |
| [Network](/docs/settings/config/network) | Network config options are: WiFi Enabled, WiFi SSID, WiFi PSK, WiFi Mode and NTP Server. |
| [Position](/docs/settings/config/position) | Position config options are: GPS Enabled, GPS Update Interval, GPS Attempt Time, Fixed Position, Smart Broadcast, Broadcast Interval and Position Packet Flags. |
| [Power](/docs/settings/config/power) | Power config options are: Charge Current, Power Saving, Shutdown after losing power, ADC Multiplier Override Wait Bluetooth Interval, Mesh Super Deep Sleep Timeout, Super Deep Sleep Interval, Light Sleep Interval and Minimum Wake Interval. |
| [User](/docs/settings/config/user) | The user config options are: Long Name, Short Name, and Is Licensed |

20
docs/configuration/module-config/index.mdx
View file

@ -1,20 +0,0 @@
---
id: module-config
title: Module Configuration
sidebar_label: Module Config
slug: /settings/moduleconfig
sidebar_position: 3
---
Modules are included in the firmware and allow users to extend the functionality of their mesh or device.
| Name | Description |
| :------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| [Audio](/docs/settings/moduleconfig/audio) | enable Support for Codec2 Voice Comms on certain devices |
| [Canned Message](/docs/settings/moduleconfig/canned-message) | Set a number of predefined messages to send out directly from the device with the use of an input device like a rotary encoder. |
| [External Notification](/docs/settings/moduleconfig/external-notification) | Incoming messages are able to alert you using circuits you attach to the device (LEDs, Buzzers, etc) |
| [MQTT](/docs/settings/moduleconfig/mqtt) | Forward packets along to an MQTT server. This allows users on the local mesh to communicate with users on another mesh over the internet. |
| [Range Test](/docs/settings/moduleconfig/range-test) | Send messages with GPS location at an interval to test the distance your devices can communicate. Requires (at least) one device set up as a sender and one as a receiver. The receiver(s) will log all incoming messages to a CSV. |
| [Serial Module](/docs/settings/moduleconfig/serial) | Send messages across the mesh by sending strings over a serial port. |
| [Telemetry](/docs/settings/moduleconfig/telemetry) | Attach sensors to the device and transmit readings on a regular interval to the mesh. |
| [Traceroute](/docs/settings/moduleconfig/traceroute) | Track which nodes are used to hop a message to a certain destination. |

118
docs/configuration/module-config/mqtt.mdx
View file

@ -1,118 +0,0 @@
---
id: mqtt
title: MQTT Module Configuration
slug: /settings/moduleconfig/mqtt
sidebar_label: MQTT
---
import Tabs from "@theme/Tabs";
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 be enabled as uplink and/or downlink for protobufs to be transmitted from and/or to the mesh (See [channels](/docs/settings/config/channels#downlink-enabled)). Without these settings the node will still connect to MQTT server and send status messages.
The MQTT module config options are: Enabled, Server Address, Username, Password, Encryption Enabled and JSON Enabled. MQTT Module config uses an admin message sending a `ConfigModule.MQTT` protobuf.
## Settings
## MQTT Module Config Values
### Enabled
Enables the MQTT module.
### Server Address
The server to use for MQTT. If not set, the default server public will be used.
### Username
MQTT Server username to use (most useful for a custom MQTT server). If using a custom server, this will be honored even if empty. If using the default public server, this will only be honored if set, otherwise the device will use the default username.
### Password
MQTT password to use (most useful for a custom MQTT server). If using a custom server, this will be honored even if empty. If using the default server, this will only be honored if set, otherwise the device will use the default password
### Encryption Enabled
Whether to send encrypted or decrypted packets to MQTT. This parameter is only honored if you also set server (the default official mqtt.meshtastic.org server can handle encrypted packets) Decrypted packets may be useful for external systems that want to consume meshtastic packets.
### JSON Enabled
Enable the sending / consumption of JSON packets on MQTT. These packets are not encrypted, but offer an easy way to integrate with systems that can read JSON.
## MQTT Module 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">
:::info
MQTT Config options are available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Module Settings > MQTT Config**
:::
</TabItem>
<TabItem value="apple">
:::info
MQTT module config is not available for Apple.
:::
</TabItem>
<TabItem value="cli">
:::info
All MQTT module config options are available in the python CLI. Example commands are below:
:::
| Setting | Acceptable Values | Default |
| :---------------------: | :---------------: | :-----: |
| mqtt.enabled | `true`, `false` | `false` |
| mqtt.address | `string` | |
| mqtt.username | `string` | |
| mqtt.password | `string` | |
| mqtt.encryption_enabled | `string` | |
| mqtt.json_enabled | `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.
```shell title="Example:"
meshtastic --set mqtt.enabled true --set mqtt.json_enabled true
```
:::
```shell title="Enable/Disable MQTT Module"
meshtastic --set mqtt.enabled true
meshtastic --set mqtt.enabled false
```
```shell title="Enable/Disable MQTT JSON"
meshtastic --set mqtt.json_enabled true
meshtastic --set mqtt.json_enabled false
```
</TabItem>
<TabItem value="web">
:::info
All MQTT module config options are available for the Web UI.
:::
</TabItem>
</Tabs>

326
docs/configuration/module-config/store-and-forward-module.mdx
View file

@ -1,326 +0,0 @@
---
id: store-and-forward-module
title: Store & Forward Module Settings
sidebar_label: Store & Forward
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
:::info
Currently only available for ESP32 based devices with external PSRAM. Requires the device to be set as a ROUTER or ROUTER_CLIENT.
**Don't enable Store & Forward Module on multiple nodes.**
:::
## Overview
:::caution
This is a work in progress and is partially available. Stability is not guaranteed.
:::
The Store & Forward Module is an implementation of a Store and Forward system to enable resilient messaging in the event that a client device is disconnected from the main network.
Because of the increased network traffic for this overhead, it's not advised to use this if you are duty cycle limited for your airtime usage (EU_868 and EU_433) nor is it advised to use this for presets using SF11 or SF12 (e.g. all of the LongRange and VeryLongRange presets).
## Settings
| Setting | Acceptable Values | Default |
| :---------------------------------: | :---------------: | :-----: |
| store_forward.enabled | `true`, `false` | `false` |
| store_forward.heartbeat | `true`, `false` | `false` |
| store_forward.history_return_max | `integer` | `0` |
| store_forward.history_return_window | `integer` | `0` |
| store_forward.records | `integer` | `0` |
### Enabled
Enables the module.
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```shell title="Enable the module"
meshtastic --set store_forward.enabled true
```
```shell title="Disable the module"
meshtastic --set store_forward.enabled false
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
### Heartbeat
The Store & Forward Router sends a periodic message onto the network. This allows connected devices to know that a router is in range and listening to received messages. A client like Android, iOS, or Web can (if supported) indicate to the user whether a store and forward router is available.
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```shell title="Set store_forward.heartbeat to default"
meshtastic --set store_forward.heartbeat 0
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
### History Return Max
Sets the maximum number of messages to return to a client device.
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```shell title="Set store_forward.history_return_max to default"
meshtastic --set store_forward.history_return_max 0
```
```shell title="Set store_forward.history_return_max to 100 messages"
meshtastic --set store_forward.history_return_max 100
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
### History Return Window
Limits the time period (in minutes) a client device can request.
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```shell title="Set store_forward.history_return_window to default"
meshtastic --set store_forward.history_return_window 0
```
```shell title="Set store_forward.history_return_window to 1 day (1440 minutes)"
meshtastic --set store_forward.history_return_window 1440
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
### Records
Set this to the maximum number of records to save. Best to leave this at the default (`0`) where the module will use 2/3 of your device's available PSRAM. This is about 11,000 records.
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```shell title="Set store_forward.records to default (≈11,000 records)"
meshtastic --set store_forward.records 0
```
```shell title="Set store_forward.records to 100 records"
meshtastic --set store_forward.records 100
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
## Details
### How it works
![Store & Forward - Overview](/img/modules/store_and_forward/store_and_forward-overview.png)
### Requirements
Initial Requirements:
- Must be installed on a ROUTER or ROUTER_CLIENT node.
- This is an artificial limitation, but is in place to enforce best practices.
- Router nodes are intended to be always online. If this module misses any messages, the reliability of the stored messages will be reduced.
- ESP32 Processor based device with external PSRAM. (tbeam > v1.0, T3S3, and maybe others)
### Usage Overview
- To use / test this you will want at least 3 devices
- One ESP32 device with PSRAM configured as a Meshtastic router.
- Two others will be regular clients. Nothing special required.
### Meshtastic channel configuration
Don't use this on the "LongRange" channel settings. You're welcome to try and report back, but those channels have a [low bitrate](/docs/overview/radio-settings#pre-defined).
Either use a custom channel configuration with at an at least 1kbit data rate or use a Medium or Short range preset.
### Router setup
:::warning
Don't enable the Store and Forward module on multiple nodes for now!
:::
- Configure your device as a router.
- Name your router node something that makes it easily identifiable, aka "Router".
- Configure the Store and Forward module
```shell title="Required - Enable the module"
meshtastic --set store_forward.enabled true
```
```shell title="Optional - Set maximum number of records to save to device"
meshtastic --set store_forward.records 100
```
:::tip
Best to leave `store_forward.records` at the default (`0`) where the module will use 2/3 of your device's available PSRAM. This is about 11,000 records.
:::
### Client Usage
Currently, no special configuration is required. To request your history sent to you, send the command into the message field "SF". That's it. This will eventually change to make it easier. At the moment, that message will be sent to everyone on the mesh but we'll (eventually) make it easier to use where there'll be a button (or maybe it'll be transparent) and the command isn't sent as a text message to the mesh.
Available Commands:
| Command | Definition |
| :-----: | :----------------------------------------------------: |
| SF | Send the last hour worth of messages I may have missed |
The Store and Forward module will only service one client at a time. If a second client requests messages while the S&F is busy, the S&F will send a private message to the second client that they will need to wait.

105
docs/configuration/module/ambient-lighting.mdx Normal file
View file

@ -0,0 +1,105 @@
---
id: ambient-lighting
title: Ambient Lighting Module Usage
sidebar_label: Ambient Lighting
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The Ambient Lighting Module has settings for control of onboard LEDs and allows users to adjust the brightness levels and respective color levels. Initially created for the RAK14001 RGB LED module using the NCP5623 with I2C. Config options are: LED State, Current, Red Level, Green Level, and Blue Level.
In order to use this module, make sure your devices have firmware version 2.2.5 or higher.
## Ambient Lighting Config Values
### LED State
Sets the LED to on or Off
### Current
Sets the current for the LED output. Default is 10.
### Red
Sets the red LED level. Values are 0-255.
### Green
Sets the green LED level. Values are 0-255.
### Blue
Sets the blue LED level. Values are 0-255.
## Ambient Lighting Module Client Availability
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'Android', value: 'android'},
{label: 'Apple', value: 'apple'},
{label: 'CLI', value: 'cli'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="android">
:::info
All Ambient Lighting Module config options are available for Android in app version 2.2.3 and higher.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Ambient Lighting**
:::
</TabItem>
<TabItem value="apple">
:::info
All Ambient Lighting Module config options are available on iOS, iPadOS and macOS app versions 2.2.3 and higher at Settings > Modules > Ambient Lighting
:::
</TabItem>
<TabItem value="cli">
:::info
All Ambient Lighting Module config options are available in the python CLI version 2.2.3 and higher.
:::
Example commands are below:
```shell title="Set the LED to on or off"
meshtastic --set ambient_lighting.led_state 1
meshtastic --set ambient_lighting.led_state 0
```
```shell title="Set the led current to 5"
meshtastic --set ambient_lighting.current 5
```
```shell title="Set the red LED brightness to 103"
meshtastic --set ambient_lighting.red 103
```
```shell title="Set the green brightness to 234"
meshtastic --set ambient_lighting.green 234
```
```shell title="Set the blue LED brightness to 148"
meshtastic --set ambient_lighting.blue 148
```
```shell title="Get the Ambient Lighting Module Configuration"
meshtastic --get ambient_lighting
```
</TabItem>
<TabItem value="web">
Not yet implemented.
</TabItem>
</Tabs>

30
docs/configuration/module-config/audio.mdx → docs/configuration/module/audio.mdx
View file

@ -1,7 +1,6 @@
---
id: audio
title: Audio Module Configuration
slug: /settings/moduleconfig/audio
sidebar_label: Audio
---
@ -53,7 +52,7 @@ The GPIO to use for the DIN signal in the I2S interface.
The GPIO to use for the SCK signal in the I2S interface.
:::info What is this?
These Pins comprise an I2S digital audio interface. Meshtastic uses it in monoaural mode. The software will use the logical 'LEFT' Stereo channel for the microphone and the logical 'RIGHT' Stereo channel for the speaker, so configure your breakouts accordingly. Audio is Half-Duplex, so we can re-use part of the pins for a bi-directional configuration. There's **no** default pin assigment, setting these is mandatory.
These Pins comprise an I2S digital audio interface. Meshtastic uses it in monoaural mode. The software will use the logical 'LEFT' Stereo channel for the microphone and the logical 'RIGHT' Stereo channel for the speaker, so configure your breakouts accordingly. Audio is Half-Duplex, so we can re-use part of the pins for a bi-directional configuration. There's **no** default pin assignment, setting these is mandatory.
:::
## Audio Module Config Client Availability
@ -74,7 +73,8 @@ values={[
Audio Config options are available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Module Settings > Audio Config**
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Audio**
:::
@ -94,29 +94,29 @@ All audio module config options are available in the python CLI. Example command
:::
| Setting | Acceptable Values | Default |
| :-----------: | :-----------------------------------------------------------------------------------------------------------------------------: | :----------------------: |
| audio.enabled | `true`, `false` | `false` |
| audio.ptt_pin | GPIO Pin Number 1-39 | Default of `39` is Unset |
| audio.bitrate | `CODEC2_DEFAULT` `CODEC2_3200` `CODEC2_2400` `CODEC2_1600` `CODEC2_1400` `CODEC2_1300` `CODEC2_1200` `CODEC2_700B` `CODEC2_700` | `CODEC2_DEFAULT` |
| audio.i2s_ws | GPIO Pin Number 1-34 | no Default |
| audio.i2s_sd | GPIO Pin Number 1-39 | no Default |
| audio.i2s_din | GPIO Pin Number 1-34 | no Default |
| audio.i2s_sck | GPIO Pin Number 1-34 | no Default |
| Setting | Acceptable Values | Default |
| :----------------: | :-----------------------------------------------------------------------------------------------------------------------------: | :----------------------: |
|audio.codec2_enabled| `true`, `false` | `false` |
| audio.ptt_pin | GPIO Pin Number 1-39 | Default of `39` is Unset |
| audio.bitrate | `CODEC2_DEFAULT` `CODEC2_3200` `CODEC2_2400` `CODEC2_1600` `CODEC2_1400` `CODEC2_1300` `CODEC2_1200` `CODEC2_700B` `CODEC2_700` | `CODEC2_DEFAULT` |
| audio.i2s_ws | GPIO Pin Number 1-34 | no Default |
| audio.i2s_sd | GPIO Pin Number 1-39 | no Default |
| audio.i2s_din | GPIO Pin Number 1-34 | no Default |
| audio.i2s_sck | GPIO Pin Number 1-34 | no Default |
:::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 audio.enabled true --set audio.bitrate CODEC2_1400
meshtastic --set audio.codec2_enabled true --set audio.bitrate CODEC2_1400
```
:::
```shell title="Enable / Disable Module"
meshtastic --set audio.enabled true
meshtastic --set audio.enabled false
meshtastic --set audio.codec2_enabled true
meshtastic --set audio.codec2_enabled false
```
```shell title="Set WS to GPIO pin number 7"

18
docs/configuration/module-config/canned-message.mdx → docs/configuration/module/canned-message.mdx
View file

@ -1,7 +1,6 @@
---
id: canned-message
title: Canned Message Module Configuration
slug: /settings/moduleconfig/canned-message
sidebar_label: Canned Message
---
@ -10,7 +9,9 @@ import TabItem from "@theme/TabItem";
The Canned Message Module will allow you to send messages to the mesh network from the device without using the phone app. You can predefine text messages to choose from.
The canned message module config options are: Enabled, Save, and Sender. Range Test Module config uses an admin message sending a `ConfigModule.CannedMessage` protobuf.
The canned message module config options are: Enabled, Send Bell, Messages, Input Source, Rotary Encoder Enabled, Up Down Encoder Enabled, Input Broker Pin A, Input Broker Pin B, Input Broker Pin Press, Input Broker Event Clockwise, Input Broker Event Counter Clockwise, and Input Broker Event Press. Canned Message config uses an admin message sending a `ConfigModule.CannedMessage` protobuf.
<object data="https://www.youtube.com/embed/qKQVYUbLLkg?autohide=1&autoplay=0" width="100%" height="400"></object>
## Canned Message Module Config Values
@ -23,11 +24,11 @@ Enables the canned message module.
Sends a bell character with each message.
The [External Notification Module](external-notification) can be set up to beep when a new message arrives.
This module can also be configured to beep only when message contains the bell character.
This module can also be configured to beep only when a message contains the bell character.
### Messages
The list of pre-set messages, up to 200 bytes.
The list of pre-set messages as configured by the user. Messages should be separated by pipes `|`. The total byte count for the message list can be up to 200 bytes
### Input Source
@ -90,7 +91,7 @@ values={[
Canned Message Config options are available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Module Settings > Canned Message Config**
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Canned Message**
:::
@ -117,8 +118,7 @@ Example commands are below:
| canned_message.enabled | `true`, `false` | `false` |
| canned_message.send_bell | `true`, `false` | `false` |
| canned_message.allow_input_source | `rotEnc1`, `_any`, `upDownEnc1`, `cardkb` | `_any` |
| canned_message.messages | `string` | `""` |
| (Messages)\* | `string` | `""` |
| --set-canned-message | `string` | `""` (separate using pipes) |
| canned_message.inputbroker_event_cw | `InputEventChar` | (not defined) |
| canned_message.inputbroker_event_ccw | `InputEventChar` | (not defined) |
| canned_message.inputbroker_event_press | `InputEventChar` | (not defined) |
@ -220,9 +220,9 @@ Example: 1|2|3||5|6|7||9|10|11||13|14|15 - the slots 4,8 and 12 can not be used.
The CardKB is fully supported in freetext mode and select mode. Use UP/DOWN/ENTER to select a predefined message and send it. For a freetext message, just type it in and press ENTER to send it.
If you don't want to broadcast your freetext message, you can use the CardKB to send it to a specific node. Just press TAB and select the target node with the LEFT/RIGHT keys. The message will be sent to the node with the matching name and node number. The target node will be remebered for your nexxt message.
If you don't want to broadcast your freetext message, you can use the CardKB to send it to a specific node. Just press TAB and select the target node with the LEFT/RIGHT keys. The message will be sent to the node with the matching name and node number. The target node will be remembered for your next message.
### 3 Buttun up/down and RAK rotary encoder
### 3 Button up/down and RAK rotary encoder
Just use UP/DOWN/ENTER to select a predefined message and send it.

135
docs/configuration/module/detection-sensor.mdx Normal file
View file

@ -0,0 +1,135 @@
---
id: detection-sensor
title: Detection Sensor Module Usage
sidebar_label: Detection Sensor
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The Detection Sensor module allows you to configure a GPIO pin to be monitored for a specified high/low status and send text alerts over the Detection Sensor portnum when an event is detected. This is particularly useful for motion detection sensors, reed switches, and other open / closed state systems in which notifications over the mesh are desired. Config options are: Enabled, Minimum Broadcast Interval, State Broadcast Interval, Send Bell, Name, Monitor Pin, Detection Triggered High, and Use Pull-up.
In order to use this module, make sure your devices have firmware version 2.2.2 or higher.
## Detection Sensor Module Config Values
### Enabled
Whether the Module is enabled.
### Minimum Broadcast Interval
The interval in seconds of how often we can send a message to the mesh when a state change is detected.
### State Broadcast Interval
The interval in seconds of how often we should send a message to the mesh with the current state regardless of changes, When set to 0, only state changes will be broadcasted, Works as a sort of status heartbeat for peace of mind.
### Send Bell
Send ASCII bell with alert message. Useful for triggering ext. notification on bell
name.
### Friendly Name
Used to format the message sent to mesh. Example: A name "Motion" would result in a message "Motion detected". Maximum length of 20 characters.
### Monitor Pin
The GPIO pin to monitor for state changes.
### Detection Triggered High
Whether or not the GPIO pin state detection is triggered on HIGH (1), otherwise LOW (0).
### Use Pull-up
Whether or not use INPUT_PULLUP mode for GPIO pin. Only applicable if the board uses pull-up resistors on the pin.
## Detection Sensor Module Client Availability
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'Android', value: 'android'},
{label: 'Apple', value: 'apple'},
{label: 'CLI', value: 'cli'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="android">
:::info
All Detection Sensor Module config options are available for Android in app version 2.2.2 and higher.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Detection Sensor**
:::
</TabItem>
<TabItem value="apple">
:::info
All Detection Sensor Module config options are available on iOS, iPadOS and macOS app versions 2.2.2 and higher at Settings > Modules > Detection Sensor
:::
</TabItem>
<TabItem value="cli">
:::info
All Detection Sensor Module config options are available in the python CLI version 2.2.2 and higher.
:::
Example commands are below:
```shell title="Enable/Disable the Detection Sensor Module"
meshtastic --set detection_sensor.enabled true
meshtastic --set detection_sensor.enabled false
```
```shell title="Set the Minimum Broadcast Interval to 90 seconds"
meshtastic --set detection_sensor.minimum_broadcast_secs 90
```
```shell title="Set the State Broadcast Interval to 5 minutes"
meshtastic --set detection_sensor.state_broadcast_secs 300
```
```shell title="Enable/Disable Send Bell"
meshtastic --set detection_sensor.send_bell true
meshtastic --set detection_sensor.send_bell false
```
```shell title="Set the friendly name to 'motion'"
meshtastic --set detection_sensor.name "motion"
```
```shell title="Set the Monitor Pin to 7"
meshtastic --set detection_sensor.monitor_pin 7
```
```shell title="Enable Notifications when the Monitor Pin goes HIGH"
meshtastic --set detection_sensor.detection_triggered_high true
```
```shell title="Enable Notifications when the Monitor Pin goes LOW"
meshtastic --set detection_sensor.detection_triggered_high false
```
```shell title="Enable the use INPUT_PULLUP mode"
meshtastic --set detection_sensor.use_pullup true
```
```shell title="Get the Detection Sensor Module Configuration"
meshtastic --get detection_sensor
```
</TabItem>
<TabItem value="web">
Not yet implemented.
</TabItem>
</Tabs>

17
docs/configuration/module-config/external-notification.mdx → docs/configuration/module/external-notification.mdx
View file

@ -1,7 +1,6 @@
---
id: external-notification
title: External Notification Module Configuration
slug: /settings/moduleconfig/external-notification
sidebar_label: External Notification
---
@ -10,12 +9,20 @@ import TabItem from "@theme/TabItem";
The External Notification Module will allow you to connect a buzzer, speaker, LED, or other device to notify you when a message has been received from the mesh network. You can enable up to 3 pins independently from each other.
The External Notification Module config options are: Enabled, Active, Alert Bell (General),Alert Bell Vibra, Alert Bell Buzzer, Alert Message (General), Alert Message Vibra, Alert Message Buzzer, Output (General), Output Vibra, Output Buzzer, Output Milliseconds, Use PWM, and Nag Timeout. External Notification config uses an admin message sending a `ConfigModule.ExternalNotificationConfig` protobuf.
<object data="https://www.youtube.com/embed/MWt3RHMpifo?autohide=1&autoplay=0" width="100%" height="400"></object>
## External Notification Module Config Values
### Enabled
Enables the external notification module.
### Active (general / LED only)
Specifies whether the external circuit is active when the device's GPIO is low or high. If this is set true, the pin will be pulled active high, false means active low.
### Alert when receiving a bell (general / LED, Vibra and Buzzer)
Specifies if an alert should be triggered when receiving an incoming bell.
@ -24,10 +31,6 @@ Specifies if an alert should be triggered when receiving an incoming bell.
Specifies if an alert should be triggered when receiving an incoming message.
### Active (general / LED only)
Specifies whether the external circuit is active when the device's GPIO is low or high.
### GPIO Pins (general / LED, Vibra and Buzzer)
Specifies the GPIO that your external circuit is attached to on the device. On devices that have a PWM buzzer, you can use the buzzer for notifications by setting the use_pwm property to TRUE. The Buzzer Pin will be ignored and the device.buzzer_gpio is used instead. If you enable PWM mode, the device will use
@ -65,7 +68,7 @@ values={[
External Notification Config options are available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Module Settings > External Notification Config**
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > External Notification**
:::
@ -183,6 +186,6 @@ Ideas for external hardware:
- Strobe Light
- Siren
## Known Problems
## Known Limitations
- This module only monitors text messages. We won't trigger on any other packet types.

25
docs/configuration/module/index.mdx Normal file
View file

@ -0,0 +1,25 @@
---
id: module-config
title: Module Configuration
sidebar_label: Module Config
sidebar_position: 2
slug: /configuration/module
---
Modules are included in the firmware and allow users to extend the functionality of their mesh or device.
| Name | Description |
| :------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| [Ambient Lighting](/docs/configuration/module/ambient-lighting) | Adjust the brightness of NCP5623 I2C RGB LEDs |
| [Audio](/docs/configuration/module/audio) | Enable Support for Codec2 Voice Comms on certain devices. |
| [Canned Message](/docs/configuration/module/canned-message) | Set a number of predefined messages to send out directly from the device with the use of an input device like a rotary encoder. |
| [Detection Sensor](/docs/configuration/module/detection-sensor) | Configure a GPIO pin to be monitored for specified high/low status and send text alerts. |
| [External Notification](/docs/configuration/module/external-notification) | Incoming messages are able to alert you using circuits you attach to the device (LEDs, Buzzers, etc). |
| [MQTT](/docs/configuration/module/mqtt) | Forward packets along to an MQTT server. This allows users on the local mesh to communicate with users on another mesh over the internet. |
| [Neighbor Info](/docs/configuration/module/neighbor-info) | Send info on 0-hop neighbors to the mesh. |
| [Range Test](/docs/configuration/module/range-test) | Send messages with GPS location at an interval to test the distance your devices can communicate. Requires (at least) one device set up as a sender and one as a receiver. The receiver(s) will log all incoming messages to a CSV. |
| [Remote Hardware](/docs/configuration/module/remote-hardware) | Set and read a GPIO status remotely over the mesh. |
| [Serial Module](/docs/configuration/module/serial) | Send messages across the mesh by sending strings over a serial port. |
| [Store & Forward](/docs/configuration/module/store-and-forward-module) | Stores messages on a device for delivery after disconnected clients rejoin the mesh. |
| [Telemetry](/docs/configuration/module/telemetry) | Attach sensors to the device and transmit readings on a regular interval to the mesh. |
| [Traceroute](/docs/configuration/module/traceroute) | Track which nodes are used to hop a message to a certain destination. |

260
docs/configuration/module/mqtt.mdx Normal file
View file

@ -0,0 +1,260 @@
---
id: mqtt
title: MQTT Module Configuration
sidebar_label: MQTT
---
import Tabs from "@theme/Tabs";
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, and Root Topic. MQTT Module config uses an admin message sending a `ConfigModule.MQTT` protobuf.
## Settings
## MQTT Module Config Values
### Enabled
Enables the MQTT module.
### Server Address
The server to use for MQTT. If not set, the default public server will be used.
### Username
MQTT Server username to use (most useful for a custom MQTT server). If using a custom server, this will be honored even if empty. If using the default public server, this will only be honored if set, otherwise the device will use the default username.
### Password
MQTT password to use (most useful for a custom MQTT server). If using a custom server, this will be honored even if empty. If using the default server, this will only be honored if set, otherwise the device will use the default password.
### Encryption Enabled
Whether to send encrypted or unencrypted packets to MQTT. This parameter is only honored if you also set server (the default official mqtt.meshtastic.org server can handle encrypted packets). Unencrypted packets may be useful for external systems that want to consume meshtastic packets.
### JSON Enabled
Enable the sending / consumption of JSON packets on MQTT. These packets are not encrypted, but offer an easy way to integrate with systems that can read JSON.
### TLS Enabled
If true, we attempt to establish a secure connection using TLS.
### Root Topic
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.
## MQTT Module 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">
:::info
MQTT Config options are available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > MQTT**
:::
</TabItem>
<TabItem value="apple">
:::info
MQTT Config options are available on iOS, iPadOS and macOS at Settings > Modules > MQTT.
:::
</TabItem>
<TabItem value="cli">
:::info
All MQTT module config options are available in the python CLI. Example commands are below:
:::
| 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` | |
:::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 mqtt.enabled true --set mqtt.json_enabled true
```
:::
```shell title="Enable/Disable MQTT Module"
meshtastic --set mqtt.enabled true
meshtastic --set mqtt.enabled false
```
```shell title="Enable/Disable MQTT JSON"
meshtastic --set mqtt.json_enabled true
meshtastic --set mqtt.json_enabled false
```
</TabItem>
<TabItem value="web">
:::info
All MQTT module config options are available for the Web UI.
:::
</TabItem>
</Tabs>
## Connect to the Default Public Server
<Tabs
defaultValue="apple"
values={[
{label: 'Android', value: 'android'},
{label: 'Apple', value: 'apple'},
{label: 'CLI', value: 'cli'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="android">
<h3>1. Enable the MQTT Module</h3>
Navigate to: Vertical Ellipsis (3 dots top right) > Radio configuration > MQTT: Turn on the slider for **MQTT enabled** and tap **Send**.
[![MQTT Settings](/img/modules/mqtt/android_mqtt_sm.png)](/img/modules/mqtt/android_mqtt.png)
*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.png)](/img/modules/mqtt/android_mqtt_proxy.png)
<h3>2. Enable Channel Uplink & Downlink</h3>
Navigate to: Vertical Ellipsis (3 dots top right) > Radio configuration > Channels > LongFast: Turn on the sliders for **Uplink enabled** and **Downlink enabled**, then tap **Save** and tap **Send**.
[![Channel Settings](/img/modules/mqtt/android_channel_sm.png)](/img/modules/mqtt/android_channel.png)
<h3>3. Configure Network Settings</h3>
Navigate to: Vertical Ellipsis (3 dots top right) > Radio configuration > Network: Turn on the slider for **WiFi enabled**, Enter the **SSID** and **PSK** for your network, then tap **Send**.
[![Network Settings](/img/modules/mqtt/android_network_sm.png)](/img/modules/mqtt/android_network.png)
</TabItem>
<TabItem value="apple">
<h3>1. Enable the MQTT Module</h3>
Navigate to Settings > MQTT: Turn on the slider for MQTT enabled and tap **Save**
[![MQTT Settings 1](/img/modules/mqtt/apple_mqtt_1_sm.png)](/img/modules/mqtt/apple_mqtt_1.png)
[![MQTT Settings 2](/img/modules/mqtt/apple_mqtt_2_sm.png)](/img/modules/mqtt/apple_mqtt_2.png)
*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.png)](/img/modules/mqtt/apple_mqtt_1_proxy.png)
<h3>2. Enable Channel Uplink & Downlink</h3>
Navigate to Settings > Channels > Primary Channel: Turn on the sliders for **Uplink enabled** and **Downlink enabled** - Tap **Save**
[![Channel Settings](/img/modules/mqtt/apple_channel_sm.png)](/img/modules/mqtt/apple_channel.png)
<h3>3. Configure Network Settings</h3>
Navigate to Settings > Network: Turn on the slider for **WiFi enabled** - Enter your **SSID** and **PSK** for your network - Tap **Save**
[![Network Settings](/img/modules/mqtt/apple_network_sm.png)](/img/modules/mqtt/apple_network.png)
</TabItem>
<TabItem value="cli">
<h3>1. Enable the MQTT Module</h3>
```shell
meshtastic --set mqtt.enabled true
```
<h3>2. Enable Channel Uplink & Downlink</h3>
```shell
meshtastic --ch-set uplink_enabled true --ch-index 0
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
```
<h3>3. Configure Network Settings</h3>
```shell
meshtastic --set network.wifi_enabled true
meshtastic --set network.wifi_ssid "your network"
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
```
</TabItem>
<TabItem value="web">
<h3>1. Enable the MQTT Module</h3>
Navigate to Config > Module Config > MQTT - Turn on the slider for MQTT enabled - Click the **Save** icon.
[![MQTT Settings](/img/modules/mqtt/web_mqtt_sm.png)](/img/modules/mqtt/web_mqtt.png)
*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.png)](/img/modules/mqtt/web_mqtt_proxy.png)
:::caution
Though this option may be visible in your UI, Client Proxy is not yet functional with the Web Client.
:::
<h3>2. Enable Channel Uplink & Downlink</h3>
Navigate to Channels > Primary: Turn on the sliders for **Uplink Enabled** and **Downlink Enabled** - Click the **Save** icon.
[![Channel Settings](/img/modules/mqtt/web_channel_sm.png)](/img/modules/mqtt/web_channel.png)
<h3>3. Configure Network Settings</h3>
Navigate to Radio Config > Device > Network: Turn on the slider for **Enabled** - Enter your **SSID** and **PSK** for your network - Click the **Save** icon.
[![Network Settings](/img/modules/mqtt/web_network_sm.png)](/img/modules/mqtt/web_network.png)
</TabItem>
</Tabs>

82
docs/configuration/module/neighbor-info.mdx Normal file
View file

@ -0,0 +1,82 @@
---
id: neighbor-info
title: Neighbor Info Module Usage
sidebar_label: Neighbor Info
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The Neighbor Info Module is for sending information on each node's 0-hop neighbors to the mesh. Config options are: Enabled and Update Interval.
In order to use it, make sure your devices use firmware version 2.2.0 or higher.
## Neighbor Info Module Config Values
### Enabled
Enables the Neighbor Info Module.
### Update Interval
How often the neighbor info is sent to the mesh.
## Neighbor Info Module Client Availability
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'Android', value: 'android'},
{label: 'Apple', value: 'apple'},
{label: 'CLI', value: 'cli'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="android">
:::info
All Neighbor Info Module config options are available for Android in app version 2.2.0 and higher.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Neighbor Info**
:::
</TabItem>
<TabItem value="apple">
Not yet implemented.
</TabItem>
<TabItem value="cli">
:::info
All Neighbor Info Module config options are available in the python CLI version 2.2.0 and higher.
:::
Example commands are below:
```shell title="Enable/Disable the Neighbor Info Module"
meshtastic --set neighbor_info.enabled true
meshtastic --set neighbor_info.enabled false
```
```shell title="Set the update interval to 10 minutes"
meshtastic --set neighbor_info.update_interval 600
```
```shell title="Get the Neighbor Info Module Configuration"
meshtastic --get neighbor_info
```
</TabItem>
<TabItem value="web">
Not yet implemented.
</TabItem>
</Tabs>

81
docs/configuration/module-config/range-test.mdx → docs/configuration/module/range-test.mdx
View file

@ -1,14 +1,22 @@
---
id: range-test
title: Range Test Module Configuration
slug: /settings/moduleconfig/range-test
sidebar_label: Range Test
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
This module allows you to test the range of your Meshtastic nodes. It requires at least two nodes, a sender and a receiver. The receiving node then saves the messages along with the GPS coordinates at which they were received into a .csv file. This .csv file can then be integrated into [Google Earth](https://earth.google.com), [Google Maps - My Maps](https://mymaps.google.com), or any other program capable of processing .csv files. This can enable you to visualize your mesh.
This module allows you to test the range of your Meshtastic nodes. It requires at least two nodes, a sender and a receiver. The receiving node saves the messages along with the GPS coordinates at which they were received into a .csv file. This .csv file can then be integrated into [Google Earth](https://earth.google.com), [Google Maps - My Maps](https://mymaps.google.com), or any other program capable of processing .csv files. This can enable you to visualize your mesh.
While a minimum of two radios is required, more can be used. You can have any number of receivers and senders that your mesh is able to handle. You can test having a single sender with multiple receivers or a single receiver with multiple senders. Let us know on the [forum thread](https://meshtastic.discourse.group/t/new-plugin-rangetestplugin/2591) the results of your configuration.
:::info
Be sure to turn off the module or disable sending when not in use. This will use a lot of time on air, slow down your mesh, and spam your channel.
:::
The range test module config options are: Enabled, Save, and Sender. Range Test Module config uses an admin message sending a `ConfigModule.RangeTest` protobuf.
@ -18,13 +26,33 @@ The range test module config options are: Enabled, Save, and Sender. Range Test
Enables the range test module.
### Save CSV File `ESP32 Only Setting`
### Save CSV File
If enabled, we will save a log of all received messages to a file named rangetest.csv which you can access from the web server Extensions > File Browser > rangetest.csv. The file will be created after receiving messages. The device will abort writing if there is less than 50k of space on the filesystem to prevent filling up the storage.
:::info
Saving files is only available on ESP32-based devises
:::
If enabled, a log of all received messages will be saved to a file named rangetest.csv.
To access this file, first turn on the WiFi on your device and connect to your network. Once you can connect to your device, navigate to `meshtastic.local/rangetest.csv` (or your_device_ip/rangetest.csv) and the file will be downloaded automatically. This file will only be created after receiving initial messages.
To prevent filling up the storage, the device will abort writing if there is less than 50kb of space on the filesystem.
### Sender Interval
How long to wait between sending test packets. 0 is default which disables sending messages.
How long to wait between sending sequential test packets. 0 is default which disables sending messages.
### Recommended Sender Settings
| Radio Setting | `range_test.sender` |
| :-----------: | :-----------------: |
| Long Slow | 60 |
| Long Alt | 30 |
| Medium | 15 |
| Short Fast | 15 |
## Range Test Module Config Client Availability
@ -44,10 +72,12 @@ values={[
Range Test Config options are available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Module Settings > Range Test Config**
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Range Test**
:::
Android also had the option to download a rangetest.csv file which is stored on your phone. This file does not require the Range Test module to be active and will log all incoming Nodeinfo, Position, Telemetry and Messages.
</TabItem>
<TabItem value="apple">
@ -55,6 +85,8 @@ Range Test Config options are available for Android.
All range test module config options are available on iOS, iPadOS and macOS at Settings > Modules > Range Test.
:::
Apple apps also have the option to download logged position data which is stored on your iPhone/iPad/Mac. Access this by clicking on the Nodes tab, selecting a node, then select Position Log and click Save. This data file does not require the Range Test module to be active.
</TabItem>
<TabItem value="cli">
@ -103,42 +135,13 @@ meshtastic --set range_test.sender 0
:::info
No range test module config options are available in the Web UI.
All range test module config options are available in the Web UI.
:::
</TabItem>
</Tabs>
## Examples
While a minimum of two radios is required, more can be used. You can have any number of receivers and senders that your mesh is able to handle. You can test having a single sender with multiple receivers or a single receiver with multiple senders. Let us know on the [forum thread](https://meshtastic.discourse.group/t/new-plugin-rangetestplugin/2591) the results of your configuration.
Be sure to turn off either the module configured as a sender or the device where the module setup as sender when not in use. This will use a lot of time on air and will spam your channel.
Also be mindful of your space usage on the file system. It has protections from filling up the space but it's best to delete old range test results.
:::note
Leaving this module on can slow down your mesh. Currently, the messages are sent using the same `TEXT_MESSAGE_APP` [port that all other messages](https://buf.build/meshtastic/protobufs/docs/main:meshtastic#meshtastic.PortNum) are sent on.
:::
### Accessing your CSV
Connect to your device over WiFi, either using the [software access point](/docs/settings/config/network#software-access-point) or [WiFi Client](/docs/settings/config/network#wifi-client). Then navigate to `meshtastic.local` (or your IP address). Your file will be available for download under `Extensions > File Browser > rangetest.csv` once it has been created by receiving messages.
```plaintext title="Example URLs"
http://meshtastic.local
http://198.168.0.15
```
### Recommended Sender Settings
| Radio Setting | `range_test.sender` |
| :-----------: | :-----------------: |
| Long Slow | 60 |
| Long Alt | 30 |
| Medium | 15 |
| Short Fast | 15 |
## Application Examples
@ -169,10 +172,6 @@ You can style the ranges differently based on the values, so you can have the pi
## FAQ
Q: Where is rangetest.csv saved?
- Turn on the WiFi on your device as either a WiFi client or a WiFi AP. Once you can connect to your device, navigate to `Extensions > File Browser` and you will see `rangetest.csv` once messages have been saved and the file has been created.
Q: Do I need to have WiFi turned on for the file to be saved?
- Nope, it'll just work.
@ -191,7 +190,7 @@ Q: What will happen if I run out of space on my device?
Q: What do I do with the rangetest.csv file when I'm done?
- Go to /static and delete the file.
- Currently the only way to erase the file is to perform a factory reset.
Q: Can I use this as a sender while on battery power?

106
docs/configuration/gpio-peripherals.mdx → docs/configuration/module/remote-hardware.mdx
View file

@ -1,31 +1,89 @@
---
id: gpio-peripherals
title: Configuring GPIO Peripherals
sidebar_label: Setup GPIO Peripherals
slug: /hardware/peripheral/
sidebar_position: 6
id: remote-hardware
title: Remote Hardware Module Usage
sidebar_label: Remote Hardware
---
## Firmware Versions
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The Remote Hardware Module allows control of a GPIO pin on a remote node. Config options are: Enabled, Allow Undefined Pin Access, Available Pins
:::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)
:::
## Remote Hardware Config Values
### Enabled
Whether the module is enabled
### Allow Undefined Pin Access
Whether the module allows consumers to read/write to pins not that are not defined in available_pins
### Available Pins
Exposes the available pins to the mesh for reading and writing
## Remote Hardware Module Client Availability
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'Android', value: 'android'},
{label: 'Apple', value: 'apple'},
{label: 'CLI', value: 'cli'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="android">
:::info
All Remote Hardware Module config options are available for Android in app.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Remote Hardware**
:::
</TabItem>
<TabItem value="apple">
:::info
All Remote Hardware Module config options are available on iOS, iPadOS and macOS app.and higher at Settings > Modules > Remote Hardware
:::
</TabItem>
<TabItem value="cli">
:::info
All Remote Hardware Module config options are available in the python CLI.
:::
</TabItem>
<TabItem value="web">
Not implemented.
</TabItem>
</Tabs>
## Remote Hardware Module Usage
:::warning
GPIO access is fundamentally dangerous because invalid options can physically damage or destroy your hardware. Ensure that you fully understand the schematic for your particular device before trying this as we do not offer a warranty. Use at your own risk.
:::
The device firmware runs on the nodes to build the mesh for communication. Each different make and model of device requires a different build of the Meshtastic firmware in order to run properly. Thankfully, due to the design of Meshtastic, it is possible to port the firmware to new devices as they become available. The firmware currently runs on a range of ESP32 based devices, but there is also increasing support for the nRF52 microprocessor with some more recent devices coming to market.
The current firmware has support for a screen to display received messages, along with information about nodes on the mesh, and more detailed information about the device on which it is running.
The latest firmware can be downloaded from the [Downloads](/downloads) page. If you wish to view the code or contribute to development of the firmware, please visit the device code [GitHub page](https://github.com/meshtastic/firmware).
:::info
Please be aware that there are significant changes between version branches 1.2.x and 1.3.x which mean that devices need to be running the same branch of firmware to be able to talk to each other. Python, Android, and other software applications will also need to be running the same branch to be able to talk to the device.
This feature uses a preinstalled module in the device code and associated command line flags/classes in the python code. You'll need to be running at least version 1.2.23 (or later) of the python and device code to use this feature.
:::
## Remote Hardware
### Supported Operations
- Set any GPIO
@ -59,7 +117,7 @@ The procedure using the python command line tool is:
meshtastic --seturl theurlyoucopiedinstep3
```
Now both devices should be able to talk over the `gpio` channel. Send a text message from one the other other verify. Also run `--nodes` to verify the second node shows up.
Now both devices should be able to talk over the `gpio` channel. Send a text message from one to the other to verify. Also run `--nodes` to verify the second node shows up.
### Masks
@ -132,9 +190,9 @@ You can add a simple LED and resistor to validate that the GPIO operations work
### Preparation
1. Disconnect the remote device from power (battery/usb)
2. Add a resistor from yellow wire to the one end of the LED (either end of the resistor is OK, either end of the LED is OK)
3. Add the yellow wire from a GPIO pin that will not cause any issues (ex: for TLoraV1, we can use GPIO21)
4. Add the black "ground" wire from the ground pin on the device (ex: for TLoraV1 it is the end pin next to the RST button) to the other end of the LED
2. Connect the resistor to the longer (positive) lead of the LED and the yellow wire to the other end of the resistor
3. Connect the other end of the yellow wire to a GPIO pin that will not cause any issues (ex: for TLoraV1, we can use GPIO21)
4. Connect the black "ground" wire from the ground pin on the device (ex: for TLoraV1 it is the end pin next to the RST button) to the shorter (negative) lead of the LED
5. Power on the device
### Validation

103
docs/configuration/module-config/serial.mdx → docs/configuration/module/serial.mdx
View file

@ -1,19 +1,20 @@
---
id: serial
title: Serial Module Configuration
slug: /settings/moduleconfig/serial
sidebar_label: Serial
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The serial module config options are: Enabled, Echo, Mode, Receive GPIO, Transmit GPIO and Sender. Serial Module config uses an admin message sending a `ConfigModule.Serial` protobuf.
The serial module config options are: Enabled, Echo, Mode, Receive GPIO, Transmit GPIO, Baud Rate, Timeout, and Override Console Serial Port. Serial Module config uses an admin message sending a `ConfigModule.Serial` protobuf.
This is a simple interface to send messages over the mesh network by sending strings over a serial port. Anything you send the node will be turned into a message sent out over the mesh, and anything received from the mesh will be sent to the serial port. Note that this module does not (yet) allow arbitrary protobuf commands to be sent over the serial connection.
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)
<object data="https://www.youtube.com/embed/HdOiGKBtapw?autohide=1&autoplay=0" width="100%" height="400"></object>
## Serial Module Config Values
### Enabled
@ -30,11 +31,12 @@ Defaults to 'Simple'.
Available Values:
- `DEFAULT`
- `SIMPLE` operate as an dumb UART tunnel. What goes in will come out, Requires a channel named 'serial'.
- `PROTO` Exposes the Protobuf Client API on this serial port. You can use this to connect from another device. [API Reference](/docs/development/device/client-api)
- `TEXTMSG` Will send the string received over the serial port as a Text Message for Display on the other devices.
- `NMEA` Will output a NMEA 0183 Data stream containing the internal GPS or fixed position and other node locations as Waypoints (WPL).
- `DEFAULT` equals `SIMPLE`.
- `SIMPLE` operates as a dumb UART tunnel. What goes in will come out, requires a channel named 'serial'.
- `PROTO` exposes the Protobuf Client API on this serial port. You can use this to connect from another device, see the [Arduino client library](https://github.com/meshtastic/Meshtastic-arduino) and the [API Reference](/docs/development/device/client-api).
- `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).
### Receive GPIO Pin
@ -56,6 +58,10 @@ The serial baud rate.
The amount of time to wait before we consider your packet as "done".
### 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.
:::tip
Once module settings are changed, a **reset** is required for them to take effect.
:::
@ -78,7 +84,7 @@ values={[
Serial Module Config options are available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Module Settings > Serial Config**
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Serial**
:::
@ -102,11 +108,13 @@ All serial module config options are available in the python CLI. Example comman
| :------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------: |
| serial.enabled | `true`, `false` | `false` |
| serial.echo | `true`, `false` | `false` |
| serial.mode | `DEFAULT` `SIMPLE` `PROTO` `TEXTMSG`, `NMEA` | `DEFAULT` |
| 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` |
| 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
@ -177,33 +185,33 @@ Default is to use RX GPIO 16 and TX GPIO 17.
- RXD 13
- TXD 14
3. Set `serial.timeout` to the amount of time to wait before we consider your packet as "done".
4. (Optional) set serial.mode to TEXTMSG if you want to send messages to/from the general text message channel
4. (Optional) set serial.mode to `TEXTMSG` if you want to send messages to/from the general text message channel. For more specific control, use the `PROTO` mode, e.g. in combination with the [Arduino client library](https://github.com/meshtastic/Meshtastic-arduino/blob/master/examples/SendReceiveClient/SendReceiveClient.ino).
5. Connect to your device over the serial interface at `38400 8N1`.
With [tio](https://github.com/tio/tio) &ndash; `tio -e -b 38400 -f none /dev/myserialport`
6. Send a packet up to 237 bytes in length. This will get relayed over the mesh network.
6. Send a packet up to 237 bytes in length. This will get broadcasted over the default channel.
7. (Optional) Set `serial.echo` to `1` and any message you send out will be echoed back to your device.
### Interfacing PIR Sensor With External Microcontroller
The following is an example of using a Raspberry Pi Pico connected to a PIR sensor to detect motion. When motion is detected, a message is sent via. serial to the T-Beam. The T-Beam transmits the message as text over the default channel by utilizing the serial module in TXTMSG mode.
#### BOM
- Raspberry Pi Pico running [CircuitPython](https://learn.adafruit.com/getting-started-with-raspberry-pi-pico-circuitpython)
- T-Beam V1.1 running Meshtastic
- PIR Sensor ([Adafruit Breadboard Model](https://www.adafruit.com/product/4871))
The following are examples of using either a Raspberry Pi Pico or Arduino Mini Pro connected to a PIR sensor to detect motion. When motion is detected, a message is sent via serial to the T-Beam. The T-Beam transmits the message as text over the default channel by utilizing the serial module in TXTMSG mode.
#### Meshtastic Software Configuration
- Serial module enabled, mode: TXTMSG
- Serial module enabled, mode: TEXTMSG
- GPIO Pins (For T-Beam) RX 13, TX 14
- 38400 Baud
#### Wiring
#### Rasberry Pi Pico BOM
![image](https://user-images.githubusercontent.com/2799310/210852481-21ea76e5-ecaa-40c1-8f34-635ef2a1c95b.png)
- A Raspberry Pi Pico running [CircuitPython](https://learn.adafruit.com/getting-started-with-raspberry-pi-pico-circuitpython)
- T-Beam V1.1 running Meshtastic
- PIR Sensor ([Adafruit Breadboard Model](https://www.adafruit.com/product/4871))
#### Raspberry Pi Pico Wiring
![image](/img/modules/Serial/pico-pir-wiring.png)
- TX pin 14 on the T-Beam to RX pin 2 on the Pico
- RX pin 13 on the T-Beam to TX pin 1 on the Pico
@ -236,3 +244,52 @@ while True:
time.sleep(30)
time.sleep(0.5)
```
#### 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))
#### Arduino Mini Pro Wiring
![image](/img/modules/Serial/arduino-mini-pro-pir-wiring.png)
- T-BEAM RX PIN 13 to TX PIN on the ARDUINO MINI
- T-BEAM TX PIN 14 to RX PINon the ARDUINO MINI
- T-BEAM PIN 3.3V to 3.3V PIN on the ARDUINO MINI
- T-BEAM PIN GND to GND PIN on the ARDUINO MINI
- ARDUINO MINI PIN 2 to OUT PIN on the PIR SENSOR
- ARDUINO MINI PIN 3.3V to 3.3V on the PIR SENSOR
- ARDUINO MINI PIN GND to GND PIN on the PIR SENSOR
#### Arduino Mini Pro Code
```cpp
int LED = 13; // the pin to which the LED is connected
int PIR = 2; // the pin to which the sensor is connected
int previousState = LOW; // previous state of the sensor
void setup() {
pinMode(LED, OUTPUT); // initialize the LED as an output
pinMode(PIR, INPUT); // initialize the sensor as an input
Serial.begin(9600); // initialize serial communication
}
void loop(){
int currentState = digitalRead(PIR); // read the current state of the sensor
if (currentState != previousState) { // check if the state has changed
if (currentState == HIGH) { // check if there is motion
digitalWrite(LED, HIGH); // turn the LED on
Serial.println("Motion Detected");
}
else {
digitalWrite(LED, LOW); // turn the LED off
Serial.println("No Motion");
}
previousState = currentState; // update the previous state
}
delay(100); // small delay to avoid false sensor readings
}
```

191
docs/configuration/module/store-and-forward-module.mdx Normal file
View file

@ -0,0 +1,191 @@
---
id: store-and-forward-module
title: Store & Forward Module Settings
sidebar_label: Store & Forward
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
:::info
Currently only available for ESP32 based devices with external PSRAM like the tbeam. Requires the device to be set as a ROUTER or ROUTER_CLIENT.
:::
## Overview
:::caution
This is a work in progress and the required client support is not yet available.
:::
The Store & Forward Module is an implementation of a Store and Forward system to enable resilient messaging in the event that a client device is disconnected from the main network.
Because of the increased network traffic for this overhead, it's not advised to use this if you are duty cycle limited for your airtime usage (EU_868 and EU_433) nor is it advised to use this for presets using SF11 or SF12 (e.g. all of the LongRange and VeryLongRange presets).
## Details
### How it works
![Store & Forward - Overview](/img/modules/store_and_forward/store_and_forward-overview.png)
### Requirements
Initial Requirements:
- Must be installed on a ROUTER or ROUTER_CLIENT node.
- This is an artificial limitation, but is in place to enforce best practices.
- Router nodes are intended to be always online. If this module misses any messages, the reliability of the stored messages will be reduced.
- ESP32 Processor based device with external PSRAM. (tbeam > v1.0, T3S3, and maybe others)
### Usage Overview
- To use / test this you will want at least 3 devices
- One ESP32 device with PSRAM configured as a Meshtastic router.
- Two others will be regular clients. Nothing special required.
### Meshtastic channel configuration
Don't use this on the "LongRange" channel settings. You're welcome to try and report back, but those channels have a [low bitrate](/docs/overview/radio-settings#pre-defined).
Either use a custom channel configuration with at an at least 1kbit data rate or use a Medium or Short range preset.
### Router setup
- Configure your device as a router.
- Name your router node something that makes it easily identifiable, aka "Router".
- Configure the Store and Forward module
```shell title="Required - Enable the module"
meshtastic --set store_forward.enabled true
```
```shell title="Optional - Set maximum number of records to save to device"
meshtastic --set store_forward.records 100
```
:::tip
Best to leave `store_forward.records` at the default (`0`) where the module will use 2/3 of your device's available PSRAM. This is about 11,000 records.
:::
### Client Usage
Currently there are no clients that support store and forward.
## Settings
### Enabled
Enables the module.
### Heartbeat
The Store & Forward Router sends a periodic message onto the network. This allows connected devices to know that a router is in range and listening to received messages. A client like Android, iOS, or Web can (if supported) indicate to the user whether a store and forward router is available.
### History Return Max
Sets the maximum number of messages to return to a client device.
### History Return Window
Limits the time period (in minutes) a client device can request.
### Records
Set this to the maximum number of records to save. Best to leave this at the default (`0`) where the module will use 2/3 of your device's available PSRAM. This is about 11,000 records.
### Client Config
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'Android', value: 'android'},
{label: 'Apple', value: 'apple'},
{label: 'CLI', value: 'cli'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="android">
:::info
Store and Forward Config options are available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Store & Forward**
:::
</TabItem>
<TabItem value="apple">
:::info
Store and Forward configuration is not currently available via the Apple clients.
:::
</TabItem>
<TabItem value="cli">
| Setting | Acceptable Values | Default |
| :---------------------------------: | :---------------: | :-----: |
| store_forward.enabled | `true`, `false` | `false` |
| store_forward.heartbeat | `true`, `false` | `false` |
| store_forward.history_return_max | `integer` | `0` |
| store_forward.history_return_window | `integer` | `0` |
| store_forward.records | `integer` | `0` |
:::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 store_forward.enabled true --set store_forward.history_return_max 0
```
:::
### Examples of CLI Usage
```shell title="Enable the module"
meshtastic --set store_forward.enabled true
```
```shell title="Disable the module"
meshtastic --set store_forward.enabled false
```
```shell title="Set store_forward.heartbeat to default"
meshtastic --set store_forward.heartbeat 0
```
```shell title="Set store_forward.history_return_max to default"
meshtastic --set store_forward.history_return_max 0
```
```shell title="Set store_forward.history_return_max to 100 messages"
meshtastic --set store_forward.history_return_max 100
```
```shell title="Set store_forward.history_return_window to default"
meshtastic --set store_forward.history_return_window 0
```
```shell title="Set store_forward.history_return_window to 1 day (1440 minutes)"
meshtastic --set store_forward.history_return_window 1440
```
```shell title="Set store_forward.records to default (≈11,000 records)"
meshtastic --set store_forward.records 0
```
```shell title="Set store_forward.records to 100 records"
meshtastic --set store_forward.records 100
```
</TabItem>
<TabItem value="web">
:::info
Store and Forward configuration is not currently available via the web client.
:::
</TabItem>
</Tabs>

64
docs/configuration/module-config/telemetry.mdx → docs/configuration/module/telemetry.mdx
View file

@ -1,18 +1,17 @@
---
id: telemetry
title: Telemetry Module Configuration
slug: /settings/moduleconfig/telemetry
sidebar_label: Telemetry
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The Telemetry Module provides two types of data over the mesh. Device metrics (Battery Level, Voltage, Channel Utilization and Airtime) from your meshtastic device and Environment Metrics from attached I2C sensors.
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.
Supported sensors connected to the I2C bus of the device will be automatically detected at startup. Environment Telemetry 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. Environment Telemetry and Air Quality must be enabled for them to be instrumented and their readings sent over the mesh.
The telemetry module config options are: Device Metrics Update Interval, Environment Metrics Update Interval, Environment Telemetry Enabled, Show on Device Screen, and Display Fahrenheit.
<object data="https://www.youtube.com/embed/6jj1s-fsPlc?autohide=1&autoplay=0" width="100%" height="400"></object>
### Currently Supported Sensor Types
@ -27,40 +26,51 @@ The telemetry module config options are: Device Metrics Update Interval, Environ
| LPS22 | 0x5D, 0x5c | Barometric pressure |
| SHTC3 | 0x70 | Temperature and humidity |
| SHT31 | 0x44 | Temperature and humidity |
| PMSA003I| 0x12 | Concentration units by size and particle counts by size |
## Module Config Values
### Update Intervals
### Environment Telemetry Enabled
### Device Metrics Update Interval
How often we should send Device Metrics over the mesh.
Default is every 15 minutes.
Enable the Environment Telemetry (Sensors).
### Environment Metrics Update Interval
How often we should send Environment(Sensor) Metrics over the mesh.
Default is every 15 minutes.
Default is `900` seconds (15 minutes).
## Sensor options
### Device Metrics Update Interval
### Environment Telemetry Enabled
How often we should send Device Metrics over the mesh.
Enable the Environment Telemetry (Sensors)
Default is `900` seconds (15 minutes).
### Show on device screen
### Environment Screen Enabled
Show the Telemetry Module on the device display.
### Display Fahrenheit
The sensor is always read in Celsius, but the user can opt to display in Fahrenheit using this setting.
Show the environment telemetry data on the device display.
Default is `false`.
## Device Config Client Availability
### Display Fahrenheit
The sensor is always read in Celsius, but the user can opt to display in Fahrenheit (on the device display only) using this setting.
Default is `false`.
### Air Quality Enabled
This option is used to enable/disable the sending of air quality metrics from an attached supported sensor over the mesh network.
Default is `false`.
### Air Quality Interval
This option is used to configure the interval (in seconds) that should be used to send air quality metrics from an attached supported sensor over the mesh network.
Default is `900` seconds (15 minutes).
## Telemetry Config Client Availability
<Tabs
groupId="settings"
@ -78,7 +88,7 @@ values={[
Telemetry Config options are available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Module Settings > Telemetry Config**
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Telemetry**
:::
@ -104,10 +114,12 @@ All telemetry module config options are available in the python CLI. Example com
| Setting | Acceptable Values | Default |
| :---------------------------------------: | :-----------------: | :---------------------------------------: |
| telemetry.device_update_interval | `integer` (seconds) | Default `0` is 15 minutes(`900` seconds). |
| telemetry.environment_display_fahrenheit | `true`, `false` | `false` |
| telemetry.environment_measurement_enabled | `true`, `false` | `false` |
| telemetry.environment_screen_enabled | `true`, `false` | `0` |
| 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 15 minutes(`900` seconds). |
| telemetry.air_quality_enabled | `true`, `false` | `false` |
| telemetry.air_quality_interval | `integer` (seconds) | Default `0` is 15 minutes(`900` seconds). |
:::tip
@ -177,7 +189,7 @@ meshtastic --set telemetry.environment_measurement_enabled true --set telemetry.
:::tip
You can change the values above to suit your needs but it is recommended that commands be chained together as one as shown.
While the above values serve as an example and can be modified to fit your specific needs, it is advisable to chain multiple commands together, as demonstrated in the example. This approach will minimize the number of necessary reboots.
:::

7
docs/configuration/module-config/traceroute.mdx → docs/configuration/module/traceroute.mdx
View file

@ -1,7 +1,6 @@
---
id: traceroute
title: Traceroute Module Usage
slug: /settings/moduleconfig/traceroute
sidebar_label: Traceroute
---
@ -14,6 +13,8 @@ Only nodes that know the encryption key of the channel you use can be tracked. A
In order to use it, make sure your devices use firmware version 2.0.8 or higher.
<object data="https://www.youtube.com/embed/PKUmaELKaUo?autohide=1&autoplay=0" width="100%" height="400"></object>
## Traceroute Module Client Availability
<Tabs
@ -27,7 +28,9 @@ values={[
]}>
<TabItem value="android">
Not yet implemented.
Make sure the app is at least version 2.1.10.
Under the node list, long hold a destination node and select 'Traceroute' to send the request. Depending on the amount of hops that is needed, this might take a while. The result will be shown using a pop-up.
</TabItem>
<TabItem value="apple">

15
docs/configuration/device-config/bluetooth.mdx → docs/configuration/radio/bluetooth.mdx
View file

@ -1,7 +1,6 @@
---
id: bluetooth
title: Bluetooth Settings
slug: /settings/config/bluetooth
sidebar_label: Bluetooth
---
@ -28,16 +27,16 @@ Specify pairing mode.
`FIXED_PIN` uses the fixed PIN that should then be additionally specified.
Finally, `NO_PIN` disables PIN authentication.
### Fixed PIN
If your pairing mode is set to `FIXED_PIN`, the default value is 123456. For all other pairing modes, this number is ignored. A custom integer (6 digits) can be set via the Bluetooth config options.
### Default Pairing Mode
The default pairing mode will be determined based on whether the device has or does not have a screen attached to it during the first boot (or with a stale device state) unless manually configured via the Bluetooth config options.
- **Screen Attached:** If your device boots up for the first time (or with a stale device state), and a screen is detected, the default pairing mode will be set to `RANDOM_PIN`. Should the attached screen be removed after the device has already been booted, the default pairing mode of `RANDOM_PIN` will remain unless manually changed to `FIXED_PIN` or `NO_PIN`. It is recommended the pairing mode be updated prior to removing the attached screen.
- **No Screen Attached:** If your device boots up for the first time (or with a stale device state), and no screen is detected, the default paring mode will be set to `FIXED_PIN` with the aforementioned default value unless manually configured to a custom value.
- **No Screen Attached:** If your device boots up for the first time (or with a stale device state), and no screen is detected, the default paring mode will be set to `FIXED_PIN` with the default value listed below unless manually configured to a custom value.
### Fixed PIN
If your pairing mode is set to `FIXED_PIN`, the default value is 123456. For all other pairing modes, this number is ignored. A custom integer (6 digits) can be set via the Bluetooth config options.
## Configure Bluetooth Config
@ -57,7 +56,7 @@ values={[
All Bluetooth config options are available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Device Settings > Bluetooth Config**
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Bluetooth**
:::
@ -116,7 +115,7 @@ meshtastic --set bluetooth.fixed_pin 111111
All Bluetooth module config options are available for the Web UI.
1. Open the Meshtastic Web UI.
2. Navigate to: **Device Config > Bluetooth**
2. Navigate to: **Radio Config > Bluetooth**
:::

53
docs/configuration/device-config/channels.mdx → docs/configuration/radio/channels.mdx
View file

@ -1,7 +1,6 @@
---
id: channels
title: Channel Configuration
slug: /settings/config/channels
sidebar_label: Channels
---
@ -11,9 +10,9 @@ import TabItem from "@theme/TabItem";
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` protobuf.
:::info
**Channel Settings** (as described on this page) should not be confused with [Modem Preset Settings](/docs/settings/config/lora#modem-preset)
**Channel Settings** (as described on this page) should not be confused with [Modem Preset Settings](/docs/configuration/radio/lora#modem-preset)
[Modem Preset Settings](/docs/settings/config/lora#modem-preset) contain the modem configuration (frequency settings, spreading factor, bandwidth, etc.) used for the LoRa radio. These settings are identical for all channels and can **not** be unique per channel.
[Modem Preset Settings](/docs/configuration/radio/lora#modem-preset) contain the modem configuration (frequency settings, spreading factor, bandwidth, etc.) used for the LoRa radio. These settings are identical for all channels and can **not** be unique per channel.
**Channel Settings** contain information for segregating message groups, configuring optional encryption, and enabling or disabling messaging over internet gateways. These settings **are** unique and configurable per channel.
:::
@ -48,7 +47,7 @@ Each channel is assigned one of 3 roles:
1. `PRIMARY` or `1`
- This is the first channel that is created for you on initial setup.
- Only one primary channel can exist and can not be disabled.
- Direct messages are only available on this channel.
- Periodic broadcasts like position and telemetry are only sent over this channel.
2. `SECONDARY` or `2`
- Can modify the encryption key (PSK).
3. `DISABLED` or `0`
@ -62,17 +61,7 @@ To ensure devices with different PRIMARY channel name transmit on the same frequ
## Channel Settings Values
The Channel Settings options are: ID, Name, PSK, Downlink Enabled, and Uplink Enabled. Channel settings are embedded in the `Channel` protobuf as a `ChannelSettings` protobuf and sent as an admin message.
:::note
The full globally unique ID will be constructed from the Name and ID (`<name>.<id>`) where ID is base36 encoded. Assuming that the number of Meshtastic users is below 20K (true for a long time) the chance of this 64 bit random number colliding with anyone else is super low. The penalty for collision is low as well.
:::
### ID
Used to construct a globally unique channel ID.
Set to `0` by default.
The Channel Settings options are: Name, PSK, Downlink Enabled, and Uplink Enabled. Channel settings are embedded in the `Channel` protobuf as a `ChannelSettings` protobuf and sent as an admin message.
### Name
@ -103,6 +92,8 @@ If enabled, messages from the mesh will be sent to the **public** internet throu
Set to `false` by default for all channels.
## Examples
<Tabs
groupId="settings"
defaultValue="cli"
@ -116,8 +107,25 @@ values={[
<TabItem value="android">
:::info
Limited Channel Config options are available on Android. QR code scanning is available.
Channel Config options are available on Android.
:::
![Android Menu Tabs](/img/android/android-menu-channel.png)
The Radio Configuration tab can be used for common tasks:
1. View your current channel configuration QR code and URL.
2. Quickly create or modify your primary channel.
3. Select a modem preset for all your channels i.e. `Long Range / Fast`.
See [Android App Usage](/docs/software/android/usage#setup-a-channel) for more further instruction on setting up your primary channel.
[![Channel Editor](/img/android/android-channel-edit-sm.png)](/img/android/android-channel-edit.png)
Tap the Channel Name (or the pen icon) 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
</TabItem>
@ -145,12 +153,7 @@ meshtastic --ch-set name "My Channel" --ch-set psk random --ch-set uplink_enable
:::
### Id
```shell title="Set the PRIMARY channel ID"
meshtastic --ch-set id 1234 --ch-index 0
```
<!-- trunk-ignore(markdownlint/MD024) -->
### Name
```shell title="Set channel name for the PRIMARY channel"
@ -159,7 +162,7 @@ meshtastic --ch-set name MyChannel --ch-index 0
# with spaces
meshtastic --ch-set name "My Channel" --ch-index 0
```
<!-- trunk-ignore(markdownlint/MD024) -->
### PSK
If you use Meshtastic for exchanging messages you don't want other people to see, `random` is the setting you should use. Selecting `default` or any of the `simple` values from the following table will use publicly known encryption keys. They're shipped with Meshtastic source code and thus, anyone can listen to messages encrypted by them. They're great for testing and public channels.
@ -192,7 +195,7 @@ meshtastic --ch-set psk base64:puavdd7vtYJh8NUVWgxbsoG2u9Sdqc54YvMLs+KNcMA= --ch
```
:::tip
Use this to copy and paste the `base64` encoded (single channel) key from the meshtastic --info command. Please dont use the omnibus (all channels) code here, it is not a valid key.
Use this to copy and paste the `base64` encoded (single channel) key from the meshtastic --info command. Please don't use the omnibus (all channels) code here, it is not a valid key.
:::
```shell title="Disable encryption on PRIMARY channel"
@ -201,7 +204,7 @@ meshtastic --ch-set psk none --ch-index 0
### Uplink / Downlink
For configuring gateways, please see [MQTT](/docs/settings/moduleconfig/mqtt)
For configuring gateways, please see [MQTT](/docs/configuration/module/mqtt)
```shell title="Enable/Disable Uplink on PRIMARY channel"
meshtastic --ch-set uplink_enabled true --ch-index 0

14
docs/configuration/device-config/device.mdx → docs/configuration/radio/device.mdx
View file

@ -1,7 +1,6 @@
---
id: device
title: Device Configuration
slug: /settings/config/device
sidebar_label: Device
---
@ -25,8 +24,8 @@ Acceptable values:
| `ROUTER` | Router - Mesh packets will prefer to be routed over this node. The assumption is that Router-type devices will be placed in locations with a height/range/antenna advantage, and therefore have better overall coverage. This node will not be used by client apps. The BLE/Wi-Fi radios and the OLED screen will be put to sleep. Please note: Due to the preferred routing, this role may cause higher power usage due to more frequent transmission. |
| `ROUTER_CLIENT` | Router Client - Hybrid of the Client and Router roles. Similar to Router, except the Router Client can be used as both a Router and an app connected Client. BLE/Wi-Fi and OLED screen will not be put to sleep. |
| `REPEATER` | Repeater - Mesh packets will prefer to be routed over this node. This role eliminates unnecessary overhead such as NodeInfo, DeviceTelemetry, and any other mesh packet, resulting in the device not appearing as part of the network. As such, direct messaging this node is not available, as it will not appear in your nodes list which results in a cleaner mesh network. Channel and modem settings of the mesh packets being repeated must be identical to the repeater's configuration. Please see Rebroadcast Mode for additional settings specific to this role. |
| `TRACKER` | Tracker - For use with devices intended as a GPS tracker. Position packets sent from this device will be higher priority. Smart Position Broadcast will default to the currently configured settings. |
| `SENSOR` | Sensor - For use with devices intended to primarily collect sensor readings. Telemetry packets sent from this device will be higher priority, broadcasting every five minutes. |
| `TRACKER` | Tracker - For use with devices intended as a GPS tracker. Position packets sent from this device will be higher priority. Smart Position Broadcast will default to the currently configured settings. When used in conjunction with power.is_power_saving = true, nodes will wake up, send position, and then sleep for position.position_broadcast_secs seconds. |
| `SENSOR` | Sensor - For use with devices intended to primarily collect sensor readings. Telemetry packets sent from this device will be higher priority, broadcasting every five minutes. When used in conjunction with power.is_power_saving = true, nodes will wake up, send environment telemetry, and then sleep for telemetry.environment_update_interval seconds. |
### Rebroadcast Mode
@ -35,7 +34,7 @@ This setting defines the device's behavior for how messages are rebroadcasted.
| Value | Description |
| :-----------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `ALL` | ALL (Default) - This setting will rebroadcast ALL messages from its primary mesh as well as other meshes with the same modem settings, including when encryption settings differ. |
| `All_SKIP_DECODING` | ALL_SKIP_DECODING - Same as behavior as ALL, but skips packet decoding and simply rebroadcasts them. **Only available with Repeater role.** |
| `ALL_SKIP_DECODING` | ALL_SKIP_DECODING - Same as behavior as ALL, but skips packet decoding and simply rebroadcasts them. **Only available with Repeater role.** |
| `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. |
### Serial Console
@ -66,6 +65,10 @@ This is the number of seconds between NodeInfo message broadcasts from the devic
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
@ -84,7 +87,7 @@ values={[
Device Config is available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Device Settings > Device Config**
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Device**
:::
@ -114,6 +117,7 @@ All device config options are available in the python CLI. Example commands are
| device.buzzer_gpio | `0` - `34` | `0` |
| device.node_info_broadcast_secs | `0` - `UINT MAX` | `10800` (3 hours) |
| device.double_tap_as_button_press | `false`, `true` | `false` |
| device.is_managed | `false`, `true` | `false` |
:::tip

23
docs/configuration/device-config/display.mdx → docs/configuration/radio/display.mdx
View file

@ -1,16 +1,15 @@
---
id: display
title: Display Configuration
slug: /settings/config/display
sidebar_label: Display
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The display config options are: Screen On Duration, Auto Carousel Interval, Always Point North and GPS Format. Display config uses an admin message sending a `Config.Display` protobuf.
The display config options are: Screen On Duration, Auto Carousel Interval, Always Point North, GPS Format, Preferred Display Units, OLED Definition, Display Mode, Heading Bold, and Wake on Tap or Motion. Display config uses an admin message sending a `Config.Display` protobuf.
## Device Config Values
## Display Config Values
### Screen On Duration
@ -18,7 +17,7 @@ How long the screen remains on after the user button is pressed or messages are
### Auto Carousel Interval
Automatically toggles to the next page on the screen like a carousel, based the specified interval.
Automatically toggles to the next page on the screen like a carousel, based on the specified interval.
### Always Point North
@ -39,15 +38,15 @@ Acceptable values:
| `OLC` | Open Location Code (Plus Codes) |
| `OSGR` | Ordnance Survey Grid Reference |
### Prefered display units
### Preferred Display Units
switch between `METRIC` (default) and `IMPERIAL` units
Switch between `METRIC` (default) and `IMPERIAL` units
### Flip Screen
If enabled, the screen will be rotated 180 degrees, for cases that mount the screen upside down
### OLED Defintion
### OLED Definition
The type of OLED Controller is auto-detected by default, but can be defined with this setting if the auto-detection fails. For the SH1107, we assume a square display with 128x128 Pixels like the GME128128-1.
@ -62,7 +61,7 @@ Acceptable values:
### Display Mode
The display mode can be set to `NORMAL` (default), `TWOCOLOR` or `INVERTED`. The `TWOCOLOR` mode is intended for OLED displays with the first line of output being a different color than the rest of the display. The `INVERTED` mode will invert that bicolor area, resulting in a white background headline on monochrome displays.
The display mode can be set to `DEFAULT` (default), `TWOCOLOR`, `INVERTED` or `COLOR`. The `TWOCOLOR` mode is intended for OLED displays with the first line of output being a different color than the rest of the display. The `INVERTED` mode will invert that bicolor area, resulting in a white background headline on monochrome displays.
### Heading Bold
@ -72,7 +71,7 @@ The heading can be hard to read when 'INVERTED' or 'TWOCOLOR' display mode is us
This option enables the ability to wake the device screen when motion, such as a tap on the device, is detected via an attached accelerometer.
## Device Config Client Availability
## Display Config Client Availability
<Tabs
groupId="settings"
@ -90,7 +89,7 @@ values={[
Display Config is available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Device Settings > Display Config**
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Display**
:::
@ -114,12 +113,12 @@ All display config options are available in the python CLI. Example commands are
| --------------------------------- | --------------------------------------------------------- | ----------------------------- |
| display.auto_screen_carousel_secs | `integer` | Default of `0` is off. |
| display.compass_north_top | `false`, `true` | `false` |
| display.flip_screen | `fasle`, `true` | `false` |
| display.flip_screen | `false`, `true` | `false` |
| display.gps_format | `DEC`, `DMS`, `UTM`, `MGRS`, `OLC`, `OSGR` | `DEC` |
| display.oled | `OLED_AUTO`, `OLED_SSD1306`, `OLED_SH1106`, `OLED_SH1107` | `OLED_AUTO` |
| display.screen_on_secs | `integer` | Default of `0` is 10 minutes. |
| display.units | `METRIC`, `IMPERIAL` | `METRIC` |
| display.displaymode | `NORMAL`, `TWOCOLOR`, `INVERTED` | `NORMAL` |
| display.displaymode | `DEFAULT`, `TWOCOLOR`, `INVERTED`, `COLOR` | `DEFAULT` |
| display.heading_bold | `false`, `true` | `false` |
| display.wake_on_tap_or_motion | `false`, `true` | `false` |

20
docs/configuration/radio/index.mdx Normal file
View file

@ -0,0 +1,20 @@
---
id: config
title: Radio Configuration
sidebar_label: Radio Config
sidebar_position: 1
---
There are several config sections in the Meshtastic firmware, these are broken out so they can be sent as small admin messages over the mesh.
| Name | Description |
| :------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| [Bluetooth](/docs/configuration/radio/bluetooth) | Bluetooth config options are: Enabled, Pairing Mode and Fixed PIN. |
| [Channels](/docs/configuration/radio/channels) | Channels config options are: Index, Role and Settings. |
| [Device](/docs/configuration/radio/device) | Device config options are: Device Role, Serial Output, Debug Log and Factory Reset. |
| [Display](/docs/configuration/radio/display) | Display config options are: Screen On Duration, Auto Carousel Interval, Always Point North, and GPS Format. |
| [LoRa](/docs/configuration/radio/lora) | The LoRa config options are: Region, Modem Preset, Max Hops, Transmit Power, Bandwidth, Spread Factor, Coding Rate, Frequency Offset, Transmit Disabled and Ignore Incoming Array. |
| [Network](/docs/configuration/radio/network) | Network config options are: WiFi Enabled, WiFi SSID, WiFi PSK, WiFi Mode and NTP Server. |
| [Position](/docs/configuration/radio/position) | Position config options are: GPS Enabled, GPS Update Interval, GPS Attempt Time, Fixed Position, Smart Broadcast, Broadcast Interval and Position Packet Flags. |
| [Power](/docs/configuration/radio/power) | Power config options are: Charge Current, Power Saving, Shutdown after losing power, ADC Multiplier Override Wait Bluetooth Interval, Light Sleep Interval and Minimum Wake Interval. |
| [User](/docs/configuration/radio/user) | The user config options are: Long Name, Short Name, and Is Licensed |

31
docs/configuration/device-config/lora.mdx → docs/configuration/radio/lora.mdx
View file

@ -1,7 +1,6 @@
---
id: lora
title: LoRa Configuration
slug: /settings/config/lora
sidebar_label: LoRa
---
@ -9,7 +8,7 @@ import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import LoRaRegions from "../../blocks/_lora-regions.mdx";
The LoRa config options are: Region, Modem Preset, Max Hops, Transmit Power, Bandwidth, Spread Factor, Coding Rate, Frequency Offset, Transmit Enabled, Channel Number and Ignore Incoming Array. LoRa config uses an admin message sending a `Config.LoRa` protobuf.
The LoRa config options are: Region, Modem Preset, Max Hops, Transmit Power, Bandwidth, Spread Factor, Coding Rate, Frequency Offset, Transmit Enabled, Channel Number, Ignore Incoming Array, Override Duty Cycle Limit, SX126x RX Boosted Gain, and Override Frequency. LoRa config uses an admin message sending a `Config.LoRa` protobuf.
:::note
In order to communicate fully, devices within a mesh must have identical settings for Region and Modem Preset, or identical custom Modem settings.
@ -36,7 +35,7 @@ The presets are designed to provide further options for optimizing either speed
1. A high number of devices exist in the mesh, or messages are sent very frequently. Faster speeds (and therefore lower radio time per device) can help with mesh network congestion.
2. Maximum range is desired, for long range scenarios where a several second delay in message receipt is acceptable (for instance, attempting to send messages from a town to a distant mountain top).
The Presets available are as follows, and follow a linear pattern of Fastest <--> Slowest, and Shortest <--> Longest range:
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)
@ -81,7 +80,7 @@ Please be aware that values < 62.5kHz may require a TCXO on some hardware device
### Spread Factor
A number from 7 to 12. Indicates the number of chirps per symbol as 1<<spread_factor.
A number from 7 to 12. Indicates the number of chirps per symbol as 1[\<\<]spread_factor.
### Coding Rate
@ -103,6 +102,10 @@ Defaults to true
This is controlling the actual hardware frequency the radio is transmitting on. A channel number between 1 and NUM_CHANNELS (whatever the max is in the current region). If this is ZERO/UNSET then the rule is "use the old channel name hash based algorithm to derive the channel number".
:::info
LoRa Channel Configuration should not to be confused with messaging [Channel Configuration](/docs/configuration/radio/channels). See [Chat Channels VS Lora Modem Channels](/docs/configuration/tips#chat-channels-vs-lora-modem-channels) for further clarification.
:::
### Ignore Incoming Array
For testing it is useful sometimes to force a node to never listen to particular other nodes (simulating radio out of range). All nodenums listed in the ignore_incoming array will have packets they send dropped on receive (by router.cpp)
@ -128,17 +131,16 @@ values={[
{label: 'Android', value: 'android'},
{label: 'Apple', value: 'apple'},
{label: 'CLI', value: 'cli'},
{label: 'Flasher', value: 'flasher'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="android">
:::info
LoRa Config options such as Region, Modem Preset, and Hop Limit can be configured on Android.
LoRa Config options are available on Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Device Settings > LoRa Config**
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > LoRa**
:::
@ -146,7 +148,7 @@ LoRa Config options such as Region, Modem Preset, and Hop Limit can be configure
<TabItem value="apple">
:::info
Configuration of Region, Modem Preset and Hop Limit is available on iOS, iPadOS and macOS at Settings > Radio Configuration > LoRa.
Configuration of Region, Modem Preset, Transmit Enabled, Hop Limit, Channel Number and RX Boosted gain is available on iOS, iPadOS and macOS at Settings > Radio Configuration > LoRa.
:::
</TabItem>
@ -160,7 +162,7 @@ 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` |
| 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` | `UNSET` |
| lora.bandwidth | `31`, `62`, `125`, `250`, `500` | `250` |
@ -169,7 +171,7 @@ LoRa config commands are available in the python CLI. Example commands are below
| 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`, `false` | `true` |
| lora.tx_enabled | `false`, `true` | `true` |
| lora.channel_num | `0`, `1` to `NUM_CHANNELS` | `0` |
| lora.override_duty_cycle | `false`, `true` | `false` |
| lora.sx126x_rx_boosted_gain | `false`, `true` | `false` |
@ -205,15 +207,6 @@ meshtastic --set lora.override_duty_cycle true
meshtastic --set lora.override_duty_cycle false
```
</TabItem>
<TabItem value="flasher">
:::info
Only `lora.region` can be set via the GUI flasher. Refer to other clients for any other config.
:::
</TabItem>
<TabItem value="web">

16
docs/configuration/device-config/network.mdx → docs/configuration/radio/network.mdx
View file

@ -1,14 +1,13 @@
---
id: network
title: Network Configuration
slug: /settings/config/network
sidebar_label: Network
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The Network config options are: WiFi Enabled, WiFi SSID, WiFi PSK, Ethernet Enabled, IPv4 Networking Mode, Static Address and NTP Server. Network config uses an admin message sending a `Config.Network` protobuf.
The Network config options are: NTP Server, WiFi Enabled, WiFi SSID, WiFi PSK, Ethernet Enabled, IPv4 Networking Mode, and Static Address. Network config uses an admin message sending a `Config.Network` protobuf.
:::info
Enabling WiFi will disable Bluetooth. Only one connection method will work at a time.
@ -32,13 +31,13 @@ Set to `false` (Disabled) by default.
### WiFi SSID
This is your WiFi Networks SSID.
This is your WiFi Network's SSID.
Empty `""` by default. (Case Sensitive, Max Length: 33)
### WiFi PSK
This is your WiFi Networks password.
This is your WiFi Network's password.
Empty `""` by default. (Case Sensitive, Max Length: 64)
@ -79,7 +78,7 @@ values={[
Network Config options are available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Device Settings > Network Config**
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Network**
:::
@ -89,7 +88,8 @@ Network Config options are available for Android.
:::info
Network config is not available on Apple OS's.
Network config options are available on iOS, iPadOS and macOS.
:::
</TabItem>
@ -106,8 +106,10 @@ All Network config options are available in the python CLI.
| :------------------: | :---------------: | :--------------: |
| network.ntp_server | string | `0.pool.ntp.org` |
| network.wifi_enabled | `true`, `false` | `false` |
| network.wifi_psk | string | `""` |
| network.wifi_ssid | string | `""` |
| network.wifi_psk | string | `""` |
| network.eth_enabled | `true`, `false` | `false` |
| network.address_mode | `DHCP`, `STATIC` | `DHCP` |
:::tip

59
docs/configuration/device-config/position.mdx → docs/configuration/radio/position.mdx
View file

@ -1,38 +1,37 @@
---
id: position
title: Position Configuration
slug: /settings/config/position
sidebar_label: Position
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The position config options are: GPS Enabled, GPS Update Interval, GPS Attempt Time, Fixed Position, Smart Broadcast, Broadcast Interval and Position Packet Flags. Position config uses an admin message sending a `Config.Position` protobuf.
The position config options are: GPS Enabled, GPS Update Interval, GPS Attempt Time, Fixed Position, Smart Broadcast, Smart Broadcast Minimum Distance, Smart Broadcast Minimum Interval, Broadcast Interval, Position Packet Flags, and GPS RX/TX Pins. Position config uses an admin message sending a `Config.Position` protobuf.
Position data from GPS is provided by either the radio or your paired phone. Position data is not required to use Meshtastic but time calculations require at least one device on the mesh have either a GPS or internet connection for time.
## Position Config Values
### GPS Disabled
### GPS Enabled
Acceptable values: `true` or `false`
Defaults to false. Should the device GPS be disabled for this node?
Defaults to true. Enables GPS on the node.
### GPS Update Interval
How often should we try to get GPS position (in seconds), or zero for the default of once every 30 seconds, or a very large value (maxint) to update only once at boot.
How often we should try to get GPS position (in seconds), or zero for the default of once every 2 minutes, or a very large value (maxint) to update only once at boot.
### GPS Attempt Time
How long should we try to get our position during each GPS update interval attempt? (in seconds) Or if zero, use the default of 30 seconds.
How long should we try to get our position during each GPS update interval attempt? (in seconds) Or if zero, use the default of 15 minutes.
### Fixed Position
Acceptable values: `true` or `false`
Off by default
False by default
If set, this node is at a fixed position. The device will generate GPS updates at the regular GPS update interval, but use whatever the last lat/lon/alt it saved for the node. The lat/lon/alt can be set by an internal GPS or with the help of the mobile device's GPS.
@ -40,7 +39,7 @@ If set, this node is at a fixed position. The device will generate GPS updates a
Acceptable values: `true` or `false`
On by default
True by default
Smart broadcast will send out your position at an increased frequency only if your location has changed enough for a position update to be useful.
@ -48,17 +47,29 @@ Smart broadcast complements broadcast interval (doesn't override that setting) b
Smart broadcast will calculate an ideal position update interval based on the data rate of your selected channel configuration.
### Smart Broadcast Minimum Distance
Default of `0` is 100 meters
The minimum distance in meters traveled (since the last send) before we can send a position to the mesh if smart broadcast is enabled.
### Smart Broadcast Minimum Interval
Default of `0` is 30 seconds
The minimum number of seconds (since the last send) before we can send a position to the mesh if smart broadcast is enabled.
### Broadcast Interval
Default of `0` is 15 minutes
If smart broadcast is of we should send our position this often (but only if it has changed significantly)
If smart broadcast is off we should send our position this often (but only if it has changed significantly)
The GPS updates will be sent out every Broadcast Interval, with either the actual GPS location, or an empty location if no GPS fix was achieved. This defaults to broadcast every 15 minutes.
The GPS updates will be sent out every Broadcast Interval, with either the actual GPS location, or an empty location if no GPS fix was achieved.
### Position Flags
Bit field of boolean configuration options for POSITION messages (bitwise OR of PositionFlags)
Defines which options are sent in POSITION messages. Values are stored as a bit field of boolean configuration options (bitwise OR of PositionFlags).
| Value | Description |
| :----------------: | :--------------------------------------------------------------: |
@ -96,7 +107,7 @@ values={[
Position Config options are available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Device Settings > Position Config**
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Position**
:::
@ -116,17 +127,19 @@ All Position config commands are available in the python CLI. Example commands a
:::
| Setting | Acceptable Values | Default |
| :---------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------: |
| position.gps_enabled | `true`, `false` | `true` |
| position.gps_update_interval | `integer` (seconds) | Default `0` is 30 Seconds |
| position.gps_attempt_time | `integer` (seconds) | Default of `0` is 30 Seconds |
| position.fixed_position | `true`, `false` | `false` |
| position.position_broadcast_smart_enabled | `true`, `false` | `true` |
| position.position_broadcast_secs | `integer` (seconds) | Default of `0` is 15 Minutes |
| position.flags | `UNSET`, `ALTITUDE`, `ALTITUDE_MSL`, `GEOIDAL_SEPARATION`, `DOP`, `HVDOP`, `PDOP`, `SATINVIEW`, `SEQ_NO`, `TIMESTAMP`, `HEADING`, `SPEED` | `UNSET` |
| position.rx_gpio | `integer` (0-39) | `UNSET` |
| position.tx_gpio | `integer` (0-34) | `UNSET` |
| Setting | Acceptable Values | Default |
| :------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------: |
| position.gps_enabled | `true`, `false` | `true` |
| position.gps_update_interval | `integer` (seconds) | Default `0` is 2 Minutes |
| position.gps_attempt_time | `integer` (seconds) | Default of `0` is 15 Minutes |
| position.fixed_position | `true`, `false` | `false` |
| position.position_broadcast_smart_enabled | `true`, `false` | `true` |
| position.broadcast_smart_minimum_distance | `integer` (meters) | Default of `0` is 100 Meters |
|position.broadcast_smart_minimum_interval_secs| `integer` (seconds) | Default of `0` is 15 Minutes |
| position.position_broadcast_secs | `integer` (seconds) | Default of `0` is 30 Seconds |
| position.flags | `UNSET`, `ALTITUDE`, `ALTITUDE_MSL`, `GEOIDAL_SEPARATION`, `DOP`, `HVDOP`, `PDOP`, `SATINVIEW`, `SEQ_NO`, `TIMESTAMP`, `HEADING`, `SPEED` | `UNSET` |
| position.rx_gpio | `integer` (0-39) | `UNSET` |
| position.tx_gpio | `integer` (0-34) | `UNSET` |
:::tip

60
docs/configuration/device-config/power.mdx → docs/configuration/radio/power.mdx
View file

@ -1,7 +1,6 @@
---
id: power
title: Power Configuration
slug: /settings/config/power
sidebar_label: Power
---
@ -9,9 +8,15 @@ import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import calculateADC from "/src/utils/calculateADC";
The power config options are: Power Saving, Shutdown after losing power, ADC Multiplier Override Wait Bluetooth Interval, Mesh Super Deep Sleep Timeout, Super Deep Sleep Interval, Light Sleep Interval and Minimum Wake Interval. Power config uses an admin message sending a `Config.Power` protobuf.
:::info
Power settings are advanced configuration, most users should choose a role under [Device Config](/docs/configuration/radio/device) to manage power for their device and shouldn't ever need to adjust these settings.
:::
Power settings are advanced configuration, most users should choose a role under Device Config to manage power for their device and should never need to touch any of these settings.
The power config options are: Power Saving, Shutdown after losing power, ADC Multiplier Override, Wait Bluetooth Interval, Light Sleep Interval, Minimum Wake Interval, and Device Battery INA2xx Address. Power config uses an admin message sending a `Config.Power` protobuf.
:::info
ADC Multiplier, The Light Sleep setting only applies to ESP32-based boards. This settings will have no effect on nRF52 modules.
:::
## Power Config Values
@ -23,7 +28,7 @@ If set, Bluetooth, Wifi, and screen (if applicable) are turned off. When using t
Automatically shut down a device after a defined time period if power is lost.
### ADC Multiplier Override `Fixes issues on Heltec v2`
### ADC Multiplier Override
Ratio of voltage divider for battery pin e.g. 3.20 (R1=100k, R2=220k)
@ -85,27 +90,13 @@ It's important to note that this calibration method only maps 4.2V to Battery Ch
### Wait Bluetooth Interval
How long wait before turning off BLE in no Bluetooth states
How long to wait before turning off BLE in no Bluetooth states
`0` for default of 1 minute
### Mesh Super Deep Sleep Timeout
### Light Sleep Interval
While in Light Sleep if this value is exceeded we will lower into super deep sleep
or Super Deep Sleep Interval (default 1 year) or a button press
`0` for default of two hours, MAXUINT for disabled
### Super Deep Sleep Interval
While in Light Sleep if Mesh Super Deep Sleep Timeout Seconds is exceeded we will lower into super deep sleep or this value (default 1 year) or a button press
`0` for default of one year
### Light Sleep Interval `ESP32 Only Setting`
In light sleep the CPU is suspended, LoRa radio is on, BLE is off an GPS is on
In light sleep the CPU is suspended, LoRa radio is on, BLE is off and GPS is on
`0` for default of five minutes
@ -115,6 +106,14 @@ While in light sleep when we receive packets on the LoRa radio we will wake and
`0` for default of 10 seconds
### Device Battery INA2xx Address
If an INA-2XX device is auto-detected on one of the I2C buses at the specified address, it will be used as the authoritative source for reading device battery level voltage. Setting is ignored for devices with PMUs (e.g. T-beams)
:::tip
I2C addresses are normally represented in hexadecimal and will require conversion to decimal in order to set via Meshtastic clients. For example the I2C address of 0x40 converted to decimal is 64.
:::
## Power Config Client Availability
<Tabs
@ -133,7 +132,7 @@ values={[
Power Config options are available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Device Settings > Power Config**
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Power**
:::
@ -160,10 +159,9 @@ All Power config options are available in the python CLI.
| power.on_battery_shutdown_after_secs | `integer` (seconds) | Default of `0` is off |
| power.adc_multiplier_override | `2-4` (floating point value) | Default of `0` uses firmware values |
| power.wait_bluetooth_secs | `integer` (seconds) | Default of `0` is 1 minute |
| power.mesh_sds_timeout_secs | `integer` (seconds) | Default of `0` is 2 hours |
| power.sds_secs | `integer` (seconds) | Default of `0` is 1 year |
| power.ls_secs | `integer` (seconds) | Default of `0` is 1 hour |
| power.ls_secs | `integer` (seconds) | Default of `0` is 5 minutes |
| power.min_wake_secs | `integer` (seconds) | Default of `0` is 10 seconds |
| power.device_battery_ina_address | `integer` (I2C address as decimal) | Default of `0` is no address set |
:::tip
@ -190,18 +188,6 @@ meshtastic --set power.wait_bluetooth_secs 0
meshtastic --set power.wait_bluetooth_secs 120
```
```shell title="Set Mesh Super Deep Sleep Timeout (Default of 0 is 2 hours/7200 seconds)"
meshtastic --set power.mesh_sds_timeout_secs 0
meshtastic --set power.mesh_sds_timeout_secs 120
// Disable using MAXUINT
meshtastic --set power.mesh_sds_timeout_secs 4294967295
```
```shell title="Set Super Deep Sleep (Default of 0 is 1 year)"
meshtastic --set power.sds_secs 0
meshtastic --set power.sds_secs 120
```
```shell title="Set Light Sleep to default (Default of 0 is 5 minutes)"
meshtastic --set power.ls_secs 0
meshtastic --set power.ls_secs 120

7
docs/configuration/device-config/user.mdx → docs/configuration/radio/user.mdx
View file

@ -1,7 +1,6 @@
---
id: user
title: User Configuration
slug: /settings/config/user
sidebar_label: User
---
@ -51,10 +50,10 @@ values={[
:::info
User Config options are available for Android.
All User config options are available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Device Settings > User Config**
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > User**
:::
@ -63,7 +62,7 @@ User Config options are available for Android.
<TabItem value="apple">
:::info
`ShortName` and `LongName` User config options are available on iOS, iPadOS and macOS at `Settings > Radio Configuration > User`.
All User config options are available on iOS, iPadOS and macOS at `Settings > Radio Configuration > User`.
:::
</TabItem>

36
docs/configuration/rak-gpio-mapping.mdx
View file

@ -1,36 +0,0 @@
---
id: rak-gpio-mapping
title: RAK GPIO Pin Mapping
sidebar_label: RAK GPIO Mapping
sidebar_position: 5
---
## RAK GPIO Pin Mapping
The RAK4631 uses symbolic labels for its I/O Pins on the module and baseboard silk screens. The following table shows the mapping of the RAK4631 GPIO pins to the corresponding Arduino pins and the MCU Port numbers.
| RAK Pin | nRF52840 Pin | Arduino GPIO | Remark |
| ------- | ------------ | ------------ | ------------------------------------------------------------------------ |
| IO1 | P0.17 | 17 | used for GPS PPM signal if GPS module is connected |
| IO2 | P1.02 | 34 | used to power all peripheral modules, not available for user application |
| IO3 | P0.21 | 21 |
| IO4 | P0.04 | 4 |
| IO5 | P0.09 | 9 | The 'User Button' is mapped here. |
| IO6 | P0.10 | 10 |
| IO7 | P0.28 | 28 |
| SW1 | P0.01 | 1 |
| A0 | P0.04/AIN2 | A2 |
| A1 | P0.31/AIN7 | A7 |
| SPI_CS | P0.26 | 26 |
When configuring GPIO pins in your device settings, the Arduino GPIO numbers should be used.
```shell title="Example"
meshtastic --set external_notification.output 10
```
This will use IO6 on a RAK4631
:::caution Note
There is no usable GPIO pin on any RAK base board except the 'big' baseboard RAK19001 without adding a RAK13002 IO module or a third party IO sensor breakout.
:::

152
docs/configuration/remote-admin.mdx
View file

@ -2,7 +2,7 @@
id: remote-admin
title: Remote Node Administration
sidebar_label: Remote Nodes
sidebar_position: 4
sidebar_position: 3
---
:::caution Disclaimer
@ -24,8 +24,10 @@ By default, nodes will **only** respond to administrative commands via the local
Before a node will allow remote admin access, it must have a primary channel:
```shell title="Expected output"
$ meshtastic --info
```shell title="Command"
meshtastic --info
```
```markdown title="Expected output"
Connected to radio
...
Channels:
@ -33,25 +35,22 @@ Channels:
Primary channel URL: https://meshtastic.org/e/#CgMSAQESCggBOANAA0gBUBs
```
So from this output you see can that this node knows about only one channel and that its PSK is set to the default value.
From this output you see can that this node knows about only one channel and that its PSK is set to the default value.
Now we add an admin channel:
```shell title="Command"
meshtastic --ch-add admin
```
:::note
The name of the channel is important and must be `admin`.
:::
Your channels will now look like this:
```shell title="Command"
meshtastic --ch-add admin
```
```shell title="Expected output"
$ meshtastic --ch-add admin
Connected to radio
Writing modified channels to device
$ meshtastic --info
```
Run `meshtastic --info` and your channels will now look like this:
```shell title="Expected output"
Connected to radio
...
Channels:
@ -61,11 +60,11 @@ Primary channel URL: https://meshtastic.org/e/#CgMSAQESCggBOANAA0gBUBs
Complete URL (includes all channels): https://meshtastic.org/e/#CgMSAQEKKRIgYyDCitupTAOOXTcaMDxyNhDpPa3eThiQFziPFCqT0moaBWFkbWluEgoIATgDQANIAVAb
```
Notice that now we have a new secondary channel and the `--info` option prints out TWO URLs. The `Complete URL` includes all of the channels this node understands. The URL contains the preshared keys and should be treated with caution and kept a secret. When deploying remote administration, you only need the node you want to administer and the node you are locally connected to know this new "admin" channel. All of the other nodes will forward the packets as long as they are a member of the primary channel.
Notice that now we have a new secondary channel and the `--info` option prints out TWO URLs. The `Complete URL` includes all of the channels this node understands. The URL contains the preshared keys and should be treated with caution and kept a secret. When deploying remote administration, you only need the node you want to administer and the node you are locally connected to, to know this new "admin" channel. All of the other nodes will forward the packets as long as they are a member of the primary channel.
## Sharing the admin channel with other nodes
Creating an "admin" channel automatically generates a preshared key. In order to administer to other nodes remotely, we need to copy the preshared key to the new nodes.
Creating an "admin" channel automatically generates a preshared key. In order to administer other nodes remotely, we need to copy the preshared key to the new nodes.
For this step you need physical access to both the nodes.
@ -77,19 +76,21 @@ For this step you need physical access to both the nodes.
```shell
meshtastic --seturl the-url-from-step-2
```
<!-- trunk-ignore(markdownlint/MD029) -->
5. Run `meshtastic --info` and confirm that the "Complete URL" is the same for both of the nodes.
At this point you can take your remote node and install it far away and still be able to change any of its settings.
At this point you can take your remote node and install it far away. You will still be able to change any of its settings.
## Remotely administering your node
Now that both your local node and the remote node contain your secret admin channel key, you can do things like:
Now that both your local node and the remote node contain your secret admin channel key, you can now change settings remotely:
Get the node list from the local node:
```shell title="Expected output"
$ meshtastic --nodes
```shell title="Command"
meshtastic --nodes
```
```markdown title="Expected output"
Connected to radio
/-------------------------------------------------------------------------------------------------------------\
|N| User |AKA| ID |Latitude|Longitude|Altitude|Battery| SNR | LastHeard | Since |
@ -99,19 +100,24 @@ Connected to radio
```
Using the node ID from that list, send a message through the mesh telling that node to change its owner name.
The --dest argument value must be in single quotes for linux/mac '!28979058', no quotes for Windows !28979058.
```shell title="Expected output"
$ meshtastic --dest '!28979058' --set-owner "Im Remote"
:::info
The --dest argument value must be in single quotes for linux/mac: '!28979058', no quotes for Windows: !28979058.
:::
```shell title="Command"
meshtastic --dest '!28979058' --set-owner "Im Remote"
```
```markdown title="Expected output"
Connected to radio
Setting device owner to Im Remote
INFO:root:Requesting configuration from remote node (this could take a while)
Waiting for an acknowledgment from remote node (this could take a while)
```
And you can now confirm via the local node that the remote node has changed:
```shell title="Expected output"
$ meshtastic --nodes
```shell title="Command"
meshtastic --nodes
```
```markdown title="Expected output"
Connected to radio
/----------------------------------------------------------------------------------------------------\
|N| User |AKA| ID | Position |Battery| SNR | LastHeard | Since |
@ -120,39 +126,77 @@ Connected to radio
\----------------------------------------------------------------------------------------------------/
```
Note: you can change **any** parameter, add channels or get info from the remote node. Here's an example of setting ls_secs and printing the complete device info from the remote node:
Note: you can change **any** parameter, add channels or get settings from the remote node. Here's an example of setting ls_secs using the `--set` command and printing the position settings from the remote node using the `--get` command:
```shell title="Expected output"
$ meshtastic --dest \!28979058 --set ls_secs 301 --info
Connected to radio
INFO:root:Requesting configuration from remote node (this could take a while)
Set ls_secs to 301
Writing modified preferences to device
Preferences: { "lsSecs": 301, "region": "TW" }
Channels:
PRIMARY psk=default { "psk": "AQ==" }
SECONDARY psk=secret { "psk": "YyDCitupTAOOXTcaMDxyNhDpPa3eThiQFziPFCqT0mo=", "name": "admin" }
Primary channel URL: https://meshtastic.org/e/#CgMSAQESCggBOANAA0gBUBs
Complete URL (includes all channels): https://meshtastic.org/e/#CgMSAQEKKRIgYyDCitupTAOOXTcaMDxyNhDpPa3eThiQFziPFCqT0moaBWFkbWluEgoIATgDQANIAVAb
```shell title="Command"
meshtastic --dest '!28979058' --set power.ls_secs 301 --get position
```
## Admin Channel Setup is Complete
You've finished setting up and adding two devices to the admin channel. Remember, because this is a mesh network, it doesn't matter which node you are at; you could administer your first device we set up from the second one we added to the channel. And the settings and examples on this page are just a taste of the other settings you can set. Also, if you ever want to view a setting without having to read through the `--info`, you can always do the following:
```shell title="--get vs. --info"
$ meshtastic --dest \!28979058 --get ls_secs
```markdown title="Expected output"
Connected to radio
INFO:root:Requesting preferences from remote node (this could take a while)
ls_secs: 301
Requesting current config from remote node (this can take a while).
power:
wait_bluetooth_secs: 60
mesh_sds_timeout_secs: 7200
sds_secs: 4294967295
ls_secs: 300
min_wake_secs: 10
Set power.ls_secs to 301
Writing modified preferences to device
Requesting current config from remote node (this can take a while).
Received an ACK.
Completed getting preferences
Waiting for an acknowledgment from remote node (this could take a while)
position:
position_broadcast_secs: 900
position_broadcast_smart_enabled: true
gps_enabled: true
gps_update_interval: 120
gps_attempt_time: 900
position_flags: 3
rx_gpio: 15
tx_gpio: 13
broadcast_smart_minimum_distance: 100
broadcast_smart_minimum_interval_secs: 30
Completed getting preferences
```
For further reading, I recommend starting out with [Meshtastic-python](/docs/software/python/cli/) if you haven't already gone through this (hopefully you have since you are reading this). But for a full reference to the settings you can change, please see:
To set the `hop_limit` to 4 and then get the lora settings to confirm your new settings:
[Settings Overview](/docs/settings) and
[Complete list of user settings in Protobufs](https://buf.build/meshtastic/protobufs/docs/main:meshtastic#meshtastic.User)
```shell title="Command"
meshtastic --dest '!28979058' --set lora.hop_limit 4 --get lora
```
```markdown title="Expected output"
lora:
use_preset: true
region: US
hop_limit: 3
tx_enabled: true
tx_power: 30
## Areas for future development
Set lora.hop_limit to 4
Writing modified preferences to device
Requesting current config from remote node (this can take a while).
Received an ACK.
Completed getting preferences
Waiting for an acknowledgment from remote node (this could take a while)
In the future we will add a "dead man's timer" to this feature so that the remote node will revert any changes if you fail to send a special "commit changes" command. This will protect against sending bad settings to nodes that you can't physically access. Instead, if the node does not receive a commit message within 10 minutes it will revert all changes and (hopefully) rejoin the mesh.
lora:
use_preset: true
region: US
hop_limit: 4
tx_enabled: true
tx_power: 30
```
## Admin Channel Setup is Complete
You've finished setting up and adding two devices to the admin channel. Remember, because this is a mesh network, it doesn't matter which node you are at; you could administer your first device we set up from the second one we added to the channel. And the settings and examples on this page are just a taste of the other settings you can set.
For further reading, I recommend starting out with the [Meshtastic Python CLI Guide](/docs/software/python/cli/) if you haven't already gone through this (hopefully you have since you are reading this). But for a full reference to the settings you can change, please see:
[Settings Overview](/docs/configuration) and
[Complete list of user settings in Protobufs](https://buf.build/meshtastic/protobufs/docs/main:meshtastic#meshtastic.User)

68
docs/configuration/tips.mdx Normal file
View file

@ -0,0 +1,68 @@
---
id: tips
title: Configuration Tips
description: Common Settings & Solutions
sidebar_label: Tips
sidebar_position: 4
---
## Roles
Leave your [ROLE](/docs/configuration/radio/device#role) set to `CLIENT` unless you're sure another role would suit the node's purpose. All `CLIENT` nodes will "repeat" and "route" packets. Roles are for very specific applications so please [read the documentation](/docs/configuration/radio/device#role) before changing your node's role.
:::info
Users report that the current implementation of the `ROUTER` role with bluetooth switched off causes instability. If you would like the functionality associated with this role, it is recommended you choose `ROUTER_CLIENT` until a firmware fix is issued.
:::
## (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).
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.
### Creating a Private Primary with Default Secondary
If you'd like to connect with other Meshtastic users but only share your location with trusted parties, you may create a private PRIMARY channel and use the defaults for a SECONDARY channel.
1. Ensure you have not changed the LoRa [Modem Preset](/docs/configuration/radio/lora#modem-preset) from the default `unset` / `LONG_FAST`.
2. On your PRIMARY channel, set anything you'd like for the channel's name and choose a random PSK.
3. Enable a SECONDARY channel with a blank name (will default to LongFast) with PSK "AQ==".
4. Since the radio's frequency is automatically changed based on your PRIMARY channel's name, you will have to manually set it back to your region's default (in LoRa settings) in order to interface with users on the default channel:
### Default Primary Channels by Region
| US | EU_433 | EU_868 | CN | JP | ANZ | KR | TW | RU | IN | NZ_865 | TH | LORA_24 | UA_433 | UA_868 |
| :--: | :----: | :----: | :--: | :-: | :--: | :--: | :--: | :--: | :--: | :----: | :--: | :-----: | :----: | :----: |
| 20 | 4 | 1 | 36 | 20 | 20 | 12 | 16 | 2 | 4 | 4 | 16 | 6 | 6 | 2 |
To quickly test this configuration, find and scan your region's QR from [this repository](https://github.com/meshtastic/meshtastic/tree/master/static/img/configuration/qr-private-primary-example/). Remember to generate a new PSK for your private channel before sharing with your trusted nodes.
## Rebroadcast "Public" Traffic
Meshtastic nodes will rebroadcast all packets if they share [LoRa modem settings](/docs/configuration/radio/lora#lora-config-values), regardless of encryption (unless [Rebroadcast mode](/docs/configuration/radio/device#rebroadcast-mode) is set to `LOCAL_ONLY`).
:::info
If you would like your nodes to include/expand the "public" mesh, you must use the default [modem preset](/docs/configuration/radio/lora#modem-preset) `LONG_FAST`. If you change your PRIMARY channel name, you must manually set the LoRa channel to the default for your region (see above).
:::
## Chat Channels VS LoRa Modem Channels
Meshtastic uses the word "channels" to define two different configuration properties: [Messaging Channels](/docs/configuration/radio/channels) & [LoRa Modem Channels](/docs/configuration/radio/lora#channel-number)
### Radio Config: Channels
These configure "message groups" and include your PRIMARY and SECONDARY channels. All SECONDARY channels use the same LoRa modem config as your PRIMARY channel (including LoRa channel number).
There are 8 total chat channels. Channel 0 is your PRIMARY channel, with channels 1-7 available for private group messaging and/or special channels such as [`admin`](/docs/configuration/remote-admin).
### Radio Config: LoRa: Channel Number
This configures the frequency the radio is set to. Check out the [frequency calculator](/docs/overview/radio-settings#channel-frequency-calculator) to view the relationship between "channel number" and radio frequency.
## Best Practices
- If you are part of a large mesh and don't know what a setting does, don't change it (unless you're super curious).
- Leave your [MAX HOPS](/docs/configuration/radio/lora#max-hops) set to 3 unless you're sure you need more (or less) to reach your destination node.
- TEST your settings and hardware before you install in hard-to-reach locations.
- Connecting a node to the [public MQTT server](http://localhost:3000/docs/configuration/module/mqtt#connect-to-the-default-public-server) may publish the locations of all nodes in your mesh to the internet. This will also add every globally connected node to your node database and potentially flood your mesh with all types of packets.

44
docs/development/device/client-api.mdx
View file

@ -18,42 +18,42 @@ This protocol is **almost** identical when it is deployed over BLE, Serial/USB,
- The stream going towards the radio is only a series of ToRadio packets (with the extra 4 byte headers)
- The stream going towards the PC is a stream of FromRadio packets (with the 4 byte headers), or if the receiver state machine does not see valid header bytes it can (optionally) print those bytes as the debug console from the radio. This allows the device to emit regular serial debugging messages (which can be understood by a terminal program) but also switch to a more structured set of protobufs once it sees that the PC client has sent a protobuf towards it.
The 4 byte header is constructed to both provide framing and to not look line 'normal' 7 bit ASCII.
The 4 byte header is constructed to both provide framing and to not look like 'normal' 7 bit ASCII.
- Byte 0: START1 (0x94)
- Byte 1: START2 (0xc3)
- Byte 2: MSB of protobuf length
- Byte 3: LSB of protobuf length
The receiver will validate length and if >512 it will assume the packet is corrupted and return to looking for START1. While looking for START1 any other characters are printed as "debug output". For small example implementation of this reader see the python implementation.
The receiver will validate length and if >512 it will assume the packet is corrupted and return to looking for START1. While looking for START1 any other characters are printed as "debug output". For a small example implementation of this reader see the python implementation.
## Bluetooth (MeshBluetoothService)
This is the main Bluetooth service for the device and provides the API your app should use to get information about the mesh, send packets, or provision the radio.
For a reference implementation of a client that uses this service see [RadioInterfaceService](https://github.com/meshtastic/Meshtastic-Android/blob/master/app/src/main/java/com/geeksville/mesh/service/RadioInterfaceService.kt).
For a reference implementation of a client that uses this service see [RadioInterfaceService](https://github.com/meshtastic/Meshtastic-Android/blob/master/app/src/main/java/com/geeksville/mesh/repository/radio/RadioInterfaceService.kt).
Typical flow when a phone connects to the device should be the following (if you want to watch this flow from the python app just run `meshtastic --debug --info` - the flow over BLE is identical):
- There are only three relevant endpoints (and they have built in BLE documentation - so use a BLE tool of your choice to watch them): FromRadio, FromNum (sends notifies when new data is available in FromRadio) and ToRadio
- SetMTU size to 512
- There are only three relevant endpoints (and they have built in BLE documentation - so use a BLE tool of your choice to watch them): FromRadio, FromNum (sends notifies when new data is available in FromRadio) and ToRadio.
- SetMTU size to 512.
- Write a ToRadio.startConfig protobuf to the "ToRadio" endpoint - this tells the radio you are a new connection and you need the entire NodeDB sent down.
- Read repeatedly from the "FromRadio" endpoint. Each time you read you will get back a FromRadio protobuf (see Meshtatastic-protobuf). Keep reading from this endpoint until you get back and empty buffer.
- Read repeatedly from the "FromRadio" endpoint. Each time you read you will get back a FromRadio protobuf (see Meshtastic-protobuf). Keep reading from this endpoint until you get back and empty buffer.
- See below for the expected sequence for your initial download.
- After the initial download, you should subscribe for BLE "notify" on the "FromNum" endpoint. If a notification arrives, that means there are now one or more FromRadio packets waiting inside FromRadio. Read from FromRadio until you get back an empty packet.
- Any time you want to send packets to the radio, you should write a ToRadio packet into ToRadio.
Expected sequence for initial download:
- After your send startConfig, you will receive a series of FromRadio packets. The sequence of these packets will be as follows (but you are best not counting on this, instead just update your model for whatever packet you receive - based on looking at the type)
- Read a RadioConfig from "radio" - used to get the channel and radio settings
- Read a User from "user" - to get the username for this node
- Read a MyNodeInfo from "mynode" to get information about this local device
- Read a series of NodeInfo packets to build the phone's copy of the current NodeDB for the mesh
- Read a endConfig packet that indicates that the entire state you need has been sent
- Read a series of MeshPackets until it returns empty to get any messages that arrived for this node while the phone was away
- After your send startConfig, you will receive a series of FromRadio packets. The sequence of these packets will be as follows (but you are best not counting on this, instead just update your model for whatever packet you receive - based on looking at the type).
- Read a RadioConfig from "radio" - used to get the channel and radio settings.
- Read a User from "user" - to get the username for this node.
- Read a MyNodeInfo from "mynode" to get information about this local device.
- Read a series of NodeInfo packets to build the phone's copy of the current NodeDB for the mesh.
- Read an endConfig packet that indicates the entire state you need has been sent.
- Read a series of MeshPackets until it returns empty to get any messages that arrived for this node while the phone was away.
For definitions (and documentation) on FromRadio, ToRadio, MyNodeInfo, NodeInfo and User protocol buffers see [mesh.proto](https://github.com/meshtastic/protobufs/blob/master/mesh.proto)
For definitions (and documentation) on FromRadio, ToRadio, MyNodeInfo, NodeInfo and User protocol buffers see [mesh.proto](https://github.com/meshtastic/protobufs/blob/master/meshtastic/mesh.proto)
UUID for the service: 6ba1b218-15a8-461f-9fa8-5dcae273eafd
@ -86,12 +86,12 @@ Note: that if the phone ever sees this number decrease, it means the ESP32 has r
Re: Queue management,
not all messages are kept in the fromradio queue (filtered based on SubPacket):
- only the most recent Position and User messages for a particular node are kept
- all Data SubPackets are kept
- No WantNodeNum / DenyNodeNum messages are kept
- A variable keepAllPackets, if set to true will suppress this behavior and instead keep everything for forwarding to the phone (for debugging)
- Only the most recent Position and User messages for a particular node are kept.
- All Data SubPackets are kept.
- No WantNodeNum / DenyNodeNum messages are kept.
- A variable keepAllPackets, if set to true will suppress this behavior and instead keep everything for forwarding to the phone (for debugging).
### A note on MTU sizes
### A Note on MTU Sizes
This device will work with any MTU size, but it is highly recommended that you call your phone's "setMTU function to increase MTU to 512 bytes" as soon as you connect to a service. This will dramatically improve performance when reading/writing packets.
@ -99,7 +99,7 @@ This device will work with any MTU size, but it is highly recommended that you c
On connect, you should send a want_config_id protobuf to the device. This will cause the device to send its node DB and radio config via the fromradio endpoint. After sending the full DB, the radio will send a want_config_id to indicate it is done sending the configuration.
### Other Bluetooth services
### Other Bluetooth Services
This document focuses on the core device protocol, but it is worth noting that the following other Bluetooth services are also
provided by the device.
@ -125,8 +125,8 @@ Characteristics
#### DeviceInformationService
Implements the standard BLE contract for this service (has software version, hardware model, serial number, etc...)
Implements the standard BLE contract for this service (has software version, hardware model, serial number, etc...).
#### BatteryLevelService
Implements the standard BLE contract service, provides battery level in a way that most client devices should automatically understand (i.e. it should show in the Bluetooth devices screen automatically)
Implements the standard BLE contract service, provides battery level in a way that most client devices should automatically understand (i.e. it should show in the Bluetooth devices screen automatically).

12
docs/development/device/http-api.mdx
View file

@ -42,7 +42,7 @@ A `PUT` request to this endpoint will be expected to contain a series of ToRadio
The protobufs will be sent in binary as the body for the request.
For the initial implementation, only one ToRadio message per request is supported, but future optimizations to improve throughput might add support for multiple ToRadios in a single request.
Only one ToRadio message per request is supported.
#### OPTIONS
@ -76,21 +76,19 @@ The protobufs will be sent in binary as the body for the request.
## Authentication
The initial release will not have **any** user authentication. We assume access to the HTTP server is enough to establish trust.
Since authentication is also eventually needed for our other transports (TCP and eventually open BLE), we will be adding authentication **in-band**. When added in the second release there will be a new payload supported inside ToRadio for `SignIn <userid> <usersecret>`. The server will respond with a FromRadio `SignInResponse okay|fail`. Also, in the case of the REST API, that SignIn status will then be associated with the current session key. Most (all?) ToRadio packets will be ignored if the client is not signed in. Most (all?) FromRadio packets will be sent to clients that are not signed in.
There isn't **any** user authentication. We assume access to the HTTP server is enough to establish trust.
## Client
### JavaScript
See: <https://github.com/meshtastic/meshtastic.js>
See: https://github.com/meshtastic/meshtastic.js
A reference client written in JavaScript will provide a JavaScript API for using this transport. That client will do HTTP connections, use the generated protobuf JavaScript code and provide an API that hides all of this REST plumbing. The two key methods will be `sendToRadio(packet)` and `onFromRadio(callback)`.
### Protoman
See: <https://github.com/spluxx/Protoman>
See: https://github.com/spluxx/Protoman
Protoman is able to interface with the Meshtastic REST API out of the box. This is useful for manual testing of the endpoints.
@ -100,4 +98,4 @@ HTTP and HTTPS are both supported on the ESP32 using self signed certificates on
## Related documents
- Interesting slide pack on the concept: <https://www.slideshare.net/mokeefe/javaone-2009-ts5276-restful-protocol-buffers>
- Interesting slide pack on the concept: https://www.slideshare.net/mokeefe/javaone-2009-ts5276-restful-protocol-buffers

6
docs/development/device/module-api.mdx
View file

@ -5,7 +5,7 @@ sidebar_label: Module API
sidebar_position: 3
---
The purpose of this tutorial is for writing new core modules that can be ran on a device. In most cases, it is best to start with utilizing the serial module rather than creating a new one. However, if you're interested in creating a new core functionality from scratch, then building a module would be appropriate.
The purpose of this tutorial is for writing new core modules that can be run on a device. In most cases, it is best to start with utilizing the serial module rather than creating a new one. However, if you're interested in creating a new core functionality from scratch, then building a module would be appropriate.
## Key concepts
@ -57,7 +57,7 @@ A number of [key services](http://github.com/meshtastic/firmware/tree/master/src
- [NodeInfoModule](http://github.com/meshtastic/firmware/tree/master/src/modules/NodeInfoModule.h) - Receives/sends User information to other nodes so that usernames are available in the databases.
- [RemoteHardwareModule](http://github.com/meshtastic/firmware/tree/master/src/modules/RemoteHardwareModule.h) - A module that provides easy remote access to device hardware (for things like turning GPIOs on or off). Intended to be a more extensive example and provide a useful feature of its own. See [remote-hardware](/docs/hardware/peripheral/#remote-hardware) for details.
- [RemoteHardwareModule](http://github.com/meshtastic/firmware/tree/master/src/modules/RemoteHardwareModule.h) - A module that provides easy remote access to device hardware (for things like turning GPIOs on or off). Intended to be a more extensive example and provide a useful feature of its own. See [remote-hardware](/docs/configuration/module/remote-hardware) for details.
- [ReplyModule](http://github.com/meshtastic/firmware/tree/master/src/modules/ReplyModule.h) - A simple module that just replies to any packet it receives (provides a 'ping' service).
@ -71,7 +71,7 @@ The easiest way to get started is:
cp src/modules/ReplyModule.* src/modules/YourModule.*
```
3. Change the port number from `PortNum_REPLY_APP` to `PortNum_PRIVATE_APP`.
4. Edit the `setupModules()` function located at `modules/Moduless.cpp` to add a call to create an instance of your module (see comment at head of that function).
4. Edit the `setupModules()` function located at `modules/Modules.cpp` to add a call to create an instance of your module (see comment at head of that function).
5. Rebuild with your new module and install on the device.
6. Use the [Meshtastic Python CLI tool](https://github.com/meshtastic/Meshtastic-python) to send a packet to your board, for example:
- `meshtastic --dest 1234 --sendping` where _1234_ is another mesh node to send the ping to.

20
docs/development/documentation/index.mdx
View file

@ -18,17 +18,15 @@ Another component that we use is [Vercel](https://vercel.com) — a platform for
## Documentation Organization
| Section | File Path | Description |
| :----------------------: | :------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| About Meshtastic | `docs/about` | High level explanation of of Meshtastic. |
| Meshtastic Software | `docs/software` | Current bulk of documentation running through each Meshtastic project. |
| Getting Started | `docs/getting-started` | Instructions on how to get the Meshtastic firmware onto a users device. |
| Device Settings | `docs/software/settings` | Details each user setting and provides explanations for what the setting does and how to configure the device using the various clients available (Android, CLI, iOS, Web) |
| Hardware Details | `docs/hardware` | Any hardware related content. Any time a user is attaching a peripheral accessory to their device. That includes 3D printed cases, antennas, buttons, chimes, rotary encoders, and screens. |
| Radio Mesh Details | `docs/mesh` | This section discusses everything relating to the Meshtastic mesh. Mesh health metrics will be discussed here as well as topics such as signal strength, range and anything else pertaining to "over the air". |
| Contribute to Meshtastic | `docs/developers` | Details each of the projects and how they work together to give a developer an idea of how the Meshtastic ecosystem operates. |
| About the Documentation | `docs/maintaining-documentation` | This section explains how our documentation is organized, how to make edits to the documentation, view a local copy of your fork of the project. Style guides and tips will also be included here. |
| Legal | `docs/legal` | Any legal information. Most changes here will be handled by developers actually working on the projects that require any legal disclosures. Examples include: the Meshtastic trademark, terms of service, and privacy policy. |
| Section | File Path | Description |
| :----------------------: | :---------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| About Meshtastic | `docs/about` | A high level explanation of Meshtastic plus everything relating to the Meshtastic mesh. This includes radio settings, mesh algorithm and encryption. |
| Getting Started | `docs/getting-started` | Instructions on how to get the Meshtastic firmware onto a users device. |
| Device Settings | `docs/settings` | Details for both the device and module configurations. Details each user setting and offers explanations on their functionalities in addition to guiding the user on how to configure the device using the various clients available (Android, CLI, iOS, Web).|
| Hardware Details | `docs/hardware` | Any hardware related content such as officially supported radios and their peripherals such as 3d printed cases, antennas, buttons, chime, rotary encoders, and screens. |
| Meshtastic Software | `docs/software` | An overview of the current software used in conjunction with Meshtastic to include officially supported client and community applications. |
| Contribute to Meshtastic | `docs/developers` | Details of the necessary information needed for developers to start contributing to the development of the Meshtastic project. |
| Legal | `docs/legal` | Any legal information. Most changes here will be handled by developers actually working on the projects that require any legal disclosures. Examples include: the Meshtastic trademark, terms of service, and privacy policy. |
## Quick Start

4
docs/development/documentation/style-guides/settings.mdx
View file

@ -59,7 +59,7 @@ import TabItem from '@theme/TabItem';
<!--- Table of settings in alphabetical order --->
| Setting | Acceptable Values | Default |
| :---------------------: | :-------------------------: | :-----: |
| :---------------------: | :-------------------------: | :-----: |
| my_setting_with_options | `apple`, `banana`, `orange` | `apple` |
<!--- H3 for each setting above (alphabetized) --->
@ -71,7 +71,7 @@ import TabItem from '@theme/TabItem';
<!--- if the setting has many options, insert a table describing what those variables do --->
| Value | Description |
| :------: | :----------------------------: |
| :------: | :----------------------------: |
| `apple` | Description of apple (default) |
| `banana` | Description of banana |
| `orange` | Description of orange |

2
docs/development/firmware/building.mdx
View file

@ -60,6 +60,6 @@ The build system is modular. Adding a new board variant for an already supported
2. [Send a proposal](https://github.com/meshtastic/firmware/issues/new?assignees=&labels=enhancement%2Ctriage&template=New+Board.yml&title=%5BBoard%5D%3A+) to add a new board.
3. If approved, go to (https://github.com/meshtastic/protobufs) and send a Pull Request for the `mesh.proto` file, adding your board to the `HardwareModel` Enum.
4. Change your define in `platformio.ini` from `PRIVATE_HW` to `YOUR_BOARD`. Adjust any macro guards in the code you need to support your board.
5. Add your board identifier to `configuration.h` on the firmware repo and send in that Pull Request too.
5. Add your board identifier to `architecture.h` on the firmware repo in the folder of the platform you are using, and send in that Pull Request too.
6. Wait for the Pulls to be merged back into Master.
7. Profit :-)

2
docs/development/firmware/oled-guide.mdx
View file

@ -10,7 +10,7 @@ sidebar_label: OLED Localization
Please note that the used font file format differs from common Adafruit GFX.
2. Update the `customFontTableLookup` function in `Screen.h`
1. To map the double-byte UTF-8 code to the corresponding extended ASCII character of the desired codepage update the `customFontTableLookup` function in the `Screen.h` file.
2. Modify the `switch (last)` statement: use left byte from UTF-8 code in the `case` label to map charachter's right byte to its extended ASCII code by specifying an offset.
2. Modify the `switch (last)` statement: use left byte from UTF-8 code in the `case` label to map character's right byte to its extended ASCII code by specifying an offset.
3. Define language and font in `Screen.cpp`
```c

2
docs/development/firmware/port-numbers.mdx
View file

@ -6,7 +6,7 @@ sidebar_label: Port Numbers
Any new app that runs on the device or via sister apps on phones/PCs should pick and use a unique "portnum" for their applications use.
The current list of port numbers can be found listed in the [protobufs](https://buf.build/meshtastic/protobufs/docs/main:meshtastic#meshtastic.CriticalErrorCode)
The current list of port numbers can be found listed in the [protobufs](https://buf.build/meshtastic/protobufs/docs/main:meshtastic#meshtastic.PortNum)
## Assignment

4
docs/development/python/building.mdx
View file

@ -41,10 +41,6 @@ pytest -m smoke1
You need permissions in the GitHub project to make a build
:::
### Meshtastic-flasher
A `meshtastic-flasher` release consists of publishing the release to PyPi https://pypi.org/project/meshtastic-flasher/ as well as producing single-executable files that are downloadable from Github https://github.com/meshtastic/Meshtastic-gui-installer/releases.
#### Instructions - automated
- Go to Actions / Make Release / Run Workflow https://github.com/meshtastic/Meshtastic-gui-installer/actions/workflows/release.yml

26
docs/development/python/library.mdx
View file

@ -20,14 +20,14 @@ interface = meshtastic.serial_interface.SerialInterface()
interface.sendText("hello mesh")
ourNode = interface.getNode('^local')
print(f'Our node preferences:{ourNode.radioConfig.preferences}')
print(f'Our node preferences:{ourNode.localConfig}')
# update a value
print('Changing a preference...')
ourNode.radioConfig.preferences.gps_update_interval = 60
ourNode.localConfig.position.gps_update_interval = 60
print(f'Our node preferences now:{ourNode.radioConfig.preferences}')
ourNode.writeConfig()
print(f'Our node preferences now:{ourNode.localConfig}')
ourNode.writeConfig("position")
interface.close()
```
@ -57,23 +57,7 @@ interface.close()
Note: Be sure to change the IP address in the code above to a valid IP address for your setup.
You can get and update settings like this:
```python
import meshtastic
import meshtastic.serial_interface
interface = meshtastic.serial_interface.SerialInterface()
ourNode = interface.getNode('^local')
print(ourNode.radioConfig.preferences)
ourNode.radioConfig.preferences.gps_update_interval = 60
print(ourNode.radioConfig.preferences)
ourNode.writeConfig()
interface.close()
```
For the rough notes/implementation plan see [TODO](https://github.com/meshtastic/Meshtastic-python/blob/master/TODO). See the API for full details of how to use the library.
For the rough notes/implementation plan see [TODO](https://github.com/meshtastic/python/blob/master/TODO.md). See the API for full details of how to use the library.
## A note to developers of this lib

2
docs/development/reference/github.mdx
View file

@ -49,7 +49,7 @@ A description about the project
<!--You may optionally include brief install/update instructions here-->
<!--Any other pertenant sections-->
<!--Any other pertinent sections-->
### Compatibility
```

2
docs/development/reference/protobufs.mdx
View file

@ -5,4 +5,4 @@ title: Protobufs
Protobufs are used by Meshtastic software to send and receive data between App and Device and Device to Device.
Documentation on the Meshtastic Protobuf messages can be fund on the [BSR(Buf Schema Registry)](https://buf.build/meshtastic/protobufs).
Documentation on the Meshtastic Protobuf messages can be found on the [BSR(Buf Schema Registry)](https://buf.build/meshtastic/protobufs).

10
docs/development/web/building.mdx
View file

@ -1,10 +0,0 @@
---
id: building
title: Building
sidebar_label: Building
---
Releases are automatically generated for every commit as per out [CI](https://github.com/meshtastic/web/blob/master/.github/workflows/main.yml). This performs two actions:
1. Generates a perpetually updated [GitHub release](https://github.com/meshtastic/web/releases/tag/latest) with an accompanying `build.tar` that a automatically get's pulled by the firmware CI at build time.
2. A hosted version is deployed to [client.meshtastic.org](https://client.meshtastic.org).

112
docs/development/web/index.mdx
View file

@ -1,100 +1,66 @@
---
id: web-interface
title: Development Overview of the Web Interface
sidebar_label: Web Interface
title: Web Client Development
sidebar_label: Web Client
sidebar_position: 4
---
## Considerations
## Overview
We have a total of 458,752 bytes (448KB) available on the SPIFFS (Serial Peripheral Interface Flash File System) -- the on-board storage of the ESP32. Of that space, let's not use more than half of that (224KB) in order to leave space for other uses.
The Meshtastic web interface can be hosted or served from a node.
Right now, the Meshtastic Device Preferences as well as SSL keys use that space. We can imagine other future uses as well, such as logging chat messages and possibly saving received signal strength with GPS coordinates to create coverage heat maps.
The official hosted version can be found at [https://client.meshtastic.org](https://client.meshtastic.org).
## Static Files
The version served from a node can be accessed by first [connecting your node to your network](/docs/configuration/radio/network) and then navigating to http://meshtastic.local (or your_node_ip.local).
Static files can be placed in the /data folder. All files should be compressed in the .gz format with a .gz extension regardless of the file type.
As an example, this would mean we will have files such as:
## Development & Building
- style.css.gz
- meshtastic.js.gz
- meshtasticlogo.png.gz
### Development
Unless otherwise stated, files in the `/data` folder of the source code will be stored in `/static` on the device.
Clone the [Meshtastic Web Repo](https://github.com/meshtastic/web) repository
```shell
git clone https://github.com/meshtastic/web.git
cd web
```
## Application Interface
Install the dependencies.
We make extensive use of [Meshtastic.js](https://github.com/meshtastic/meshtastic.js).
```bash
pnpm i
```
### Building
## Embedded Server
Build the project:
### Root
```bash
pnpm build
```
When requesting to the root of the web server, the either /static/index.html or /static/index.html.gz will be fetched from the file system and served to the client. We require that the file is in the gzip format. Serving an uncompressed file is not supported. If both index.html and index.html.gz are on the filesystem, index.html will be served and index.html.gz will be ignored.
Start the development server:
### /static
```bash
pnpm dev
```
All files stored in /data/static in the Meshtastic source code will be available in /static on the Meshtastic device.
### Packaging
If a file is uploaded in a .gz format, the .gz extension will be stripped prior to being served to the client. Keep your filenames as short as possible. Short filenames work better than long file names.
Build the project:
An experimental file system browser with upload and delete capability is available by going to either:
```bash
pnpm build
```
- http://meshtastic.local/static
- https://meshtastic.local/static
GZip the output:
There are known issues with uploading files with large file sizes.
```bash
pnpm package
```
The current preferred method to upload data is through PlatformIO and the file system browser is provided without guarantees.
### /restart
## Releases
A post to this location will cause the device to restart.
Releases are automatically generated for every commit as per out [CI](https://github.com/meshtastic/web/blob/master/.github/workflows/main.yml). This performs two actions:
### /favicon.ico
The Meshtastic logo in .ico format.
### /hotspot-detect.html
Used by the Apple Captive Portal Assistant.
### /upload
Endpoint to upload files. Used by the file manager.
### /json/report
Return a report of airtime statistics and current status.
Formula to calculate when the current time period will roll over:
`data.airtime.seconds_per_period - (data.airtime.seconds_since_boot % data.airtime.seconds_per_period)`
### /json/scanNetworks
Returns a json data structure of WiFi networks in the area. It's recommended to call this at least 2 or 3 times and combine the results.
We purposely exclude open (insecure) networks from the list.
### /json/spiffs/browse/static
Returns a json data structure with the contents of /static.
If a filename includes a '.gz' extension, will also return a modified version of the filename with the extension stripped. This is to support the functionality in /static (see above).
### /json/spiffs/delete/static
Delete file specified by the parameter "delete". Use the method "DELETE".
eg: /json/spiffs/delete/static?delete=static/something.txt
### Performance
As a general guide, the ESP32 will return HTTP requests significantly faster than HTTPS requests. For responses of 1kb or less, expect the following for real world performance:
HTTP - 3.0 requests / sec
HTTPS - 0.4 requests / sec
The bottleneck of HTTPS is with the SSL handshake. We will get better performance serving one large file rather than multiple small files.
1. Generates a perpetually updated [GitHub release](https://github.com/meshtastic/web/releases/tag/latest) with an accompanying `build.tar` that a automatically get's pulled by the firmware CI at build time.
2. A hosted version is deployed to [client.meshtastic.org](https://client.meshtastic.org).

68
docs/development/web/partitions.mdx
View file

@ -1,68 +0,0 @@
---
id: esp32-partitions
title: Managing ESP32 partitions
sidebar_label: ESP32 partitions
---
:::caution
It has been reported that some of this information is out of date. Flashing the device with [Meshtastic-flasher](/docs/software/python/flasher) should fix these partition issues and update you to the current web interface.
FIXME - Investigate and rewrite document to reflect the current ESP32 Partition mitigation.
:::
## Insufficient space to upload web interface files
This problem seems to occur when your board has the partitioning structure set incorrectly. This typically occurs when the board has had a firmware other than Meshtastic on it previously. In this situation, the file upload page on the device typically shows a free space of around 48,000 bytes, rather than the ~300,000 bytes that it should have free.
![Meshtastic.local's upload page showing insufficient storage space](/img/insufficient-space.png)
There are a number of methods that essentially involve erasing the flash and then re-uploading the Meshtastic firmware.
## Install Script
The most reliable way to fix this problem is to use the install script that is included in the meshtastic firmware zip. If that doesn’t work, these other methods may work:
## Alternative methods
### Using the Arduino IDE:
https://meshtastic.discourse.group/t/solved-help-installing-with-other-than-esphome-flasher/2214/9
### Using Pio in Windows
```powershell
pio run --target erase --environment tbeam
```
Then re-install the firmware ie using ESPHome Flasher.
Requires: [Python](https://www.python.org), [Pio](https://pypi.org/project/pio), command to be run in the root directory of the firmware project once you’ve cloned it (this last requirement is an assumption based on pio not knowing what a tbeam is, may also require Visual Studio Code and PlatformIO as these were installed during use).
### Esptool.py
@1984 posted another method using the python based esptool.py to erase and re-flash the firmware:
```shell
esptool.py --baud 921600 erase_flash
esptool.py --baud 921600 write_flash 0x1000 system-info.bin
esptool.py --baud 921600 write_flash 0x00390000 spiffs-*.bin
esptool.py --baud 921600 write_flash 0x10000 firmware-tbeam-EU865-1.1.42.bin
```
Requires: [Python](https://www.python.org) and [esptool.py](https://github.com/espressif/esptool)
### Visual Studio & PlatformIO
There is also the method of using the Visual Studio IDE. This requires having Visual Studio and PlatformIO installed, along with having cloned the firmware code as per the [build instructions](/docs/development/firmware/build). After loading the project in Visual Studio, select the PlatformIO alien icon, then find the appropriate device, and then click the Erase Flash command.
![Erasing the flash using PlatformIO in Visual Studio Code](/img/platformio-erase.png)
https://meshtastic.discourse.group/t/configuring-channel-via-python-api/1948/17
Requires: [Visual Studio Code](https://code.visualstudio.com), [PlatformIO](https://platformio.org), cloned copy of the Meshtastic Firmware project
## How do I know it's worked?
Once it has been successfully erased and re-flashed, visiting https://192.168.42.1/static should leave you with free space on the order of 300,000 bytes, rather than the ~48,000 bytes you currently have. You can then upload the files from the meshtastic web release.
Occasionally, this may glitch may appear when uploading the larger app.js.gz file, but a further erase and flash typically solves this.

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

@ -13,19 +13,16 @@ import Link from "@docusaurus/Link";
Make sure not to power the radio on without first attaching the antenna! You could damage the radio chip!
:::
For ESP32 devices if the device already has a version of Meshtastic installed using the OTA firmware upgrade tool in the Android app is the friendliest path for users. OTA firmware updates are not yet available on Apple platforms.
If your ESP32 device does not have Meshtastic pre-installed flashing
Before you flash your device start by verifying connectivity with the device being flashed. Outlined below are steps that can be taken to verify connectivity and, if necessary, to install the appropriate drivers. If you end up needing to install drivers be sure to reboot your computer afterwards to verify the installation is complete.
:::note
The [T-Beam 0.7](/docs/hardware/devices/tbeam#t-beam---v07) board is an earlier version of the T-Beam board, and due to changes in the design in subsequent iterations this board uses a specific firmware file different from the other T-Beam boards.
`firmware-tbeam0.7-1.x.x.bin` is the correct firmware. `firmware-tbeam-1.x.x.bin` is incompatible. For all other [T-Beam](/docs/hardware/devices/tbeam) boards `firmware-tbeam-1.x.x.bin` is the correct selection.
`firmware-tbeam0.7-X.X.X.xxxxxxx.bin` is the correct firmware. `firmware-tbeam-X.X.X.xxxxxxx.bin` is incompatible. For all other [T-Beam](/docs/hardware/devices/tbeam) boards `firmware-tbeam-X.X.X.xxxxxxx.bin` is the correct selection.
:::
## Command Line Interface Instructions
### Install Prerequisite Software
<Tabs
groupId="operating-system"
defaultValue="linux"
@ -36,7 +33,6 @@ values={[
]}>
<TabItem value="linux">
### Install Prerequisite Software
Check if you have `python3` and `pip` installed with the following command
@ -56,18 +52,12 @@ If `pip` is not installed, install with
```shell
sudo apt-get install python3-pip
```
### Install `esptool`
```shell
pip3 install --upgrade esptool
```
</TabItem>
<TabItem value="macos">
### Install Prerequisite Software
OS X comes with `Python 2.7` installed, but not `pip`. The following uses Homebrew to install `python3` which includes `pip3`. On MacOS you will use `pip3` instead > of `pip`.
@ -99,12 +89,6 @@ Confirm `pip3` was installed alongside `python3`
```shell
pip3 -v
```
### Install `esptool`
```shell
pip3 install --upgrade esptool
```
</TabItem>
@ -126,15 +110,17 @@ pip --version
:::
### Install `esptool`
```shell
pip install --upgrade esptool
```
</TabItem>
</Tabs>
### Install `esptool`
```shell
pip3 install --upgrade esptool
```
### Confirm Communication With Chip
<Tabs
@ -200,7 +186,7 @@ cd ~/Downloads/firmware/
Install or Update the device that you have by using the following commands according to your operating system:
:::caution
Be very careful to install the correct load 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.
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
@ -228,12 +214,14 @@ values={[
</TabItem>
<TabItem value="macos">
<!-- trunk-ignore(markdownlint/MD024) -->
#### Install
```shell title="Command"
./device-install.sh -f firmware-BOARD-VERSION.bin
```
<!-- trunk-ignore(markdownlint/MD024) -->
#### Update
```shell title="Command"
@ -243,12 +231,14 @@ values={[
</TabItem>
<TabItem value="windows">
<!-- trunk-ignore(markdownlint/MD024) -->
#### Install
```shell title="Command"
device-install.bat -f firmware-BOARD-VERSION.bin
```
<!-- trunk-ignore(markdownlint/MD024) -->
#### Update
```shell title="Command"
@ -258,17 +248,6 @@ device-update.bat -f firmware-BOARD-VERSION.bin
</TabItem>
</Tabs>
### Select Firmware
Browse to the previously downloaded firmware and select the correct firmware based on the board type and frequency.
:::caution
Be very careful to install the correct load 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 firmware: It may appear to flash correctly, but if your device has a screen it might stay blank. On-board radio peripherals might be damaged because of GPIO pin direction, but you should just try to flash with the correct version.
:::
### Flash Firmware
Select `Flash ESP`. It may take a minute or two. Once complete, "Done! Flashing is complete!" will be shown.
## Connect and Configure Device

16
docs/getting-started/flashing-firmware/esp32/external-serial-adapter.mdx
View file

@ -10,7 +10,7 @@ import TabItem from "@theme/TabItem";
import Link from "@docusaurus/Link";
:::info
This information will likely only be helpful if you've already attempted to go through the prerequisites and processes outlined in [meshtastic flasher](/docs/software/python/flasher) or [manually flashing](/docs/getting-started/flashing-firmware/esp32/cli-script)
This information will likely only be helpful if you've already attempted to go through the prerequisites and processes outlined in [manually flashing](/docs/getting-started/flashing-firmware/esp32/cli-script)
:::
:::caution
@ -19,7 +19,7 @@ Make sure not to power the radio on without first attaching the antenna! You cou
## Background
Situations that may require usage an external USB to Serial Adapter:
Situations that may require using an external USB to Serial Adapter:
- Due to the chip shortage, recently purchased devices such as the TTGO T-Beam may come with legacy or non-standard USB to Serial adapter chips that are unreliable in some cases.
- Certain devices might have defective USB to Serial chip.
@ -55,10 +55,7 @@ Disconnect your USB to Serial Adapter from the computer before starting this pro
### Flashing
After following the steps above, your device should be in flash mode. You can flash your device using the [Meshtastic flasher](/docs/software/python/flasher) or [manual method](/docs/getting-started/flashing-firmware/esp32/cli-script)
Example using the Meshtastic Flasher
![image](https://user-images.githubusercontent.com/9000580/168447086-313e0649-1bfe-4ccb-b891-0f56059d8063.png)
After following the steps above, your device should be in flash mode. You can flash your device using the [manual method](/docs/getting-started/flashing-firmware/esp32/cli-script)
After flashing the device is complete, reset your device (via the RST button if available).
If you have the Meshtastic Python CLI installed, you can run `meshtastic --noproto` to connect the device again over the adapter and view the serial output to confirm Meshtastic installed correctly.
@ -66,14 +63,9 @@ If you have the Meshtastic Python CLI installed, you can run `meshtastic --nopro
### Troubleshooting
In the Meshtastic Flasher, device detection may not work when using the external USB to Serial adapter. You might need to manually select the correct device type from the drop-down.
![image](https://user-images.githubusercontent.com/9000580/168447197-206f7e14-debe-4b6a-bb2a-7647418075e4.png)
Sometimes you might receive an error for COM port permission in the Meshtastic Flasher or the manual device install scripts, this can be caused by a number of different issues.
You might receive an error for COM port permission in the manual device install scripts, this can be caused by a number of different issues.
You might need to run the process as an administrator, check to ensure software like Cura isn't monopolizing COM ports, or reboot.
![image](https://user-images.githubusercontent.com/9000580/168447232-1a3af39b-e3cc-44b9-bc3a-32843a9e6f1f.png)
## Connect and Configure Device

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

@ -14,3 +14,9 @@ The recommended method for firmware flashing is the [Web-Based Installer.](https
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.**
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.
:::info note
The [web client](http://localhost:3000/docs/software/web-client) at meshtastic.local is only updated with a full wipe and reinstall of the device. If you choose a reinstall, you will get the latest (bundled) web interface. To preserve your settings, you may [export your configuration](../../../software/python/cli/#--export-config) prior to a reinstall and load them back after.
:::

11
docs/getting-started/flashing-firmware/esp32/python-flasher.mdx
View file

@ -1,11 +0,0 @@
---
id: python-flasher
title: Using Meshtastic Python Flasher
sidebar_label: Python Flasher
sidebar_position: 2
---
import MFlasher from "../../../software/python-flasher.mdx";
import Link from "@docusaurus/Link";
<MFlasher components={props.components} />

20
docs/getting-started/flashing-firmware/nrf52/convert-rak4631r.mdx
View file

@ -9,6 +9,26 @@ The only difference between the _RAK4631-R_ (RUI3) and the _RAK4631_ (Arduino) i
Meshtastic requires the Arduino bootloader on RAK WisBlock nRF52-based boards. The process of converting the bootloader only needs to be performed once.
Here are two ways to flash the bootloader:
## USB Device Firmware Upgrade (DFU)
1. Install [Python](https://www.python.org/downloads/)
2. Install [adafruit-nrfutil](https://github.com/adafruit/Adafruit_nRF52_nrfutil)
```shell
pip3 install adafruit-nrfutil
```
3. Download the required bootloader: [WisCore_RAK4631_Board_Bootloader.zip](https://github.com/RAKWireless/WisBlock/releases/download/0.4.2/WisCore_RAK4631_Board_Bootloader.zip)
4. Connect your RAK device by USB.
5. Flash the bootloader
```shell
adafruit-nrfutil --verbose dfu serial --package ./WisCore_RAK4631_Board_Bootloader.zip -p /dev/ttyACM0 -b 115200 --singlebank --touch 1200
```
Note: The serial port name (`/dev/ttyACM0`) may differ depending on your operating system. Make sure to identify the correct port name for your setup.
6. Continue with the normal [flashing instructions](/docs/getting-started/flashing-firmware/nrf52/drag-n-drop)
## Debugger
This conversion requires the use of either a [DAPLink](https://daplink.io/) or [J-Link](https://www.segger.com/products/debug-probes/j-link/). The most reasonably priced and available is the [RAKDAP1](https://store.rakwireless.com/products/daplink-tool).
1. Install [Python](https://www.python.org/downloads/)

2
docs/getting-started/flashing-firmware/nrf52/drag-n-drop.mdx
View file

@ -17,7 +17,7 @@ Download and unzip the latest firmware from [Meshtastic Downloads](https://mesht
2. Double click the reset button on your device (this will put it into bootloader mode)
3. Notice a new drive will be mounted on your computer (Windows, Mac, or Linux)
4. Open this drive and you should see three files: `CURRENT.UF2`, `INDEX.HTM`, and `INFO_UF2.TXT`
5. Drop the appropriate firmware file (`firmware-DEVICE_NAME-vx.x.x-xxxxxxx.uf2`) from the release onto this drive.
5. Drop the appropriate firmware file (`firmware-DEVICE_NAME-x.x.x-xxxxxxx.uf2`) from the release onto this drive.
Once the file has finished copying onto the drive, the device will reboot and install the Meshtastic firmware.

12
docs/getting-started/flashing-firmware/nrf52/index.mdx
View file

@ -9,4 +9,14 @@ sidebar_position: 2
The nRF52 based devices have the easiest firmware upgrade process. No driver or software install is required on any platform.
1. The [Drag & Drop](/docs/getting-started/flashing-firmware/nrf52/drag-n-drop) firmware installation method is considered the "manual process" and recommended as the easiest solution.
### Drag & Drop
nRF52 devices use the [Drag & Drop](/docs/getting-started/flashing-firmware/nrf52/drag-n-drop) installation method to install firmware releases.
### Over-The-Air (OTA)
nRF52 devices are able to accept [OTA firmware updates](/docs/getting-started/flashing-firmware/nrf52/ota) from a mobile device over bluetooth.
### Factory Erase
You may wish to perform a [Factory Erase](/docs/getting-started/flashing-firmware/nrf52/nrf52-erase) prior to installing firmware to clear data that may change format and location between releases.
### Convert RAK4631-R to RAK4631
If your device did not come with the Arduino bootloader you will need to [perform the conversion](/docs/getting-started/flashing-firmware/nrf52/convert-rak4631r).

50
docs/getting-started/flashing-firmware/nrf52/ota.mdx Normal file
View file

@ -0,0 +1,50 @@
---
id: ota
title: nRF52 OTA Firmware Updates
sidebar_label: Over-The-Air
sidebar_position: 2
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
nRF52 devices from RAK are able to accept OTA firmware updates from a mobile device over bluetooth. The T-Echo bootloader does not have OTA support.
<Tabs
groupId="settings"
defaultValue="apple"
values={[
{label: 'Android', value: 'android'},
{label: 'Apple', value: 'apple'},
]}>
<TabItem value="android">
:::info
As of this writing, the current Android release of the nRF DFU app (v2.3.0) is not compatible with Meshtastic firmware updates. Please use the instructions below for updating via OTA with the nRF Connect App.
:::
OTA firmware updates are available for Android using an older release of the more advanced nRF Connect App __version 4.24.3__ which is available for download from the [Nordic Semiconductor GitHub page](https://github.com/NordicSemiconductor/Android-nRF-Connect/releases/tag/v4.24.3).
1. Download the firmware release you wish to install from the [Meshtastic Download Page](/downloads) or [Meshtastic GitHub](https://github.com/meshtastic/firmware/releases).
2. Unzip the firmware folder
3. Open the nRF Connect App and select CONNECT on your device from the SCANNER tab
4. Select the DFU icon from the top-right of the screen
5. Select the correct device firmware file (will end with -ota.zip)
6. The update will start automatically
</TabItem>
<TabItem value="apple">
OTA firmware updates are available on iOS & iPadOS using the nRF Device Firmware Update App available through the [Apple App Store](https://apps.apple.com/us/app/nrf-device-firmware-update/id1624454660)
1. Download the firmware release you wish to install from the [Meshtastic Download Page](/downloads), [Meshtastic GitHub](https://github.com/meshtastic/firmware/releases), or via the iOS or iPadOS app.
2. Unzip the firmware folder
3. Open the nRF DFU App and select the correct device firmware file (will end with -ota.zip)
4. Connect to your device
5. Upload the firmware
</TabItem>
</Tabs>

11
docs/getting-started/flashing-firmware/nrf52/python-flasher.mdx
View file

@ -1,11 +0,0 @@
---
id: python-flasher
title: Using Meshtastic Python Flasher
sidebar_label: Python Flasher
sidebar_position: 2
---
import Link from "@docusaurus/Link";
import MFlasher from "../../../software/python-flasher.mdx";
<MFlasher components={props.components} />

28
docs/getting-started/index.mdx
View file

@ -18,25 +18,33 @@ This guide assumes that you have already purchased the devices you will be using
to see your options.
:::
Before you begin, it's important to determine which kind of hardware you're using. Meshtastic works with devices that have either of these two types of Micro-Controller Units (MCU):
Before you begin, it's important to determine which kind of hardware you're using. Meshtastic works with devices that have these types of Micro-Controller Units (MCU):
### ESP32
The ESP32 chip is older and consumes more power than the nRF52 chip, but is equipped with both WiFi and Bluetooth. Supported ESP32 devices:
The ESP32 chip is older and consumes more power than the nRF52 chip, but is equipped with both WiFi and Bluetooth. Supported ESP32 devices include:
- LILYGO® TTGO T-Beam
- LILYGO® TTGO Lora
- LILYGO® TTGO T-Beam (>V1.1 recommended)
- LILYGO® TTGO Lora (>V2.1 recommended)
- Nano G1
- Station G1
- Heltec V3 and Wireless Stick Lite V3
- RAK11200 Core module for RAK WisBlock modular boards
### nRF52
The nRF52 chip is much more power efficient than the ESP32 chip and easier to update, but is only equipped with Bluetooth. Supported nRF52 devices:
The nRF52 chip is much more power efficient than the ESP32 chip and easier to update, but is only equipped with Bluetooth. Supported nRF52 devices include:
- RAK WisBlock
- RAK4631 Core module for RAK WisBlock modular boards
- LILYGO® TTGO T-Echo
### RP2040
The RP2040 is a dual-core ARM chip developed by Raspberry Pi. Supported RP2040 devices include:
- Raspberry Pi Pico + Waveshare LoRa Module (Note: **Bluetooth and Wi-Fi on the Pico W is not yet supported by Meshtastic**)
- RAK11310 Core module for RAK WisBlock modular boards
:::info
If your device is not listed above, please review our [supported devices](/docs/supported-hardware) to determine which MCU your device has or contact us in [Discord](https://discord.gg/ktMAKGBnBs) with any questions.
@ -57,7 +65,13 @@ Some cables only provide _charging_, verify that your cable is also capable of _
### Install Serial Drivers
If you don't have serial drivers installed on your computer, please choose one of the options below and install it before continuing.
:::caution
nRF52 devices typically do not require serial drivers. They use the UF2 bootloader which makes the devices appear as flash drives. Do _NOT_ download the USB device drivers unless required to install UF2 support.
:::
If you require serial drivers installed on your computer, please choose one of the options below and install it before continuing.
<div className="indexCtasBody">
<div className="split-container">

4
docs/getting-started/initial-config.mdx
View file

@ -34,7 +34,7 @@ values={[
- [Android App](/docs/category/android-app)
- [Web Client](https://client.meshtastic.org)
- [iOS App](/docs/category/apple-apps)
- [iOS/iPadOS/macOS App](/docs/category/apple-apps)
</TabItem>
<TabItem value="network">
@ -113,7 +113,7 @@ Now that you have set the LoRa region on your device, you can continue with conf
<div className="indexCtasBody">
<Link
className={"button button--outline button--lg cta--button"}
to={"/docs/settings/"}
to={"/docs/configuration/"}
>
Device Configuration
</Link>

22
docs/getting-started/serial-drivers/serial-drivers-nrf52.mdx
View file

@ -11,6 +11,12 @@ import Link from "@docusaurus/Link";
## Install nRF52 USB to Serial Drivers
:::caution
nRF52 devices typically do not require serial drivers. They use the UF2 bootloader which makes the devices appear as flash drives. Do _NOT_ download the USB device drivers unless required to install UF2 support.
:::
<Tabs
groupId="operating-system"
defaultValue="windows"
@ -22,17 +28,16 @@ values={[
<TabItem value="linux">
- [CH9102 Driver - Linux Download](http://www.wch-ic.com/downloads/CH341SER_LINUX_ZIP.html)
- [CH34x Driver - Linux Download](http://www.wch-ic.com/downloads/CH341SER_LINUX_ZIP.html)
</TabItem>
<TabItem value="macos">
- [CH9102 Driver - macOS Download](https://github.com/WCHSoftGroup/ch34xser_macos)
:::caution
:::info
With the latest versions of MacOS, the USB Serial driver is built-in. Do _NOT_ download the USB device drivers unless required. If you downloaded/installed any already, please remove them.
With the latest versions of MacOS, the USB Serial driver is built-in. If you downloaded/installed any already, please remove them.
:::
@ -47,11 +52,18 @@ Uninstall the kernel extension:
3. `sudo rm -rf /Library/Extensions/usbserial.kext`
4. Reboot
### Install the CH34x Driver
- [CH34x Driver- macOS Download](https://github.com/WCHSoftGroup/ch34xser_macos)
</TabItem>
<TabItem value="windows">
- [CH9102 Driver - Windows Download](http://www.wch-ic.com/downloads/CH341SER_EXE.html)
- [CH34x Driver - Windows Download](http://www.wch-ic.com/downloads/CH341SER_EXE.html)
</TabItem>

6
docs/getting-started/serial-drivers/test-serial-driver-installation.mdx
View file

@ -43,12 +43,13 @@ values={[
</TabItem>
<TabItem value="macos">
1. Navigate to `Apple Menu  > About This Mac > System Report... > Hardware > USB`.
1. Navigate to `Apple Menu  > About This Mac > More Info > System Report... > Hardware > USB`.
2. You should see similar to one of the following entries:
- `CP210X USB to UART Bridge Controller`
- `CH9102 USB to UART Bridge Controller`
- `WisCore RAK4631 Board`
- `USB Single Serial`
</TabItem>
<TabItem value="windows">
@ -58,7 +59,8 @@ values={[
- `Silicon Labs CP210X USB to UART Bridge (COM5)`
- `Silicon Labs CH9102 USB to UART Bridge (COM5)`
- `FIXME (WISBLOCK OUTPUT)`
- `USB-Enhanced-SERIAL CH9102 (COM5)`
- `USB Serial Device (COM5)`
</TabItem>
</Tabs>

7
docs/hardware/antennas/_category_.yml
View file

@ -1,7 +0,0 @@
label: Antennas
collapsible: true
position: 2
link:
type: generated-index
title: Antennas
slug: antenna

2
docs/hardware/antennas/antenna-report.mdx
View file

@ -7,6 +7,6 @@ sidebar_position: 2
## RicInNewMexico
[_RicInNewMexico_](https://github.com/RicInNewMexico) has gone through the trouble of testing a number of commonly purchased antennas in the Meshtastic community and given an opinion on whether or not a given antenna is performing optimally.
[_RicInNewMexico_](https://github.com/RicInNewMexico) and others have gone through the trouble of testing a number of commonly purchased antennas in the Meshtastic community and given an opinion on whether or not a given antenna is performing optimally.
Please check out the project on Github: [Meshtastic-Antenna-Reports](https://github.com/RicInNewMexico/Meshtastic-Antenna-Reports)

44
docs/hardware/antennas/index.mdx Normal file
View file

@ -0,0 +1,44 @@
---
id: antennas
title: LoRa Antennas
sidebar_label: Antennas
sidebar_position: 2
---
## Pages
[Antenna Testing](./testing.mdx)<br></br>
Guidance for testing and using your antennas.
[Antenna Reports](./antenna-report.mdx)<br></br>
Community submitted SWR testing.
[Antenna Selection](./lora-antennas.mdx)<br></br>
Considerations for choosing an antenna.
[Additional Resources](./resources.mdx)<br></br>
Antenna designs, tools, and coverage simulators.
## Community Favorites
These antennas have garnered positive feedback and frequent recommendations within our community. However, we encourage you to conduct your own research to ensure the best choice for your needs. We are not responsible for individual experiences or results.
### Compact / Handheld
| Frequency | Model | Purchase Links |
| :--: | :--: | :--: |
| 915 or 868 | GIZONT 17cm | [AliExpress](https://www.aliexpress.us/item/3256804421300249.html) |
| 915 or 868 | GIZONT 20cm | [AliExpress](https://www.aliexpress.us/item/3256804397374144.html) |
| 915 | LINX ANT-916-CW-HW-SMA | [Mouser](https://www.mouser.com/ProductDetail/TE-Connectivity-Linx-Technologies/ANT-916-CW-HW-SMA?qs=PKuFCuYbGOfeZQiEfd4fWA%3D%3D) [DigiKey](https://www.digikey.com/en/products/detail/te-connectivity-linx/ANT-916-CW-HW-SMA/2694126) |
| 915 | ZIISOR TX915-JKS-20 | [AliExpress](https://www.aliexpress.us/item/3256801688016561.html) |
| 915 | CDEBYTE TX915-JKD-20 (5-pack)| [AliExpress](https://www.aliexpress.us/item/3256803106771365.html) |
### Base Station / Repeater
| Frequency | Model | Purchase Links |
| :--: | :--: | :--: |
| 915 | Alfa AOA-915-5ACM | [Rokland](https://store.rokland.com/products/alfa-aoa-915-5acm-5-dbi-omni-outdoor-915mhz-802-11ah-mini-antenna-for-lora-halow-application) |
| 915 | Rokland 32" 5.8 dBi | [Rokland](https://store.rokland.com/collections/802-11ah-wi-fi-halow/products/5-8-dbi-n-male-omni-outdoor-915-mhz-antenna-large-profile-32-height-for-helium-rak-miner-2-nebra-indoor-bobcat) |
### Automotive
| Frequency | Model | Purchase Links |
| :--: | :--: | :--: |
| 915 | Laird MA9-5N | [DigiKey](https://www.digikey.com/en/products/detail/te-connectivity-laird/MA9-5N/3486940) |
| 915 | Taoglas TI.16.5F11 | [DigiKey](https://www.digikey.com/en/products/detail/taoglas-limited/TI-16-5F11/3724558) |

4
docs/hardware/antennas/lora-antennas.mdx
View file

@ -17,9 +17,11 @@ The antenna's design will affect:
- Amount of signal which is reflected back to the device itself
:::caution
While the LoRa devices we use for Meshtastic are relatively low power radios, care should be taken _not_ to operate any radio transmission device without an antenna or with a poorly matched antenna. Un-transmitted radio signal reflected back to the transmitter can damage the device.
While the LoRa devices we use for Meshtastic are relatively low power radios, care should be taken _not_ to operate any radio transmission device without an antenna or with a poorly matched antenna. Radio signals transmitted without an antenna can reflect back and damage the device.
:::
<object data="https://www.youtube.com/embed/V3f-Y3EfsBU?autohide=1&autoplay=0" width="100%" height="400"></object>
## Important considerations
### What transmission frequency are you using?

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

@ -9,8 +9,8 @@ Testing of antennas can be both simple and complex. At its simplest, testing inv
If you have sufficient range with your existing aerial, skip this section. If you don't, consider either getting more nodes and / or replace the stock aerial with one tuned (to your region transmitter's frequency):
- A quarter wave _tuned_ stubby aerial (<10cm for fit-in-pocket) should have a real-world range of a couple of km without significant obstacles (buildings / hills).
- Aerial criteria: 50 Ohm, appropriate connector (usually SMA male or U.FL), low VSWR (<2) (at tuning frequency - see its datasheet), gain > 0 dBi .
- A quarter wave _tuned_ stubby aerial (\<10cm for fit-in-pocket) should have a real-world range of a couple of km without significant obstacles (buildings / hills).
- Aerial criteria: 50 Ohm, appropriate connector (usually SMA male or U.FL), low VSWR (\<2) (at tuning frequency - see its datasheet), gain > 0 dBi .
- Caution, avoid suppliers who:
- don't state the aerial's tuned frequency and its specific purpose (LoRa network)
- claim huge gain figures on omni-directional aerials
@ -27,7 +27,7 @@ Some understanding of the factors affecting radio communications will help achie
The Meshtastic devices (of various flavors) lend themselves to experimentation, not only because you can replace their aerials, but also because of their mesh operation. All nodes will, without alteration, relay communications from any other members of the mesh around obstacles and over greater distances. The cost of aerial investment should be weighed against investment in additional low-cost nodes.
:::caution
While the LoRa devices we are using for Meshtastic are relatively low power radios, care should be taken _not_ to operate any radio transmission device without an aerial or with a poorly matched aerial. Un-transmitted radio signal reflected back to the transmitter can damage the device.
While the LoRa devices we are using for Meshtastic are relatively low power radios, care should be taken _not_ to operate any radio transmission device without an aerial or with a poorly matched aerial. Radio signals transmitted without an antenna can reflect back and damage the device.
:::
The information collected here is by no means definitive, and necessarily abbreviated (it's a huge topic).
@ -42,7 +42,7 @@ As mentioned, while stating the obvious, the simplest way of performing a test i
- Change aerials, repeat, and evaluate results.
:::note
The [range test module](/docs/settings/moduleconfig/range-test) has been designed for exactly this purpose. It allows one node to transmit a frequent message, and another node to record which messages were received. This data is saved and can be imported to applications such as Google Earth.
The [range test module](/docs/configuration/module/range-test) has been designed for exactly this purpose. It allows one node to transmit a frequent message, and another node to record which messages were received. This data is saved and can be imported to applications such as Google Earth.
:::
On the topic of testing - performing your own testing and providing feedback is the lifeblood of Meshtastic and open source projects.
@ -72,7 +72,7 @@ Unless you're using your devices in a vacuum, with clear line of sight between a
- Absorption by materials (with varying degrees attenuation, by material and depth),
- Reflection off surfaces (and channeling through material tunnels, including warm / cold air tunnels commonly present in the atmosphere),
- Diffraction around obstacles (over forests and around corners).
- [Fresnel Zone](They may not have been selected for your given frequency range, tuned or of a quality design.) - Football shape between antennas that must be clear of obstructions or else the signal is attenuated.
- Fresnel Zone - A football shape between antennas that must be clear of obstructions or else the signal is attenuated.
### Environmental Factors

75
docs/hardware/devices/Nano Series/buttons.mdx Normal file
View file

@ -0,0 +1,75 @@
---
id: buttons
title: Hardware Buttons
sidebar_label: Buttons
sidebar_position: 1
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
## Device
<Tabs
groupId="nano-series"
defaultValue="g2"
values={[
{label: 'Nano G2 Ultra', value:'g2'},
{label: 'Nano G1 Explorer', value: 'g1-e'},
{label: 'Nano G1', value: 'g1'}
]}>
<TabItem value="g2">
### Nano G2 Ultra Buttons
- **User/Program Button:**
- **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.
- **Long press:** Will signal the device to shutdown after 5 seconds (*soft off*).
- **Message Read Button:**
- **Single press:** Clears the New Message LED.
### Nano G2 Ultra Switches
- **Power:**
- **Toggle Up:** Turns on the device.
- **Toggle Down:** Turns off the device.
- **Location Pin:**
- **Toggle Up:** Sets GPS to operating mode.
- **Toggle Down:** Sets GPS to low power mode.
- **Bell:**
- **Toggle Up:** Selects Buzzer for Enhanced Message Notification Circuit.
- **Toggle Down:** Selects LED for Enhanced Message Notification Circuit.
</TabItem>
<TabItem value="g1-e">
### Nano G1 Explorer Buttons
- **User/Program Button:**
- **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.
- **Message Read Button:**
- **Single press:** Clears the New Message LED.
### Nano G1 Explorer Switches
- **Power:**
- **Toggle Up:** Turns on the device.
- **Toggle Down:** Turns off the device.
- **Location Pin:**
- **Toggle Up:** Sets GPS to operating mode.
- **Toggle Down:** Sets GPS to low power mode.
- **Bell:**
- **Toggle Up:** Selects Buzzer for Enhanced Message Notification Circuit.
- **Toggle Down:** Selects LED for Enhanced Message Notification Circuit.
</TabItem>
<TabItem value="g1">
</TabItem>
</Tabs>

147
docs/hardware/devices/Nano Series/index.mdx Normal file
View file

@ -0,0 +1,147 @@
---
id: nano-series
title: Nano Series
sidebar_label: Nano Series
sidebar_position: 7
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The Nano Series, designed by Neil Hao from B&Q Consulting and powered by Meshtastic, are devices engineered to be a portable and durable solution for outdoor adventures such as hiking, piloting, skiing and more. They are designed to strike a balance between RF performance, size, ruggedness, and power efficiency — providing users with a reliable solution in various outdoor environments.
For a full and complete comparison of the different devices in the Nano series, be sure to visit B&Q Consulting's [nano series wiki page](https://wiki.uniteng.com/en/meshtastic#nano-edition).
<Tabs
groupId="nano-series"
defaultValue="g2"
values={[
{label: 'Nano G2 Ultra', value:'g2'},
{label: 'Nano G1 Explorer', value: 'g1-e'},
{label: 'Nano G1', value: 'g1'}
]}>
<TabItem value="g2">
The Nano G2 Ultra and Nano G1 Explorer have exactly the same Lora front-end circuit design and internal wideband Lora antenna. The primary design goal of the Nano G2 Ultra is to reduce power consumption and improve battery life by using the low power MCU NRF52840. The typical battery life is optimized to be about 3.5 days. As with the Nano G1 Explorer, the Nano G2 Ultra's design also takes into account the potential impact of the human body on its antenna performance, ensuring optimal RF performance even when carried in a pocket.
### Nano G2 Ultra Specifications
- **MCU:**
- NRF52840
- Bluetooth 5.4
- **LoRa Transceiver:**
- Semtech SX1262
- **Frequency Options:**
- _US (902.0Mhz to 928.0Mhz), EU_868 (869.4Mhz to 869.65Mhz), JP (920.8Mhz to 927.8Mhz), ANZ (915.0Mhz to 928.0Mhz), RU (868.7Mhz to 869.2Mhz), KR (920.0Mhz to 923.0Mhz), TW (920.0Mhz to 925.0Mhz), IN (865.0Mhz to 867.0Mhz), NZ_865 (864.0Mhz to 868.0Mhz), TH (920.0Mhz to 925.0Mhz), UA_868 (868.0Mhz to 868.6Mhz)._
- **Navigation Module:**
- ATGM336H-5N-71 (Supports GPS, BDS and GLONASS)
- **Antenna:**
- New internal wide-band antenna with optimized wide-band LoRa RF frontend circuit.
- **Connectors:**
- USB-C
### Nano G2 Ultra Features
- Meshtastic pre-installed.
- New internal GPS antenna that significantly reduces GPS lock time compared to the Nano G1. Additionally, the GPS module can be set to a low-power mode with the GPS physical switch.
- Integrated enhanced message notification circuit for LED or Buzzer, configurable via physical switches.
- Physical power switch to easily turn the device on/off.
- Replaceable 1.3" OLED screen with a FPC connector.
- Internal Li-Polymer Battery Charger. _(An optional 3.7V 603450 JST 1.25mm Rechargeable Li-Polymer Battery can also be installed.)_
- Buck-boost converter to provide stable 3.3V to the system even in the event the Li-Polymer battery voltage drops to as low as 2.5V. Supply voltage stability is very important to ensure that the performance of RF circuits meets design expectations.
- NXP PCF8563 Real Time Clock (RTC)
- Optional I2C Extension Board (1x GROVE I2C Socket and 1x SparkFun QWIIC I2C Socket for Sensors and Keyboard)
### Nano G2 Ultra Resources
- Firmware file: `firmware-nano-g2-ultra-X.X.X.xxxxxxx.uf2`
- Official Purchase Links:
- [Official Store](https://shop.uniteng.com/product/meshtastic-mesh-device-nano-g2-ultra/)
- [Official Tindie Store](https://www.tindie.com/products/neilhao/meshtastic-mesh-device-nano-g2-ultra/)
Further information on the Nano G2 Ultra can be found on [Unit Engineering's Wiki](https://wiki.uniteng.com/en/meshtastic/nano-g2-ultra).
![Nano G2 Ultra](/img/hardware/nano_g2_ultra.jpeg)
</TabItem>
<TabItem value="g1-e">
The Nano G1 Explorer, powered by Meshtastic, is a significant upgrade from the Nano G1. It incorporates the latest RF technologies from B&Q Consulting, featuring a new internal wide-band LoRa antenna that can support frequencies ranging from 815 MHz to 940 MHz. With this new antenna, combined with an optimized wide-band LoRa RF frontend circuit, the Nano G1 Explorer is capable of working with the majority of LoRa frequency bands worldwide without the need for antenna changes. The device's design also takes into account the potential impact of the human body on its antenna performance, ensuring optimal RF performance even when carried in a pocket.
### Nano G1 Explorer Specifications
- **MCU:**
- ESP32 WROOM (WiFi & Bluetooth)
- Bluetooth 4.2
- **LoRa Transceiver:**
- Semtech SX1262
- **Frequency Options:**
- _US (902.0Mhz to 928.0Mhz), EU_868 (869.4Mhz to 869.65Mhz), JP (920.8Mhz to 927.8Mhz), ANZ (915.0Mhz to 928.0Mhz), RU (868.7Mhz to 869.2Mhz), KR (920.0Mhz to 923.0Mhz), TW (920.0Mhz to 925.0Mhz), IN (865.0Mhz to 867.0Mhz), NZ_865 (864.0Mhz to 868.0Mhz), TH (920.0Mhz to 925.0Mhz), UA_868 (868.0Mhz to 868.6Mhz)._
- **Navigation Module:**
- ATGM336H-5N-71 (Supports GPS, BDS and GLONASS)
- **Antenna:**
- New internal wide-band antenna with optimized wide-band LoRa RF frontend circuit.
- **Connectors:**
- USB-C
### Nano G1 Explorer Features
- Meshtastic pre-installed.
- New internal GPS antenna that significantly reduces GPS lock time compared to the Nano G1. Additionally, the GPS module can be set to a low-power mode with the GPS physical switch.
- Integrated enhanced message notification circuit for LED or Buzzer, configurable via physical switches.
- Physical power switch to easily turn the device on/off.
- Replaceable 1.3" OLED screen with a FPC connector.
- Internal Li-Polymer Battery Charger. _(An optional 3.7V 603450 JST 1.25mm Rechargeable Li-Polymer Battery can also be installed.)_
- Buck-boost converter to provide stable 3.3V to the system even in the event the Li-Polymer battery voltage drops to as low as 2.5V. Supply voltage stability is very important to ensure that the performance of RF circuits meets design expectations.
### Nano G1 Explorer Resources
- Firmware file: `firmware-nano-g1-explorer-X.X.X.xxxxxxx.bin`
- Official Purchase Links:
- [Official Store](https://shop.uniteng.com/product/meshtastic-mesh-device-nano-edition/)
- [Official Tindie Store](https://www.tindie.com/products/neilhao/meshtastic-mesh-device-nano-g1-explorer/)
Further information on the Nano G1 can be found on [Unit Engineering's Wiki](https://wiki.uniteng.com/en/meshtastic/nano-g1-explorer).
![Nano G1 Explorer](/img/hardware/nano_g1_explorer.jpeg)
</TabItem>
<TabItem value="g1">
The Nano G1 is the first dedicated hardware device to be designed from scratch purely for Meshtastic by Neil Hao. It has been designed to be small and compact with the inclusion of a high quality internal PCB antenna.
### Nano G1 Specifications
- **MCU**
- ESP32 WROOM (WiFi & Bluetooth)
- Bluetooth 4.2
- **LoRa Transceiver**
- Semtech SX1276
- Additional ultra-low noise amplifier to improve LoRa receiver sensitivity
- **Frequency options**
- US-915 MHz
- **Navigation Module**
- ATGM336H-5N-71 (Supports GPS, BDS and GLONASS)
- **Antenna**
- Built in 915Mhz Lora PCB Antenna (VSWR \<=1.5 @ 915 MHz)
- **Connectors**
- USB-C
### Nano G1 Features
- Meshtastic pre-installed
- User button
- 1.3 inch OLED screen
- Buzzer
### Nano G1 Resources
- Firmware file: `firmware-nano-g1-X.X.X.xxxxxxx.bin`
Further information on the Nano G1 can be found on [Unit Engineering's Wiki](https://uniteng.com/wiki/doku.php?id=meshtastic:nano).
![Nano G1](/img/hardware/nano-g1-front.jpg)
</TabItem>
</Tabs>

244
docs/hardware/devices/heltec/index.mdx
View file

@ -1,8 +1,8 @@
---
id: heltec
title: HELTEC® Lora 32
sidebar_label: HELTEC® Lora 32
sidebar_position: 7
title: HELTEC® LoRa 32
sidebar_label: HELTEC® LoRa 32
sidebar_position: 5
---
import Tabs from "@theme/Tabs";
@ -12,91 +12,35 @@ import TabItem from "@theme/TabItem";
groupId="heltec"
defaultValue="v3"
values={[
{label: 'Lora32 V1', value: 'v1'},
{label: 'Lora32 V2.0', value: 'v2.0'},
{label: 'Lora32 V2.1', value: 'v2.1'},
{label: 'Lora32 V3', value:'v3'},
{label: 'Wireless Stick Lite V3', value:'Wireless Stick Lite V3'}
{label: 'LoRa32 V2.1', value: 'v2.1'},
{label: 'LoRa32 V3', value:'v3'},
{label: 'Wireless Stick Lite V3', value:'Wireless Stick Lite V3'},
{label: 'Wireless Tracker', value: 'tracker'},
{label: 'Wireless Paper', value: 'paper'}
]}>
<TabItem value="v1">
:::warning
Not recommended! Very old board with design issues. Support is being phased out. Use V3 in new projects.
:::
- **MCU**
- ESP32 (WiFi & Bluetooth)
- **LoRa Transceiver**
- Semtech SX1276
- **Frequency options**
- 433 MHz
- 915 MHz
- 868 MHz
- **Connectors**
- Micro USB
- Antenna: U.FL antenna connector
## Features
- Built in 0.96 inch OLED display
- User and Reset switches
- No GPS
## Resources
- Firmware file: `firmware-heltec-v1-X.X.X.xxxxxxx.bin`
</TabItem>
<TabItem value="v2.0">
:::warning
Not recommended because of design issues! Support is being phased out. Use V3 in new projects.
:::
- **MCU**
- ESP32 (WiFi & Bluetooth)
- **LoRa Transceiver**
- Semtech SX127x
- **Frequency options**
- 915 MHz
- 868 MHz
- **Connectors**
- Micro USB
- Antenna: U.FL antenna connector
## Features
- Built in 0.96 inch OLED display
- User and Reset switches
- No GPS
## Resources
- Firmware file: `firmware-heltec-v2.0-X.X.X.xxxxxxx.bin`
</TabItem>
<TabItem value="v2.1">
:::warning
Not recommended because of design issues! Support is being phased out. Use V3 in new projects.
:::
- **MCU**
- **MCU:**
- ESP32 (WiFi & Bluetooth)
- **LoRa Transceiver**
- **LoRa Transceiver:**
- Semtech SX127x
- **Frequency options**
- **Frequency Options:**
- 433 MHz
- 868 MHz
- 915 MHz
- **Connectors**
- **Connectors:**
- Micro USB
- Antenna: U.FL antenna connector
- Antenna:
- U.FL/IPEX antenna connector for LoRa
## Features
- Built in 0.96 inch OLED display
- User and Reset switches
- User and Reset Buttons
- No GPS
## Resources
@ -106,64 +50,168 @@ Not recommended because of design issues! Support is being phased out. Use V3 in
</TabItem>
<TabItem value="v3">
- **MCU**
- ESP32-S3 (WiFi & Bluetooth)
- **LoRa Transceiver**
- Semtech SX126x
- **Frequency options**
- 868 MHz
- 915 MHz
- **Connectors**
- USB-C
- Antenna: U.FL antenna connector
:::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:**
- 433 MHz
- 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
<!-- trunk-ignore(markdownlint/MD024) -->
## Features
- Built in 0.96 inch OLED display
- User and Reset switches
- User and Reset Buttons
- No GPS
### Pin Map
![HTIT-WSL_V3_PIN_MAP](/img/hardware/HTIT-WB32LA(F)_V3.png)
Image Source: [Heltec](https://resource.heltec.cn/download/WiFi_LoRa32_V3/HTIT-WB32LA(F)_V3.png)
<!-- trunk-ignore(markdownlint/MD024) -->
## Resources
- Firmware file: `firmware-heltec-v3-X.X.X.xxxxxxx.bin`
- Purchase link: [AliExpress](https://www.aliexpress.com/item/1005004970848837.html)
- Purchase link: [Heltec](https://heltec.org/project/wifi-lora-32-v3/)
- Purchase link: [AliExpress](https://www.aliexpress.us/item/3256805256690400.html)
</TabItem>
<TabItem value="Wireless Stick Lite V3">
- **MCU**
- ESP32-S3 (WiFi & Bluetooth)
- **LoRa Transceiver**
- Semtech SX126x
- **Frequency options**
- 433 MHz
- 868 MHz
- 915 MHz
- **Connectors**
- USB-C
- Antenna: IPEX/u.FL antenna connector
:::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:**
- 433 MHz
- 470 - 510 MHz
- 863 - 870 MHz
- 902 - 928 MHz
- **Connectors:**
- USB-C
- Antenna:
- Dedicated 2.4 GHz stamped metal antenna for WiFi/Bluetooth
- U.FL/IPEX antenna connector for LoRa
<!-- trunk-ignore(markdownlint/MD024) -->
## Features
- No display.
- User and Reset switches.
- Additional GPIO availability.
- No GPS.
- User and Reset Buttons
- Additional GPIO availability
- No GPS
### Meshtastic I2C Definitions
- SCL: GPIO47
- SDA: GPIO48
<!-- trunk-ignore(markdownlint/MD024) -->
### Pin Map
![HTIT-WSL_V3_PIN_MAP](/img/hardware/HTIT-WSL_V3_PIN_MAP.png)
Image Source: [Heltec](https://resource.heltec.cn/download/Wireless_Stick_Lite_V3/HTIT-WSL_V3.png)
<!-- trunk-ignore(markdownlint/MD024) -->
## Resources
- Firmware file: `firmware-heltec-wsl-v3-X.X.X.xxxxxxx.bin`
- Purchase link: [AliExpress](https://www.aliexpress.com/item/1005004839521502.html)
- Purchase link: [Heltec](https://heltec.org/project/wireless-stick-lite-v2/)
- Purchase link: [AliExpress](https://www.aliexpress.us/item/3256805256996507.html)
</TabItem>
<TabItem value="tracker">
:::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
<!-- trunk-ignore(markdownlint/MD024) -->
## Features
- Onboard 0.96-inch LCD display
- User and Reset Buttons
<!-- trunk-ignore(markdownlint/MD024) -->
## Pin Map
![HT-Tracker_V1 Pin Map](/img/hardware/HT-Tracker_V1_Pin_Map.png)
Image Source: [Heltec](https://heltec.org/project/wireless-tracker/)
<!-- trunk-ignore(markdownlint/MD024) -->
## Resources
- Firmware file: `firmware-heltec-wireless-tracker-X.X.X.xxxxxxx.bin`
- Purchase link: [Heltec](https://heltec.org/project/wireless-tracker/)
- Purchase link: [AliExpress](https://www.aliexpress.us/item/3256805495189423.html)
</TabItem>
<TabItem value="paper">
:::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:
- U.FL/IPEX antenna connector for LoRa
- Integrated 2.4 GHz PCB antenna
<!-- trunk-ignore(markdownlint/MD024) -->
## Features
- Onboard 2.13-inch black and white E-Ink display screen
- User and Reset switches
- No GPS
<!-- trunk-ignore(markdownlint/MD024) -->
## Resources
- Firmware file: `firmware-heltec-wireless-paper-X.X.X.xxxxxxx.bin`
- Purchase link: [Heltec](https://heltec.org/project/wireless-paper/)
- Purchase link: [AliExpress](https://www.aliexpress.us/item/3256805461611876.html)
</TabItem>
</Tabs>

4
docs/hardware/devices/lora/index.mdx
View file

@ -2,7 +2,7 @@
id: lora
title: LILYGO® TTGO Lora Devices
sidebar_label: LILYGO® Lora
sidebar_position: 3
sidebar_position: 4
---
import Tabs from "@theme/Tabs";
@ -84,7 +84,6 @@ This board is still in production but for various reasons not recommended for ne
- Firmware file: `firmware-tlora_v1_3-X.X.X.xxxxxxx.bin`
- Purchase link: [AliExpress](https://www.aliexpress.com/item/4000628100802.html)
- US Distributor - Purchase link: [Rokland](https://store.rokland.com/products/lilygo-lora-v1-3-esp32-sx1276-915mhz-wifi-wireless-bluetooth-module-0-96-inch-oled-screen-support-arduino-development-board-q312?ref=8Bb2mUO5i-jKwt)
![LILYGO® TTGO Lora V1.3](/img/hardware/lora-v1.3.png)
![LILYGO® TTGO Lora V1.3 pin map](/img/hardware/lora-v1.3_pinmap.webp)
@ -190,7 +189,6 @@ Early versions of some of these boards contained the wrong component in the LiPo
## Resources
- Firmware file: `firmware-tlora-v2-1-1.8-X.X.X.xxxxxxx.bin`
- Purchase link: [Banggood](https://www.banggood.com/LILYGO-LORA-H570-V1_8-SX1280-ESP32-2_4G-Smart-WiFi-bluetooth-Wireless-Module-0_96inch-OLED-Display-Development-Board-with-Antenna-Type-C-p-1969395.html)
![TTGO Lora V2.1-1.8](/img/hardware/lora-v2.1-1.8.jpg)

34
docs/hardware/devices/nano-g1-explorer/buttons.mdx
View file

@ -1,34 +0,0 @@
---
id: buttons
title: Hardware Buttons
sidebar_label: Buttons
sidebar_position: 1
---
import { power } from "@heroicons/react/24/solid";
import { information_circle } from "@heroicons/react/24/solid";
import { envelope_open } from "@heroicons/react/24/solid";
import { map_pin } from "@heroicons/react/24/solid";
import { bell } from "@heroicons/react/24/solid";
## Functionality
### Buttons
- **User/Program Button:**
- **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.
- **Message Read Button:**
- **Single press:** Clears the New Message LED.
### Switches
- **Power:**
- **Toggle Up:** Turns on the device.
- **Toggle Down:** Turns off the device.
- **Location Pin:** Toggles GPS module into operating and lower power modes.
- **Toggle Up:** Sets GPS to operating mode.
- **Toggle Down:** Sets GPS to low power mode.
- **Bell:**
- **Toggle Up:** Selects Buzzer for Enhanced Message Notification Circuit.
- **Toggle Down:** Selects LED for Enhanced Message Notification Circuit.

45
docs/hardware/devices/nano-g1-explorer/index.mdx
View file

@ -1,45 +0,0 @@
---
id: nano-g1-explorer
title: Nano G1 Explorer
sidebar_label: Nano G1 Explorer
sidebar_position: 6
---
The Nano G1 Explorer, powered by Meshtastic, is a significant upgrade from the Nano G1. It incorporates the latest RF technologies from B&Q Consulting, featuring a new internal wide-band LoRa antenna that can support frequencies ranging from 815 MHz to 940 MHz. With this new antenna, combined with an optimized wide-band LoRa RF frontend circuit, the Nano G1 Explorer is capable of working with the majority of LoRa frequency bands worldwide without the need for antenna changes. The device's design also takes into account the potential impact of the human body on its antenna performance, ensuring optimal RF performance even when carried in a pocket.
### Specifications
- **MCU:**
- ESP32 WROOM (WiFi & Bluetooth)
- Bluetooth 4.2
- **LoRa Transceiver:**
- Semtech SX1262
- **Frequency Options:**
- _US (902.0Mhz to 928.0Mhz), EU_868 (869.4Mhz to 869.65Mhz), JP (920.8Mhz to 927.8Mhz), ANZ (915.0Mhz to 928.0Mhz), RU (868.7Mhz to 869.2Mhz), KR (920.0Mhz to 923.0Mhz), TW (920.0Mhz to 925.0Mhz), IN (865.0Mhz to 867.0Mhz), NZ_865 (864.0Mhz to 868.0Mhz), TH (920.0Mhz to 925.0Mhz), UA_868 (868.0Mhz to 868.6Mhz)._
- **Navigation Module:**
- ATGM336H-5N-71 (Supports GPS, BDS and GLONASS)
- **Antenna:**
- New internal wide-band antenna with optimized wide-band LoRa RF frontend circuit.
- **Connectors:**
- USB-C
### Features
- Meshtastic pre-installed.
- New internal GPS antenna that significantly reduces GPS lock time compared to the Nano G1. Additionally, the GPS module can be set to a low-power mode with the GPS physical switch.
- Integrated enhanced message notification circuit for LED or Buzzer, configurable via physical switches.
- Physical power switch to easily turn the device on/off.
- Replaceable 1.3" OLED screen with a FPC connector.
- Internal Li-Polymer Battery Charger. _(An optional 3.7V 603450 JST 1.25mm Rechargeable Li-Polymer Battery can also be installed.)_
- Buck-boost converter to provide stable 3.3V to the system even in the event the Li-Polymer battery voltage drops to as low as 2.5V. Supply voltage stability is very important to ensure that the performance of RF circuits meets design expectations.
### Resources
- Firmware file: `firmware-nano-g1-explorer-x.x.x.bin`
- Official Purchase Links:
- [Official Store](https://shop.uniteng.com/product/meshtastic-mesh-device-nano-edition/)
- [Official Tindie Store](https://www.tindie.com/products/neilhao/meshtastic-mesh-device-nano-g1-explorer/)
Further information on the Nano G1 can be found on [Unit Engineering's Wiki](https://wiki.uniteng.com/en/meshtastic/nano-g1-explorer).
![Nano G1 Explorer](/img/hardware/nano_g1_explorer.jpeg)

12
docs/hardware/devices/nano-g1/buttons.mdx
View file

@ -1,12 +0,0 @@
---
id: buttons
title: Hardware Buttons
sidebar_label: Buttons
sidebar_position: 1
---
## Functionality
- **User/Program Button:**
- **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.

41
docs/hardware/devices/nano-g1/index.mdx
View file

@ -1,41 +0,0 @@
---
id: nano-g1
title: Nano G1 device
sidebar_label: Nano G1
sidebar_position: 5
---
The Nano G1 is the first dedicated hardware device to be designed from scratch purely for Meshtastic by Neil Hao. It has been designed to be small and compact with the inclusion of a high quality internal PCB antenna.
### Specifications
- **MCU**
- ESP32 WROOM (WiFi & Bluetooth)
- Bluetooth 4.2
- **LoRa Transceiver**
- Semtech SX1276
- Additional ultra-low noise amplifier to improve LoRa receiver sensitivity
- **Frequency options**
- US-915 MHz
- **Navigation Module**
- ATGM336H-5N-71 (Supports GPS, BDS and GLONASS)
- **Antenna**
- Built in 915Mhz Lora PCB Antenna (VSWR <=1.5 @ 915 MHz)
- **Connectors**
- USB-C
### Features
- Meshtastic pre-installed
- User button
- 1.3 inch OLED screen
- Buzzer
### Resources
- Firmware file: `firmware-nano-g1-1.x.x.bin`
- [Purchase link](https://www.tindie.com/products/neilhao/meshtastic-mesh-device-nano-edition/)
Further information on the Nano G1 can be found on [Unit Engineering's Wiki](https://uniteng.com/wiki/doku.php?id=meshtastic:nano).
![Nano G1](/img/hardware/nano-g1-front.jpg)

127
docs/hardware/devices/rak/core-modules.mdx
View file

@ -15,27 +15,26 @@ groupId="rakcore"
defaultValue="RAK4631"
values={[
{label: 'RAK4631', value: 'RAK4631'},
{label: 'RAK11200', value: 'RAK11200'}
{label: 'RAK11200', value: 'RAK11200'},
{label: 'RAK11310', value: 'RAK11310'}
]}>
<TabItem value="RAK4631">
### RAK4631
## RAK4631 - nRF52
:::info
Please be aware of the difference between the RAK4631 (Arduino bootloader) and the RAK4631-R (RUI3 bootloader). Meshtastic requires the Arduino bootloader. If you have a RAK4631-R, please see the [instructions for converting the bootloader](/docs/getting-started/flashing-firmware/nrf52/convert-rak4631r).
:::
- [RAK4631](https://store.rakwireless.com/products/rak4631-lpwan-node?variant=37505443856582)
- RAK4631
- **MCU**
- nRF52840
- Bluetooth BLE 5.0
- Very low power consumption
- **Meshtastic Firmware**
- [`firmware-rak4631-2.X.X.xxxxxxx.uf2`](/downloads)
- **LoRa transceiver**
- **LoRa Transceiver:**
- SX1262
- **Frequency Options**
- **Frequency Options:**
- 433 MHz
- 470 MHz
- 799 MHz
@ -44,12 +43,16 @@ Please be aware of the difference between the RAK4631 (Arduino bootloader) and t
- 915 MHz
- 920 MHz
- 923 MHz
- **Connectors**
- U.FL antenna
- **Connectors:**
- U.FL/IPEX antenna connector for LoRa
Further information on the RAK4631 can be found on the [RAK Documentation Center](https://docs.rakwireless.com/Product-Categories/WisBlock/RAK4631/Overview/#product-description).
### RAK4631 Resources
US Distributor - Purchase link: [Rokland - US915 Mhz](https://store.rokland.com/products/rak-wireless-rak4631-nordic-nrf52840-ble-core-module-for-lorawan-with-lora-sx1262)
- Firmware file: `firmware-rak4631-X.X.X.xxxxxxx.uf2`
- Further information on the RAK4631 can be found on the [RAK Documentation Center](https://docs.rakwireless.com/Product-Categories/WisBlock/RAK4631/Overview/#product-description).
- US Distributor - Purchase link: [Rokland - US915 Mhz](https://store.rokland.com/products/rak-wireless-rak4631-nordic-nrf52840-ble-core-module-for-lorawan-with-lora-sx1262)
- Purchase Link: [RAK Wireless Store](https://store.rakwireless.com/products/rak4631-lpwan-node?variant=37505443856582)
- Purchase Link: [RAK Wireless Aliexpress](https://www.aliexpress.us/item/3256801470104151.html)
<img
alt="RAK4631 Core Module"
@ -57,44 +60,61 @@ US Distributor - Purchase link: [Rokland - US915 Mhz](https://store.rokland.com/
style={{ zoom: "50%" }}
/>
### GPIO
:::caution Note
There is no usable GPIO pin on any RAK base board except the 'big' baseboard RAK19001 without adding a RAK13002 IO module or a third party IO sensor breakout.
:::
The RAK4631 uses symbolic labels for its I/O Pins on the module and baseboard silk screens. The following table shows the mapping of the RAK4631 GPIO pins to the corresponding Arduino pins and the MCU Port numbers.
| RAK Pin | nRF52840 Pin | Arduino GPIO | Remark |
| ------- | ------------ | ------------ | ----------------------------------------------------------------------------------------------------- |
| IO1 | P0.17 | 17 | used to toggle power to peripheral modules using 3v3_S power rail, not available for user application |
| IO2 | P1.02 | 34 | used to power all peripheral modules, not available for user application |
| IO3 | P0.21 | 21 |
| IO4 | P0.04 | 4 |
| IO5 | P0.09 | 9 | The 'User Button' is mapped here. |
| IO6 | P0.10 | 10 |
| IO7 | P0.28 | 28 |
| SW1 | P0.01 | 1 |
| A0 | P0.04/AIN2 | A2 |
| A1 | P0.31/AIN7 | A7 |
| SPI_CS | P0.26 | 26 |
When configuring GPIO pins in your device settings, the Arduino GPIO numbers should be used.
```shell title="Example"
meshtastic --set external_notification.output 10
```
This will use IO6 on a RAK4631
</TabItem>
<TabItem value="RAK11200">
### RAK11200 / RAK13300
## RAK11200 - ESP32
:::caution Note
Only supported on the RAK5005-O / RAK19007 and the RAK19001 base board.
:::info
Only supported on the RAK5005-O / RAK19007 and the RAK19001 base boards.
:::
The RAK11200 does not contain a LoRa transceiver, and thus needs to be added separately in the form of the [RAK13300 LPWAN module](https://store.rakwireless.com/products/rak13300-wisblock-lpwan). This occupies the IO Port of the base board.
- [RAK11200](https://store.rakwireless.com/products/wiscore-esp32-module-rak11200)
- **MCU**
- RAK11200
- **MCU:**
- ESP32-WROVER
- Bluetooth 4.2
- WiFi 802.11 b/g/n
- High power consumption (relative to nRF52)
- **Meshtastic Firmware**
- [`firmware-rak11200-2.X.X.xxxxxx.bin`](/downloads)
Further information on the RAK11200 can be found on the [RAK Documentation Center](https://docs.rakwireless.com/Product-Categories/WisBlock/RAK11200/Overview/#product-description).
### RAK11200 Resources
- [RAK13300](https://store.rakwireless.com/products/rak13300-wisblock-lpwan)
- **LoRa transceiver**
- SX1262
- **Frequency Options**
- 433 MHz
- 470 MHz
- 864 MHz
- 865 MHz
- 868 MHz
- 915 MHz
- 920 MHz
- 923 MHz
- **Connectors**
- U.FL antenna
Further information on the RAK13300 can be found on the [RAK Documentation Center](https://docs.rakwireless.com/Product-Categories/WisBlock/RAK13300/Overview/#product-description).
- Firmware file: `firmware-rak11200-X.X.X.xxxxxxx.bin`
- Further information on the RAK11200 can be found on the [RAK Documentation Center](https://docs.rakwireless.com/Product-Categories/WisBlock/RAK11200/Overview/#product-description).
- Purchase Link: [RAK Wireless Store](https://store.rakwireless.com/products/wiscore-esp32-module-rak11200)
- Purchase Link: [RAK Wireless Aliexpress](https://www.aliexpress.us/item/3256802312474717.html)
<img
alt="RAK4631 5005 11200"
@ -102,5 +122,42 @@ Further information on the RAK13300 can be found on the [RAK Documentation Cente
style={{ zoom: "50%" }}
/>
</TabItem>
<TabItem value="RAK11310">
## RAK11310 - RP2040
:::info
**Please note, this core module does NOT include BLE/WiFi.**
:::
- **MCU:**
- Raspberry Pi RP2040
- Dual M0+ Core
- 133MHz CPU Clock
- **LoRa Transceiver:**
- SX1262
- **Frequency Options:**
- 433 MHz
- 470 MHz
- 864 MHz
- 865 MHz
- 868 MHz
- 915 MHz
- 920 MHz
- 923 MHz
- **Connectors:**
- U.FL/IPEX antenna connector for LoRa
### RAK11310 Resources
- Firmware file: `firmware-rak11310-X.X.X.xxxxxxx.uf2`
- Further information on the RAK11310 can be found on the [RAK Documentation Center](https://docs.rakwireless.com/Product-Categories/WisBlock/RAK11310/Overview/#product-description).
- Purchase Link: [RAK Wireless Store](https://store.rakwireless.com/products/rak11310-wisblock-lpwan-module)
- Purchase Link: [RAK Wireless Aliexpress](https://www.aliexpress.us/item/3256803225175784.html)
</TabItem>
</Tabs>

2
docs/hardware/devices/rak/index.mdx
View file

@ -18,7 +18,7 @@ If you wish to purchase parts separately, you will need a [WisBlock Base Board](
You can optionally purchase peripherals such as a GPS module, Screen, Sensor, or other various modules.
Please see the RAK documentation for the correct way to connect your hardware to ensure that you do not damage the device. There is currently no pin required to pair RAK devices via BLE.
Please see the RAK documentation for the correct way to connect your hardware to the baseboard to ensure that you do not damage the device.
## Resources

2
docs/hardware/devices/rak/screens.mdx
View file

@ -43,7 +43,7 @@ The [RAK1400 EPD module](https://store.rakwireless.com/products/wisblock-epd-mod
- Resolution 212 x 104 pixels
- Occupies the IO Port of a Wisblock Base
- Firmware for 5005 with RAK14000 e-paper: [`firmware-rak4631_eink-1.3.x.uf2`](/downloads)
- Firmware for 5005 with RAK14000 e-paper: [`firmware-rak4631_eink-X.X.X.xxxxxxx.uf2`](/downloads)
<img
alt="RAK4631 5005 14000"

50
docs/hardware/devices/raspberry-pi/index.mdx Normal file
View file

@ -0,0 +1,50 @@
---
id: raspberry-pi
title: Raspberry Pi Pico
sidebar_label: Raspberry Pi Pico
sidebar_position: 8
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The Raspberry Pi Pico series is a range of tiny, fast, and versatile boards built using RP2040, the flagship microcontroller chip designed by Raspberry Pi in the UK.
:::info
Only the Pico W has WiFi/BLE capabilities. However, Meshtastic does not currently support the Pico W's WiFi/BLE
:::
### Pico
- **MCU:**
- Raspberry Pi RP2040
- Dual M0+ Core
- 133MHz CPU Clock
- **Connectors (On Pico):**
- Micro-USB on Pico
:::note
Please be aware that the Raspberry Pi Pico must be used in combination with a [Waveshare LoRa Module](https://www.waveshare.com/product/raspberry-pi/boards-kits/raspberry-pi-pico-cat/pico-lora-sx1262-868m.htm), which provides the necessary SX1262 LoRa radio. Please ensure to select the correct frequency for your region.
:::
- **LoRa Transceiver (On LoRa Module):**
- SX1262
- **Frequency Options:**
- 410 - 525 MHz
- 863 - 870 MHz
- 902 - 930 MHz
- **Connectors (On LoRa Module):**
- U.FL/IPEX antenna connector for LoRa
- 1.25mm 2-Pin JST for battery
### Pico Resources
- Firmware file:`firmware-pico-X.X.X.xxxxxxx.uf2`
- [Offical Website for the Raspberry Pi Pico](https://www.raspberrypi.com/products/raspberry-pi-pico/), including official reseller links.

14
docs/hardware/devices/raspberry-pi/peripherals.mdx Normal file
View file

@ -0,0 +1,14 @@
---
id: peripherals
title: Supported Peripherals
sidebar_label: Peripherals
sidebar_position: 1
---
## I<sup>2</sup>C peripherals
I<sup>2</sup>C peripherals like OLED Displays (e.g. SSD1306 or SH1106) and keyboards (e.g. CardKB) can be connected to GPIO pins 4 (SDA) and 5 (SCL), which will be recognized on boot. Note that for keyboard input, the [Canned Message Module](/docs/configuration/module/canned-message) has to be enabled and the [input source](/docs/configuration/module/canned-message#input-source) should be specified.
## External device using Serial Module
For connecting an external device via the [Serial Module](/docs/configuration/module/serial), it's recommended to use GPIO pins 8 (`serial.txd`) and 9 (`serial.rxd`).

10
docs/hardware/devices/station-g1/index.mdx
View file

@ -2,7 +2,7 @@
id: station-g1
title: Station G1 device
sidebar_label: Station G1
sidebar_position: 4
sidebar_position: 6
---
The Station G1 is the second dedicated hardware device to be designed from scratch purely for Meshtastic Licensed (HAM) Operation by Neil Hao. It has been designed to be small and compact with the inclusion of 35dBm high power PA.
@ -35,8 +35,12 @@ The Station G1 is the second dedicated hardware device to be designed from scrat
### Resources
- Firmware file: `firmware-station-g1-1.x.x.bin`
- [Purchase link](https://www.tindie.com/products/neilhao/meshtastic-mesh-device-station-edition/)
- Firmware file: `firmware-station-g1-X.X.X.xxxxxxx.bin`
- [Official Store](https://shop.uniteng.com/product/meshtastic-mesh-device-station-edition/)
- [Official Tindie Store](https://www.tindie.com/products/neilhao/meshtastic-mesh-device-station-edition/)
Further information on the Station G1 can be found on [Unit Engineering's Wiki](https://uniteng.com/wiki/doku.php?id=meshtastic:station).

85
docs/hardware/devices/tbeam/index.mdx
View file

@ -8,7 +8,7 @@ sidebar_position: 2
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
All T-beam models have an 18650 size battery holder on the rear of the device. This is designed to the original specification of the 18650 and only fits unprotected flat top 18650 cells. Button top and protected cells are typically longer than 65mm, often approaching 70mm.
All T-beam models (with the exception of the S3-Core) have an 18650 size battery holder on the rear of the device. This is designed to the original specification of the 18650 and only fits unprotected flat top 18650 cells. Button top and protected cells are typically longer than 65mm, often approaching 70mm.
Further information on the LILYGO® T-Beam devices can be found on LILYGO®'s [GitHub page](https://github.com/Xinyuan-LilyGO/LilyGo-LoRa-Series).
@ -19,7 +19,9 @@ values={[
{label: 'T-Beam v0.7', value:'0.7'},
{label: 'T-Beam v1.1', value: '1.1'},
{label: 'T-Beam with M8N', value: 'm8n'},
{label: 'T-Beam with M8N & SX1262', value: 'sx1262'}
{label: 'T-Beam with M8N & SX1262', value: 'sx1262'},
{label: 'T-Beam S3-Core', value: 's3core'},
{label: 'T-Beam Supreme', value: 'supreme'}
]}>
<TabItem value="0.7">
@ -75,12 +77,14 @@ This is an earlier version of the T-Beam board. Due to changes in the design thi
- Micro USB
- Antenna: SMA antenna connector
<!-- trunk-ignore(markdownlint/MD024) -->
## Features
- Meshtastic preinstalled
- Power, Program and Reset switches
- **Comes with 0.96 inch OLED display** (soldering required to assemble)
<!-- trunk-ignore(markdownlint/MD024) -->
## Resources
- Firmware file: `firmware-tbeam-X.X.X.xxxxxxx.bin`
@ -109,12 +113,14 @@ This is an earlier version of the T-Beam board. Due to changes in the design thi
- Micro USB
- Antenna: U.FL antenna connector
<!-- trunk-ignore(markdownlint/MD024) -->
## Features
- Meshtastic preinstalled
- Power, Program and Reset switches
- Screen sold separately
<!-- trunk-ignore(markdownlint/MD024) -->
## Resources
- Firmware file: `firmware-tbeam-X.X.X.xxxxxxx.bin`
@ -141,12 +147,14 @@ This is an earlier version of the T-Beam board. Due to changes in the design thi
- Micro USB
- Antenna: U.FL antenna connector
<!-- trunk-ignore(markdownlint/MD024) -->
## Features
- Meshtastic preinstalled
- Power, Program and Reset switches
- Screen sold separately
<!-- trunk-ignore(markdownlint/MD024) -->
## Resources
- Firmware file: `firmware-tbeam-X.X.X.xxxxxxx.bin`
@ -156,4 +164,77 @@ This is an earlier version of the T-Beam board. Due to changes in the design thi
![T-Beam M8N & SX1262](/img/hardware/t-beam-sx1262.png)
</TabItem>
<TabItem value = "s3core">
- **MCU**
- ESP32-S3 (WiFi & Bluetooth 5LE)
- **LoRa Transceiver**
- **Semtech SX1262** (improved performance)
- **Frequency options**
- 433 MHz
- 868 MHz
- 915 MHz
- **Navigation Module**
- **NEO-M10S - GNSS receiver (supports GPS, GLONASS, Galileo, BeiDou)** (better GPS sensitivity)
- **Quectel L76K - (supports GPS, Beidou, GLONASS)** (lower price)
- **Connectors**
- USB-C
- Antenna: U.FL antenna connector
<!-- trunk-ignore(markdownlint/MD024) -->
## Features
- SoftRF preinstalled (flashing to Meshtastic required)
- Boot and Reset switches
- Can be used standalone without 'Supreme' daughterboard in a headless configuration
<!-- trunk-ignore(markdownlint/MD024) -->
## Resources
- Firmware file: `firmware-tbeam-s3-core-X.X.X.xxxxxxx.bin`
- Purchase Link: [AliExpress](https://www.aliexpress.com/item/1005005418286231.html)
![T-Beam S3-Core](/img/hardware/T-BEAM-S3Core.jpg)
</TabItem>
<TabItem value = "supreme">
- **MCU**
- ESP32-S3 (WiFi & Bluetooth 5LE)
- **LoRa Transceiver**
- **Semtech SX1262** (improved performance)
- **Frequency options**
- 433 MHz
- 868 MHz
- 915 MHz
- **Navigation Module**
- **NEO-M10S - GNSS receiver (supports GPS, GLONASS, Galileo, BeiDou)** (better GPS sensitivity)
- **Quectel L76K - (supports GPS, Beidou, GLONASS)** (lower price)
- **Connectors**
- USB-C
- Antenna: U.FL antenna connector
<!-- trunk-ignore(markdownlint/MD024) -->
## Features
- Includes T-Beam S3-Core Module
- SoftRF preinstalled (flashing to Meshtastic required)
- Power, Boot and Reset switches
- 1.3" OLED included
- BME280 Air pressure sensor
- QMI8658 IMU
- QMC6310 Magnetometer
- PCF8563 RTC
- Micro-SD reader (not implemented in Meshtastic)
<!-- trunk-ignore(markdownlint/MD024) -->
## Resources
- Firmware file: `firmware-tbeam-s3-core-X.X.X.xxxxxxx.bin`
- Purchase Link: [AliExpress](https://www.aliexpress.com/item/1005005418286231.html)
![T-Beam Supreme](/img/hardware/T-BEAM-S3-Supreme.jpg)
</TabItem>
</Tabs>

2
docs/hardware/devices/techo/index.mdx
View file

@ -2,7 +2,7 @@
id: techo
title: LILYGO® TTGO T-Echo devices
sidebar_label: LILYGO® T-Echo
sidebar_position: 2
sidebar_position: 3
---
The T-Echo is the latest device to be release by LILYGO® supporting a low power consumption micro-controller.

16
docs/legal/trademark-grants.mdx
View file

@ -8,3 +8,19 @@ sidebar_label: Trademark Grants
- Details: Meshtastic.pt is a fan page created before the trademark usage guidelines were authored. Agreement with Sérgio Matos that meshtastic.pt may continue use of meshtastic in domain name provided they stay non commercial and maintain that they are non-official. The grant is revokable at any time for any reason.
- Grant: https://meshbrasil.com
- Details: Meshbrasil.com is an online shop for Meshtastic powered devices and accessories which carry the "Powered by Meshtastic" logo. The use of the Meshtastic Logo and Trademarks does not imply Meshbrasil.com is sponsored or endorsed by Meshtastic. Meshbrasil.com also agrees to maintain compliance with the Meshtastic Legal requirements. This grant is revokable at any time for any reason.
- Grant: [Garth Vander Houwen](https://garthvh.com/store/)
- Details: Garth is a member of the Meshtastic LLC, is the developer of the iOS app and runs an online shop for Meshtastic powered devices which carry the "Powered by Meshtastic" and "Chirpy" logo. The use of the Meshtastic Logo and Trademarks does not imply Garth is sponsored or endorsed by Meshtastic. Garth also agrees to maintain compliance with the Meshtastic Legal requirements. This grant is revokable at any time for any reason.
- Grant: [Anthony (Tony) Good](https://quantumshadow3d.etsy.com)
- Details: Tony is an admin and contributer of computer aided design (CAD)/3D designs primarily for device enclosures and accessories, and runs an online shop for Meshtastic powered devices which carry the "Meshtastic" and "M" logos. The use of the Meshtastic Logo and Trademarks does not imply Tony is sponsored or endorsed by Meshtastic. Tony also agrees to maintain compliance with the Meshtastic Legal requirements. This grant is revokable at any time for any reason.
- Grant: http://k9rocket.tech
- Details: K9 Rocket Technologies is an open technology development company selling and implementing Meshtastic-powered devices. The devices and their respective promotional content carry the "Powered by Meshtastic", "Meshtastic", & "M" logos. The use of the Meshtastic Logo and Trademarks does not imply K9 Rocket Technologies is sponsored or endorsed by Meshtastic. K9 Rocket Technologies also agrees to maintain compliance with the Meshtastic Legal requirements. This grant is revokable at any time for any reason
- Grant: Ben Lipsey
- Details: Ben Lipsey is a Meshtastic Contributor and Promotional Materials Distributor. Promotional materials carry the "Meshtastic" and "M" logos. Materials also carry the Meshtastic.org URL. The use of the Meshtastic Logo and Trademarks does not imply Ben Lipsey is sponsored or endorsed by Meshtastic. Ben Lipsey also agrees to maintain compliance with the Meshtastic Legal requirements. This grant is revokable at any time for any reason.
- Grant: Mark Birss
- Details: Mark Birss is a Meshtastic contributor/developer of DIY devices that carry the "Meshtastic" , Meshtastic.org URL and "M" logos. The use of the Meshtastic Logo and Trademarks does not imply Mark Birss is sponsored or endorsed by Meshtastic. Mark Birss also agrees to maintain compliance with the Meshtastic Legal requirements. This grant is revokable at any time for any reason.
- Grant [Paul Carney](https://www.etsy.com/shop/3Dsafe)
- Details: Paul primarily designs enclosures and assembles complete Meshtastic Radios for sale using modules from TTGO, Heltec and RAK. He runs an online shop for Meshtastic powered devices which carry the "Meshtastic" and M logos. The use of the Meshtastic Logo and Trademarks does not imply Paul is sponsored or endorsed by Meshtastic. Paul also agrees to maintain compliance with the Meshtastic Legal requirements. This grant is revokable at any time for any reason.
- Grant: [Keith Monaghan](http://voltaicenclosures.com/)
- Details: Keith is a contributer of computer aided design (CAD)/3D designs primarily for device enclosures and accessories, and runs an online shop for Meshtastic powered devices which carry the "Meshtastic" and "M" logos. The use of the Meshtastic Logo and Trademarks does not imply Keith is sponsored or endorsed by Meshtastic. Keith also agrees to maintain compliance with the Meshtastic Legal requirements. This grant is revokable at any time for any reason.
- Grant: [Neil Hao](https://shop.uniteng.com/)
- Details: Neil is a contributer of hardware designs, and runs an online shop for Meshtastic powered devices which carry the "Meshtastic" and "M" logos. The use of the Meshtastic Logo and Trademarks does not imply Neil is sponsored or endorsed by Meshtastic. Neil also agrees to maintain compliance with the Meshtastic Legal requirements. This grant is revokable at any time for any reason.

69
docs/legal/trademark.mdx
View file

@ -16,23 +16,24 @@ Below are the guidelines for use of the Meshtastic Trademarks where, as long as
- the use is not disparaging to Meshtastic or software distributed by Meshtastic.
- the use does not imply sponsorship or endorsement by Meshtastic.
- proper trademark symbols are used in connection with the Meshtastic Trademarks and the trademark attribution statement must appear as explained in Proper Trademark Use
- the Logo Usage Guidelines are strictly observed
- proper trademark symbols are used in connection with the Meshtastic Trademarks and the trademark attribution statement must appear as explained in Proper Trademark Use.
- the Logo Usage Guidelines are strictly observed.
### Noncommercial and community web sites
In the past, community members have inquired whether it is permissible to show support for Meshtastic by:
placing the Meshtastic Trademarks on a personal web site or blog to support open source software
making a page on a social networking web service to support open source software
linking to the Meshtastic website to provide information or show support for open source software
- placing the Meshtastic Trademarks on a personal web site or blog to support open source software.
- making a page on a social networking web service to support open source software.
- linking to the Meshtastic website to provide information or show support for open source software.
The guidelines relating to such usage are set forth in this section.
It is permissible to use the Meshtastic Trademarks on websites to show your support for the open source software, provided that:
- where possible, the design logo hyperlinks to the Meshtastic website, [http://meshtastic.org/](http://meshtastic.org/), or if that is not possible, the site includes a prominent link to the Meshtastic website at [http://meshtastic.org/](http://meshtastic.org/).
- proper trademark symbols are used in connection with the Meshtastic Trademarks and the trademark attribution statement must appear as explained in Proper Trademark Use
- the Logo Usage Guidelines are strictly observed
- proper trademark symbols are used in connection with the Meshtastic Trademarks and the trademark attribution statement must appear as explained in Proper Trademark Use.
- the Logo Usage Guidelines are strictly observed.
- the site indicates clearly that it is not affiliated with or endorsed by Meshtastic; in addition, where possible:
the site must include the text "This site is not affiliated with or endorsed by the Meshtastic project" prominently on any page that includes the Meshtastic Trademarks, and
- if the Meshtastic Trademarks appear in a page header or any area that is designed to be presented on more than one page, the notice must also be designed to be presented on all of those pages as well. (i.e., if the Meshtastic Trademarks appear in a site-wide header, the informational text must appear in that header or an identically site-wide footer.)
@ -43,21 +44,21 @@ It is permissible to use the Meshtastic Trademarks on websites to show your supp
In the past, community members have inquired whether it is permissible to show support for Meshtastic by:
- displaying a link to the Meshtastic website using the Meshtastic Trademarks from a business web site
- displaying the Meshtastic Trademarks as part of a business that utilizes Meshtastic software
- displaying a link to the Meshtastic website using the Meshtastic Trademarks from a business web site.
- displaying the Meshtastic Trademarks as part of a business that utilizes Meshtastic software.
The guidelines relating to such usage are set forth in this section.
It is permissible to use the Meshtastic Trademarks on business web sites, provided that:
- the web site has non-Meshtastic primary branding
- the design logo hyperlinks to the Meshtastic website, [http://meshtastic.org/](http://meshtastic.org/)
- the use does not imply sponsorship or endorsement by Meshtastic
- the use of the Meshtastic Trademarks does not imply an association with nor any form of endorsement by Meshtastic
- proper trademark symbols are used in connection with the Meshtastic Trademarks and the trademark attribution statement must appear as explained in Proper Trademark Use
- the Logo Usage Guidelines are strictly observed
- the site does not use visual styling that could be confusing to viewers or visitors as to whether the site is hosted by or on behalf of Meshtastic
- A copy of the use of the Meshtastic Trademarks is provided to the Trademark Supervisor within seven (7) days of its initial use, for example by sending a URL or other copy of such use
- the web site has non-Meshtastic primary branding.
- the design logo hyperlinks to the Meshtastic website, [http://meshtastic.org/](http://meshtastic.org/).
- the use does not imply sponsorship or endorsement by Meshtastic.
- the use of the Meshtastic Trademarks does not imply an association with nor any form of endorsement by Meshtastic.
- proper trademark symbols are used in connection with the Meshtastic Trademarks and the trademark attribution statement must appear as explained in Proper Trademark Use.
- the Logo Usage Guidelines are strictly observed.
- the site does not use visual styling that could be confusing to viewers or visitors as to whether the site is hosted by or on behalf of Meshtastic.
- a copy of the use of the Meshtastic Trademarks is provided to the Trademark Supervisor within seven (7) days of its initial use, for example by sending a URL or other copy of such use.
### Promotional events
@ -65,11 +66,11 @@ In the past, community members have inquired whether it is permissible to use th
It is permissible to use the Meshtastic Trademarks in such promotional events, provided that:
- the use does not imply sponsorship or endorsement by Meshtastic
- the use of the Meshtastic Trademarks does not imply an association with or endorsement of the event of the goods distributed at such event
- proper trademark symbols are used in connection with the Meshtastic Trademarks and the trademark attribution statement must appear as explained in Proper Trademark Use
- the Logo Usage Guidelines are strictly observed
- A copy of the use of the Meshtastic Trademarks is provided to the Trademark Supervisor within seven (7) days of its initial use, for example by sending a URL or other copy of such use
- the use does not imply sponsorship or endorsement by Meshtastic.
- the use of the Meshtastic Trademarks does not imply an association with or endorsement of the event of the goods distributed at such event.
- proper trademark symbols are used in connection with the Meshtastic Trademarks and the trademark attribution statement must appear as explained in Proper Trademark Use.
- the Logo Usage Guidelines are strictly observed.
- A copy of the use of the Meshtastic Trademarks is provided to the Trademark Supervisor within seven (7) days of its initial use, for example by sending a URL or other copy of such use.
If you would like to make some non-software goods to give away or sell at the event and don't already have a license to do so, see Non-software goods.
@ -77,11 +78,11 @@ If you would like to make some non-software goods to give away or sell at the ev
It is permissible to use the Meshtastic Trademarks in the title and content of a publication, provided that:
- The use is clearly in reference to Meshtastic.
- The use does not imply sponsorship or endorsement of the publication by Meshtastic.
- Proper trademark symbols are used in connection with the Meshtastic Trademarks and the trademark attribution statement must appear as explained in Proper Trademark Use.
- The Logo Usage Guidelines are strictly observed.
- A copy of the use of the Meshtastic Trademarks is provided to the Trademark Supervisor within seven (7) days of its initial use, for example by sending a URL or other copy of such use.
- the use is clearly in reference to Meshtastic.
- the use does not imply sponsorship or endorsement of the publication by Meshtastic.
- proper trademark symbols are used in connection with the Meshtastic Trademarks and the trademark attribution statement must appear as explained in Proper Trademark Use.
- the Logo Usage Guidelines are strictly observed.
- a copy of the use of the Meshtastic Trademarks is provided to the Trademark Supervisor within seven (7) days of its initial use, for example by sending a URL or other copy of such use.
## Usage that Require Prior Written Approval
@ -106,8 +107,8 @@ Community members may request from the Trademark Supervisor designated by the Ad
The following uses of the Meshtastic Trademarks are not approved under any foreseeable circumstances.
- Violations of the Logo Usage Guidelines or Trademark Usage Guidelines
- Any use outside these guidelines not by explicit written permission
- Violations of the Logo Usage Guidelines or Trademark Usage Guidelines.
- Any use outside these guidelines not by explicit written permission.
- Except as set forth herein, Meshtastic retains and reserves all rights to the Meshtastic Trademarks and their use, including the right to modify these guidelines.
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.
@ -137,19 +138,19 @@ Unacceptable: Never using the ® mark for Meshtastic Logo, nor a trademark state
- Never combine your company name with the Meshtastic name or use the Meshtastic name in a way that it could be perceived that Meshtastic and your company have an organizational link such as a joint venture.
- Never use the Meshtastic Trademarks in a disparaging manner or that violates any federal, state, or international law.
Unacceptable: Cartoon character micturating on the Meshtastic Logo, applying Meshtastic Logo outside permitted uses
Unacceptable: Cartoon character micturating on the Meshtastic Logo, applying Meshtastic Logo outside permitted uses.
- Never use terminology that states or implies that Meshtastic assumes any responsibility for the performance of your products and services.
- The Meshtastic Logo must be hyperlinked to [http://meshtastic.org/](http://meshtastic.org/), in contexts where such a hyperlink is technically feasible.
Acceptable: Hyperlinking the Meshtastic Logo where feasible
Acceptable: Hyperlinking the Meshtastic Logo where feasible.
Unacceptable: Not hyperlinking the Meshtastic Logo where feasible
Unacceptable: Not hyperlinking the Meshtastic Logo where feasible.
Except as prohibited by law, the person or entity who is using the Meshtastic Trademark under the terms of these Guidelines ("User") acknowledges that Meshtastic is the sole and exclusive owner of the Meshtastic Trademarks and agrees that it will do nothing inconsistent with such ownership either during the term of such use or afterwards. Specifically, User will take no action that will interfere with or diminish Meshtastic's right in the Meshtastic Trademarks. The User acknowledges that the Meshtastic Trademarks are valid under the applicable law and that User's utilization of the Meshtastic Trademarks will not create any right, title or interest in the Meshtastic Trademarks. The User agrees not to apply or assist any third party to register the Meshtastic Trademarks or a confusingly similar designation anywhere in the world. If any application for registration is or has been filed by or on behalf of User in any country and relates to any mark which, in the reasonable opinion of Meshtastic, is confusingly similar, deceptive or misleading with respect to, or dilutes or any way damages the Meshtastic Trademark, User shall, at Meshtastic's request, abandon all use of such mark, and any registration or application for registration thereof and shall reimburse Meshtastic for all costs and expenses of any oppMeshtastiction or related legal proceeding, including attorneys' fees, instigation by Meshtastic or its authorized representative. Upon the written statement that the User is not using the Meshtastic Trademarks in accordance with the Guidelines, within ten (10) days, User shall modify its use to comply with the Guidelines or cease using the Meshtastic Trademarks.
Except as prohibited by law, the person or entity who is using the Meshtastic Trademark under the terms of these Guidelines ("User") acknowledges that Meshtastic is the sole and exclusive owner of the Meshtastic Trademarks and agrees that it will do nothing inconsistent with such ownership either during the term of such use or afterwards. Specifically, User will take no action that will interfere with or diminish Meshtastic's right in the Meshtastic Trademarks. The User acknowledges that the Meshtastic Trademarks are valid under the applicable law and that User's utilization of the Meshtastic Trademarks will not create any right, title or interest in the Meshtastic Trademarks. The User agrees not to apply or assist any third party to register the Meshtastic Trademarks or a confusingly similar designation anywhere in the world. If any application for registration is or has been filed by or on behalf of User in any country and relates to any mark which, in the reasonable opinion of Meshtastic, is confusingly similar, deceptive or misleading with respect to, or dilutes or any way damages the Meshtastic Trademark, User shall, at Meshtastic's request, abandon all use of such mark, and any registration or application for registration thereof and shall reimburse Meshtastic for all costs and expenses of any opposition or related legal proceeding, including attorneys' fees, instigation by Meshtastic or its authorized representative. Upon the written statement that the User is not using the Meshtastic Trademarks in accordance with the Guidelines, within ten (10) days, User shall modify its use to comply with the Guidelines or cease using the Meshtastic Trademarks.
### Logo Usage Guidelines
The Meshtastic logo is a trademark of Meshtastic LLC. In order to protect and grow the Meshtastic brand, we have a distinguishable logo. When displaying the Meshtastic logo, please follow our standard Trademark Guidelines. Other sizes and resolutions of the logo, some suitable for print, can be found [here](https://github.com/meshtastic/design).
To join the discussion about Meshtastic Trademark policies, and participate in shaping future policy visit the [Meshtastic Discourse](http://meshtastic.discourse.group) or [Meshtastic Discord](https://discord.com/invite/UQJ5QuM7vq).
To join the discussion about Meshtastic Trademark policies, and participate in shaping future policy visit the [Meshtastic Discourse](http://meshtastic.discourse.group) or [Meshtastic Discord](https://discord.com/invite/ktMAKGBnBs).

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

@ -19,12 +19,12 @@ You will need a device with Meshtastic installed to go any further. See the [get
[![Search for devices](/img/android/android-settings-none-c.png)](/img/android/android-settings-none.png)
To find devices to connect via Bluetooth click the button on the bottom right corner.
To find devices to connect via Bluetooth click the "+" button on the bottom right corner.
[![Device available to select](/img/android/android-settings-connect-sm.png)](/img/android/android-settings-connect.png)
1. Select the device name, `Meshtastic_bebc` in this example. (You will see devices within range, so make sure to get the right one.)
2. Before you can connect for the first time, you need to "pair" the devices to allow communication between them. Some devices are pinless, others require entering a PIN shown on the screen.
1. Select the device name, `Meshtastic_769d` in this example. (You will see devices within range, so make sure to get the right one.)
2. Before you can connect for the first time, you need to "pair" the devices to allow communication between them. Some devices are pinless, others require entering a PIN shown on the device screen.
:::note
If the device was flashed without a screen connected, it will automatically default to a pairing PIN of '123456'. If it was booted with a screen once, the config is set to random pin. If you remove the screen afterwards, it stays like this.
Either set it to use the default pin manually, or factory reset it and it will revert to '123456' after the next boot.
@ -43,19 +43,24 @@ The cloud icon at the top right corner indicates if you are connected to a devic
## 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.
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.png)](/img/android/android-settings-mike.png)
### Setup a channel
If you have been sent a QR code or link for Meshtastic, then skip ahead to [Join a Channel](#join-a-channel). Devices have a default channel preconfigured, shown as `#LongSlow-V (Long range / Slow)`. It is OK to use this initially.
If you have been sent a QR code or link for Meshtastic, then skip ahead to [Join a Channel](#join-a-channel). Devices have a default channel preconfigured, shown as `#LongFast-I (Long range / Fast)`. It is OK to use this channel if you want your node to be visible to all Meshtastic users (within range) who are using the default channel.
You can also create a new Channel and share the details with your group. The group is private and only those who have the details can join the group and see the messages. You will need to do this once initially, and then only when you want to change or make a new mesh network group.
The Channel tab allows you to do this. This screen is initially locked so that you don't change it accidentally. Press the lock symbol, and you will be able to edit. First, select the Channel options, as shown here, and chose the most appropriate option:
The Channel tab allows you to create a new private mesh. This screen is initially locked so that you don't change it accidentally. Press the lock symbol, and you will be able to edit. First, select the Channel options, as shown here, and chose the most appropriate option:
[![Changing channel settings](/img/android/android-change-channel-sm.png)](/img/android/android-change-channel.png)
@ -67,7 +72,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.png)](/img/android/android-new-channel.png)
The app will generate a new QR code on the screen, and 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
@ -77,23 +82,11 @@ The app will generate a new QR code on the screen, and this encodes the channel
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".
<details>
<summary>Troubleshooting shared links: Can't "open with Meshtastic".</summary>
<div>
<div>
If you don't see "Meshtastic" as an option to open the file or link with:
<br />
1. Go to Android Settings > Apps > Default apps > Meshtastic > Opening
links
<br />
2. Make sure you have in "links/web address": www.meshtastic.org
<br />
3. If you see the option "Open the supported links", make sure it is
enabled.
<br />
</div>
</div>
</details>
:::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.png)](/img/android/android-accept-channel.png)
@ -112,17 +105,17 @@ You can test changing channels with the QR code shown below.
[![Messages](/img/android/android-messages-sm.png)](/img/android/android-messages.png)
The message window operates like most messaging apps. Note that the `(All) Primary channel` contact is always shown and works as a group chat. Other contacts are for Direct Messaging, or private chat.
The message window operates like most messaging apps. Note that your primary channel i.e. `LongFast` contact is always shown and works as a group chat. Other contacts are for direct messaging, or private group chats.
- Long press contacts or messages for options, like delete.
- Long press a node from the Nodes tab to send Direct Messages.
- Press a node from the Nodes tab to send Direct Messages.
With LoRa (or any radio) there is some uncertainty that the messages 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:
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 of your direct message acknowledged the message.
- 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.
By default there is no long-term store-and-forward of messages, so messages not received during transmission are lost.
@ -131,19 +124,27 @@ By default there is no long-term store-and-forward of messages, so messages not
[![Local Meshtastic network](/img/android/android-nodes-sm.png)](/img/android/android-nodes.png)
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, Lora V2 is the local user, m8n was last heard from 3 minutes ago and is 29m away, and 25C is active and 498m away.
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.
This is a list of network nodes, unnamed nodes are shown as `Unknown a3c9` (where `a3c9` is the last 4 hex digits from the MAC address.)
- Long press a node from the list to send Direct Messages.
- Tap on a node from the list to start Direct Messaging, request a position update, request a [traceroute](/docs/configuration/module/traceroute) or add it to your [Ignore Incoming Array](/docs/configuration/radio/lora#ignore-incoming-array).
- If you have an [Admin Channel](/docs/configuration/remote-admin) enabled on your devices, tapping on the node will also display an option to remotely configure the node.
### View the map
[![Mapping provided by Mapbox](/img/android/android-map-sm.png)](/img/android/android-map.png)
[![Meshtastic Map View](/img/android/android-map-sm.png)](/img/android/android-map.png)
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 against the icon.
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.
The map is provided by [Mapbox](https://docs.mapbox.com/help/how-mapbox-works) (free-tier), and the map data is sourced from [OpenStreetMap OSM](https://www.openstreetmap.org). Mapbox currently requires analytics to be enabled for you to use their mapping system. There is currently no off-line maps (phone needs mobile data or Wifi), although this will be improved in the future. If you don't see the features that you'd expect on the map then head over to [OpenStreetMap OSM](https://www.openstreetmap.org) where you can contribute new data to the map.
[![Map Layers](/img/android/android-map-layers-c.png)](/img/android/android-map-layers.png)
- Clicking the layers icon in the top-right will allow you to select the map type.
### Offline maps
[![Download offline maps](/img/android/android-map-download-c.png)](/img/android/android-map-download.png)
- 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
@ -157,28 +158,39 @@ Pressing the three vertical dots in the top right corner shows the configuration
The debug panel allows you to see all packets sent between the application and the device. This can be useful for debugging purposes.
### Advanced settings
### Radio Configuration
[![Advanced settings](/img/android/android-advanced-settings-c.png)](/img/android/android-advanced-settings.png)
[![Meshtastic configuration options](/img/android/android-radio-configuration-c.png)](/img/android/android-radio-configuration.png)
#### Broadcast position period
This allows you to disable or change the frequency with which your location is broadcast across the mesh. By default, this is set to 900 seconds (15 minutes). The minimum time this can be set for the default channel is 375 seconds, the reasons for which have been [discussed on the forum](https://meshtastic.discourse.group/t/lost-messages-while-testing/2455/19).
#### Device sleep period (now disabled by default & no longer recommended)
ESP32 devices can enter sleep mode to save battery life. During sleep Bluetooth is turned off. This setting allows the length of the sleep mode to be changed from the default 300 seconds (5 minutes). After this time period, they awake to check the phone for any queued messages and then go back to sleep, alternating between sleep and awake states. Receiving a message over LoRa (the LoRa receiver never switches off) or pressing a program button (if there is one on the device) also awakes the device.
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.
### Export rangetest.csv
This allows you to save all your position data with GPS coordinates into a .csv (comma separated value) file on your phone. This feature is similar but independent from the device range test module, and results may differ.
Allows you to save all your network's position data with GPS coordinates into a .csv (comma separated value) file on your phone. This file can be imported into the spreadsheet application of your choice for easy viewing. This feature is similar but independent from the device [range test module](/docs/configuration/module/range-test), and results may differ.
### Theme
[![Meshtastic theme](/img/android/android-settings-theme-c.png)](/img/android/android-settings-theme.png)
This allows you to change between light and dark themes, or to select the system default.
Allows you to change between light and dark themes, or to select the system default.
### Language
Allows you to select a language for the application's user interface.
### Show Introduction
Opens the introduction slideshow.
### Quick chat options
[![Quick Chat](/img/android/android-quick-chat-sm.png)](/img/android/android-quick-chat.png)
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
Clicking this shows the current app version.
Displays the current app version.

1
docs/software/apple/installation.mdx
View file

@ -1,6 +1,7 @@
---
id: installation
title: Apple Application Installation
description: Download on the App Store
sidebar_label: Installation
---

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

@ -11,5 +11,6 @@ Current community projects:
- [ATAK (Android Team Awareness Kit) Forwarder](/docs/software/community/community-atak) - An ATAK plugin for forwarding CoT messages via a hardware layer which supports Meshtastic devices.
- [Meshtasticator (Simulator)](/docs/software/community/community-meshtasticator) - Meshtasticator is a discrete-event and interactive simulator that mimics the radio section of the device software.
- [Meshtastic Web API](/docs/software/community/meshtastic-web-api) - Meshtastic Web API provides a RESTful interface to interact with a Meshtastic node via a serial connection.
Support for these projects should be sought from their respective authors.

26
docs/software/community/meshtastic-web-api.mdx Normal file
View file

@ -0,0 +1,26 @@
---
id: meshtastic-web-api
title: Meshtastic Web API
sidebar_label: Meshtastic Web API
sidebar_position: 3
---
:::note
This is a community project maintained by @bmswens.
Development can be followed on [GitHub](https://github.com/bmswens/Meshtastic-Web-API).
Support should be sought from the respective authors.
:::
## Overview
Meshtastic Web API provides a RESTful interface to interact with a Meshtastic node via a serial connection.
## Links
- [Source](https://github.com/bmswens/Meshtastic-Web-API)
- [API Docs](https://bmswens.github.io/Meshtastic-Web-API/)
- [Installation Instructions](https://github.com/bmswens/Meshtastic-Web-API/wiki/Installation)
- [Supported Services](https://github.com/bmswens/Meshtastic-Web-API/wiki/Supported-Services)
* Mattermost

28
docs/software/integrations/atak-plugin.mdx Normal file
View file

@ -0,0 +1,28 @@
---
id: integrations-atak-plugin
title: ATAK Plugin
sidebar_label: ATAK Plugin
sidebar_position: 2
---
## Official Meshtastic ATAK Plugin
Meshtastic can integrate with ATAK on Android using the [Official ATAK Plugin.](https://github.com/meshtastic/ATAK-Plugin)
### Introduction
The ATAK plugin does not permit any Meshtastic configuration. The plugin does three things:
1. Bind to the IMeshService provided by the Meshtastic Android App in order to send.
2. Intercept all outgoing ATAK CoT via the ATAK "PreSendProcessor" Interface and send them to the IMeshService.
3. Listen for broadcasts from the Meshtastic Android App regarding ATAK_FORWARDER portnum packets.
The current iteration works very well for ATAK CoT that fit within the 200ish byte range (after we shrink via libcotshirnk) because they fit into a single DataPacket.
### Instructions
1. Use the Meshtastic Android App on all party's devices, and ensure they can talk to their local LoRa radio. Confirm they are able to achieve basic text messaging using the App.
2. With the Meshtastic Android App running in the background (to ensure the IMeshService is alive), launch ATAK (with the Meshtastic ATAK-Plugin installed or install it once ATAK is running) and you should observe a green Meshtastic icon in the bottom right. If the icon is red, then the plugin was not able to bind to the IMeshService provided by the Meshtastic Android App. If this is the case, check to ensure the Meshtastic Android App is functioning. The plugin will reconnect after a failed bind without restarting ATAK.
3. ATAK PLI and simple map markers will fit within the "small send" DataPackets. Sending larger CoT such as freestyle map drawings or GeoChats will fragment and take longer to send. Don't try to send a bunch without waiting for the previous one to complete.

62
docs/software/integrations/caltopo.mdx Normal file
View file

@ -0,0 +1,62 @@
---
id: integrations-caltopo
title: CalTopo / SARTopo
sidebar_label: CalTopo / SARTopo
sidebar_position: 1
---
## CalTopo / SARTopo
Meshtastic can integrate with [CalTopo](https://caltopo.com/) Desktop edition quite easily through the product's APRS over serial support functionality.
<object data="https://www.youtube.com/embed/z_51FAPPl34
?autohide=1&autoplay=0" width="100%" height="400"></object>
### Configuring the Meshtastic device
To configure our Meshtastic device for this integration, we have a couple of different options, both of which utilize the [Serial module](/docs/configuration/module/serial):
#### Enabling serial over the device's USB port
```shell title="Serial over USB"
meshtastic --set serial.enabled true --set serial.baud BAUD_9600 --set serial.mode CALTOPO --set serial.override_console_serial_port true
```
#### Enabling serial over an external USB to Serial adapter
```shell title="External serial adapter"
meshtastic --set serial.enabled true --set serial.baud BAUD_9600 --set serial.mode CALTOPO --set serial.txd = 13 --set serial.rxd = 14
```
:::info
Ensure that serial baud rate is set to `9600` on both the Meshtastic device and the CalTopo / SARTopo `topo.properties` configuration
:::
### Setting up CalTopo / SARTopo
To setup CalTopo for Meshtastic integration using the Live Tracking via APRS, refer to the official [documentation](https://training.caltopo.com/all_users/share/live-tracking#aprs).
Example `topo.properties` file configuration for use with Meshtastic:
![topo.properties](/img/software/integrations/caltopo/properties.png)
After starting CalTopo Desktop, NMEA waypoint location sentences should be streamed into the logs from the connected Meshtastic device every 10 seconds:
![CalTopo Logs](/img/software/integrations/caltopo/logs.png)
In the desktop's web UI for your CalTopo map, scroll down and check the **Shared Locations** checkbox under **Realtime Data**. Your nodes should appear on the map as points if they are connected correctly.
![shared-locations](/img/software/integrations/caltopo/local-stations.png)
You can click on one or more of the node points and in the resulting tooltip, click **Record to Map**
![node point](/img/software/integrations/caltopo/click.png)
In the resulting dialog, you can assign attributes such as a label or color to the live track created by the node.
![track](/img/software/integrations/caltopo/track.png)
When you view the shared map on another device or mobile, the nodes should appear there as well now, if both the desktop and mobile device have internet connectivity.
![app](/img/software/integrations/caltopo/app.png)

16
docs/software/integrations/index.mdx Normal file
View file

@ -0,0 +1,16 @@
---
title: Meshtastic Integrations
slug: /software/integrations
sidebar_label: Integrations
sidebar_position: 11
---
The Meshtastic ecosystem is highly extensible and allows easy integration with a number of existing software products and projects.
Current Meshtastic integrations:
- [CalTopo / SARTopo](/docs/software/integrations/integrations-caltopo) - Track Meshtastic nodes in CalTopo and SARTopo.
- [ATAK Plugin](/docs/software/integrations/integrations-atak-plugin) - Official Meshtastic ATAK Plugin for sending CoT to IMeshService in the Meshtastic Android app.
Support for the integrated products should be sought from their respective authors or vendors.

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