mudhorn/meshtastic
1
0
Fork 0
mirror of https://github.com/meshtastic/meshtastic.git synced 2024-11-09 23:24:10 -08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'remotes/origin/master' into i18n

Browse source
This commit is contained in:
Thomas Göttgens 2023-11-16 08:23:29 +01:00
parent d80e4c2684 cf159b9de5
commit 2435e9dfb4
232 changed files with 7984 additions and 9700 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
.github/workflows/ci.yml vendored
View file

@ -21,8 +21,5 @@ jobs:
- name: Install Dependencies
run: pnpm install
- name: Trunk Check
uses: trunk-io/trunk-action@v1
- name: Build Site
run: pnpm build

27
.github/workflows/nightly.yml vendored
View file

@ -1,27 +0,0 @@
name: Nightly
on:
schedule:
- cron: 0 8 * * 1-5
workflow_dispatch: {}
jobs:
trunk_check:
name: Trunk Check Upload
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Setup pnpm
uses: pnpm/action-setup@v2.2.1
with:
version: latest
- name: Install Dependencies
run: pnpm install
- name: Trunk Check
uses: trunk-io/trunk-action@v1
with:
trunk-token: ${{ secrets.TRUNK_TOKEN }}

7
.trunk/.gitignore vendored
View file

@ -1,7 +0,0 @@
*out
*logs
*actions
*notifications
plugins
user_trunk.yaml
user.yaml

10
.trunk/configs/.markdownlint.yaml
View file

@ -1,10 +0,0 @@
# Autoformatter friendly markdownlint config (all formatting rules disabled)
default: true
blank_lines: false
bullet: false
html: false
indentation: false
line_length: false
spaces: false
url: false
whitespace: false

7
.trunk/configs/.shellcheckrc
View file

@ -1,7 +0,0 @@
enable=all
source-path=SCRIPTDIR
disable=SC2154
# If you're having issues with shellcheck following source, disable the errors via:
# disable=SC1090
# disable=SC1091

17
.trunk/configs/rome.json
View file

@ -1,17 +0,0 @@
{
"$schema": "../../node_modules/rome/configuration_schema.json",
"formatter": {
"enabled": true,
"indentStyle": "space",
"indentSize": 2
},
"linter": {
"enabled": true,
"rules": {
"recommended": true
}
},
"organizeImports": {
"enabled": true
}
}

14
.trunk/configs/svgo.config.js
View file

@ -1,14 +0,0 @@
module.exports = {
plugins: [
{
name: "preset-default",
params: {
overrides: {
removeViewBox: false, // https://github.com/svg/svgo/issues/1128
sortAttrs: true,
removeOffCanvasPaths: true,
},
},
},
],
};

25
.trunk/trunk.yaml
View file

@ -1,25 +0,0 @@
version: 0.1
cli:
version: 1.3.1
plugins:
sources:
- id: trunk
ref: v0.0.8
uri: https://github.com/trunk-io/plugins
lint:
disabled:
- eslint
- prettier
enabled:
- rome@12.0.0
- markdownlint@0.33.0
- actionlint@1.6.22
- gitleaks@8.15.2
- git-diff-check
- shellcheck@0.9.0
- shfmt@3.5.0
- svgo@3.0.2
runtimes:
enabled:
- go@1.18.3
- node@18.12.1

2
.vscode/extensions.json vendored
View file

@ -1,3 +1,3 @@
{
"recommendations": ["trunk.io"]
"recommendations": ["biomejs.biome"]
}

7
.vscode/settings.json vendored
View file

@ -1,7 +1,4 @@
{
"editor.formatOnSave": true,
"editor.defaultFormatter": "trunk.io",
"files.associations": {
"*.mdx": "markdown"
}
"editor.defaultFormatter": "biomejs.biome",
"editor.formatOnSave": true
}

18
biome.json Normal file
View file

@ -0,0 +1,18 @@
{
"$schema": "https://biomejs.dev/schemas/1.3.3/schema.json",
"formatter": {
"enabled": true,
"indentStyle": "space",
"indentWidth": 2
},
"organizeImports": {
"enabled": true
},
"linter": {
"enabled": true,
"rules": {
"all": true
}
}
}

2
docs/about/contributing.mdx
View file

@ -33,7 +33,7 @@ The [firmware repo](https://github.com/meshtastic/firmware) is where all of the
### Firmware Modules
[Modules](/docs/settings/moduleconfig) 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.
[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)

8
docs/about/faq.mdx
View file

@ -45,7 +45,7 @@ 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?
@ -117,7 +117,7 @@ Once the node wakes up from sleep, your phone will relay any delayed messages th
### How can I tell the device not to sleep?
See [Device Power Configuration](/docs/settings/config/power) options.
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?
@ -141,7 +141,7 @@ 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
@ -187,7 +187,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?

91
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.
@ -54,60 +58,3 @@ I'm assuming that meshtastic is being used to hike in places where someone capab
- 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 protection 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
- Optionally 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 phase 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 identified 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)

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

@ -36,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

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

@ -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.
@ -73,11 +73,11 @@ We have six predefined channels. These are the most common settings and have bee
| Channel setting | Alt Channel Name | Data-Rate | SF / Symbols | Coding Rate | Bandwidth | Link Budget |
| :--------------------: | :--------------: | :-----------------: | :----------: | :---------: | :-------: | :---------: |
| Short Range / Fast | Short Fast | 6.8 kbps | 7 / 128 | 4/8 | 250 | 137dB |
| Short Range / Slow | Short Slow | 3.9 kbps | 8 / 256 | 4/8 | 250 | 140dB |
| Medium Range / Fast | Medium Fast | 2.2 kbps | 9 / 512 | 4/8 | 250 | 143dB |
| Medium Range / Slow | Medium Slow | 1.2 kbps | 10 / 1024 | 4/8 | 250 | 146dB |
| Long Range / Fast | Long Fast | 0.67 kbps (default) | 11 / 2048 | 4/8 | 250 | 148.5dB |
| Short Range / Fast | Short Fast | 10.94 kbps | 7 / 128 | 4/5 | 250 | 137dB |
| Short Range / Slow | Short Slow | 6.25 kbps | 8 / 256 | 4/5 | 250 | 140dB |
| Medium Range / Fast | Medium Fast | 3.52 kbps | 9 / 512 | 4/5 | 250 | 143dB |
| Medium Range / Slow | Medium Slow | 2.95 kbps | 10 / 1024 | 4/5 | 250 | 146dB |
| Long Range / Fast | Long Fast | 1.07 kbps (default) | 11 / 2048 | 4/5 | 250 | 148.5dB |
| Long Range / Moderate | Long Moderate | 0.335 kbps | 11 / 2048 | 4/8 | 125 | 151dB |
| Long Range / Slow | Long Slow | 0.18 kbps | 12 / 4096 | 4/8 | 125 | 154dB |
| Very Long Range / Slow | Very Long Slow | 0.09 kbps | 12 / 4096 | 4/8 | 62.5 | 157dB |

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

@ -6,13 +6,25 @@ 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)
### Modem Settings
<h2 id="modem-settings-254">Modem Settings</h2>
Default Long_Fast
- **Frequency:** 915MHz
@ -20,13 +32,13 @@ Default Long_Fast
- **Spread Factor:** 11
- **Coding Rate:** 4/8
### Node A
<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
### Node B
<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
@ -39,68 +51,26 @@ Default Long_Fast
<img src="/img/records/kboxlabs_map.png" alt="Geographic Locations" />
## Previous Record
- **Range:** 206km (128 miles)
- **Record Holders:** _StarWatcher, CVR, rook, kboxlabs_
- **Source:** [Meshtastic Discourse](https://meshtastic.discourse.group/t/practical-range-test-results/692/130)
<!-- trunk-ignore(markdownlint/MD024) -->
### Modem Settings
Default Long_Fast
- **Frequency:** 915MHz
- **Bandwidth:** 250
- **Spread Factor:** 11
- **Coding Rate:** 4/8
<!-- trunk-ignore(markdownlint/MD024) -->
### Node A
- **Device:** [LILYGO TTGO T-Beam](/docs/hardware/devices/tbeam)
- **Firmware Version:** 2.1.10
- **Antenna:** Stock Antenna
<!-- trunk-ignore(markdownlint/MD024) -->
### Node B
- **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" />
<!-- trunk-ignore(markdownlint/MD024) -->
## Previous Record
## Previous Record 166km
- **Range:** 166km (103 miles)
- **Record Holder:** _PuzzledPancake_
- **Source:** [Meshtastic Discourse](https://meshtastic.discourse.group/t/practical-range-test-results/692/44)
<!-- trunk-ignore(markdownlint/MD024) -->
### Modem Settings
<h2 id="modem-settings-166">Modem Settings</h2>
- **Frequency:** 868MHz
- **Bandwidth:** 125
- **Spread Factor:** 12
- **Coding Rate:** 4/8
<!-- trunk-ignore(markdownlint/MD024) -->
### 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)
<!-- trunk-ignore(markdownlint/MD024) -->
### 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
@ -112,6 +82,42 @@ Default Long_Fast
![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, Light Sleep Interval and Minimum Wake Interval. |
| [User](/docs/settings/config/user) | The user config options are: Long Name, Short Name, and Is Licensed |

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

@ -1,21 +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. |
| [Store & Forward](/docs/settings/moduleconfig/store-and-forward-module) | Stores messages on a device for delivery after disconnected clients rejoin the mesh. |
| [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. |

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

@ -1,130 +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 also be enabled as uplink and/or downlink for packets to be transmitted from and/or to your mesh (See [channels](/docs/settings/config/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>

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

@ -0,0 +1,108 @@
---
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">
:::info
All Ambient Lighting module config options are available in the Web UI.
:::
</TabItem>
</Tabs>

1
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
---

1
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
---

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

@ -0,0 +1,138 @@
---
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">
:::info
All Detection Sensor module config options are available in the Web UI.
:::
</TabItem>
</Tabs>

1
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
---

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>

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

@ -0,0 +1,86 @@
---
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">
:::info
All Neighbor Info module config options are available in the Web UI.
:::
</TabItem>
</Tabs>

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

@ -1,7 +1,6 @@
---
id: range-test
title: Range Test Module Configuration
slug: /settings/moduleconfig/range-test
sidebar_label: Range Test
---

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

@ -1,12 +1,84 @@
---
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
---
## Remote Hardware
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.

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

@ -1,7 +1,6 @@
---
id: serial
title: Serial Module Configuration
slug: /settings/moduleconfig/serial
sidebar_label: Serial
---
@ -10,7 +9,7 @@ import TabItem from "@theme/TabItem";
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)
@ -32,12 +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).
- `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).
- `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
@ -112,7 +111,7 @@ All serial module config options are available in the python CLI. Example comman
| 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` |
@ -186,12 +185,12 @@ 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
@ -200,7 +199,7 @@ The following are examples of using either a Raspberry Pi Pico or Arduino Mini P
#### Meshtastic Software Configuration
- Serial module enabled, mode: TXTMSG
- Serial module enabled, mode: TEXTMSG
- GPIO Pins (For T-Beam) RX 13, TX 14
- 38400 Baud

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

@ -1,7 +1,6 @@
---
id: store-and-forward-module
title: Store & Forward Module Settings
slug: /settings/moduleconfig/store-and-forward-module
sidebar_label: Store & Forward
---
@ -9,15 +8,13 @@ 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.**
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 is partially available. Stability is not guaranteed.
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.
@ -53,10 +50,6 @@ Either use a custom channel configuration with at an at least 1kbit data rate or
### 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
@ -75,15 +68,7 @@ Don't enable the Store and Forward module on multiple nodes for now!
### 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.
Currently there are no clients that support store and forward.
## Settings

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

@ -1,7 +1,6 @@
---
id: telemetry
title: Telemetry Module Configuration
slug: /settings/moduleconfig/telemetry
sidebar_label: Telemetry
---
@ -71,7 +70,7 @@ This option is used to configure the interval (in seconds) that should be used t
Default is `900` seconds (15 minutes).
## Device Config Client Availability
## Telemetry Config Client Availability
<Tabs
groupId="settings"

1
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
---

3
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
---
@ -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**
:::

8
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.
:::
@ -154,7 +153,6 @@ meshtastic --ch-set name "My Channel" --ch-set psk random --ch-set uplink_enable
:::
### Name
```shell title="Set channel name for the PRIMARY channel"
@ -205,7 +203,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

5
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

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

@ -1,7 +1,6 @@
---
id: display
title: Display Configuration
slug: /settings/config/display
sidebar_label: Display
---
@ -10,7 +9,7 @@ import TabItem from "@theme/TabItem";
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
@ -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"

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 |

9
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
---
@ -58,6 +57,8 @@ The Presets available are as follows, and follow a linear pattern of Fastest \<\
Maximum number of hops. This can't be greater than 7. Default is 3 which should be fine for most applications. _**Really, 3 is fine.**_
![Hop Count](/img/configuration/max-hops.png)
### Transmit Power
If zero then, use default max legal continuous power (i.e. something that won't burn out the radio hardware)
@ -103,6 +104,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)
@ -159,7 +164,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` |

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

@ -1,7 +1,6 @@
---
id: network
title: Network Configuration
slug: /settings/config/network
sidebar_label: Network
---
@ -22,7 +21,7 @@ ESP32 devices have the ability to connect to WiFi as a client. SoftAP mode is no
The NTP server used if IP networking is available.
Set to `0.pool.ntp.org` by default. (Max Length: 33)
Set to `0.pool.ntp.org` by default. (Max Length: 32)
### WiFi Enabled
@ -34,7 +33,7 @@ Set to `false` (Disabled) by default.
This is your WiFi Network's SSID.
Empty `""` by default. (Case Sensitive, Max Length: 33)
Empty `""` by default. (Case Sensitive, Max Length: 32)
### WiFi PSK

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

@ -1,7 +1,6 @@
---
id: position
title: Position Configuration
slug: /settings/config/position
sidebar_label: Position
---

3
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
---
@ -10,7 +9,7 @@ import TabItem from "@theme/TabItem";
import calculateADC from "/src/utils/calculateADC";
:::info
Power settings are advanced configuration, most users should choose a role under [Device Config](/docs/settings/config/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](/docs/configuration/radio/device) to manage power for their device and shouldn't ever need to adjust 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.

1
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
---

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.
:::

8
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
@ -198,9 +198,5 @@ You've finished setting up and adding two devices to the admin channel. Remember
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/settings) and
[Settings Overview](/docs/configuration) and
[Complete list of user settings in Protobufs](https://buf.build/meshtastic/protobufs/docs/main:meshtastic#meshtastic.User)
## Areas for future development
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.

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.

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

@ -18,14 +18,14 @@ 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)
@ -35,8 +35,8 @@ For a reference implementation of a client that uses this service see [RadioInte
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 Meshtastic-protobuf). Keep reading from this endpoint until you get back and empty buffer.
- See below for the expected sequence for your initial download.
@ -45,13 +45,13 @@ Typical flow when a phone connects to the device should be the following (if you
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/meshtastic/mesh.proto)
@ -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).

10
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,9 +76,7 @@ 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
@ -90,7 +88,7 @@ A reference client written in JavaScript will provide a JavaScript API for using
### 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

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

@ -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).

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/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

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

@ -11,7 +11,7 @@ The Meshtastic web interface can be hosted or served from a node.
The official hosted version can be found at [https://client.meshtastic.org](https://client.meshtastic.org).
The version served from a node can be accessed by first [connecting your node to your network](/docs/settings/config/network) and then navigating to http://meshtastic.local (or your_node_ip.local).
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).
## Development & Building

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

@ -18,7 +18,7 @@ Before you flash your device start by verifying connectivity with the device bei
:::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
@ -186,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
@ -244,17 +244,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

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.
:::

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.

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

@ -24,8 +24,8 @@ Before you begin, it's important to determine which kind of hardware you're usin
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

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>

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

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) |

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

@ -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.

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>

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

@ -2,7 +2,7 @@
id: heltec
title: HELTEC® LoRa 32
sidebar_label: HELTEC® LoRa 32
sidebar_position: 7
sidebar_position: 5
---
import Tabs from "@theme/Tabs";
@ -69,7 +69,6 @@ This device may have issues charging a connected battery if utilizing a USB-C to
- 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
@ -82,7 +81,6 @@ This device may have issues charging a connected battery if utilizing a USB-C to
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`
@ -111,7 +109,6 @@ This device may have issues charging a connected battery if utilizing a USB-C to
- Dedicated 2.4 GHz stamped metal antenna for WiFi/Bluetooth
- U.FL/IPEX antenna connector for LoRa
<!-- trunk-ignore(markdownlint/MD024) -->
## Features
- No display.
@ -123,14 +120,12 @@ This device may have issues charging a connected battery if utilizing a USB-C to
- 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`
@ -158,20 +153,17 @@ This device may have issues charging a connected battery if utilizing a USB-C to
- 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`
@ -199,14 +191,12 @@ This device may have issues charging a connected battery if utilizing a USB-C to
- 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`

26
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";
@ -217,6 +217,30 @@ Early versions of some of these boards contained the wrong component in the LiPo
- microSD connector
- No GPS
## Flashing the T3S3
:::warning
Do not proceed unless an antenna is connected to avoid possible damage to the device's radio.
:::
The following process will manually place the device into the Espressif Firmware Download mode:
1. Switch off the device.
2. Connect the USB-C data cable to the device. A blue LED will illuminate while display stays black.
3. Press and hold the BOOT button to the right of the display.
4. Switch the device on.
5. After 2-3 seconds, release the BOOT button.
With the device now in the Espressif Firmware Download mode, you can proceed with flashing using one of the supported flashing methods. It's generally recommended to use the [Web Flasher](https://flasher.meshtastic.org/). You can select "Tlora T3s3 V1" from the device drop-down.
:::note
If after successfully flashing the device and the screen remains black, you may need to use the [CLI Script](https://meshtastic.org/docs/getting-started/flashing-firmware/esp32/cli-script) to flash Meshtastic.
:::
## Resources
- Firmware file: `firmware-tlora-t3s3-v1.xxxxxxx.bin`

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.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)

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.

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

@ -1,40 +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-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)

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

@ -60,6 +60,37 @@ Please be aware of the difference between the RAK4631 (Arduino bootloader) and t
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">

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

@ -43,6 +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
- US Distributor - Purchase link: [Rokland](https://store.rokland.com/products/rak-wireless-wisblock-epd-module-rak14000-pid-110024)
- Firmware for 5005 with RAK14000 e-paper: [`firmware-rak4631_eink-X.X.X.xxxxxxx.uf2`](/downloads)
<img

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

@ -2,7 +2,7 @@
id: raspberry-pi
title: Raspberry Pi Pico
sidebar_label: Raspberry Pi Pico
sidebar_position: 9
sidebar_position: 8
---
import Tabs from "@theme/Tabs";

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`).

2
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.

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

@ -77,19 +77,17 @@ 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`
- Purchase link: [AliExpress](https://www.aliexpress.com/item/4001178678568.html)
- US Distributor - Purchase link: [Rokland](https://store.rokland.com/products/lilygo-ttgo-t-beam-v1-1-lora-esp32-development-board-wifi-bluetooth-module-gps-neo-6m-sx1276-915mhz-q219?ref=8Bb2mUO5i-jKwt)
- US Distributor - Purchase link: Rokland [No OLED](https://store.rokland.com/products/lilygo-ttgo-t-beam-v1-1-lora-esp32-development-board-wifi-bluetooth-module-gps-neo-6m-sx1276-915mhz-q219?ref=8Bb2mUO5i-jKwt), [OLED](https://store.rokland.com/products/lilygo-ttgo-meshtastic-t-beam-v1-1-esp32-lora-915-mhz-wireless-module-wifi-gps-neo-6m-with-oled-display-soldered-for-arduino-q349)
![TTGO T-Beam v1.1](/img/hardware/t-beam-v1.1.png)
![TTGO T-Beam v1.1 pinmap](/img/hardware/t-beam_v1.1_pinmap.webp)
@ -113,14 +111,12 @@ 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`
@ -147,14 +143,12 @@ 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`
@ -181,14 +175,12 @@ This is an earlier version of the T-Beam board. Due to changes in the design thi
- 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`
@ -214,7 +206,6 @@ This is an earlier version of the T-Beam board. Due to changes in the design thi
- USB-C
- Antenna: U.FL antenna connector
<!-- trunk-ignore(markdownlint/MD024) -->
## Features
- Includes T-Beam S3-Core Module
@ -227,11 +218,12 @@ This is an earlier version of the T-Beam board. Due to changes in the design thi
- 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)
- US Distributor - Purchase link: Rokland [NEO-M10S](https://store.rokland.com/products/lilygo-t-beam-supreme-esp32-s3-lora-development-board-sx1262-915mhz-gps-l76k-or-u-blox?variant=41051191378003), [Quectel L76K](https://store.rokland.com/products/lilygo-t-beam-supreme-esp32-s3-lora-development-board-sx1262-915mhz-gps-l76k-or-u-blox?variant=41051191345235)
![T-Beam Supreme](/img/hardware/T-BEAM-S3-Supreme.jpg)

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.

7
docs/hardware/solar-powered/_category_.yml Normal file
View file

@ -0,0 +1,7 @@
label: Solar Powered
collapsible: true
position: 3
link:
type: generated-index
title: Solar Powered
slug: solar-powered

55
docs/hardware/solar-powered/measure-device-power-consumption.mdx Normal file
View file

@ -0,0 +1,55 @@
---
id: measure-power-consumption
title: How To Measure Meshtastic Device Power Consumption
sidebar_label: Measure Power Consumption
sidebar_position: 1
---
Before you can calculate what size solar panel and battery bank are required you need to determine how much power your device consumes. This is an essential and first step in building a solar powered anything.
## Setup and Requirements
To measure the average power consumption of a radio device, like a Meshtastic node, requires some hardware and some understanding.
### Power Meter
You need a way to measure power. This could be a bench power supply with voltage and amperage readings. It could be a dedicated device like a USB power meter or something else. Most important is that you need to read either volts and amps OR watts over time (over time means it needs to keep track of power used over time, not just instantaneous readings). Also consider if your meter has the resolution to measure as low as you need it to. For example, some nodes consume 0.005A at 5v. Can your power meter measure and display results that small? The important part here is that your meter needs to keep track of amp hours or watt hours. A normal multimeter won't track this.
### What Are We Measuring?
A watt is the unit used to measure power. Use this unit to express how much power your device consumes. If you measure volts and amps you get watts. It's an easy equation. Just multiply volts times amps to get watts: 5v x 50mA = 250mW (also described as 5v x 0.05A = 0.25W). 250mW is a measure of consumed power at a specific instance. Technically, it describes the power consumed over one hour. We can't use this number because radio devices like Meshtastic spend a lot of time receiving and only some time transmitting (transmitting consumes a lot more power than receiving). If we measure power when the device is receiving and we say that's how much it consumes in an hour we are not accounting for the less frequent but more power hungry transmissions. We need to get an average over time. To measure power over time we use watt hours. For example, if your device consumes 250mW for one hour and you want to know how much power it consumes in 24 hours, we express it like this: 24h * 250mW = 6000mWh. This result is expressed in milliwatt hours (it can also be expressed as: 6Wh).
### Duty Cycle
Radios consume relatively little power when receiving. In contrast, they consume a lot more power when transmitting. Duty cycle is the percentage of time the radio transmits. Over a period of time how much of that time is spent transmitting? 5%? 10%? 25%? It's hard to know. It depends on your use-case. Instead of trying to run calculations of receive power vs transmit power based on datasheet numbers, you can run a simulated test and measure power consumption over a period of time. Run your power consumption test for at least 1 hour but the longer you run the test the more accurate it will be (if your test conditions are representative of real life). Consider 2-6 hours as a good test duration.
## Test Conditions
Running a test is pretty simple in practice but requires some understanding of how Meshtastic operates in the background.
### Background Network Activity
Meshtastic nodes transmit data at regular intervals. These data packets are not messages you might send to other people. They're like beacons; used to tell the mesh your node is operational and on the network. Your node will know if other nodes are online and where they are (for GPS-enabled nodes). These data packets are sent in the background and are required for the network to function (though some of these can be disabled or configured to transmit less often). Other nodes on the network will respond to some of these beacons with an acknowledgement of receipt. This means there is a baseline of network activity that will consume some power through receiving and transmitting regardless of the messages you manually send.
### Simulated Testing
To set up a proper test you need to know or guess how much message traffic your network will have (manual messages sent from a node). Is it 5, 10, 20, or 50 messages in an hour? Only you can know this because everyone's situation is different.
If your message rate is small (like 2-5 messages per hour) it may not impact power consumption very much. The node is already regularly transmitting through background activity so this small number of additional message transmissions will have a low impact on overall power consumption. Your message rate is entirely use-case dependent and no one can tell you what your duty-cycle is. But you can guess and add margin to your calculations to ensure uptime.
#### Set A Low GPS Location Broadcast Interval
One way to simulate a message in Meshtastic is to increase the number of times the node sends a GPS location update. Your device does not need a GPS module to use this option. At the time of this writing, the default interval is 2 minutes for a normal node with GPS or 15 minutes for a node with a fixed position. You can decrease this interval and it will broadcast a message more frequently, thus simulating a manual message on the network. You can change this interval on the iPhone app, Android app, web app and CLI. We can use this feature to force more frequent transmissions and thus simulate message traffic. This is helpful because it's automated and doesn't require you to remember to manually send messages during the test.
#### Fixed Position Broadcast Interval
Most solar base stations don't have a GPS module because it doesn't change location and GPS consumes a lot of power. In Meshtastic you can manually set the GPS coordinates for any node. This is common for solar nodes. When a node has a fixed position it will send out that position update every 15 minutes (by default). That's a baseline of 4 GPS location updates per hour. If you want to simulate 16 messsage transmissions per hour you can set this interval to 3 minutes. That will send an update every 3 minutes which is 20 updates in total. Subtract the baseline 4 updates (that will be present after your test, when deployed) and you get 16 "messages" per hour. For 56 simluated messages per hour you would set this interval to 1 minute.
### Example Test Condition With Node Settings
Tests will require at least 2 nodes. The node you measure power from and one other. Though, it may be more realistic to include 3 or 4 nodes on the network. The goal is to be as close to your final deployment network size when measuring power consumption. These test conditions would simulate a "chatty" network:
- 3 nodes on the network.
- 1 "other" node set to broadcast location every 60 seconds (disable smart location).
- Test node is paired with phone over Bluetooth.
- Test node has a fixed GPS position.
- Test node is set to broadcast location every 60 seconds (disable smart location).
Configure all your devices as indicated. It may be helpful to start the test on the hour or on a 15 minute interval (like 2:15). Write the start time on a sticky note and put it next to the test node. When you stop the test try to do it on the hour or at the 15 minute interval. This makes calculating the results easier. Make sure to reset any previous power measurements on your power meter before starting. Run the test and record the stop time and the total power consumed during the test.
## Results
Your results will hopefully be listed in watt hours. Just divide the recorded watt hours by the number of hours for your test to achieve your average power rating in watt hours or miliwatt hours. Save this result and continue to calculating solar panel size.
If your meter measures amp hours you need to convert it.
### Convert Amp Hours To Watt Hours
Take your total amp hour result and multiply it by the volts used for the test. For example, your test ran for 3 hours at 5.1v and your meter reads 142mAh. That's 5.1v * 142mAh = 724.2mWh. Now divide the total by the test duration: 724.2mWh / 3h = 241.4mW. This example shows an average power consumption of 241.1mW. Save your test result for the next step, calculating solar panel size.

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).

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

@ -82,23 +82,11 @@ The app will generate a new QR code on the screen. This encodes the channel det
2. If the channel is shared from a file or link using the `Share` button, you can click on the file or link and you need to choose "Open with Meshtastic".
<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)
@ -138,7 +126,7 @@ By default there is no long-term store-and-forward of messages, so messages not
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.
- Tap on a node from the list to start Direct Messaging, request a position update, or request a [traceroute](/docs/settings/moduleconfig/traceroute).
- 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
@ -152,6 +140,8 @@ The Map tab will show a local map with an icon for each active mesh node that ha
- 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.
@ -173,13 +163,13 @@ The debug panel allows you to see all packets sent between the application and t
[![Meshtastic configuration options](/img/android/android-radio-configuration-c.png)](/img/android/android-radio-configuration.png)
Radio Configuration opens a list of all radio and module configuration settings.
- See [Device Config](/docs/settings/config) for radio settings.
- See [Module Config](/docs/settings/moduleconfig) for module 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
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/settings/moduleconfig/range-test), 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

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.

BIN
docs/software/integrations/app.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 1.6 MiB

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.

2
docs/software/integrations/caltopo.mdx
View file

@ -15,7 +15,7 @@ Meshtastic can integrate with [CalTopo](https://caltopo.com/) Desktop edition qu
### 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/settings/moduleconfig/serial):
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"

2
docs/software/integrations/index.mdx
View file

@ -11,4 +11,6 @@ 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.

174
docs/software/mqtt/adafruit-io.mdx Normal file
View file

@ -0,0 +1,174 @@
---
id: adafruit-io
title: Adafruit IO
sidebar_label: Adafruit IO
sidebar_position: 5
---
### Adafruit IO for Meshtastic
Adafruit IO can be used to graph telemetry and messages from a Meshtastic network via json/mqtt. The following example script will listen for node packets and publish voltage, rssi, snr and messages to individual feeds on adafruit IO. If a feed doesn't exist it will be created. Be aware, however, that the free Adafruit account is limited to 10 feeds. Once your feeds are being populated with data you can create dashboards to display graphs and gauges with the data.
:::info
To utilize this script you need to have an Adafruit IO account, a working mqtt broker setup and a mesh node that is publishing to the mqtt broker.
:::
You will need to modify the script with your Adafruit IO and mqtt credentials and mqtt publisher node id
```python
# Persistent mqtt client, watch for voltage, teleme, message packets and publish them to io
# feeds will be created. free tier maxes out at 10
# Import Adafruit IO REST client.
from Adafruit_IO import Client, Feed, Data, RequestError
from datetime import datetime
import paho.mqtt.client as mqtt
import os
import sys
import json
import time
import random
import pytz
# set your timezone here
timezone = pytz.timezone("US/Hawaii")
# set your Adafruit IO creds here
AIO_USER = "tavdog"
AIO_KEY = "XXXXXXXXXXXXX"
# set your MQTT broker information
MQTT_SERVER = "XXXXXXXXXX"
MQTT_PORT = 1883 # default
MQTT_TOPIC_PREFIX = "mesh" # specified when you setup your node to publish mqtt
MQTT_USERNAME = "xxxxxxxxx"
MQTT_PASSWORD = "xxxxxxxxx"
# your node ID that is publishingn to the MQTT broker
MQTT_NODE_ID = "!387e0248"
# your channel (node must be set to json output)
MQTT_CHANNEL = "LongFast"
print("\n\n")
client_id = str(random.randint(0, 100))
mqttClient = mqtt.Client("python_mesh_client_%s" % client_id) # this needs to be kind of unique. mqtt broker will not allow duplicate connections.
mqttClient.username_pw_set(MQTT_USERNAME, MQTT_PASSWORD)
mqttClient.connect(MQTT_SERVER, MQTT_PORT)
mqttClient.loop_start()
print("Subscribing to %s/2/json/%s/%s" % (MQTT_TOPIC_PREFIX, MQTT_CHANNEL,MQTT_NODE_ID))
mqttClient.subscribe("%s/2/json/%s/%s" % (MQTT_TOPIC_PREFIX, MQTT_CHANNEL,MQTT_NODE_ID))
time.sleep(1)
# you can add more channels here
#mqttClient.subscribe("%s/2/json/MauiMesh/%s" % (MQTT_TOPIC_PREFIX, MQTT_NODE_ID))
aio = Client(AIO_USER, AIO_KEY)
node_db = dict()
# bootstrap your node_db here if you want. otherwise it will populate eventually but die on restart.
# node_db = { 634792740: 'Tavis Blue',
# 947782216: 'G1 Wailuku',
# 1839130823: 'Giggle Hill',
# 2330585902: 'Ayla Kekona',
# 634717328: 'Nani Hoku',
# 3667835576: 'Rachael'}
def get_feed(full_name,kind):
name = full_name.split('-')[0]
try:
feed = aio.feeds(f"mesh.{name.lower()}-{kind}")
except:
print("creating feed:" + kind)
# Create Feed
new_feed = Feed(name=f"{name}_{kind}")
feed = aio.create_feed(feed=new_feed,group_key="mesh")
return feed
def publish_rssi(data,metadata):
name = node_db[data['from']]
feed = get_feed(name,"rssi") # use a function here because we will create the feed if it doens't exist already.
print(feed.key + " \t\t: " + str(data['rssi']))
aio.send_data(feed.key, data['rssi'],metadata)
def publish_snr(data,metadata):
name = node_db[data['from']]
feed = get_feed(name,"snr") # use a function here because we will create the feed if it doens't exist already.
print(feed.key + " \t\t: " + str(data['snr']))
aio.send_data(feed.key, data['snr'],metadata)
def publish_voltage(data,metadata):
name = node_db[data['from']]
feed = get_feed(name,"voltage") # use a function here because we will create the feed if it doens't exist already. print(feed.key + " \t: " + str(data['payload'].get('voltage',"none")))
print(feed.key + " \t: " + str(data['payload']['voltage']))
aio.send_data(feed.key, data['payload'].get('voltage',0),metadata)
def publish_packet(data):
feed = aio.feeds("mesh.messages")
if (data['from'] in node_db):
data['fname'] = node_db[data['from']]
# trim down the data. we really only want to see the message content
trimmed = {
'from' : data.get('fname',None) or data.get('from'),
'message' : data['payload']['text'],
'stamp' : datetime.fromtimestamp(data['timestamp'],timezone).strftime('%Y-%m-%d %H:%M:%S'),
}
aio.send_data(feed.key, json.dumps(trimmed, indent=4))
def on_message(client, userdata, message):
print("\n")
print("message received " ,str(message.payload.decode("utf-8")))
print("\n")
data = json.loads(str(message.payload.decode("utf-8")))
# check the topic of the message
if data['type'] == "text":
# publish all message packets to the packet log
publish_packet(data)
# update node_db if needed
if data['type'] == 'nodeinfo':
# add to the node_db if we haven't seen it before
if data['from'] not in node_db:
node_db[data['from']] = data['payload']['shortname'] + '-' + data['payload']['longname']
print(str(node_db))
return # don't publish data from nodedb packets.
# "payload":{"altitude":113,"latitude_i":208759687,"longitude_i":-1565037665
metadata = None
if data['type'] == 'position':
metadata = {
'lat': data['payload']['latitude_i'] / 10000000, #40.726190,
'lon': data['payload']['longitude_i'] / 10000000, #-74.005334,
'ele': data['payload'].get('altitude',None),
'created_at': datetime.now(timezone),
}
# add to the node_db if we know who they are already
if data['from'] in node_db:
try:
if 'rssi' in data and data['rssi'] != 0:
# do the doings
publish_rssi( data, metadata )
if 'snr' in data and data['snr'] != 0:
publish_snr( data, metadata )
if 'payload' in data and data['payload'].get('voltage',0) != 0:
publish_voltage( data, metadata )
except Exception as e:
print("Error sending to IO:", str(e))
mqttClient.on_message = on_message
# loop forever
while(True):
pass
```

313
docs/software/mqtt/home-assistant.mdx Normal file
View file

@ -0,0 +1,313 @@
---
id: home-assistant
title: Home Assistant
sidebar_label: Home Assistant
sidebar_position: 4
---
### Home Assistant Integrations for Meshtastic
Integrating Meshtastic into Home Assistant brings a new level of control and monitoring to your mesh network. On this page, we'll guide you through the process of creating Meshtastic MQTT sensor entities within Home Assistant. Whether you want to keep an eye on battery levels, environmental conditions, or even receive notifications from your mesh network, these integrations provide you with the tools to make it happen.
:::info
It is highly recommended to download MQTT Explorer for analyzing the JSON threads that come across the broker. This can be downloaded here: http://mqtt-explorer.com/
:::
## Create Meshtastic MQTT Sensor Entities
- Ensure your mesh unit is connected to your MQTT broker and using JSON as an output.
- Open configuration.yaml and include the following line:
```yaml
mqtt: !include mqtt.yaml
```
- Create a new text file called `mqtt.yaml` in the root directory of home assistant (the same folder as configuration.yaml).
- Copy the following code to the mqtt.yaml file.
### Default Node Telemetry Example
```yaml
sensor:
# Node #1
- name: "Node 1 Battery Voltage"
unique_id: "node_1__battery_voltage"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_class: measurement
value_template: >-
{% if value_json.from == 4038675309 and
value_json.payload.voltage is defined and
value_json.payload.temperature is not defined %}
{{ (value_json.payload.voltage | float) | round(2) }}
{% else %}
{{ states('sensor.node_1_battery_voltage') }}
{% endif %}
unit_of_measurement: "Volts"
# Telemetry packets come in two flavors: The default node telemetry, and the I2C sensor data.
# Both packets contain "voltage" so we check for temperature to ignore the sensor packet here.
- name: "Node 1 Battery Percent"
unique_id: "node_1_battery_percent"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_class: measurement
value_template: >-
{% if value_json.from == 4038675309 and value_json.payload.battery_level is defined %}
{{ (value_json.payload.battery_level | float) | round(2) }}
{% else %}
{{ states('sensor.node_1_battery_percent') }}
{% endif %}
unit_of_measurement: "%"
- name: "Node 1 ChUtil"
unique_id: "node_1_chutil"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_class: measurement
value_template: >-
{% if value_json.from == 4038675309 and value_json.payload.channel_utilization is defined %}
{{ (value_json.payload.channel_utilization | float) | round(2) }}
{% else %}
{{ states('sensor.node_1_chutil') }}
{% endif %}
unit_of_measurement: "%"
- name: "Node 1 AirUtilTX"
unique_id: "node_1_airutiltx"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_class: measurement
value_template: >-
{% if value_json.from == 4038675309 and value_json.payload.air_util_tx is defined %}
{{ (value_json.payload.air_util_tx | float) | round(2) }}
{% else %}
{{ states('sensor.node_1_airutiltx') }}
{% endif %}
unit_of_measurement: "%"
```
### Telemetry Module Entities
- If you have environmental sensors installed, create entities for these by including some or all of the following blocks:
```yaml
- name: "Node 1 Temperature"
unique_id: "node_1_temperature"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_class: measurement
value_template: >-
{% if value_json.from == 4038675309 and value_json.payload.temperature is defined %}
{{ (((value_json.payload.temperature | float) * 1.8) +32) | round(2) }}
{% else %}
{{ states('sensor.node_1_temperature') }}
{% endif %}
unit_of_measurement: "F"
# For Celsius use: {{ (value_json.payload.temperature | float) | round(1) }}
# For Fahrenheit use: {{ (((value_json.payload.temperature | float) * 1.8) +32) | round(2) }}
- name: "Node 1 Humidity"
unique_id: "node_1_humidity"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_class: measurement
value_template: >-
{% if value_json.from == 4038675309 and value_json.payload.relative_humidity is defined %}
{{ (value_json.payload.relative_humidity | float) | round(2) }}
{% else %}
{{ states('sensor.node_1_humidity') }}
{% endif %}
unit_of_measurement: "%"
- name: "Node 1 Pressure"
unique_id: "node_1_pressure"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_class: measurement
value_template: >-
{% if value_json.from == 4038675309 and value_json.payload.barometric_pressure is defined %}
{{ (value_json.payload.barometric_pressure | float) | round(2) }}
{% else %}
{{ states('sensor.node_1_pressure') }}
{% endif %}
unit_of_measurement: "hPa"
- name: "Node 1 Gas Resistance"
unique_id: "node_1_gas_resistance"
state_topic: "msh/2/json/LongFast/!67ea9400"
state_class: measurement
value_template: >-
{% if value_json.from == 4038675309 and value_json.payload.gas_resistance is defined %}
{{ (value_json.payload.gas_resistance | float) | round(2) }}
{% else %}
{{ states('sensor.node_1_gas_resistance') }}
{% endif %}
unit_of_measurement: "MOhms"
```
### Message Entities
- For added functionality you can create an entity for messages received from a node:
```yaml
- name: "Node 1 Messages"
unique_id: "node_1_messages"
state_topic: "msh/2/json/LongFast/!67ea9400"
value_template: >-
{% if value_json.from == 4038675309 and value_json.payload.text is defined %}
{{ value_json.payload.text }}
{% else %}
{{ states('sensor.node_1_messages') }}
{% endif %}
```
### Additional Entities
Home Assistant entities can be created for any data type that is published to MQTT. For example: altitude, latitude_i, longitude_i, time, current, and neighbors. Use the templates above as a guide to create additional entities if desired.
### Configure With Your Topic & Node ID's
- In every entity, replace `msh/2/json/LongFast/!67ea9400` with the topic your node publishes to. In this example, `!67ea9400` refers to the node that has mqtt enabled on the mesh and is publishing to the broker.
- In every entity replace `4038675309` with the node number of the radio you wish to monitor. In this example `4038675309` is the node on the mesh with environment sensors and telemetry that I wish to observe. Node numbers can be found by monitoring the output in MQTT Explorer, listening with the MQTT addon or by using the Python CLI with `meshtastic --info`.
### Additional Nodes
Copy and paste these entities then change `name`, `unique_id`, `from`, and `states` to create entities from any additional nodes' parameters:
```yaml
- name: "Node 2 Messages"
unique_id: "node_2_messages"
state_topic: "msh/2/json/LongFast/!67ea9400"
value_template: >-
{% if value_json.from == 695318008 and value_json.payload.text is defined %}
{{ value_json.payload.text }}
{% else %}
{{ states('sensor.node_2_messages') }}
{% endif %}
```
### Check Configuration & Reload YAML
- In Home Assistant, run `CHECK CONFIGURATION` in the developer tools section and then reload all yaml configuration.
:::danger warning
Always Check Configuration before reloading YAML or restarting Home Assistant to identify errors.
:::
![HA Developer Tools](/img/software/mqtt/ha_developer_tools.png)
## Create Dashboard Cards
### Entities Card for Telemetry
Create a new Entities Card and select the entities you have created.
![HA Entities Card](/img/software/mqtt/ha_entities_card.png)
### Logbook Card for Messaging
The logbook card is useful to keep a record of incoming messages from the mesh. Below is an example of how the logbook card would be set up.
![HA Logbook Card](/img/software/mqtt/ha_logbook_card.png)
## Trigger HA Automations
It is possible to have Home Assistant trigger automations based on messages or events on your mesh.
### Notifications
This example waits for a message containing @Tropho and then sends a pop-up notification to his flip phone with the message. Optionally you can have ALL messages from the mesh sent as HA notifications to your phone.
![HA At Tropho Message](/img/software/mqtt/ha_at_tropho.png)
Add the following code to your automations.yaml file. Be sure to modify the `topic`, `regex_search`, and `service` for your configuration.
```yaml
- alias: Meshtastic - New notification
description: any message with an @Tropho will send to mobile device
trigger:
- platform: mqtt
topic: msh/2/json/LongFast/!67ea9400
condition:
- condition: template
value_template: "{{ trigger.payload_json.payload.text | regex_search('@Tropho') }}"
# or send ALL messages from the mesh to HA notifications (except for range tests)
# value_template: "{{ trigger.payload_json.payload.text is defined and "seq " not in trigger.payload_json.payload.text}}"
enabled: true
action:
- service: notify.mobile_app_trophos_galaxy_z_flip5
data:
# show the message as coming from "Meshtastic":
message: "Meshtastic: {{ trigger.payload_json.payload.text }}"
# or show the device id instead:
# message: "{{ trigger.payload_json.from }}: {{ trigger.payload_json.payload.text }}"
- delay:
hours: 0
minutes: 0
seconds: 30
milliseconds: 0
mode: single
```
This same type of automation is very useful to trigger other actions in Home Assistant. For example, you could turn on a fan when the temperature reaches a certain value, or a play a sound on a speaker when a new message is received.
## Create a Send Message Entity
It is possible to create an input text box to send messages to your mesh from within Home Assistant.
### Input Text Helper Entity
First, create an input text helper entity. The preferred way to configure an input text is via the HA interface at Settings > Devices & Services > Helpers. Click the add button and then choose the Text option. Make a text input helper with a max length of 190 to be on the safe side. See example below:
![HA Input Text Helper](/img/software/mqtt/ha_input_text_helper.png)
### Create a Send Message Automation
This automation will check the send box for changes. After typing a message, either hit enter or click off the box and the automation will send a text string in JSON to the mqtt broker. Make sure to update the channel name and device ID in the example below.
```yaml
- alias: Meshtastic - Send Automation
description: ""
trigger:
- platform: state
entity_id:
- input_text.meshtastic_send_box
condition: []
action:
- delay:
hours: 0
minutes: 0
seconds: 1
milliseconds: 0
- service: mqtt.publish
data:
qos: 0
retain: false
topic: msh/2/json/LongFast/!67ea9400
payload: >-
{"channel":"0","sender":"broker","type":"sendtext","payload":"{{
states('input_text.meshtastic_send_box') }}"}
- delay:
hours: 0
minutes: 0
seconds: 1
milliseconds: 0
- service: input_text.set_value
data:
value: " "
target:
entity_id: input_text.meshtastic_send_box
- delay:
hours: 0
minutes: 0
seconds: 2
milliseconds: 0
mode: single
```
Add this card to your dashboard by going to Edit Dashboard -> + ADD CARD. Then search BY ENTITY for Meshtastic Send Box and check the box next to the entry. Click CONTINUE, then ADD TO DASHBOARD.

1067
docs/software/mqtt/index.mdx
View file

File diff suppressed because it is too large Load diff

50
docs/software/mqtt/mosquitto.mdx Normal file
View file

@ -0,0 +1,50 @@
---
id: mosquitto
title: Mosquitto
sidebar_label: Mosquitto
sidebar_position: 1
---
### Using mosquitto on a mac
1. install mqtt server
```sh
brew install mosquitto
```
2. start the mqtt server
```sh
brew services restart mosquitto
```
3. Do a quick test of server, start a subscriber on a topic:
Note: this will wait until you press control-c (publish a message, see below)
```sh
mosquitto_sub -t test/hello
```
4. In another window, publish a message to that topic:
```sh
mosquitto_pub -h localhost -q 0 -t test/hello -m 'yo!'
```
5. For Meshtastic to be able to access that server, two settings need to be changed in the
`/usr/local/etc/mosquitto/mosquitto.conf` file:
```shell
listener 1883 0.0.0.0
allow_anonymous true
```
6. Restart the service:
```shell
brew services restart mosquitto
```
7. If you are using the mac firewall, you will need to go into: System Preferences > Security & Privacy > Firewall > Firewall Options and add it.

945
docs/software/mqtt/nodered.mdx Normal file
View file

@ -0,0 +1,945 @@
---
id: nodered
title: Node-RED
sidebar_label: Node-RED
sidebar_position: 3
---
### Using MQTT with Node-RED
Below is a valid JSON envelope for information sent by MQTT to a device for broadcast onto the mesh.
```json
{
"sender":"whatever you want to be the SENDER",
"type":"sendtext",
"payload": text or a json object go here
}
```
Node-RED is a free cross-platform programming tool for wiring together hardware, APIs, and online services developed originally by IBM for IOT. It is widely used for home automation by many non-professional programmers and runs well on Pi's. Node-RED has many plug-in modules written by the community. I will use this platform as a practical example on how to interface with the MQTT features of Meshtastic. Everything can be done from GUI's without using command line.
Step one: use http://client.meshtastic.org/ , the python CLI, or an Apple or Android app to connect to your device and adjust these settings.
Enable and enter network SSID/PSK. Settings--> Radio Config--> Network; Save.
Set MQTT server address. Settings--> Module Config--> MQTT config; Verify Encryption Enabled is OFF. Turn JSON Output Enabled ON. Save.
Go to Channel Editor and set Uplink and Downlink enabled to True. Save.
Step two: if you don't want to depend on JSON decoding on the device, you can decode the protobuf messages off-device. To do that you will need to get the .proto files from https://github.com/meshtastic/protobufs. They function as a schema and are required for decoding in Node-RED. Save the files where the node-RED application can access them and note the file path of the "mqtt.proto" file.
Step three: install Node-RED plug-ins to your node-RED application for an embedded MQTT server and a protobuf decoder.
https://flows.nodered.org/node/node-red-contrib-aedes
https://flows.nodered.org/node/node-red-contrib-protobuf
Drag, drop, and wire the nodes like this. For this example, I ran node-RED on a Windows machine. Note that file paths might be specified differently on different platforms. MQTT server wild cards are usually the same. A "+" is a single level wildcard for a specific topic level. A "#" is a multiple level wildcard that can be used at the end of a topic filter. The debug messages shown are what happens when the inject button sends a JSON message with a topic designed to be picked up by the specified Meshtastic device and then having it rebroadcast the message.
[<img src="/documents/mqtt/NodeRedTwo.jpg" style={{zoom:'50%'}} />](/documents/mqtt/NodeRedTwo.jpg)
[<img src="/documents/mqtt/NodeRedThree.jpg" style={{zoom:'50%'}} />](/documents/mqtt/NodeRedThree.jpg)
[<img src="/documents/mqtt/NR_nodes.jpg" style={{zoom:'50%'}} />](/documents/mqtt/NR_nodes.jpg)
The aedes broker must be set up on the same flow as the other nodes. By activating the Publish debug node, you can see all the published messages.
[<img src="/documents/mqtt/Broker1.jpg" style={{zoom:'50%'}} />](/documents/mqtt/Broker1.jpg)
Receiving a json mqtt message is very simple.
[<img src="/documents/mqtt/Consume.jpg" style={{zoom:'50%'}} />](/documents/mqtt/Consume.jpg)
Injecting a json message to be sent by a device is also very simple. You do need the correct envelope.
[<img src="/documents/mqtt/Inject.jpg" style={{zoom:'50%'}} />](/documents/mqtt/Inject.jpg)
Forwarding a text message from one device, through a broker, to another broker/device/channel would look like this.
[<img src="/documents/mqtt/Forward.jpg" style={{zoom:'50%'}} />](/documents/mqtt/Forward.jpg)
If you want to decode text and position messages without json, it gets complicated:
[<img src="/documents/mqtt/DecodeNewest.jpg" style={{zoom:'50%'}} />](/documents/mqtt/DecodeNewest.jpg)
If you are interested in my flow for this it is here:
```json
[
{
"id": "10fe1b2e9cb3feb2",
"type": "decode",
"z": "23dbb1ee.bc2e8e",
"name": "decode Protobuf",
"protofile": "a0d4288141f6a629",
"protoType": "ServiceEnvelope",
"x": 295.5,
"y": 285,
"wires": [["d3e396cf4f0a9608", "d08865b41a69d85d", "6f592d47b6a2eac4"]]
},
{
"id": "40c9ee66fe7a34cb",
"type": "function",
"z": "23dbb1ee.bc2e8e",
"name": "function get the message as string from TEXT_MESSAGE_APP",
"func": "msg.payload = msg.payload.packet.decoded.payload;\n\nlet bufferObj = Buffer.from(msg.payload, \"base64\");\nlet decodedString = bufferObj.toString(\"utf8\");\nmsg.payload = decodedString;\n\nreturn msg;",
"outputs": 1,
"noerr": 0,
"initialize": "",
"finalize": "",
"libs": [],
"x": 410.5,
"y": 450,
"wires": [["553374591214eaca"]]
},
{
"id": "553374591214eaca",
"type": "debug",
"z": "23dbb1ee.bc2e8e",
"name": "text message out",
"active": true,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "payload",
"targetType": "msg",
"statusVal": "",
"statusType": "auto",
"x": 762.5,
"y": 449,
"wires": []
},
{
"id": "c6afbb9f1665b162",
"type": "debug",
"z": "23dbb1ee.bc2e8e",
"name": "channelId",
"active": false,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "payload",
"targetType": "msg",
"statusVal": "",
"statusType": "auto",
"x": 785.5,
"y": 257,
"wires": []
},
{
"id": "607ef387d5701985",
"type": "debug",
"z": "23dbb1ee.bc2e8e",
"name": "gatewayId",
"active": false,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "payload",
"targetType": "msg",
"statusVal": "",
"statusType": "auto",
"x": 792.5,
"y": 293,
"wires": []
},
{
"id": "d3e396cf4f0a9608",
"type": "debug",
"z": "23dbb1ee.bc2e8e",
"name": "entire payload",
"active": false,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "payload",
"targetType": "msg",
"statusVal": "",
"statusType": "auto",
"x": 296.5,
"y": 247,
"wires": []
},
{
"id": "2339b328bb9bb1d8",
"type": "comment",
"z": "23dbb1ee.bc2e8e",
"name": "Decode all cleartext text and position messages sent by Meshtastic devices into JSON without relying on JSON conversion on the device.",
"info": "",
"x": 515.5,
"y": 214,
"wires": []
},
{
"id": "408d796d997bb832",
"type": "function",
"z": "23dbb1ee.bc2e8e",
"name": "function get the nested payload as base64",
"func": "msg.payload = msg.payload.packet.decoded.payload;\n\nlet bufferObj = Buffer.from(msg.payload, \"base64\");\n//let decodedString = bufferObj.toString(\"hex\");\nmsg.payload = bufferObj;\nmsg.topic=\"\";\n//if you don't zero out the protubufTopic it will try to\n//decode it as part of the mqtt service envelope instead\n//of two-stage decoding\nmsg.protobufType=null;\n\nreturn msg;",
"outputs": 1,
"noerr": 0,
"initialize": "",
"finalize": "",
"libs": [],
"x": 349,
"y": 552,
"wires": [["9435a3c605efedb4", "1ed6f96c8214d7b3"]]
},
{
"id": "61995c9f8e8266b3",
"type": "debug",
"z": "23dbb1ee.bc2e8e",
"name": "portnum",
"active": false,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "payload",
"targetType": "msg",
"statusVal": "",
"statusType": "auto",
"x": 784.5,
"y": 330,
"wires": []
},
{
"id": "9435a3c605efedb4",
"type": "debug",
"z": "23dbb1ee.bc2e8e",
"name": "nested payload",
"active": false,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "true",
"targetType": "full",
"statusVal": "",
"statusType": "auto",
"x": 281.5,
"y": 603,
"wires": []
},
{
"id": "b832775d386f7ac9",
"type": "mqtt in",
"z": "23dbb1ee.bc2e8e",
"name": "",
"topic": "msh/+/c/#",
"qos": "2",
"datatype": "buffer",
"broker": "37cadac381653b1e",
"nl": false,
"rap": true,
"rh": 0,
"inputs": 0,
"x": 117.5,
"y": 286,
"wires": [["10fe1b2e9cb3feb2"]]
},
{
"id": "d08865b41a69d85d",
"type": "switch",
"z": "23dbb1ee.bc2e8e",
"name": "switch manual decoding nested message based on portum",
"property": "payload.packet.decoded.portnum",
"propertyType": "msg",
"rules": [
{ "t": "eq", "v": "TEXT_MESSAGE_APP", "vt": "str" },
{ "t": "eq", "v": "POSITION_APP", "vt": "str" }
],
"checkall": "true",
"repair": false,
"outputs": 2,
"x": 281.5,
"y": 505,
"wires": [["40c9ee66fe7a34cb"], ["408d796d997bb832"]]
},
{
"id": "8abb1bb458af2c4f",
"type": "change",
"z": "23dbb1ee.bc2e8e",
"name": "",
"rules": [
{
"t": "set",
"p": "gatewayId",
"pt": "flow",
"to": "payload",
"tot": "msg"
}
],
"action": "",
"property": "",
"from": "",
"to": "",
"reg": false,
"x": 1021.5,
"y": 288,
"wires": [[]]
},
{
"id": "1ced0be28eeef0d3",
"type": "change",
"z": "23dbb1ee.bc2e8e",
"name": "",
"rules": [
{
"t": "set",
"p": "latitude",
"pt": "flow",
"to": "payload",
"tot": "msg"
}
],
"action": "",
"property": "",
"from": "",
"to": "",
"reg": false,
"x": 1026.5,
"y": 407,
"wires": [[]]
},
{
"id": "313fd3cfe6d91850",
"type": "change",
"z": "23dbb1ee.bc2e8e",
"name": "",
"rules": [
{
"t": "set",
"p": "longitude",
"pt": "flow",
"to": "payload",
"tot": "msg"
}
],
"action": "",
"property": "",
"from": "",
"to": "",
"reg": false,
"x": 1036.5,
"y": 450,
"wires": [["d02e53cdfb565da6"]]
},
{
"id": "33dd43e3c05f826c",
"type": "geofence",
"z": "23dbb1ee.bc2e8e",
"name": "geofence",
"mode": "circle",
"inside": "true",
"rad": 69174.91569647488,
"points": [],
"centre": {
"latitude": 40.16287050252407,
"longitude": -86.60385131835938
},
"floor": "",
"ceiling": "",
"worldmap": true,
"outputs": 2,
"x": 1202.5,
"y": 595,
"wires": [[], ["4d01eb8f1b31f039"]]
},
{
"id": "d02e53cdfb565da6",
"type": "function",
"z": "23dbb1ee.bc2e8e",
"name": "trigger function to send a mapping point",
"func": "let lat = parseFloat(flow.get(\"latitude\"));\nlet lon = parseFloat(flow.get(\"longitude\"));\nlat=lat * 0.0000001;\nlon=lon * 0.0000001;\nlet name = flow.get(\"from\")\n\nmsg={\"payload\":{\"name\":name,\n \"lat\":lat,\n \"lon\":lon,\n \"action\":\"send\",\n \"icon\": \"car\",\n \"label\":name\n }}\n\nreturn msg;",
"outputs": 1,
"noerr": 0,
"initialize": "",
"finalize": "",
"libs": [],
"x": 1181.5,
"y": 520,
"wires": [["33dd43e3c05f826c", "4d01eb8f1b31f039"]]
},
{
"id": "4d01eb8f1b31f039",
"type": "worldmap",
"z": "23dbb1ee.bc2e8e",
"name": "",
"lat": "40",
"lon": "-86",
"zoom": "7",
"layer": "OSMG",
"cluster": "",
"maxage": "",
"usermenu": "show",
"layers": "show",
"panit": "false",
"panlock": "false",
"zoomlock": "false",
"hiderightclick": "false",
"coords": "none",
"showgrid": "false",
"showruler": "false",
"allowFileDrop": "false",
"path": "/worldmap",
"overlist": "DR,CO,RA,DN,HM",
"maplist": "OSMG,OSMC,EsriC,EsriS,EsriT,EsriDG,UKOS",
"mapname": "",
"mapurl": "",
"mapopt": "",
"mapwms": false,
"x": 1206.5,
"y": 675,
"wires": []
},
{
"id": "1ed6f96c8214d7b3",
"type": "decode",
"z": "23dbb1ee.bc2e8e",
"name": "decode Position Protobuf",
"protofile": "dbab6472b07929a0",
"protoType": "Position",
"x": 667.5,
"y": 548,
"wires": [["db1933ba36503bd9", "dad9f487318f21d9"]]
},
{
"id": "db1933ba36503bd9",
"type": "debug",
"z": "23dbb1ee.bc2e8e",
"name": "Position decoded",
"active": false,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "true",
"targetType": "full",
"statusVal": "",
"statusType": "auto",
"x": 673.5,
"y": 607,
"wires": []
},
{
"id": "dad9f487318f21d9",
"type": "function",
"z": "23dbb1ee.bc2e8e",
"name": "Split",
"func": "var lat = { payload: msg.payload.latitudeI };\nvar lon = { payload: msg.payload.longitudeI };\nvar alt = { payload: msg.payload.altitude };\nvar tm = { payload: msg.payload.time };\n\nreturn [lat,lon,alt,tm];",
"outputs": 4,
"noerr": 0,
"initialize": "",
"finalize": "",
"libs": [],
"x": 875.5,
"y": 549,
"wires": [
["1ced0be28eeef0d3", "8bb97f802662976c"],
["313fd3cfe6d91850", "c8e135f3e542bb1b"],
["602fb2020680280c"],
["ed424ae3d45dd2ac"]
]
},
{
"id": "8bb97f802662976c",
"type": "debug",
"z": "23dbb1ee.bc2e8e",
"name": "lat",
"active": true,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "payload",
"targetType": "msg",
"statusVal": "",
"statusType": "auto",
"x": 1017.5,
"y": 583,
"wires": []
},
{
"id": "c8e135f3e542bb1b",
"type": "debug",
"z": "23dbb1ee.bc2e8e",
"name": "lon",
"active": true,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "payload",
"targetType": "msg",
"statusVal": "",
"statusType": "auto",
"x": 1018.5,
"y": 618,
"wires": []
},
{
"id": "602fb2020680280c",
"type": "debug",
"z": "23dbb1ee.bc2e8e",
"name": "alt",
"active": true,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "payload",
"targetType": "msg",
"statusVal": "",
"statusType": "auto",
"x": 1017.5,
"y": 654,
"wires": []
},
{
"id": "ed424ae3d45dd2ac",
"type": "debug",
"z": "23dbb1ee.bc2e8e",
"name": "time",
"active": true,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "payload",
"targetType": "msg",
"statusVal": "",
"statusType": "auto",
"x": 1018.5,
"y": 688,
"wires": []
},
{
"id": "6f592d47b6a2eac4",
"type": "function",
"z": "23dbb1ee.bc2e8e",
"name": "Split Decoded 1",
"func": "var channelId = { payload: msg.payload.channelId};\nvar gatewayId = { payload: msg.payload.gatewayId};\nvar portnum = { payload: msg.payload.packet.decoded.portnum};\nvar fr= {payload: \"!\" + msg.payload.packet.from.toString(16)};\nvar to = {payload:\"!\"+ msg.payload.packet.to.toString(16)};\n\nreturn [channelId, gatewayId, portnum, fr, to ];",
"outputs": 5,
"noerr": 0,
"initialize": "",
"finalize": "",
"libs": [],
"x": 577.5,
"y": 294,
"wires": [
["c6afbb9f1665b162"],
["607ef387d5701985", "8abb1bb458af2c4f"],
["61995c9f8e8266b3"],
["fd881fac22422773", "a389f9875da672ec"],
["cf066ad415df30ae"]
]
},
{
"id": "fd881fac22422773",
"type": "debug",
"z": "23dbb1ee.bc2e8e",
"name": "from",
"active": true,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "payload",
"targetType": "msg",
"statusVal": "",
"statusType": "auto",
"x": 772.5,
"y": 365,
"wires": []
},
{
"id": "cf066ad415df30ae",
"type": "debug",
"z": "23dbb1ee.bc2e8e",
"name": "to",
"active": false,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "payload",
"targetType": "msg",
"statusVal": "",
"statusType": "auto",
"x": 771.5,
"y": 399,
"wires": []
},
{
"id": "a389f9875da672ec",
"type": "change",
"z": "23dbb1ee.bc2e8e",
"name": "set flow.from",
"rules": [
{ "t": "set", "p": "from", "pt": "flow", "to": "payload", "tot": "msg" }
],
"action": "",
"property": "",
"from": "",
"to": "",
"reg": false,
"x": 1012.5,
"y": 364,
"wires": [[]]
},
{
"id": "a0d4288141f6a629",
"type": "protobuf-file",
"protopath": "E:\\Meshtastic-protobufs-master\\mqtt.proto",
"watchFile": true,
"keepCase": false
},
{
"id": "37cadac381653b1e",
"type": "mqtt-broker",
"name": "",
"broker": "192.168.2.45",
"port": "1883",
"clientid": "",
"autoConnect": true,
"usetls": false,
"protocolVersion": "4",
"keepalive": "60",
"cleansession": true,
"birthTopic": "",
"birthQos": "0",
"birthPayload": "",
"birthMsg": {},
"closeTopic": "",
"closeQos": "0",
"closePayload": "",
"closeMsg": {},
"willTopic": "",
"willQos": "0",
"willPayload": "",
"willMsg": {},
"userProps": "",
"sessionExpiry": ""
},
{
"id": "dbab6472b07929a0",
"type": "protobuf-file",
"protopath": "E:\\Meshtastic-protobufs-master\\mesh.proto",
"watchFile": true,
"keepCase": false
}
]
```
(documents/mqtt/Flow.txt)
Node-red can rapidly (minutes vs days) put together some pretty impressive output when paired with meshtastic. Here is the output of that flow geofencing and mapping via mqtt data.
[<img src="/documents/mqtt/Mapping.jpg" style={{zoom:'50%'}} />](/documents/mqtt/Mapping.jpg)
Advanced use, such as encoding Position and sending it to a device via MQTT without using JSON can get a little complicated. An example of how it can be done is below.
[<img src="/documents/mqtt/EncodingPosition.jpg" style={{zoom:'50%'}} />](/documents/mqtt/EncodingPosition.jpg)
The flow is:
```json
[
{
"id": "32ca608d9e7c5236",
"type": "inject",
"z": "23dbb1ee.bc2e8e",
"name": "",
"props": [{ "p": "payload" }, { "p": "topic", "vt": "str" }],
"repeat": "",
"crontab": "",
"once": false,
"onceDelay": 0.1,
"topic": "",
"payload": "",
"payloadType": "date",
"x": 96.5,
"y": 1952,
"wires": [["2b536512e8c7aef2"]]
},
{
"id": "20bbd2d1408b8dc5",
"type": "change",
"z": "23dbb1ee.bc2e8e",
"name": "",
"rules": [
{
"t": "set",
"p": "channelId_outbound",
"pt": "flow",
"to": "LongFast",
"tot": "str"
}
],
"action": "",
"property": "",
"from": "",
"to": "",
"reg": false,
"x": 772,
"y": 2027,
"wires": [[]]
},
{
"id": "c6cb373157be01d6",
"type": "change",
"z": "23dbb1ee.bc2e8e",
"name": "",
"rules": [
{
"t": "set",
"p": "gatewayId_outbound",
"pt": "flow",
"to": "\"!55c7312c\"",
"tot": "str"
}
],
"action": "",
"property": "",
"from": "",
"to": "",
"reg": false,
"x": 772,
"y": 2066,
"wires": [[]]
},
{
"id": "24199ec7eaf89c1a",
"type": "change",
"z": "23dbb1ee.bc2e8e",
"name": "",
"rules": [
{
"t": "set",
"p": "portnum_outbound",
"pt": "flow",
"to": "3",
"tot": "num"
}
],
"action": "",
"property": "",
"from": "",
"to": "",
"reg": false,
"x": 774,
"y": 2106,
"wires": [[]]
},
{
"id": "de38ad5ef343623a",
"type": "change",
"z": "23dbb1ee.bc2e8e",
"name": "",
"rules": [
{
"t": "set",
"p": "from_outbound",
"pt": "flow",
"to": "1439117612",
"tot": "num"
}
],
"action": "",
"property": "",
"from": "",
"to": "",
"reg": false,
"x": 781,
"y": 2146,
"wires": [[]]
},
{
"id": "d435e8abe0852f93",
"type": "change",
"z": "23dbb1ee.bc2e8e",
"name": "",
"rules": [
{
"t": "set",
"p": "to_outbound",
"pt": "flow",
"to": "4294967295",
"tot": "num"
}
],
"action": "",
"property": "",
"from": "",
"to": "",
"reg": false,
"x": 790,
"y": 2188,
"wires": [[]]
},
{
"id": "1f8d172708898860",
"type": "function",
"z": "23dbb1ee.bc2e8e",
"name": "Assemble Position protobuf",
"func": "msg.protobufType=null;\nmsg.payload =\n{\n \"packet\": {\n \"from\": flow.get(\"from_outbound\"),\n \"to\": flow.get(\"to_outbound\"), \n \"decoded\":{\n //how ENUMS are handled here\n //portnum is decoded as string but encoded as number\n //in the encode/decode node-red nodes based on protobuf.js\n \"portnum\": flow.get(\"portnum_outbound\"),\n \"payload\": msg.payload \n } \n },\n\n \"channelId\": flow.get(\"channelId_outbound\"),\n \"gatewayId\": flow.get(\"gatewayId_outbound\"),\n};\nreturn msg;\n//info on how to get json data into protobuf \"bytes\" field\n//https://github.com/protobufjs/protobuf.js/wiki/Changes-in-ProtoBuf.js-3.8",
"outputs": 1,
"noerr": 0,
"initialize": "",
"finalize": "",
"libs": [],
"x": 1086,
"y": 2019,
"wires": [["b8ccf1cfe8bf40a3"]]
},
{
"id": "b8ccf1cfe8bf40a3",
"type": "encode",
"z": "23dbb1ee.bc2e8e",
"name": "",
"protofile": "a0d4288141f6a629",
"protoType": "ServiceEnvelope",
"x": 1287,
"y": 2020,
"wires": [["dbc78f035c9c2b56", "a002c148f3a06bac"]]
},
{
"id": "03a7e69ca6d471fe",
"type": "debug",
"z": "23dbb1ee.bc2e8e",
"name": "show hex string",
"active": true,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "true",
"targetType": "full",
"statusVal": "",
"statusType": "auto",
"x": 1319,
"y": 2180,
"wires": []
},
{
"id": "dbc78f035c9c2b56",
"type": "function",
"z": "23dbb1ee.bc2e8e",
"name": "dump payload as hex string",
"func": "var hex=Buffer.from(msg.payload,\"hex\");\nmsg.payload=hex.toString(\"hex\");\nreturn msg;",
"outputs": 1,
"noerr": 0,
"initialize": "",
"finalize": "",
"libs": [],
"x": 1096,
"y": 2178,
"wires": [["03a7e69ca6d471fe"]]
},
{
"id": "2b536512e8c7aef2",
"type": "function",
"z": "23dbb1ee.bc2e8e",
"name": "Inject lat lon alt",
"func": "msg.payload={\n \"latitudeI\": 399600000,\n \"longitudeI\": -862600000,\n \"altitude\": 100\n}\nreturn msg;",
"outputs": 1,
"noerr": 0,
"initialize": "",
"finalize": "",
"libs": [],
"x": 277.5,
"y": 1953,
"wires": [["9443a9a980e54c75"]]
},
{
"id": "9443a9a980e54c75",
"type": "encode",
"z": "23dbb1ee.bc2e8e",
"name": "encode Position as protobuf",
"protofile": "dbab6472b07929a0",
"protoType": "Position",
"x": 506,
"y": 1953,
"wires": [["5c36d3a7f4dca14e"]]
},
{
"id": "5c36d3a7f4dca14e",
"type": "change",
"z": "23dbb1ee.bc2e8e",
"name": "",
"rules": [
{
"t": "set",
"p": "nested_outbound",
"pt": "flow",
"to": "payload",
"tot": "msg"
}
],
"action": "",
"property": "",
"from": "",
"to": "",
"reg": false,
"x": 776,
"y": 1952,
"wires": [
[
"20bbd2d1408b8dc5",
"c6cb373157be01d6",
"24199ec7eaf89c1a",
"de38ad5ef343623a",
"d435e8abe0852f93",
"04d0c4a5f3485c6f"
]
]
},
{
"id": "04d0c4a5f3485c6f",
"type": "function",
"z": "23dbb1ee.bc2e8e",
"name": "dump payload as base64 string",
"func": "var hex=Buffer.from(msg.payload,\"base64\");\nmsg.payload=hex.toString(\"base64\");\nreturn msg;",
"outputs": 1,
"noerr": 0,
"initialize": "",
"finalize": "",
"libs": [],
"x": 1082,
"y": 1952,
"wires": [["1f8d172708898860"]]
},
{
"id": "a002c148f3a06bac",
"type": "decode",
"z": "23dbb1ee.bc2e8e",
"name": "test decode Protobuf",
"protofile": "a0d4288141f6a629",
"protoType": "ServiceEnvelope",
"x": 1249,
"y": 1860,
"wires": [["4b6fc79398d05782"]]
},
{
"id": "4b6fc79398d05782",
"type": "debug",
"z": "23dbb1ee.bc2e8e",
"name": "test entire payload",
"active": true,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "payload",
"targetType": "msg",
"statusVal": "",
"statusType": "auto",
"x": 1458,
"y": 1859,
"wires": []
},
{
"id": "a0d4288141f6a629",
"type": "protobuf-file",
"protopath": "E:\\Meshtastic-protobufs-master\\mqtt.proto",
"watchFile": true,
"keepCase": false
},
{
"id": "dbab6472b07929a0",
"type": "protobuf-file",
"protopath": "E:\\Meshtastic-protobufs-master\\mesh.proto",
"watchFile": true,
"keepCase": false
}
]
```
Sending a position to a device for broadcast to the mesh is much easier with JSON. This introduces a new MQTT Service Envelope type: "sendposition". A valid MQTT envelope and message to broadcast lat, lon, altitude looks like this.
```json
{
"sender": "someSender",
"type": "sendposition",
"payload": {
"latitude_i": 399600000,
"longitude_i": -862600000,
"altitude": 100,
"time": 1670201543
}
}
```
An example of doing this in node-red:
[<img src="/documents/mqtt/PosJSON.jpg" style={{zoom:'50%'}} />](/documents/mqtt/PosJSON.jpg)

53
docs/software/mqtt/python.mdx Normal file
View file

@ -0,0 +1,53 @@
---
id: mqtt-python
title: Python
sidebar_label: Python
sidebar_position: 2
---
### Sending/receiving messages on mosquitto server using python
Here is an example publish message in python:
```python
#!/usr/bin/env python3
import paho.mqtt.client as mqtt
from random import randrange, uniform
import time
client = mqtt.Client("some_client_id")
client.connect('localhost')
while True:
randNumber = uniform(20.0, 21.0)
client.publish("env/test/TEMPERATURE", randNumber)
print("Just published " + str(randNumber) + " to topic TEMPERATURE")
time.sleep(1)
```
Here is example subscribe in python:
```python
#!/usr/bin/env python3
import paho.mqtt.client as paho
def on_message(mosq, obj, msg):
print("%-20s %d %s" % (msg.topic, msg.qos, msg.payload))
mosq.publish('pong', 'ack', 0)
def on_publish(mosq, obj, mid):
pass
if __name__ == '__main__':
client = paho.Client()
client.on_message = on_message
client.on_publish = on_publish
client.connect("localhost", 1883, 60)
client.subscribe("env/test/TEMPERATURE", 0)
while client.loop() == 0:
pass
```

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

@ -124,7 +124,7 @@ meshtastic --qr
Gets a preferences field.
Configuration values are described in: [Configuration](https://meshtastic.org/docs/settings).
Configuration values are described in: [Configuration](https://meshtastic.org/docs/configuration).
```shell title="Usage"
meshtastic --get lora
@ -135,7 +135,7 @@ meshtastic --get lora.region
Sets a preferences field.
Configuration values are described in: [Configuration](https://meshtastic.org/docs/settings).
Configuration values are described in: [Configuration](https://meshtastic.org/docs/configuration).
```shell title="Usage"
meshtastic --set lora.region Unset
@ -306,7 +306,16 @@ meshtastic --sendping
Traceroute from connected node to a destination. You need pass the destination ID as an argument. Only nodes that have the encryption key can be traced.
```shell title="Usage"
meshtastic --traceroute 'ba4bf9d0'
meshtastic --traceroute '!ba4bf9d0'
```
### --request-telemetry
Request telemetry from a node. You need to pass the destination ID as an argument with '--dest'. For repeaters, the nodeNum is required.
```shell title="Usage"
meshtastic --request-telemetry --dest '!ba4bf9d0'
meshtastic --request-telemetry --dest 1828779180
```
### --ack

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

@ -95,9 +95,9 @@ Toggling `set-ham` changes your device settings in the following ways.
| Setting | `set-ham` Default | Normal Default |
| :----------: | :---------------: | :------------------------------------------------------------------------: |
| `IsLicensed` | `true` | See [User Config - IsLicensed](/docs/settings/config/user#is-licensed-ham) |
| `LongName` | _Your CallSign_ | See [User Config - LongName](/docs/settings/config/user#long-name) |
| `ShortName` | _Abrv CallSign_ | See [User Config - ShortName](/docs/settings/config/user#short-name) |
| `IsLicensed` | `true` | See [User Config - IsLicensed](/docs/configuration/radio/user#is-licensed-ham) |
| `LongName` | _Your CallSign_ | See [User Config - LongName](/docs/configuration/radio/user#long-name) |
| `ShortName` | _Abrv CallSign_ | See [User Config - ShortName](/docs/configuration/radio/user#short-name) |
| `PSK` | `""` | See [Channel Settings - PSK](#changing-the-preshared-key) |
## Changing the preshared key

4
docs/software/web-client.mdx
View file

@ -31,7 +31,7 @@ This can be found on the screen of the device, via your router's DHCP lease page
:::
You can accessing your device over HTTP after you set up your [Network Connection](/docs/settings/config/network)
You can accessing your device over HTTP after you set up your [Network Connection](/docs/configuration/radio/network)
### Bluetooth
@ -51,6 +51,6 @@ The web interface is included in firmware releases. When a new firmware version
## Self Hosting
The source code for the WebUI can be found on out [GitHub](https://github.com/meshtastic/web)
The source code for the WebUI can be found on our [GitHub](https://github.com/meshtastic/web)
Instructions for building and running the project can be found in the repo's readme.

6
docusaurus.config.js
View file

@ -15,11 +15,6 @@ const config = {
organizationName: "meshtastic",
projectName: "meshtastic",
themeConfig: /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ {
announcementBar: {
id: "2_0",
content:
'🎉 Meshtastic 2.0 Has Now Launched! Check it Out <a href="/2.0">Here</a> 🎉',
},
docs: {
sidebar: {
autoCollapseCategories: true,
@ -86,7 +81,6 @@ const config = {
},
algolia: {
appId: "IG2GQB8L3V",
// trunk-ignore(gitleaks/generic-api-key)
apiKey: "2e4348812173ec7ea6f7879c7032bb21",
indexName: "meshtastic",
contextualSearch: false,

50
package.json
View file

@ -15,39 +15,35 @@
"crowdin:sync": "docusaurus write-translations && crowdin upload && crowdin download"
},
"dependencies": {
"@crowdin/cli": "^3.2.2",
"@algolia/client-search": "^4.19.1",
"@docusaurus/core": "3.0.0-alpha.0",
"@docusaurus/plugin-content-docs": "3.0.0-alpha.0",
"@docusaurus/preset-classic": "3.0.0-alpha.0",
"@docusaurus/theme-common": "3.0.0-alpha.0",
"@docusaurus/theme-mermaid": "3.0.0-alpha.0",
"@headlessui/react": "^1.7.16",
@crowdin/cli": "^3.2.2",
"@algolia/client-search": "^4.20.0",
"@docusaurus/core": "3.0.0",
"@docusaurus/plugin-content-docs": "3.0.0",
"@docusaurus/preset-classic": "3.0.0",
"@docusaurus/theme-common": "3.0.0",
"@docusaurus/theme-mermaid": "3.0.0",
"@heroicons/react": "^2.0.18",
"@mdx-js/react": "^2.3.0",
"@meshtastic/meshtasticjs": "2.2.0-0",
"autoprefixer": "^10.4.14",
"@mdx-js/react": "^3.0.0",
"@meshtastic/meshtasticjs": "2.2.13-1",
"autoprefixer": "^10.4.16",
"base64-js": "^1.5.1",
"clsx": "^2.0.0",
"dotenv": "^16.3.1",
"framer-motion": "^6.5.1",
"postcss": "^8.4.27",
"postcss": "^8.4.31",
"react": "^18.2.0",
"react-dom": "^18.2.0",
"react-icons": "^4.10.1",
"react-responsive-carousel": "^3.2.23",
"swr": "^2.2.0",
"tailwindcss": "^3.3.3",
"url-search-params-polyfill": "^8.2.4",
"use-breakpoint": "^3.1.1"
"react-icons": "^4.12.0",
"swr": "^2.2.4",
"tailwindcss": "^3.3.5"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "3.0.0-alpha.0",
"@tailwindcss/typography": "^0.5.9",
"@tsconfig/docusaurus": "^2.0.0",
"@types/node": "^20.4.8",
"@types/react": "^18.2.18",
"@types/react-dom": "^18.2.7",
"rome": "^12.1.3",
"typescript": "^5.1.6"
"@docusaurus/module-type-aliases": "3.0.0",
"@tailwindcss/typography": "^0.5.10",
"@tsconfig/docusaurus": "^2.0.2",
"@types/node": "^20.9.0",
"@types/react": "^18.2.37",
"@types/react-dom": "^18.2.15",
"biome": "^0.3.3",
"typescript": "^5.2.2"
}
}

6722
pnpm-lock.yaml
View file

File diff suppressed because it is too large Load diff

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