mudhorn/meshtastic
1
0
Fork 0
mirror of https://github.com/meshtastic/meshtastic.git synced 2025-01-12 22:37:33 -08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge branch 'meshtastic:master' into master

Browse source
This commit is contained in:
Daniel BP 2022-03-09 10:11:53 -03:00 committed by GitHub
parent d206286ef2 125ad871e5
commit 0db92d7fdf
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
132 changed files with 12006 additions and 11377 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -1,20 +1,19 @@
---
name: Documentation Change Request
about: Create a report about our documentation to help us improve
title: 'Documentation Change Request'
labels: ''
assignees: ''
title: "Documentation Change Request"
labels: ""
assignees: ""
---
Please - if you just have a question, post in our [forum](https://meshtastic.discourse.group/) instead. Please reserve this system for requesting changes to the Meshtastic documentation.
Please - if you just have a question, post in our [forum](https://meshtastic.discourse.group) instead. Please reserve this system for requesting changes to the Meshtastic documentation.
**Describe what section of the docs is outdated or otherwise in need of change**
Be as clear and concise as possible. Provide a URL or GitHub path to the doc you are referencing.
Be as clear and concise as possible. Provide a URL or GitHub path to the doc you are referencing.
**Suggested Changes**
What specifically in that documentation area needs to be changed / removed / added?
If possible provide replacement text when requesting changes or new text to fill in missing documentation.
What specifically in that documentation area needs to be changed / removed / added?
If possible provide replacement text when requesting changes or new text to fill in missing documentation.
**Additional Notes**
Add any other context here.
Add any other context here.

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

@ -22,7 +22,7 @@ jobs:
- name: Install protoc-gen-doc
run: go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc
- name: Checkout code
uses: actions/checkout@v2
uses: actions/checkout@v3
with:
submodules: true
- name: Generate protobuf docs

25
.github/workflows/pr.yml vendored
View file

@ -6,11 +6,26 @@ jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Checkout code & submodules
uses: actions/checkout@v3
with:
submodules: true
- uses: actions/setup-node@v2-beta
- name: Setup pnpm
uses: pnpm/action-setup@v2.2.1
with:
node-version: 16
- run: yarn install
- run: yarn run build
version: latest
- name: Setup NodeJS
uses: actions/setup-node@v3
with:
node-version: 17
- name: Install Dependencies
run: pnpm install
- name: Lint & Format
run: pnpm format
- name: Build Site
run: pnpm build

2
.github/workflows/update_protobufs.yml vendored
View file

@ -8,7 +8,7 @@ jobs:
steps:
- name: Checkout code
uses: actions/checkout@v2
uses: actions/checkout@v3
with:
submodules: true

3
.gitmodules vendored
View file

@ -4,9 +4,6 @@
[submodule "protobufs"]
path = protobufs
url = https://github.com/meshtastic/meshtastic-protobufs/
[submodule "public/design"]
path = public/design
url = https://github.com/meshtastic/meshtastic-design/
[submodule "static/design"]
path = static/design
url = https://github.com/meshtastic/meshtastic-design/

66
How to configure a device as a relay.md
View file

@ -1,66 +0,0 @@
If you have not already done so, download and have the latest firmware for your device, and flash it to your device.
There is a very good guide for doing this [here](https://github.com/meshtastic/Meshtastic-device#firmware-installation).
Part of this guide covers the installation of pip which must be done first.
**For Linux users:**
From a terminal copy and paste the following command
```bash
pip3 install meshtastic
```
**For Windows users:**
_Insert instructions on how to install meshtastic here_
**For Mac OS users:**
_Insert instructions on how to install meshtastic here_
Using a text editor, open a blank document and copy and paste the following text
```bash
#/bin/sh
clear
echo "Set all Router Parameter"
meshtastic --setowner MeshRelay
meshtastic --settime
meshtastic --set is_router true
meshtastic --setlat 53.9 --setlon -6.8 --setalt 91
meshtastic –info
```
Alter the parameter `meshtastic --setowner MeshRelay` and change "MeshRelay" to your chosen name
This will set the name of the relay.
Alter the parameter `meshtastic --setlat 53.9 --setlon -6.8 --setalt 91`
This parameter sets the latitude, longitude and altitude of your relay, assuming it doesn’t have a working or installed GPS. If you have a working GPS, the device will connect to a GPS satellite and update the latitude, longitude and altitude.
Using this site, find the location of where you plan to place your relay.
[Get latitude, longitude and altitude](https://www.maps.ie/coordinates.html)
Move the place marker over the spot where your relay is to placed, and it will give you the latitude, longitude and altitude.
Enter the latitude and longitude to one decimal place and altitude is recorded in meters in the configuration file.
As a suggestion, save the configuration file into the same folder, where you have downloaded the latest device firmware.
Save the file as `relay.sh`
Go to the folder where you have saved the script and right click on "Open in Terminal"
At the command prompt in Terminal, enter the following command
```bash
sudo chmod -R 777 relay.sh
```
This enables the script to be executed as a program.
Then at the prompt enter: `./relay.sh`
That's it, your Meshtastic device is now configure to operate as a relay.
**Some explanations of other parameters**
`meshtastic --set is_router true` tells node to be power conscious and to only power up the screen/BLE if the user presses a button. Eventually will also imply that "this node has good line of sight and should be heavily weighted when routing". This is the option you should probably use.
`meshtastic --set is_low_power true`. This option means "work like a regular node, with the normal sleep/wake pattern but even though you see power coming in on USB don’t constantly stay awake". You **almost certainly don't want this option** but it is useful for some edge cases (solar powered node that still talks Bluetooth to the app etc...).

3
docs/about/concepts/channels.md
View file

@ -3,9 +3,10 @@ id: channels
title: Channels
sidebar_label: Channels
---
## Overview
Meshtastic Channels: Can create a *somewhat* secure method of communication on the same mesh network. The channel can be encrypted to prevent normal people from listening in on the traffic. But, it could probably be easily [cracked](https://crypto.stackexchange.com/questions/46559/what-are-the-chances-that-aes-256-encryption-is-cracked) by determined individuals. See [Channel Config](https://meshtastic.org/docs/software/settings/channel) for more info. It is also possible that your location could be triangulated by determined individuals.
Meshtastic Channels: Can create a _somewhat_ secure method of communication on the same mesh network. The channel can be encrypted to prevent normal people from listening in on the traffic. But, it could probably be easily [cracked](https://crypto.stackexchange.com/questions/46559/what-are-the-chances-that-aes-256-encryption-is-cracked) by determined individuals. See [Channel Config](/docs/settings/channel) for more info. It is also possible that your location could be triangulated by determined individuals.
## Channels

1
docs/about/concepts/clients.md
View file

@ -3,6 +3,7 @@ id: clients
title: Clients
sidebar_label: Clients
---
## Overview
## Available Clients

23
docs/about/concepts/external-devices.md
View file

@ -3,32 +3,33 @@ id: external-devices
title: External Devices
sidebar_label: External Devices
---
## Overview
External hardware can be connected to your device using a GPIO (General Purpose Input/Output) interface. Using GPIO, you are able to connect external buttons, circuits, rotary encoders, environmental sensors and more. Many of our plugins offer solutions to implement additional functionality.
External hardware can be connected to your device using a GPIO (General Purpose Input/Output) interface. Using GPIO, you are able to connect external buttons, circuits, rotary encoders, environmental sensors and more. Many of our modules offer solutions to implement additional functionality.
Soldering is likely required when attaching items to your device, so practice your skills elsewhere before trying on your radio. If you're not careful or don't know what your doing, you can damage your hardware.
## Features using External Devices
Many of our plugins require external hardware to be attached to the device.
Many of our modules require external hardware to be attached to the device.
### Canned Message Plugin
### Canned Message Module
Requires use of the [rotary encoder plugin](#rotary-encoder-plugin). The rotary encoder acts as an input to select one of up to 50 customizable messages. This way you can send canned messages without needing to pair your device to a phone.
Requires use of the [rotary encoder module](#rotary-encoder-module). The rotary encoder acts as an input to select one of up to 50 customizable messages. This way you can send canned messages without needing to pair your device to a phone.
### Environmental Measurment Plugin
### Environmental Measurement Module
Broadcast environmental measurments to your mesh! Temperature, Humidity, Pressure, & VOC Gas are all options that are currently available with the supported sensors.
Broadcast environmental measurements to your mesh! Temperature, Humidity, Pressure, & VOC Gas are all options that are currently available with the supported sensors.
### External Notifications Plugin
### External Notifications Module
Use lights, buzzers, or speakers to alert you of incoming messages.
### Rotary Encoder Plugin
### Rotary Encoder Module
Currently used only for the [canned message plugin](#canned-message-plugin), this plugin allows you to connect a rotary encoder to be used as an additional input to the device.
Currently used only for the [canned message module](#canned-message-module), this module allows you to connect a rotary encoder to be used as an additional input to the device.
### Serial Plugin
### Serial Module
Available for ESP32 based devices, the serial plugin allows you to send messages over the mesh by sending strings over a serial port.
Available for ESP32 based devices, the serial moduleallows you to send messages over the mesh by sending strings over a serial port.

3
docs/about/concepts/internet.md
View file

@ -3,9 +3,10 @@ id: internet
title: Internet Connectivity
sidebar_label: Internet Connectivity
---
## Overview
Captive Portal: Using Meshtastic, you can create a separate Wifi network for you join your phone or computer on a mesh network. See [Web Interface](https://meshtastic.org/docs/software/web/web-app-software) for more info. This is ideal in a situation where you are remote, such as in the forest, on a mountain, or if there is a major power/internet outage such as in a storm or other disaster.
Captive Portal: Using Meshtastic, you can create a separate Wifi network for you join your phone or computer on a mesh network. See [Web Interface](/docs/software/web/web-app-software) for more info. This is ideal in a situation where you are remote, such as in the forest, on a mountain, or if there is a major power/internet outage such as in a storm or other disaster.
## Features using Internet Connectivity

5
docs/about/concepts/mesh.md
View file

@ -3,10 +3,11 @@ id: mesh
title: Mesh Routing
sidebar_label: Mesh Routing
---
## Overview
Mesh Networking: An interconnected network by using [low-power radios](https://meshtastic.org/docs/hardware) to connect other low-power radios using LoRa to be able to send and receive messages and data. This can be completely separate from any other networks such as the internet. You can start small and get two devices to start experimenting. Do not expect to stream music or videos as LoRa is intended for smaller, lower bandwidth type uses such as text communication.
Mesh Networking: An interconnected network by using [low-power radios](/docs/hardware) to connect other low-power radios using LoRa to be able to send and receive messages and data. This can be completely separate from any other networks such as the internet. You can start small and get two devices to start experimenting. Do not expect to stream music or videos as LoRa is intended for smaller, lower bandwidth type uses such as text communication.
## Devices
## Routers

1
docs/about/concepts/overview.md
View file

@ -3,4 +3,5 @@ id: overview
title: Meshtastic Concepts
sidebar_label: Concepts Overview
---
## Overview

2
docs/about/overview.md
View file

@ -4,6 +4,7 @@ title: About Meshtastic
sidebar_label: About Meshtastic
slug: /about
---
:::info
This section is new and is still being developed. If you'd like to contribute, please do!
:::
@ -25,6 +26,7 @@ When a receiving radio captures a packet, it checks to see if it has heard that
For each message a radio rebroadcasts, it marks the "hop limit" down by one. When a radio receives a packet with a hop limit of zero, it will not rebroadcast the message.
## Who develops Meshtastic
<!--- FIXME add Github organization list/contributor list --->
Meshtastic is an open source project available on GitHub. Our generous volunteers donate their personal time to write and maintain this codebase. If you would like to contribute see our [GitHub](https://github.com/meshtastic), join our [Discord server](https://discord.com/invite/UQJ5QuM7vq), and read up on our [forum](https://meshtastic.discourse.group).

2
docs/academy/academy.md
View file

@ -12,4 +12,4 @@ I want something that just works.
Tinkerer
Maker
Maker

20
docs/developers/android/build.md
View file

@ -6,11 +6,11 @@ sidebar_label: Building Android App
## Build instructions
If you would like to develop this application we'd love your help! These build instructions are brief and should be improved, please send a PR if you can.
If you would like to develop this application we'd love your help! These build instructions are brief and should be improved, please send a PR if you can.
* Use Android Studio 4.1.2 to build/debug (other versions might work but no promises)
* Use `git submodule update --init --recursive` to pull in the various submodules we depend on
* There are a few config files which you'll need to copy from templates included in the project. Run the following commands to do so:
- Use Android Studio 4.1.2 to build/debug (other versions might work but no promises)
- Use `git submodule update --init --recursive` to pull in the various submodules we depend on
- There are a few config files which you'll need to copy from templates included in the project. Run the following commands to do so:
```
rm ./app/google-services.json
@ -21,13 +21,14 @@ If you would like to develop this application we'd love your help! These build
cp ./app/special/curfirmwareversion.xml ./app/src/main/res/values/
```
* (Unfortunately) you need to get a (free) mapbox developer token [here](https://docs.mapbox.com/android/maps/guides/install/) and put that token in your user gradle.properties.
- (Unfortunately) you need to get a (free) mapbox developer token [here](https://docs.mapbox.com/android/maps/guides/install) and put that token in your user gradle.properties.
```
~/development/meshtastic/MeshUtil$ cat ~/.gradle/gradle.properties
MAPBOX_DOWNLOADS_TOKEN=sk.yourtokenherexxx
```
* Now you should be able to select "Run / Run" in the IDE and it will happily start running on your phone or the emulator.
- Now you should be able to select "Run / Run" in the IDE and it will happily start running on your phone or the emulator.
:::note
The emulators don't support Bluetooth, so some features can not be used in that environment.
@ -35,8 +36,8 @@ The emulators don't support Bluetooth, so some features can not be used in that
## Analytics setup
* Analytics are included but can be disabled by the user on the settings screen
* On dev devices
- Analytics are included but can be disabled by the user on the settings screen
- On dev devices
```shell
adb shell setprop debug.firebase.analytics.app com.geeksville.mesh
@ -44,10 +45,11 @@ adb shell setprop log.tag.FirebaseCrashlytics DEBUG
```
for verbose logging:
```shell
adb shell setprop log.tag.FA VERBOSE
```
## Publishing to google play
* Only supported if you are a core developer that needs to do releases
- Only supported if you are a core developer that needs to do releases

6
docs/developers/android/mapbox.md
View file

@ -12,9 +12,9 @@ In order to compile a new version of Meshtastic that can use MapBox you will nee
This is fairly simple to do.
* Create an account at MapBox
* Copy the public token associated with that account to the clipboard
* Paste that into the file "…/src/main/res/values/mapbox-token.xml"
- Create an account at MapBox
- Copy the public token associated with that account to the clipboard
- Paste that into the file "…/src/main/res/values/mapbox-token.xml"
## Examples of what can be achieved with MapBox

88
docs/developers/build.md
View file

@ -1,88 +0,0 @@
---
id: build-env
title: Creating a build/development environment
sidebar_label: Building Meshtastic
---
This project uses the simple PlatformIO build system. PlatformIO is an extension to Microsoft VSCode.
## GUI Installation
1. Install [Python](https://www.python.org/downloads/).
2. Install [Git](https://git-scm.com/downloads) or [GitHub Desktop](https://desktop.github.com/)
3. Install [Microsoft Visual Studio Code](https://code.visualstudio.com/)
4. Install [PlatformIO](https://platformio.org/platformio-ide).
5. Click the PlatformIO icon on the side bar.
![platformio icon](https://user-images.githubusercontent.com/47490997/89482668-77c7ea00-d7ee-11ea-8785-5faf8ff99800.png)
6. Under `Quick Access, Miscellaneous, Clone Git Project` enter the URL of the Meshtastic repo found [here](https://github.com/meshtastic/Meshtastic-device).
![image](https://user-images.githubusercontent.com/47490997/89483047-4c91ca80-d7ef-11ea-91f4-1d53d4e8acd9.png)
7. Select a file location to save the repo.
8. Once loaded, open the `platformio.ini` file.
9. At the line `default_envs` you can change it to the board type you are building for ie. `tlora-v2, tlora-v1, tlora-v2-1-1.6, tbeam, heltec, tbeam0.7` (boards are listed further down in the file).
10. The hardware can be configured for different countries by adding a definition to the `configuration.h` file. `#define HW_VERSION_US` or `HW_VERSION_EU433, HW_VERSION_EU865, HW_VERSION_CN, HW_VERSION_JP`. Other country settings can be found in `MeshRadio.h`. The default is `HW_VERSION_US`.
11. Click the PlatformIO icon on the side bar. Under `Project Tasks` you can now build or upload.
:::note
To get a clean build you may have to delete the auto-generated file `./.vscode/c_cpp_properties.json`, close and re-open Visual Studio and WAIT until the file is auto-generated before compiling again.
:::
## Manual Installation on Linux
1. On a Linux distro (like Ubuntu), ensure you have pre-requisites installed:
```
sudo apt-get update
sudo apt-get install python3 python3-dev g++ zip
```
2. Install PlatformIO (which is usually via wget/curl command).
```
wget https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py -O get-platformio.py
chmod +x get-platformio.py
python3 get-platformio.py
```
3. Clone the repo https://github.com/meshtastic/Meshtastic-device
4. Change into the Meshtastic-device and then download submodules
```
cd Meshtastic-device
git submodule update --init --recursive
```
Note: If you get an error like this:
```
Compiling .pio/build/rak4631_5005/src/plugins/PositionPlugin.cpp.o
src/nrf52/NRF52CryptoEngine.cpp:3:10: fatal error: ocrypto_aes_ctr.h: No such file or directory
```
then you need to run that submodule command from the main Meshtastic-device directory.
5. Activate the Platformio python virtual environment
```
source ~/.platformio/penv/bin/activate
```
6. Build everything (optionally just build what you really need by editing platformio.ini)
```
./bin/build-all.sh
```
7. See the newly built bits in release/archive/firmware-1.2.49.XXX.zip (where XXX is the git commit)
## Running the Native environment on Linux
(From @caveman99 )
- linux. flavour doesn't matter. in my case it Centos stream.
- pio run -e native
- then cd .pio/build/native
- gdb program
- on the gdb prompt, execute "run"
- if it eventually coredumps it returns to the gdb prompt, then run bt for a backtrace.
- the actual name of the binary is 'program'

28
docs/developers/firmware/build.md Normal file
View file

@ -0,0 +1,28 @@
---
id: build
title: Creating a build environment
sidebar_label: Building Meshtastic
---
Meshtastic uses the [PlatformIO](https://platformio.org) development environment, that enables easy multiplatform development and centralized tooling.
## Setup
1. Install PlatformIO, following the instructions available [here](https://platformio.org/platformio-ide).
2. Clone the `meshtastic-device` repository located [here](https://github.com/meshtastic/meshtastic-device). ([Instructions on cloning](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository))
3. Clone the [Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
```bash
git submodule update --init
```
4. Some utilities and scripts use the Python programming language, Downloads available [here](https://www.python.org/downloads).
## Building
1. Open the newly cloned folder in [Visual Studio Code](https://code.visualstudio.com).
1. To select the device you you wish to build for, first open your [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) (`Ctrl + Shift + P`) and enter: `platformio: Switch Project Environment` and select your target.
1. To build the firmware, simply run `PlatformIO: Build` from your command palette.
1. Finally flashing the firmware to your device is as easy as running `PlatformIO: Upload`

24
docs/developers/device/device-api.md → docs/developers/firmware/device-api.md
View file

@ -4,7 +4,7 @@ title: Bluetooth/serial/TCP protocol API
sidebar_label: Device API
---
This document describes the protocol for external API clients using our devices. If you are interested in running your own code on the device itself, see the [plugin API](plugin-api.md) documentation instead.
This document describes the protocol for external API clients using our devices. If you are interested in running your own code on the device itself, see the [module API](module-api.md) documentation instead.
The Device API is design to have only a simple stream of ToRadio and FromRadio packets and all polymorphism comes from the flexible set of Google Protocol Buffers which are sent over the wire. We use protocol buffers extensively both for the Bluetooth API and for packets inside the mesh or when providing packets to other applications on the phone.
@ -82,7 +82,7 @@ When the ESP32 advances fromnum, it will delay doing the notify by 100ms, in the
Note: that if the phone ever sees this number decrease, it means the ESP32 has rebooted.
Re: Queue management,
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
@ -111,16 +111,16 @@ SoftwareUpdateService UUID cb0b9a0b-a84c-4c0d-bdbb-442e3144ee30
Characteristics
| UUID | properties | description |
| ------------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------- |
| e74dd9c0-a301-4a6f-95a1-f0e1dbea8e1e | write,read | total image size, 32 bit, write this first, then read back to see if it was acceptable (0 mean not accepted) |
| e272ebac-d463-4b98-bc84-5cc1a39ee517 | write | data, variable sized, recommended 512 bytes, write one for each block of file |
| 4826129c-c22a-43a3-b066-ce8f0d5bacc6 | write | crc32, write last - writing this will complete the OTA operation, now you can read result |
| 5e134862-7411-4424-ac4a-210937432c77 | read,notify | result code, readable but will notify when the OTA operation completes |
| 5e134862-7411-4424-ac4a-210937432c67 | write | sets the region for programming, currently only 0 (app) or 100 (spiffs) are defined, if not set app is assumed |
| GATT_UUID_SW_VERSION_STR/0x2a28 | read | We also implement these standard GATT entries because SW update probably needs them: |
| GATT_UUID_MANU_NAME/0x2a29 | read | |
| GATT_UUID_HW_VERSION_STR/0x2a27 | read | |
| UUID | properties | description |
| ------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------- |
| e74dd9c0-a301-4a6f-95a1-f0e1dbea8e1e | write,read | total image size, 32 bit, write this first, then read back to see if it was acceptable (0 mean not accepted) |
| e272ebac-d463-4b98-bc84-5cc1a39ee517 | write | data, variable sized, recommended 512 bytes, write one for each block of file |
| 4826129c-c22a-43a3-b066-ce8f0d5bacc6 | write | crc32, write last - writing this will complete the OTA operation, now you can read result |
| 5e134862-7411-4424-ac4a-210937432c77 | read,notify | result code, readable but will notify when the OTA operation completes |
| 5e134862-7411-4424-ac4a-210937432c67 | write | sets the region for programming, currently only 0 (app) or 100 (spiffs) are defined, if not set app is assumed |
| GATT_UUID_SW_VERSION_STR/0x2a28 | read | We also implement these standard GATT entries because SW update probably needs them: |
| GATT_UUID_MANU_NAME/0x2a29 | read | |
| GATT_UUID_HW_VERSION_STR/0x2a27 | read | |
#### DeviceInformationService

0
docs/developers/device/documents.md → docs/developers/firmware/documents.md
View file

6
docs/developers/device/encryption.md → docs/developers/firmware/encryption.md
View file

@ -9,7 +9,7 @@ Cryptography is tricky, so we've tried to 'simply' apply standard crypto solutio
- 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).
Always keep in mind [xkcd's note on encryption](https://xkcd.com/538/).
Always keep in mind [xkcd's note on encryption](https://xkcd.com/538).
## Summary of strengths/weaknesses of our current implementation
@ -31,7 +31,7 @@ Possible future areas of work (if there is enough interest - post in our [forum]
If you are reviewing our implementation, this is a brief statement of our method.
- We do all crypto at the SubPacket (payload) level only, so that all meshtastic nodes will route for others - even those channels which are encrypted with a different key.
- Mostly based on reading [Wikipedia](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_(CTR)) and using the modes the ESP32 provides support for in hardware.
- Mostly based on reading [Wikipedia](<https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_(CTR)>) and using the modes the ESP32 provides support for in hardware.
- We use AES256-CTR as a stream cypher (with zero padding on the last BLOCK) because it is well supported with hardware acceleration.
- Our AES key is 128 or 256 bits, shared as part of the 'Channel' specification.
- The node number concatenated with the packet number is used as the NONCE. This nonce will be stored in flash in the device and should essentially never repeat. If the user makes a new 'Channel' (i.e. picking a new random 256 bit key), the packet number will start at zero.
@ -51,4 +51,4 @@ I'm assuming that meshtastic is being used to hike in places where someone capab
- I think the bigger encryption question is "what does the encryption need to do"? As it stands, an attacker who has yet to capture any of the devices cannot reasonably capture text or location data. An attacker who captures any device in the channel/mesh can read everything going to that device, everything stored on that device, and any other communication within the channel that they captured in encrypted form. If that capability basically matches your expectations, it is suitable for whatever adventures this was intended for, then, based on information publicly available or widely disclosed, the encryption is good. If those properties are distressing (like, device history is deliberately limited and you don't want a device captured today to endanger the information sent over the channel yesterday) we could talk about ways to achieve that (most likely synchronizing time and replacing the key with its own SHA256 every X hours, and ensuring the old key is not retained unnecessarily).
- Two other things to keep in mind are that AES-CTR does not itself provide authenticity (e.g. an attacker can flip bits in replaying data and scramble the resulting plaintext), and that the current scheme gives some hints about transmission in the size. So, if you worry about an adversary deliberately messing-up messages or knowing the length of a text message, it looks like those might be possible.
I'm guessing that the network behaves somewhat like a store-and-forward network - or, at least, that the goal is to avoid establishing a two-way connection to transmit data. I'm afraid I haven't worked with mesh networks much, but remember studying them briefly in school about ten years ago.
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.

0
docs/developers/device/http-api.md → docs/developers/firmware/http-api.md
View file

62
docs/developers/device/mesh-alg.md → docs/developers/firmware/mesh-alg.md
View file

@ -6,7 +6,7 @@ sidebar_label: Mesh algorithm
## Current Algorithm
The routing protocol for Meshtastic is really quite simple (and suboptimal). It is heavily influenced by the mesh routing algorithm used in [RadioHead](https://www.airspayce.com/mikem/arduino/RadioHead/) (which was used in very early versions of this project). It has four conceptual layers.
The routing protocol for Meshtastic is really quite simple (and suboptimal). It is heavily influenced by the mesh routing algorithm used in [RadioHead](https://www.airspayce.com/mikem/arduino/RadioHead) (which was used in very early versions of this project). It has four conceptual layers.
### A Note About Protocol Buffers
@ -23,23 +23,23 @@ This preamble allows receiving radios to synchronize clocks and start framing. W
This layer is conventional non-reliable LoRa packet transmission. The transmitted packet has the following representation before encoding for transmission:
| Offset | Length | Type | Usage |
|--------|--------|------|-------|
| 0x00 | 1 byte | Integer | syncWord, always `0x2B`. |
| 0x01 | 4 bytes | Integer | Packet header: Destination. The destination's unique NodeID. `0xFFFFFFFF` for broadcast. |
| 0x05 | 4 bytes | Integer | Packet Header: Sender. The sender's unique NodeID. |
| 0x09 | 4 bytes | Integer | Packet Header: The sending node's unique packet ID for this packet. |
| 0x0D | 32 bits | Bits | Packet Header: Flags. See the [header flags](#packet-header-flags) for usage. |
| 0x11 .. 0xFD | Varies, maximum of 237 bytes. | Bytes | Actual packet data. Unused bytes are not transmitted. |
| 0xFE .. 0xFF | 2 Bytes | Bytes | Unused. |
| Offset | Length | Type | Usage |
| ------------ | ----------------------------- | ------- | ---------------------------------------------------------------------------------------- |
| 0x00 | 1 byte | Integer | syncWord, always `0x2B`. |
| 0x01 | 4 bytes | Integer | Packet header: Destination. The destination's unique NodeID. `0xFFFFFFFF` for broadcast. |
| 0x05 | 4 bytes | Integer | Packet Header: Sender. The sender's unique NodeID. |
| 0x09 | 4 bytes | Integer | Packet Header: The sending node's unique packet ID for this packet. |
| 0x0D | 32 bits | Bits | Packet Header: Flags. See the [header flags](#packet-header-flags) for usage. |
| 0x11 .. 0xFD | Varies, maximum of 237 bytes. | Bytes | Actual packet data. Unused bytes are not transmitted. |
| 0xFE .. 0xFF | 2 Bytes | Bytes | Unused. |
#### Packet Header Flags
| Index | # of Bits | Usage |
|-------|-----------|-------|
| 0 | 3 | HopLimit (see note in Layer 3) |
| 3 | 1 | WantAck |
| 4 .. 32 | 28 | Currently unused |
| Index | # of Bits | Usage |
| ------- | --------- | ------------------------------ |
| 0 | 3 | HopLimit (see note in Layer 3) |
| 3 | 1 | WantAck |
| 4 .. 32 | 28 | Currently unused |
#### Usage Details
@ -49,26 +49,26 @@ This layer is conventional non-reliable LoRa packet transmission. The transmitte
- **Packet Header - Unique ID:** The ID is a large, 32 bit ID to ensure there is enough unique state to protect an encrypted payload from attack.
- **Payload:** An encrypted and packed protobuf encoding of the SubPacket protobuf. Only the SubPacket is encrypted, while headers are not. This allows the option of eventually allowing nodes to route packets without knowing anything about the encrypted payload. For more information, see the [encryption](/docs/developers/device/encryption) and [protobufs](/docs/developers/protobufs/api) documentation. Any data past the maximum length is truncated.
- **Payload:** An encrypted and packed protobuf encoding of the SubPacket protobuf. Only the SubPacket is encrypted, while headers are not. This allows the option of eventually allowing nodes to route packets without knowing anything about the encrypted payload. For more information, see the [encryption](/docs/developers/firmware/encryption) and [protobufs](/docs/developers/protobufs/api) documentation. Any data past the maximum length is truncated.
#### Collision Avoidance
All transmitters must listen before attempting to transmit. If another node is heard transmitting, the listening node will reattempt transmission after a calculated delay. The delay depends on various settings and is based on Semtech's [LoRa Modem Design Guide](/documents/LoRa_Design_Guide.pdf), section 4 and implemented in `RadioInterface::getPacketTime`. The following tables contains some calculated values for how long it takes to transmit a packet, which is used to calculate the delay.
| Payload Bytes | Spreading Factor | Bandwidth | Coding Rate | Time |
|---------------|------------------|-----------|-------------|------|
| 0 | 7 | 125 kHz | 4/5 | 13 ms |
| 237 | 7 | 125 kHz | 4/5 | 100 ms |
| 0 | 7 | 500 kHz | 4/5 | 4 ms |
| 237 | 7 | 500 kHz | 4/5 | 25 ms |
| 0 | 10 | 250 kHz | 4/7 | 51 ms |
| 237 | 10 | 250 kHz | 4/7 | 391 ms |
| 0 | 11 | 250 kHz | 4/6 | 101 ms |
| 237 | 11 | 250 kHz | 4/6 | 633 ms |
| 0 | 9 | 31.25 kHz | 4/8 | 201 ms |
| 237 | 9 | 31.25 kHz | 4/8 | 2.413 **seconds** |
| 0 | 12 | 125 kHz | 4/8 | 402 ms |
| 237 | 12 | 125 kHz | 4/8 | 3.482 **seconds** |
| Payload Bytes | Spreading Factor | Bandwidth | Coding Rate | Time |
| ------------- | ---------------- | --------- | ----------- | ----------------- |
| 0 | 7 | 125 kHz | 4/5 | 13 ms |
| 237 | 7 | 125 kHz | 4/5 | 100 ms |
| 0 | 7 | 500 kHz | 4/5 | 4 ms |
| 237 | 7 | 500 kHz | 4/5 | 25 ms |
| 0 | 10 | 250 kHz | 4/7 | 51 ms |
| 237 | 10 | 250 kHz | 4/7 | 391 ms |
| 0 | 11 | 250 kHz | 4/6 | 101 ms |
| 237 | 11 | 250 kHz | 4/6 | 633 ms |
| 0 | 9 | 31.25 kHz | 4/8 | 201 ms |
| 237 | 9 | 31.25 kHz | 4/8 | 2.413 **seconds** |
| 0 | 12 | 125 kHz | 4/8 | 402 ms |
| 237 | 12 | 125 kHz | 4/8 | 3.482 **seconds** |
The actual delay calculation is a random value between 100ms (a hardcoded minimum) and the time taken to transmit just the header, which is given in the table as a 0 Byte payload.
@ -81,7 +81,7 @@ The default messaging provided by Layer 1 is extended by setting the `WantAck` f
> This packet is being sent as a reliable message, we would prefer it to arrive at the destination. We would like to receive an ACK packet in response.
>
> Broadcast messages treat this flag specially: Since ACKs for broadcasts would rapidly flood the channel, the normal ACK behavior is suppressed. Instead, the original sender listens to see if at least one node is rebroadcasting this
packet (because naive flooding algorithm). If it hears that, the odds (given typical LoRa topologies) are very high that every node should eventually receive the message. So FloodingRouter.cpp generates an implicit ACK which is delivered to the original sender. If after some time we don't hear anyone rebroadcast our packet, we will timeout and retransmit, using the regular resend logic.
> packet (because naive flooding algorithm). If it hears that, the odds (given typical LoRa topologies) are very high that every node should eventually receive the message. So FloodingRouter.cpp generates an implicit ACK which is delivered to the original sender. If after some time we don't hear anyone rebroadcast our packet, we will timeout and retransmit, using the regular resend logic.
If a transmitting node does not receive an ACK (or NAK) packet within FIXME milliseconds, it will use Layer 1 to attempt a retransmission of the sent packet. A reliable packet (at this 'zero hop' level) will be resent a maximum of three times. If no ACK or NAK has been received by then the local node will internally generate a NAK (either for local consumption or use by higher layers of the protocol).

48
docs/developers/device/plugin-api.md → docs/developers/firmware/module-api.md
View file

@ -1,16 +1,16 @@
---
id: plugin-api
title: Plugin API
sidebar_label: Plugin API
id: module-api
title: Module API
sidebar_label: Module API
---
This is a tutorial on how to write small plugins which run on the device. Plugins are bits regular 'Arduino' code that can send and receive packets to other nodes/apps/PCs using our mesh.
This is a tutorial on how to write small modules which run on the device. Modules are bits of regular 'Arduino' code that can send and receive packets to other nodes/apps/PCs using our mesh.
## Key concepts
All plugins should be subclasses of MeshPlugin. By inheriting from this class and creating an instance of your new plugin your plugin will be automatically registered to receive packets.
All modules should be subclasses of MeshModule. By inheriting from this class and creating an instance of your new module your module will be automatically registered to receive packets.
Messages are sent to particular port numbers (similar to UDP networking). Your new plugin should eventually pick its own port number (see below), but at first you can simply use PRIVATE_APP (which is the default).
Messages are sent to particular port numbers (similar to UDP networking). Your new module should eventually pick its own port number (see below), but at first you can simply use PRIVATE_APP (which is the default).
Packets can be sent/received either as raw binary structures or as [Protobufs](https://developers.google.com/protocol-buffers).
@ -18,13 +18,13 @@ Packets can be sent/received either as raw binary structures or as [Protobufs](h
The relevant bits of the class hierarchy are as follows
- [MeshPlugin](http://github.com/meshtastic/meshtastic-device/tree/master/src/mesh/MeshPlugin.h) (in src/mesh/MeshPlugin.h) - you probably don't want to use this baseclass directly
- [SinglePortPlugin](http://github.com/meshtastic/meshtastic-device/tree/master/src/mesh/SinglePortPlugin.h) (in src/mesh/SinglePortPlugin.h) - for plugins that send/receive from a single port number (the normal case)
- [ProtobufPlugin](http://github.com/meshtastic/meshtastic-device/tree/master/src/mesh/ProtobufPlugin.h) (in src/mesh/ProtobufPlugin.h) - for plugins that send/receive a single particular Protobuf type. Inherit from this if you are using protocol buffers in your plugin.
- [MeshModule](http://github.com/meshtastic/meshtastic-device/tree/master/src/mesh/MeshModule.h) (in src/mesh/MeshModule.h) - you probably don't want to use this baseclass directly
- [SinglePortModule](http://github.com/meshtastic/meshtastic-device/tree/master/src/mesh/SinglePortModule.h) (in src/mesh/SinglePortModule.h) - for modules that send/receive from a single port number (the normal case)
- [ProtobufModule](http://github.com/meshtastic/meshtastic-device/tree/master/src/mesh/ProtobufModule.h) (in src/mesh/ProtobufModule.h) - for modules that send/receive a single particular Protobuf type. Inherit from this if you are using protocol buffers in your module.
You will typically want to inherit from either SinglePortPlugin (if you are just sending/receiving raw bytes) or ProtobufPlugin (if you are sending/receiving protobufs). You'll implement your own handleReceived/handleReceivedProtobuf - probably based on the example code.
You will typically want to inherit from either SinglePortModule (if you are just sending/receiving raw bytes) or ProtobufModule (if you are sending/receiving protobufs). You'll implement your own handleReceived/handleReceivedProtobuf - probably based on the example code.
If your plugin needs to perform any operations at startup you can override and implement the setup() method to run your code.
If your module needs to perform any operations at startup you can override and implement the setup() method to run your code.
If you need to send a packet you can call service.sendToMesh with code like this (from the examples):
@ -35,33 +35,33 @@ p->to = dest;
service.sendToMesh(p);
```
## Example plugins
## Example modules
A number of [key services](http://github.com/meshtastic/meshtastic-device/tree/master/src/plugins) are implemented using the plugin API, these plugins are as follows:
A number of [key services](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules) are implemented using the module API, these modules are as follows:
- [TextMessagePlugin](http://github.com/meshtastic/meshtastic-device/tree/master/src/plugins/TextMessagePlugin.h) - receives text messages and displays them on the LCD screen/stores them in the local DB
- [NodeInfoPlugin](http://github.com/meshtastic/meshtastic-device/tree/master/src/plugins/NodeInfoPlugin.h) - receives/sends User information to other nodes so that usernames are available in the databases
- [RemoteHardwarePlugin](http://github.com/meshtastic/meshtastic-device/tree/master/src/plugins/RemoteHardwarePlugin.h) - a plugin 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/software/other/remote-hardware-service) for details.
- [ReplyPlugin](http://github.com/meshtastic/meshtastic-device/tree/master/src/plugins/ReplyPlugin.h) - a simple plugin that just replies to any packet it receives (provides a 'ping' service).
- [TextMessageModule](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules/TextMessageModule.h) - receives text messages and displays them on the LCD screen/stores them in the local DB
- [NodeInfoModule](http://github.com/meshtastic/meshtastic-device/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/meshtastic-device/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/software/other/remote-hardware-service) for details.
- [ReplyModule](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules/ReplyModule.h) - a simple module that just replies to any packet it receives (provides a 'ping' service).
## Getting started
The easiest way to get started is:
- [Build and install](/docs/software/other/build-instructions) the standard codebase from GitHub.
- Copy [src/plugins/ReplyPlugin.\*](http://github.com/meshtastic/meshtastic-device/tree/master/src/plugins/ReplyPlugin.cpp) into src/plugins/YourPlugin.*. Then change the port number from *PortNum_REPLY_APP* to *PortNum_PRIVATE_APP\*.
- Edit plugins/Plugins.cpp:setupPlugins() to add a call to create an instance of your plugin (see comment at head of that function)
- [Build and install](/docs/developers/firmware/build) the standard codebase from GitHub.
- Copy [src/modules/ReplyModule.\*](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules/ReplyModule.cpp) into src/modules/YourModule.*. Then change the port number from *PortNum_REPLY_APP* to *PortNum_PRIVATE_APP\*.
- Edit moduless/Moduless.cpp:setupModules() to add a call to create an instance of your module (see comment at head of that function)
- Rebuild with your new messaging goodness and install on the device
- Use the [meshtastic commandline tool](https://github.com/meshtastic/Meshtastic-python) to send a packet to your board, for example `meshtastic --dest 1234 --sendping`, where _1234_ is another mesh node to send the ping to.
## Threading
It is very common that you would like your plugin to be invoked periodically.
We use a crude/basic cooperative threading system to allow this on any of our supported platforms. Simply inherit from OSThread and implement runOnce(). See the OSThread [documentation](http://github.com/meshtastic/meshtastic-device/tree/master/src/concurrency/OSThread.h) for more details. For an example consumer of this API see RemoteHardwarePlugin::runOnce.
It is very common that you would like your module to be invoked periodically.
We use a crude/basic cooperative threading system to allow this on any of our supported platforms. Simply inherit from OSThread and implement runOnce(). See the OSThread [documentation](http://github.com/meshtastic/meshtastic-device/tree/master/src/concurrency/OSThread.h) for more details. For an example consumer of this API see RemoteHardwareModule::runOnce.
## Sending messages
If you would like to proactively send messages (rather than just responding to them), just call service.sendToMesh(). For an example of this see [NodeInfoPlugin::sendOurNodeInfo(...)](http://github.com/meshtastic/meshtastic-device/tree/master/src/plugins/NodeInfoPlugin.cpp).
If you would like to proactively send messages (rather than just responding to them), just call service.sendToMesh(). For an example of this see [NodeInfoModule::sendOurNodeInfo(...)](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules/NodeInfoModule.cpp).
## Picking a port number
@ -72,7 +72,7 @@ If you are making a new app using meshtastic, please send in a pull request to a
- **0-63** Core Meshtastic use; do not use for third party apps
- **64-127** Registered 3rd party apps. Send in a pull request that adds a new entry to portnums.proto to register your application
- **256-511** Use one of these portnums for your private applications that you don't want to register publicly
- **1024-66559** Are reserved for use by IP tunneling (see [here](/docs/developers/device/portnum) for more information)
- **1024-66559** Are reserved for use by IP tunneling (see [here](/docs/developers/firmware/portnum) for more information)
All other values are reserved.

12
docs/developers/device/port-numbers.md → docs/developers/firmware/port-numbers.md
View file

@ -6,13 +6,13 @@ sidebar_label: Port numbers
For any new apps that run on the device or via sister apps on phones/PCs they should pick and use a unique 'portnum' for their application.
If you are making a new app using meshtastic, please send in a pull request to add your 'portnum' to this master table. PortNums should be assigned in the following range:
If you are making a new app using meshtastic, please send in a pull request to add your 'portnum' to this master table. PortNums should be assigned in the following range:
| Portnum | Usage |
| --- | --- |
| 0-63 | Core Meshtastic use, do not use for third party apps |
| 64-127 | Registered 3rd party apps, send in a pull request that adds a new entry to portnums.proto to register your application |
| 256-511 | Use one of these portnums for your private applications that you do not want to register publicly |
| Portnum | Usage |
| ------- | ---------------------------------------------------------------------------------------------------------------------- |
| 0-63 | Core Meshtastic use, do not use for third party apps |
| 64-127 | Registered 3rd party apps, send in a pull request that adds a new entry to portnums.proto to register your application |
| 256-511 | Use one of these portnums for your private applications that you do not want to register publicly |
All other values are reserved.

38
docs/developers/device/radio-settings.md → docs/developers/firmware/radio-settings.md
View file

@ -59,14 +59,14 @@ Considerations:
We have six predefined channels. These are the most common settings and have been proven to work well:
| Channel setting | Alt Channel Name | Data-rate | SF / Symbols | Coding Rate | Bandwidth | Link Budget |
| :------------------------- | :--------------- | :------------------- | :----------- | :---------- | :-------- | :---------- |
| Short Range / Fast | Short Fast | 18.89 kbps | 7 / 128 | 4/5 | 500 | 134dB |
| Short Range / Slow | Short Slow | 4.69 kbps | 7 / 128 | 4/5 | 125 | 140dB |
| Medium Range / Fast | Medium Fast | 1.2 kbps | 10 / 1024 | 4/6 | 250 | 146dB |
| Medium Range / Slow | Medium Slow | 0.75 kbps | 11 / 2048 | 4/7 | 250 | 148dB |
| Long Range / Fast | Long Fast | 0.19 kbps | 9 / 512 | 4/8 | 31 | 153dB |
| Long Range / Slow | Long Slow | 0.13 kbps (default) | 12 / 4096 | 4/8 | 125 | 154dB |
| Channel setting | Alt Channel Name | Data-rate | SF / Symbols | Coding Rate | Bandwidth | Link Budget |
| :------------------ | :--------------- | :------------------ | :----------- | :---------- | :-------- | :---------- |
| Short Range / Fast | Short Fast | 18.89 kbps | 7 / 128 | 4/5 | 500 | 134dB |
| Short Range / Slow | Short Slow | 4.69 kbps | 7 / 128 | 4/5 | 125 | 140dB |
| Medium Range / Fast | Medium Fast | 1.2 kbps | 10 / 1024 | 4/6 | 250 | 146dB |
| Medium Range / Slow | Medium Slow | 0.75 kbps | 11 / 2048 | 4/7 | 250 | 148dB |
| Long Range / Fast | Long Fast | 0.19 kbps | 9 / 512 | 4/8 | 31 | 153dB |
| Long Range / Slow | Long Slow | 0.13 kbps (default) | 12 / 4096 | 4/8 | 125 | 154dB |
Note: The link budget used by these calculations assumes a transmit power of 17dBm and an antenna with 0dB gain. Adjust your link budget assumptions based on your actual devices. Data-rate in this table is actual measured but doesn't count mesh overhead, hops and retransmissions.
@ -82,17 +82,17 @@ After applying the settings, you will need to restart the device. After your dev
Some example settings:
| Data-rate | SF / Symbols | Coding Rate | Bandwidth | Link Budget | Note |
| :--------- | :----------- | :---------- | :-------- | :---------- | :---------------------------------------------------------------------- |
| 37.50 kbps | 6 / 64 | 4/5 | 500 | 129dB | Fastest possible speed |
| 3.125 kbps | 8 / 256 | 4/5 | 125 | 143dB | |
| 1.953 kbps | 8 / 256 | 4/8 | 125 | 143dB | |
| 1.343 kbps | 11 / 2048 | 4/8 | 500 | 145dB | |
| 1.099 kbps | 9 / 512 | 4/8 | 125 | 146dB | |
| 0.814 kbps | 10 / 1024 | 4/6 | 125 | 149dB | |
| 0.610 kbps | 10 / 1024 | 4/8 | 125 | 149dB | |
| 0.488 kbps | 11 / 2048 | 4/6 | 125 | 152dB | |
| 0.336 kbps | 11 / 2048 | 4/8 | 125 | 152dB | |
| Data-rate | SF / Symbols | Coding Rate | Bandwidth | Link Budget | Note |
| :--------- | :----------- | :---------- | :-------- | :---------- | :----------------------------------------------------------------------- |
| 37.50 kbps | 6 / 64 | 4/5 | 500 | 129dB | Fastest possible speed |
| 3.125 kbps | 8 / 256 | 4/5 | 125 | 143dB | |
| 1.953 kbps | 8 / 256 | 4/8 | 125 | 143dB | |
| 1.343 kbps | 11 / 2048 | 4/8 | 500 | 145dB | |
| 1.099 kbps | 9 / 512 | 4/8 | 125 | 146dB | |
| 0.814 kbps | 10 / 1024 | 4/6 | 125 | 149dB | |
| 0.610 kbps | 10 / 1024 | 4/8 | 125 | 149dB | |
| 0.488 kbps | 11 / 2048 | 4/6 | 125 | 152dB | |
| 0.336 kbps | 11 / 2048 | 4/8 | 125 | 152dB | |
| 0.073 kbps | 12 / 4096 | 4/5 | 31 | 160dB | Twice the range and/or coverage of "Long Slow", low resilience to noise |
| 0.046 kbps | 12 / 4096 | 4/8 | 31 | 160dB | Twice the range and/or coverage of "Long Slow", high resilience to noise |

33
docs/developers/firmware/stacktrace-decode.md Normal file
View file

@ -0,0 +1,33 @@
---
id: stacktrace-decode
title: Decoding Stacktraces
sidebar_label: Decoding Stacktraces
---
You may encounter a situation where your device crashes and are left with a stacktrace, below are two methods of decoding them.
## Manual
:::info
This method uses the symbols of the `firmware.elf` file generated from your latest build, you may wish to rebuild to get up-to-date symbols.
:::
First save the backtrace string to a text file:
```text title="backtrace.txt"
Backtrace: 0x....
```
Now run the exception decoder:
```bash
bin/exception_decoder.py backtrace.txt
```
## Real Time
In order to decode stack traces in real time, kep the following command (replacing `DEVICE_PORT` with your device's port) running in your terminal with the suspect device connected
```bash
pio device monitor --port DEVICE_PORT -f esp32_exception_decoder
```

3
docs/developers/maintaining-documentation/docusaurus.md
View file

@ -3,8 +3,11 @@ id: docusaurus
title: Docusaurus
sidebar_label: Docusaurus
---
## Overview
Meshtastic's documentation is set up using [Docusaurus](https://docusaurus.io). It is highly encouraged to look at [their documentation](https://docusaurus.io/docs) when looking for a solution to a problem with our docs. They most likely have thought of the use case you've discovered.
## Known Issues
- Admonitions within a `TabItem` component need to be completely unindented to show up correctly.

3
docs/developers/maintaining-documentation/github.md
View file

@ -3,9 +3,12 @@ id: github
title: GitHub
sidebar_label: GitHub
---
## Overview
All of Meshtastic's code and documentation is hosted on GitHub. If you would like to contribute to the project, having a GitHub account is an important step to doing so.
## Set up GitHub account
- Go to [github.com](https://github.com)
- Click `Sign Up`

33
docs/developers/maintaining-documentation/overview.md
View file

@ -3,9 +3,11 @@ id: overview
title: Maintaining Documentation
sidebar_label: Maintaining Documentation
---
Meshtastic documentation is an important ingredient to the overall project. We want users to hit the ground running with the information they need right at their finger tips. This section will discuss the documentation software stack, file organization, and style guides.
## Software Stack
All of our documentation resides on GitHub. Instructions for setting up your GitHub account are located [here](github).
Our documentation is powered by [Docusaurus](https://docusaurus.io) — a documentation platform built on React that utilizes markdown files. Because markdown files are easy to edit, most content changes should be fairly simple. Instructions for setting up your instance of Docusaurus are located [here](docusaurus).
@ -13,37 +15,45 @@ Our documentation is powered by [Docusaurus](https://docusaurus.io) — a docume
Another component that we use is [Vercel](https://vercel.com) — a platform for frontend frameworks and static sites. Instructions for setting up your instance of Vercel are located [here](vercel).
## Documentation Organization
| Section | File Path | Description |
| :-----: | :-------: | :---------: |
| About Meshtastic | `docs/about` | High level explanation of of Meshtastic. |
| Meshtastic Software | `docs/software` | Current bulk of documentation running through each Meshtastic project. |
| Getting Started | `docs/getting-started` | Instructions on how to get the Meshtastic firmware onto a users device. |
| Device Settings | `docs/software/settings` | Details each user setting and provides explanations for what the setting does and how to configure the device using the various clients available (Android, CLI, iOS, Web) |
| Hardware Details | `docs/hardware` | Any hardware related content. Any time a user is attaching a peripheral accessory to their device. That includes 3d printed cases, antennas, buttons, chimes, rotary encoders, and screens. |
| Radio Mesh Details | `docs/mesh` | This section discusses everything relating to the Meshtastic mesh. Mesh health metrics will be discussed here as well as topics such as signal strength, range and anyting else pertaining to "over the air". |
| Contribute to Meshtastic | `docs/developers` | Details each of the projects and how they work together to give a developer an idea of how the Meshtastic ecosystem operates. |
| About the Documentation | `docs/maintaining-documentation` | This section explains how our documentation is organized, how to make edits to the documentation, view a local copy of your fork of the project. Style guides and tips will also be included here. |
| Legal | `docs/legal` | Any legal information. Most changes here will be handled by developers actually working on the projects that require any legal disclosures. Examples include: the Meshtastic trademark, terms of service, and privacy policy. |
| Section | File Path | Description |
| :----------------------: | :------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| About Meshtastic | `docs/about` | High level explanation of of Meshtastic. |
| Meshtastic Software | `docs/software` | Current bulk of documentation running through each Meshtastic project. |
| Getting Started | `docs/getting-started` | Instructions on how to get the Meshtastic firmware onto a users device. |
| Device Settings | `docs/software/settings` | Details each user setting and provides explanations for what the setting does and how to configure the device using the various clients available (Android, CLI, iOS, Web) |
| Hardware Details | `docs/hardware` | Any hardware related content. Any time a user is attaching a peripheral accessory to their device. That includes 3d printed cases, antennas, buttons, chimes, rotary encoders, and screens. |
| Radio Mesh Details | `docs/mesh` | This section discusses everything relating to the Meshtastic mesh. Mesh health metrics will be discussed here as well as topics such as signal strength, range and anyting else pertaining to "over the air". |
| Contribute to Meshtastic | `docs/developers` | Details each of the projects and how they work together to give a developer an idea of how the Meshtastic ecosystem operates. |
| About the Documentation | `docs/maintaining-documentation` | This section explains how our documentation is organized, how to make edits to the documentation, view a local copy of your fork of the project. Style guides and tips will also be included here. |
| Legal | `docs/legal` | Any legal information. Most changes here will be handled by developers actually working on the projects that require any legal disclosures. Examples include: the Meshtastic trademark, terms of service, and privacy policy. |
## Quick Start
Assuming you have the [prerequisites installed](serve-docs-locally#prerequisites), running a local instance of Docusaurus takes three steps:
1. Fork/Clone the [meshtastic/Meshtastic](https://github.com/meshtastic/Meshtastic) repository and navigate to the root directory of the project.
```bash title="Clone the project"
git clone https://github.com/meshtastic/Meshtastic.git
```
```bash title="Clone fork of the project"
git clone https://github.com/[username]/Meshtastic.git
```
```bash title="Change Directory"
cd ~/Meshtastic
```
2. Install Dependencies
```bash title="Install dependencies using Yarn"
yarn install
```
3. Run Docusaurus
```bash title="Run node.js server"
yarn start
```
@ -54,4 +64,5 @@ Before submitting a pull request, it's helpful to run the following command to e
```bash title="Build Project"
yarn build
```
:::

8
docs/developers/maintaining-documentation/serve-docs-locally.md
View file

@ -3,16 +3,20 @@ id: serve-docs-locally
title: Setting up Local Documentation
sidebar_label: Serve Docs Locally
---
:::note
Some things won't display properly like logos or protobufs, this is not cause for concern.
:::
## Prerequisites
In order to set up your local environment, you will need to install:
- [Node & Node package manager (NPM)](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
- [Yarn package manager](https://yarnpkg.com/getting-started/install)
## Getting Started
### Fork the Meshtastic Repository
Log into Github and create a fork of the [meshtastic/Meshtastic](https://github.com/meshtastic/Meshtastic) repository.
@ -28,16 +32,19 @@ git clone https://github.com/username/Meshtastic.git
```
### Change directory to Local copy
```bash title="Change Directory"
cd ~/Meshtastic
```
### Install Dependencies
```bash title="Install dependencies using Yarn"
yarn install
```
### Run Development Server
```bash title="Run node.js server"
yarn start
```
@ -48,4 +55,5 @@ Before submitting a pull request, it's helpful to run the following command to e
```bash title="Build Project"
yarn build
```
:::

82
docs/developers/maintaining-documentation/style-guides/settings.md
View file

@ -3,41 +3,50 @@ id: style-guide-settings
title: Style Guide - Settings Pages
sidebar_label: Settings Pages
---
## Overview
Setting pages should focus solely on settings and configuring the device. Hardware is often a related topic, however these pages should not attempt to explain attaching hardware. Mention that hardware is required and link to the appropriate page(s).
## Layout
### Overview
This section should describe the group of settings and what they do for the device.
### Settings
This section starts with an alphabetized table of settings, available values, and default values.
Available values should be listed with tick marks `` surrounding the value.
| Value Type | Example |
| :--------: | :-----: |
| Boolean | `true`, `false` |
| List | `apple`, `banana`, `orange` |
| Range | `0`-`100` |
| Value Type | Example |
| :--------: | :-------------------------: |
| Boolean | `true`, `false` |
| List | `apple`, `banana`, `orange` |
| Range | `0`-`100` |
After the table each setting is described in brief detail. If the available options for a setting need additional explanation, a table should be used to describe each available option.
### Details
If additional details are needed, this optional section can explain that. These would include prerequisites, links to hardware guides, etc.
### Examples
This optional section can have examples of configurations needed where multiple settings are required to be set up for a specific use case.
This optional section can have examples of configurations needed where multiple settings are required to be set up for a specific use case.
## Example Template
```markdown title="Template for Settings Pages"
---
id: unique-id
title: Title for Page
sidebar_label: Label for Sidebar
---
<!--- Allows client-specific tabs to be used --->
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -48,48 +57,55 @@ import TabItem from '@theme/TabItem';
## Settings
<!--- Table of settings in alphabetical order --->
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| Setting | Acceptable Values | Default |
| :---------------------: | :-------------------------: | :-----: |
| my_setting_with_options | `apple`, `banana`, `orange` | `apple` |
<!--- H3 for each setting above (alphabetized) --->
### my_setting_with_options
<!--- description for what the setting does --->
<!--- if the setting has many options, insert a table describing what those variables do --->
| Value | Description |
| :---: | :---------: |
| `apple` | Description of apple (default) |
| `banana` | Description of banana |
| `orange` | Description of orange |
| Value | Description |
| :------: | :----------------------------: |
| `apple` | Description of apple (default) |
| `banana` | Description of banana |
| `orange` | Description of orange |
<!--- Client tabs that were imported above --->
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
CLI content here
</TabItem>
<TabItem value="android">
Android content here
</TabItem>
<TabItem value="iOS">
iOS content here
</TabItem>
<TabItem value="web">
Web content here
</TabItem>
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
CLI content here
</TabItem>
<TabItem value="android">
Android content here
</TabItem>
<TabItem value="iOS">
iOS content here
</TabItem>
<TabItem value="web">
Web content here
</TabItem>
</Tabs>
## Details
<!--- Additional details about the settings IF NEEDED otherwise delete this h2 header --->
## Examples
<!--- Meant for examples where multiple settings are configured at the same time (WiFi type/SSID/password in a single command). If not needed, delete this h2 header --->
```

2
docs/developers/maintaining-documentation/vercel.md
View file

@ -3,7 +3,9 @@ id: vercel
title: Vercel
sidebar_label: Vercel
---
## Overview
Setting up a Vercel account is an optional step that can help you view your changes to the documentation in a server environment just like the actual docs. This can be helpful to include when submitting a pull request so that developers can review your changes and visually check that things look correct.
## Set up Vercel account

38
docs/developers/overview.md
View file

@ -4,36 +4,42 @@ title: Contribute to Meshtastic
sidebar_label: Contribute to Meshtastic
slug: /developers
---
# How to Help
Meshtastic is a team of volunteers, and as such there is always plenty of ways to help. This project gets great contributions from people in their off hours. Those contributors work on the features they are interested in. It is a very open and welcoming developer community, and we are always looking for help to improve Meshtastic.
* If you're a developer, there's plenty stuff to do. Dig in!
* If you're interacting with Meshtastic radios, we could use help with testing, documenting, and providing feedback.
* If you're into Web Development, check out the different web repos.
* If you're into Kotlin and Android, check out the link to the repo below.
* If you're into Python, check out the link to the repo below
* If you're into Ham Radio and LoRa, then this is a great project for you!
* ... basically... we would love to have your help and feedback
- If you're a developer, there's plenty stuff to do. Dig in!
- If you're interacting with Meshtastic radios, we could use help with testing, documenting, and providing feedback.
- If you're into Web Development, check out the different web repos.
- If you're into Kotlin and Android, check out the link to the repo below.
- If you're into Python, check out the link to the repo below
- If you're into Ham Radio and LoRa, then this is a great project for you!
- ... basically... we would love to have your help and feedback
There are several developers, testers, and active users on [Discord](https://discord.gg/UQJ5QuM7vq).
There are many technologies (and repositories) used in creating the Meshtastic ecosystem. Below is a breakdown:
## Protocol buffers
Most communication and interactions happen with protocol buffers. The [Meshtastic-protobufs](https://github.com/meshtastic/Meshtastic-protobufs) repo is where all of the protocol buffer changes happen. See the [Protobuf API Reference](https://meshtastic.org/docs/developers/protobufs/api) for more details.
Most communication and interactions happen with protocol buffers. The [Meshtastic-protobufs](https://github.com/meshtastic/Meshtastic-protobufs) repo is where all of the protocol buffer changes happen. See the [Protobuf API Reference](/docs/developers/protobufs/api) for more details.
## Firmware
The [Meshtastic-device](https://github.com/meshtastic/Meshtastic-device) is where all of the firmware development happens. This is where the code for the ESP32 and nRF52 based devices is developed. It is mainly C and C++ code.Think Arduino. It is where the first level of hardware interaction begins and ends.
## Plugins
[Plugins](https://meshtastic.org/docs/software/plugins/) are also implemented mainly in the Meshtastic-device repo above. Typically, you would add functionality in the protobufs repo and the device repo to implement plugin functionality. You probably also want to have some client/device use/interact with the plugin and that is where the Device support comes into play.
## modules
[Modules](/docs/software/modules) are also implemented mainly in the Meshtastic-device repo above. Typically, you would add functionality in the protobufs repo and the device repo to implement module functionality. You probably also want to have some client/device use/interact with the module and that is where the Device support comes into play.
## Device Support
The [Meshtastic-python](https://github.com/meshtastic/Meshtastic-python) is typically where the first device interaction takes place, but that is not a requirement. This repo has a command line utility that allows you to interact with most functionality with the devices. This python library can also be consumed for other applications. See [Community applications](https://meshtastic.org/docs/software/community/community-overview) for other Meshtastic applications.
The [Meshtastic-python](https://github.com/meshtastic/Meshtastic-python) is typically where the first device interaction takes place, but that is not a requirement. This repo has a command line utility that allows you to interact with most functionality with the devices. This python library can also be consumed for other applications. See [Community applications](/docs/software/community/community-overview) for other Meshtastic applications.
## Web Application
The [Meshtastic-web](https://github.com/meshtastic/meshtastic-web) is where the hosted web server on the ESP32 devices in Typescript is developed. See the [Web interface overview](https://meshtastic.org/docs/software/web/web-app-software) for more details.
The [Meshtastic-web](https://github.com/meshtastic/meshtastic-web) is where the hosted web server on the ESP32 devices in Typescript is developed. See the [Web interface overview](/docs/software/web/web-app-software) for more details.
The [meshtastic.js](https://github.com/meshtastic/meshtastic.js) is a JavaScript library that provides an interface for Meshtastic devices.
@ -42,13 +48,15 @@ The [meshtastic.js](https://github.com/meshtastic/meshtastic.js) is a JavaScript
* Saving of preferences
* Better loading state indicators
* Chat scroll lock
* Various plugin support
* Various module support
## Phone Apps
There are two phone apps that interact with the Meshtastic devices:
* The [Meshtastic-Android](https://github.com/meshtastic/Meshtastic-Android) repo contains the Kotlin code for Android based interactions with Meshtastic devices. See [here](https://meshtastic.org/docs/developers/android/build-app) for how to build/create a development environment for the Meshtastic Android App.
* The iOS app is in the process of a complete re-write in Swift and will have the new repo published soon. Note: There are a couple of earlier implementations.
- The [Meshtastic-Android](https://github.com/meshtastic/Meshtastic-Android) repo contains the Kotlin code for Android based interactions with Meshtastic devices. See [here](/docs/developers/android/build-app) for how to build/create a development environment for the Meshtastic Android App.
- The iOS app is in the process of a complete re-write in Swift and will have the new repo published soon. Note: There are a couple of earlier implementations.
## Documentation
This website is in the [Meshtastic](https://github.com/meshtastic/Meshtastic) repository.

1
docs/faq/antenna.md
View file

@ -3,4 +3,5 @@ id: antenna
title: FAQs - Antenna
sidebar_label: Antenna
---
## Overview

3
docs/faq/bluetooth.md
View file

@ -3,11 +3,12 @@ id: bluetooth
title: FAQs - Bluetooth
sidebar_label: Bluetooth
---
## Overview
### How do I pair my phone to the device if my device doesn't have a screen?
Use [Wifi](https://meshtastic.org/docs/software/device/device-wifi) or Bluetooth with screenless pairing: before you initiate pairing, double click on the device button. The LED will blink 3 times in confirmation and the PIN will be set temporarily to `123456`.
Use [Wifi](/docs/settings/wifi) or Bluetooth with screenless pairing: before you initiate pairing, double click on the device button. The LED will blink 3 times in confirmation and the PIN will be set temporarily to `123456`.
### Can I have Bluetooth enabled and use WiFi radio?

1
docs/faq/channel.md
View file

@ -3,6 +3,7 @@ id: channel
title: FAQs - Channel
sidebar_label: Channel
---
## Overview
### What is a Meshtastic Channel?

1
docs/faq/client-android.md
View file

@ -3,6 +3,7 @@ id: client-android
title: FAQs - Android
sidebar_label: Android
---
## Overview
### What versions of Android does the Meshtastic Android App require?

3
docs/faq/client-ios.md
View file

@ -3,6 +3,7 @@ id: client-ios
title: FAQs - iOS
sidebar_label: iOS
---
## Overview
### What version of iOS does the Meshtastic iOS App Require?
@ -11,4 +12,4 @@ The now-in-beta iOS app requires iOS v15.
### How do I get the Meshtastic iOS App?
See [iOS App](https://meshtastic.org/docs/software/ios/ios-development)
See [iOS App](/docs/software/ios/ios-development)

1
docs/faq/client-python-cli.md
View file

@ -3,6 +3,7 @@ id: client-python-cli
title: FAQs - CLI
sidebar_label: CLI
---
## Overview
### How do I find out more about installing (and using) Meshtastic via command line?

1
docs/faq/client-web.md
View file

@ -3,6 +3,7 @@ id: client-web
title: FAQs - Web
sidebar_label: Web
---
## Overview
### How do I access the network from my web browser?

7
docs/faq/device.md
View file

@ -3,11 +3,12 @@ id: device
title: FAQs - Device
sidebar_label: Device
---
## Overview
### Where do I purchase the device hardware?
Each [supported device](https://meshtastic.org/docs/hardware/supported/tbeam) has a "Purchase Link".
Each [supported device](/docs/hardware/supported/tbeam) has a "Purchase Link".
### I have my hardware. How do I install the firmware and any required drivers?
@ -35,5 +36,5 @@ Push the left PWR button for about 1 second.
### How can I tell the device not to sleep?
- Android instructions see: [Android Usage](https://meshtastic.org/docs/software/android/android-usage#configuration-options)
- Python CLI instructions see: [Python Usage](https://meshtastic.org/docs/software/python/python-cli#changing-device-settings)
- Android instructions see: [Android Usage](/docs/software/android/android-usage#configuration-options)
- Python CLI instructions see: [Python Usage](/docs/software/python/python-cli#changing-device-settings)

4
docs/faq/faq.md
View file

@ -4,6 +4,7 @@ title: FAQs - General
sidebar_label: General
slug: /faq
---
<!---
Note to Contributors:
@ -20,6 +21,7 @@ Details about FAQ page
Answer (Include links to settings/developers/supported hardware etc)
--->
## Overview
### What is Meshtastic?
@ -32,4 +34,4 @@ After reading this FAQ and checking out the links on the left, there are two pla
### How can I contribute to Meshtastic?
Everyone contributes in a different way. Join the [Forum](https://meshtastic.discourse.group) and/or the [Meshtastic Discord](https://discord.com/invite/UQJ5QuM7vq) and introduce yourself. We're all very friendly. If you'd like to pitch in some code, check out the [Developers](https://meshtastic.org/docs/developers) menu on the left.
Everyone contributes in a different way. Join the [Forum](https://meshtastic.discourse.group) and/or the [Meshtastic Discord](https://discord.com/invite/UQJ5QuM7vq) and introduce yourself. We're all very friendly. If you'd like to pitch in some code, check out the [Developers](/docs/developers) menu on the left.

1
docs/faq/mesh.md
View file

@ -3,4 +3,5 @@ id: mesh
title: FAQs - Mesh
sidebar_label: Mesh
---
## Overview

19
docs/faq/modules.md Normal file
View file

@ -0,0 +1,19 @@
---
id: modules
title: FAQs - Modules
sidebar_label: Modules
---
## Overview
### What are Modules?
Modules are features that expand the basic device functionality and/or integrate with other services.
### What modules do we have available?
A list of available modules is available [here](/docs/software/modules).
### I'd like to write a module. How do I get started?
API documentation for creating modules is available [here](/docs/developers/firmware/module-api).

1
docs/faq/mqtt.md
View file

@ -3,4 +3,5 @@ id: mqtt
title: FAQs - MQTT
sidebar_label: MQTT
---
## Overview

18
docs/faq/plugins.md
View file

@ -1,18 +0,0 @@
---
id: plugins
title: FAQs - Plugins
sidebar_label: Plugins
---
## Overview
### What are Plugins?
Plugins are features that expand the basic device functionality and/or integrate with other services.
### What plugins do we have available?
To see the list of available plugins, please go to: https://meshtastic.org/docs/software/plugins/
### I'd like to write a plugin. How do I get started?
See: https://meshtastic.org/docs/developers/device/plugin-api

1
docs/faq/wifi.md
View file

@ -3,6 +3,7 @@ id: wifi
title: FAQs - WiFi
sidebar_label: WiFi
---
## Overview
### How do I turn on the WiFI radio?

8
docs/getting-started/clients.md
View file

@ -3,7 +3,8 @@ id: clients
title: Meshtastic Clients
sidebar_label: Meshtastic Clients
---
import { DownloadCard } from '/src/pages/downloads/_components/DownloadCard.tsx'
import { DownloadCard } from '/src/pages/downloads/\_components/DownloadCard.tsx'
## Overview
@ -20,14 +21,17 @@ To install/upgrade Meshtastic-python manually, see below:
```bash title="Install Meshtastic-python (includes CLI)"
pip install meshtastic
```
```bash title="Upgrade Meshtastic-python (includes CLI)"
pip install --upgrade meshtastic
```
:::note
Some installations of python may require you to substitute 'pip3' for the 'pip' command.
:::
### Mobile Client Downloads
<ul
style={{
position: "relative",
@ -57,7 +61,7 @@ Using your preferred program (PuTTy, Serial, etc) connect to your device with th
| Baudrate | Data Bits | Parity | Stop Bits |
| :------: | :-------: | :----: | :-------: |
| `921600` | `8` | `None` | `1` |
| `921600` | `8` | `None` | `1` |
### Web

1
docs/getting-started/first-steps.md
View file

@ -3,6 +3,7 @@ id: first-steps
title: First Steps
sidebar_label: First Steps
---
## Overview
Congratulations! Your node should now be running Meshtastic and hopefully you've paired to a client on your mobile device, desktop, or browser.

10
docs/getting-started/flashing-esp32.md
View file

@ -111,8 +111,8 @@ pip3 install --upgrade esptool
</TabItem>
<TabItem value="windows">
- Download and install [Python](https://www.python.org/). When installing, make sure to click `Add Python X.Y to PATH`.
- Download and install [Gitbash](https://gitforwindows.org/) (or other appropriate shell) and run all subsequent commands from that shell.
- Download and install [Python](https://www.python.or). When installing, make sure to click `Add Python X.Y to PATH`.
- Download and install [Gitbash](https://gitforwindows.org) (or other appropriate shell) and run all subsequent commands from that shell.
:::note
Confirm installation of `python` & `pip` with the following commands.
@ -146,9 +146,9 @@ values={[
{label: 'macOS', value: 'macos'},
{label: 'Windows', value: 'windows'},
]}>
<TabItem value="linux"></TabItem>
<TabItem value="macos"></TabItem>
<TabItem value="windows">
<TabItem value="linux"></TabItem>
<TabItem value="macos"></TabItem>
<TabItem value="windows">
:::important
On Windows, you must explicitly declare esptool as a .py script. Use `esptool.py chip_id`.

54
docs/getting-started/flashing-firmware.md
View file

@ -3,6 +3,7 @@ id: flashing-firmware
title: Firmware Flashing Prerequisites
sidebar_label: Prerequisites
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -34,14 +35,14 @@ If you don't see your device in the following test, you either:
2. Are currently using a charging only cable.
<Tabs
groupId="operating-system"
defaultValue="linux"
values={[
{label: 'Linux', value: 'linux'},
{label: 'macOS', value: 'macos'},
{label: 'Windows', value: 'windows'},
]}>
<TabItem value="linux">
groupId="operating-system"
defaultValue="linux"
values={[
{label: 'Linux', value: 'linux'},
{label: 'macOS', value: 'macos'},
{label: 'Windows', value: 'windows'},
]}>
<TabItem value="linux">
Connect your Meshtastic device to your USB port, open a `Terminal` and enter the following command:
```bash
@ -49,8 +50,8 @@ lsusb
```
You should see something like: `ID xxxx:xxxx Silicon Labs CP210x UART Bridge`, `ID xxxx:xxxx QinHeng Electronics USB Single Serial`, or `FIXME (WISBLOCK OUTPUT)`.
</TabItem>
<TabItem value="macos">
</TabItem>
<TabItem value="macos">
Navigate to `Apple Menu  > About This Mac > System Report... > Hardware > USB`. You should see something like `CP210X USB to UART Bridge Controller`, `CH9102 USB to UART Bridge Controller`, or `WisCore RAK4631 Board`. If not download the appropriate drivers below.
@ -71,14 +72,14 @@ You may need to install a driver from Silicon Labs for the [CP210X USB to UART b
Some newer boards may require the CH9102 (CH340/CH341) Driver.
<Tabs
groupId="operating-system"
defaultValue="linux"
values={[
{label: 'Linux', value: 'linux'},
{label: 'macOS', value: 'macos'},
{label: 'Windows', value: 'windows'},
]}>
<TabItem value="linux">
groupId="operating-system"
defaultValue="linux"
values={[
{label: 'Linux', value: 'linux'},
{label: 'macOS', value: 'macos'},
{label: 'Windows', value: 'windows'},
]}>
<TabItem value="linux">
[CP210X USB to UART bridge - Download](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers)
@ -110,14 +111,14 @@ Reboot your computer after you have installed the driver to complete the install
### NRF52 Drivers
<Tabs
groupId="operating-system"
defaultValue="linux"
values={[
{label: 'Linux', value: 'linux'},
{label: 'macOS', value: 'macos'},
{label: 'Windows', value: 'windows'},
]}>
<TabItem value="linux">
groupId="operating-system"
defaultValue="linux"
values={[
{label: 'Linux', value: 'linux'},
{label: 'macOS', value: 'macos'},
{label: 'Windows', value: 'windows'},
]}>
<TabItem value="linux">
[CH9102 Driver - Linux Download](http://www.wch-ic.com/downloads/CH341SER_LINUX_ZIP.html)
@ -146,7 +147,6 @@ With the latest versions of MacOS, the USB Serial driver is built-in. Do _NOT_ d
:::
</TabItem>
<TabItem value="windows">

1
docs/getting-started/getting_started.md
View file

@ -4,6 +4,7 @@ title: Getting Started
sidebar_label: Getting Started
slug: /getting-started
---
import Link from '@docusaurus/Link';
## What is Meshtastic?

118
docs/getting-started/meshtastic-flasher.md
View file

@ -4,6 +4,7 @@ title: Using Meshtastic Flasher
sidebar_label: Using Meshtastic Flasher
pagination_next: getting-started/clients
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -56,6 +57,7 @@ Navigate to `Device Manager > Ports (COM & LPT)`. You should see something like
</Tabs>
### Install using `pip`
<Tabs
groupId="operating-system"
defaultValue="linux"
@ -64,70 +66,70 @@ values={[
{label: 'macOS', value: 'macos'},
{label: 'Windows', value: 'windows'},
]}>
<TabItem value="linux">
<TabItem value="linux">
```bash title="Install Meshtastic Flasher"
python3 --version
# ensure you are using at least python v3.6
# change to a directory where you want to create a python virtual environment
mkdir some_dir
cd some_dir
# if the following command fails, it might tell you what package to install
python3 -m venv venv
# activate the python virtual environment
source venv/bin/activate
# your prompt should change - it should include "(venv) in the front
# upgrade pip
pip install --upgrade pip
pip install meshtastic-flasher
```
```bash title="Install Meshtastic Flasher"
python3 --version
# ensure you are using at least python v3.6
# change to a directory where you want to create a python virtual environment
mkdir some_dir
cd some_dir
# if the following command fails, it might tell you what package to install
python3 -m venv venv
# activate the python virtual environment
source venv/bin/activate
# your prompt should change - it should include "(venv) in the front
# upgrade pip
pip install --upgrade pip
pip install meshtastic-flasher
```
```bash title="Running Meshtastic Flasher"
meshtastic-flasher
```
```bash title="Running Meshtastic Flasher"
meshtastic-flasher
```
</TabItem>
<TabItem value="macos">
```bash title="Install Meshtastic Flasher"
python3 --version
# ensure you are using at least python v3.6
# change to a directory where you want to create a python virtual environment
mkdir some_dir
cd some_dir
python3 -m venv venv
# activate the python virtual environment
source venv/bin/activate
# your prompt should change - it should include "(venv) in the front
# upgrade pip
pip install --upgrade pip
pip install meshtastic-flasher
```
```bash title="Install Meshtastic Flasher"
python3 --version
# ensure you are using at least python v3.6
# change to a directory where you want to create a python virtual environment
mkdir some_dir
cd some_dir
python3 -m venv venv
# activate the python virtual environment
source venv/bin/activate
# your prompt should change - it should include "(venv) in the front
# upgrade pip
pip install --upgrade pip
pip install meshtastic-flasher
```
```bash title="Running Meshtastic Flasher"
meshtastic-flasher
```
```bash title="Running Meshtastic Flasher"
meshtastic-flasher
```
</TabItem>
<TabItem value="windows">
```bash title="Install Meshtastic Flasher"
# open a command prompt
# create a new directory for the python virtual environment
cd c:\
mkdir some_dir
cd some_dir
# check that python version is sufficient, must be at least v3.9+
python -m venv venv
# activate the python virtual environment
venv\Scripts\activate
# your prompt should change - it should have (venv) at the beginning
pip install meshtastic-flasher
```
```bash title="Install Meshtastic Flasher"
# open a command prompt
# create a new directory for the python virtual environment
cd c:\
mkdir some_dir
cd some_dir
# check that python version is sufficient, must be at least v3.9+
python -m venv venv
# activate the python virtual environment
venv\Scripts\activate
# your prompt should change - it should have (venv) at the beginning
pip install meshtastic-flasher
```
```bash title="Running Meshtastic Flasher"
meshtastic-flasher
```
```bash title="Running Meshtastic Flasher"
meshtastic-flasher
```
</TabItem>
</Tabs>
@ -138,9 +140,9 @@ The Meshtastic Flasher will flash the latest firmware to esp32 and nrf52 devices
There are three steps:
* Click the "GET VERSIONS" button to get the versions available (from GitHub).
* Click the "DETECT DEVICE" button to determine the port and device variant connected.
* Click the "FLASH" button to flash the version selected, using the port selected to the device.
- Click the "GET VERSIONS" button to get the versions available (from GitHub).
- Click the "DETECT DEVICE" button to determine the port and device variant connected.
- Click the "FLASH" button to flash the version selected, using the port selected to the device.
## Issues?
@ -152,6 +154,6 @@ The code can be found at the [Meshtastic-gui-installer repo](https://github.com/
The following are known limitations:
* Raspberry Pi is not available, since it is arm-based and there are no pre-built libraries for [PySide](https://wiki.qt.io/Qt_for_Python)
* Ubuntu 20.04 is the version used for testing, it may work with other versions
* see [README](https://github.com/meshtastic/Meshtastic-gui-installer/blob/master/README.md) for more details
- Raspberry Pi is not available, since it is arm-based and there are no pre-built libraries for [PySide](https://wiki.qt.io/Qt_for_Python)
- Ubuntu 20.04 is the version used for testing, it may work with other versions
- see [README](https://github.com/meshtastic/Meshtastic-gui-installer/blob/master/README.md) for more details

11
docs/hardware/antenna/aerials.md
View file

@ -10,13 +10,14 @@ The stock aerials provided bundled with the t-Beam and other boards are a 'mixed
Matching an aerial to the transceiver frequency is important, as is choosing an appropriate design.
The aerial's design will affect:
- proportion of the signal which leaves the aerial (efficiency),
- proportion of the signal which leaves the aerial (efficiency),
- directions in which it's transmitted,
- whether it will be affected by horizontal or vertical polarization,
- and proportion of signal which is reflected back within the device itself.
:::caution
While the LoRa devices we are using for Meshtastic are relatively low power radios, care should be taken _not_ to operate any radio transmission device without an aerial or with a poorly matched aerial. Un-transmitted radio signal reflected back to the transmitter can damage the device.
While the LoRa devices we are using for Meshtastic are relatively low power radios, care should be taken _not_ to operate any radio transmission device without an aerial or with a poorly matched aerial. Un-transmitted radio signal reflected back to the transmitter can damage the device.
:::
### Important considerations:
@ -25,11 +26,11 @@ While the LoRa devices we are using for Meshtastic are relatively low power radi
- Devices on another frequency will not be able to interact with yours.
- See this listing by [The Things Network](https://www.thethingsnetwork.org/docs/lorawan/frequencies-by-country.html) for frequencies licensed for specific countries.
- How will you be carrying / transporting the radio?
- A large directional aerial will transmit over significantly greater distance than an omni-directional aerial. However, it must be pointed at its target so isn't optimal for mobile use.
- A large directional aerial will transmit over significantly greater distance than an omni-directional aerial. However, it must be pointed at its target so isn't optimal for mobile use.
- A tuned half-wave whip aerial may have more omni-directional range than the quarter wave stubby; but it will be conspicuous in your pocket.
- Many antennas, especially quarter wave stubby antennas, require the use of ground planes to transmit at peak performance.
- Do you want transmission in all directions?
- While humans (mostly water) don't attenuate signal greatly (at LoRa frequencies), buildings & walls do.
- While humans (mostly water) don't attenuate signal greatly (at LoRa frequencies), buildings & walls do.
- If your aerial is permanently positioned against a building, signal transmitted towards the wall will be largely lost or attenuated.
- Does my Meshtastic device have the right power range, impedance, and connector for the aerial?
- For the LoRa devices, it should be 50 Ohm impedance with SMA connector. Many antennas will be recommended for LoRa use in their technical details.
@ -41,6 +42,6 @@ While the LoRa devices we are using for Meshtastic are relatively low power radi
## Terminology / references
You could do a lot worse than reading the [Wikipedia entry for Antenna](https://en.wikipedia.org/wiki/Antenna_(radio)), along with the [Wikipedia entry for LoRa](https://en.wikipedia.org/wiki/LoRa).
You could do a lot worse than reading the [Wikipedia entry for Antenna](<https://en.wikipedia.org/wiki/Antenna_(radio)>), along with the [Wikipedia entry for LoRa](https://en.wikipedia.org/wiki/LoRa).
Instead of listing the terms, let us recommend this superb [tutorial](https://www.youtube.com/watch?v=J3PBL9oLPX8) by Andreas Spiess (the 'guy with the Swiss accent').

14
docs/hardware/antenna/antenna.md
View file

@ -7,27 +7,27 @@ slug: /hardware/antenna
## TL; DR
If you have sufficient range with your existing aerial, skip this section. If you don't, consider either getting more nodes and / or replace the stock aerial with one tuned (to your region transmitter's frequency):
If you have sufficient range with your existing aerial, skip this section. If you don't, consider either getting more nodes and / or replace the stock aerial with one tuned (to your region transmitter's frequency):
- A quarter wave _tuned_ stubby aerial (<10cm for fit-in-pocket) should have a real-world range of a couple of km without significant obstacles (buildings / hills).
- A quarter wave _tuned_ stubby aerial (<10cm for fit-in-pocket) should have a real-world range of a couple of km without significant obstacles (buildings / hills).
- Aerial criteria: 50 Ohm, appropriate connector (usually SMA male or U.FL), low VSWR (<2) (at tuning frequency - see its datasheet), gain > 0 dBi .
- Caution, avoid suppliers who:
- don't state the aerial's tuned frequency and its specific purpose (LoRa network)
- claim huge gain figures on omni-directional aerials
- don't provide boringly professional datasheets
- don't provide boringly professional datasheets
If you want more range, directionality, or specificity read on.
## General guidance
The Meshtastic system is designed to be simple and intuitive to use. However, its LoRa radios rely on point-to-point communications, unit-to-unit, aerial-to-aerial; quite different to the near ubiquitous radio coverage of today's cellphone & Wifi connections.
The Meshtastic system is designed to be simple and intuitive to use. However, its LoRa radios rely on point-to-point communications, unit-to-unit, aerial-to-aerial; quite different to the near ubiquitous radio coverage of today's cellphone & Wifi connections.
Some understanding of the factors affecting radio communications will help achieve substantially better service and faster transmission over a greater range with your devices. Here, we'll attempt to provide a top-level set of guidance for use and aerial selection, how to test the aerials, a set of resources for further research, and plenty of opportunity for going deeper.
Some understanding of the factors affecting radio communications will help achieve substantially better service and faster transmission over a greater range with your devices. Here, we'll attempt to provide a top-level set of guidance for use and aerial selection, how to test the aerials, a set of resources for further research, and plenty of opportunity for going deeper.
The Meshtastic devices (of various flavors) lend themselves to experimentation, not only because you can replace their aerials, but also because of their mesh operation. All nodes will, without alteration, relay communications from any other members of the mesh around obstacles and over greater distances. The cost of aerial investment should be weighed against investment in additional low-cost nodes.
The Meshtastic devices (of various flavors) lend themselves to experimentation, not only because you can replace their aerials, but also because of their mesh operation. All nodes will, without alteration, relay communications from any other members of the mesh around obstacles and over greater distances. The cost of aerial investment should be weighed against investment in additional low-cost nodes.
:::caution
While the LoRa devices we are using for Meshtastic are relatively low power radios, care should be taken _not_ to operate any radio transmission device without an aerial or with a poorly matched aerial. Un-transmitted radio signal reflected back to the transmitter can damage the device.
While the LoRa devices we are using for Meshtastic are relatively low power radios, care should be taken _not_ to operate any radio transmission device without an aerial or with a poorly matched aerial. Un-transmitted radio signal reflected back to the transmitter can damage the device.
:::
The information collected here is by no means definitive, and necessarily abbreviated (it's a huge topic).

2
docs/hardware/antenna/non-aerial.md
View file

@ -6,6 +6,7 @@ slug: /hardware/non-aerial
---
Unless you're using your devices in a vacuum, with clear line of sight between aerials the following will have an effect:
- Weather (temperature, humidity, and air pressure),
- Transmission power, bandwidth, spreading factor, and other associated channel factors,
- Number of nodes within reach of the mesh (affects retries consequent duty cycle hit),
@ -17,6 +18,7 @@ Unless you're using your devices in a vacuum, with clear line of sight between a
### Environmental factors
For a bit of light reading on environmental research:
- [RF attenuation in vegetation](https://web.archive.org/web/20201216041455/https://www.itu.int/dms_pubrec/itu-r/rec/p/R-REC-P.833-9-201609-I!!PDF-E.pdf) (yes really); if you wander through the woods wondering how your RF is bouncing off leaves dependent on their variety, and wind speed … well you do, now.
- [RF attenuation with various building materials](https://www.ofcom.org.uk/__data/assets/pdf_file/0016/84022/building_materials_and_propagation.pdf).
- This one by ITU again is very detailed in its [analysis of the drivers of attenuation](https://web.archive.org/web/20211005174833/https://www.itu.int/dms_pubrec/itu-r/rec/p/R-REC-P.2040-1-201507-I!!PDF-E.pdf) (I wasn’t aware that all EMF radiation exhibits reflection / transmission characteristics akin to light hitting a material boundary. So, depending on the angle of incidence, material and the EMF wavelength, it will be reflected and / or transmitted through).

45
docs/hardware/antenna/resources.md
View file

@ -7,47 +7,44 @@ slug: /hardware/resources
### More antenna information
* [Hackaday's Introduction to Antenna Basics](https://www.youtube.com/playlist?list=PL_tws4AXg7authztKFg5ZN5qWGtq3N_nI)
* An excellent series of presentations on the basics of antenna design and function, presented by spacecraft radio engineer Karen Rucker.
- [Hackaday's Introduction to Antenna Basics](https://www.youtube.com/playlist?list=PL_tws4AXg7authztKFg5ZN5qWGtq3N_nI)
- An excellent series of presentations on the basics of antenna design and function, presented by spacecraft radio engineer Karen Rucker.
### Coverage prediction
* [Tower Coverage.com](https://www.towercoverage.com/)
* Commercial, but has free options
- [Tower Coverage.com](https://www.towercoverage.com)
- Commercial, but has free options
* [HeyWhat'sThat](http://www.heywhatsthat.com/)
* Free with path profiling options
- [HeyWhat'sThat](http://www.heywhatsthat.com)
- Free with path profiling options
* [Radio Mobile Online](https://www.ve2dbe.com/rmonline_s.asp)
* Radio Mobile Online is a radio wave propagation prediction tool dedicated to amateur radio
- [Radio Mobile Online](https://www.ve2dbe.com/rmonline_s.asp)
- Radio Mobile Online is a radio wave propagation prediction tool dedicated to amateur radio
### RF Tools
* [Times Microwave Systems](https://www.timesmicrowave.com/calculator/?Product=RG-6&RunLength=10&Frequency=868)
* Coaxial Cable Attenuation & Power Handling Calculator
- [Times Microwave Systems](https://www.timesmicrowave.com/calculator/?Product=RG-6&RunLength=10&Frequency=868)
- Coaxial Cable Attenuation & Power Handling Calculator
* [Solwise Link Budget Calculator](https://www.solwise.co.uk/link-budget.htm)
* Predict the received signal strength
- [Solwise Link Budget Calculator](https://www.solwise.co.uk/link-budget.htm)
- Predict the received signal strength
* [Amateur Radio Toolkit](https://play.google.com/store/apps/details?id=com.daveyhollenberg.amateurradiotoolkit)
* Android app with lots of antenna information
- [Amateur Radio Toolkit](https://play.google.com/store/apps/details?id=com.daveyhollenberg.amateurradiotoolkit)
- Android app with lots of antenna information
### Antenna designs
* [1/4 Wave Ground Plane Antenna Calculator](https://m0ukd.com/calculators/quarter-wave-ground-plane-antenna-calculator/)
- [1/4 Wave Ground Plane Antenna Calculator](https://m0ukd.com/calculators/quarter-wave-ground-plane-antenna-calculator)
- [Quadrifilar helicoidal antenna calculator](https://jcoppens.com/ant/qfh/calc.en.php)
* [Quadrifilar helicoidal antenna calculator](https://jcoppens.com/ant/qfh/calc.en.php)
- [Building an 868/915 MHz co-linear antenna tutorial](https://www.youtube.com/watch?v=1_1LxuOngHs)
- [868 MHz antenna schematic PDF](https://github.com/IRNAS/ttn-irnas-gw/blob/master/Collinear868MHzLoRaantenna.PDF)
- [915 MHz antenna schematic PDF](https://github.com/IRNAS/ttn-irnas-gw/blob/master/CollinearLoRaantenna915MHzIRNAS.PDF)
* [Building an 868/915 MHz co-linear antenna tutorial](https://www.youtube.com/watch?v=1_1LxuOngHs)
* [868 MHz antenna schematic PDF](https://github.com/IRNAS/ttn-irnas-gw/blob/master/Collinear868MHzLoRaantenna.PDF)
* [915 MHz antenna schematic PDF](https://github.com/IRNAS/ttn-irnas-gw/blob/master/CollinearLoRaantenna915MHzIRNAS.PDF)
* [NEC based antenna modeler and optimizer](https://www.qsl.net/4nec2/)
- [NEC based antenna modeler and optimizer](https://www.qsl.net/4nec2)

10
docs/hardware/antenna/testing.md
View file

@ -9,27 +9,29 @@ Testing of antennas can be both simple and complex. At its simplest, testing inv
## Range testing
As mentioned, while stating the obvious, the simplest way of performing a test is:
- Walk around with a radio sending messages,
- For each message, note location and whether 'ACK' ticks are received,
- Also, note reported signal strengths,
- Change aerials, repeat, and evaluate results.
:::note
The [range test plugin](/docs/software/plugins/range-test-plugin) 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/software/modules/range-test-module) 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.
On the topic of testing - performing your own testing and providing feedback is the lifeblood of Meshtastic and open source projects.
## Signal strength testing
Real world testing is also discussed by Andreas Spiess (the 'guy with the Swiss accent') in his [tutorial](https://www.youtube.com/watch?v=J3PBL9oLPX8). He has written [code](https://github.com/SensorsIot/Antenna-Tester) for testing antennas using two Lora32 V1 boards to compare how different antennas behave. Lilygo have also made code available for testing the RSSI on the [LORA32](https://github.com/LilyGO/TTGO-LORA32) [boards](https://github.com/Xinyuan-LilyGO/TTGO-LoRa-Series) and the [T-Beam](https://github.com/LilyGO/TTGO-T-Beam).
Here are a [couple](https://medium.com/home-wireless/testing-lora-antennas-at-915mhz-6d6b41ac8f1d) of [excellent](https://medium.com/home-wireless/testing-and-reviewing-lora-antennas-5b37dfa594a3) aerial comparisons. Their utility goes beyond the specific aerials tested, giving insight into:
Here are a [couple](https://medium.com/home-wireless/testing-lora-antennas-at-915mhz-6d6b41ac8f1d) of [excellent](https://medium.com/home-wireless/testing-and-reviewing-lora-antennas-5b37dfa594a3) aerial comparisons. Their utility goes beyond the specific aerials tested, giving insight into:
- Aerial types & their characteristics,
- Testing approaches.
## Antenna matching & vector network analyzers
One of the first things to ensure, is that the antenna you have is tuned to the frequency that you are using. A lot of cheap antennas come labeled with an incorrect working frequency, and this will immediately reduce the emitted signal strength. A Vector Network Analyzer (VNA) can be used to ensure that the antenna is appropriately matched to the transmission circuit, ensuring that it is operating at the correct impedance, and has a low level of power reflected back from the antenna to the transmitter at the desired transmission frequency.
One of the first things to ensure, is that the antenna you have is tuned to the frequency that you are using. A lot of cheap antennas come labeled with an incorrect working frequency, and this will immediately reduce the emitted signal strength. A Vector Network Analyzer (VNA) can be used to ensure that the antenna is appropriately matched to the transmission circuit, ensuring that it is operating at the correct impedance, and has a low level of power reflected back from the antenna to the transmitter at the desired transmission frequency.
Andreas Spiess also gives a great explanation of [how to use Vector Network Analyzers](https://www.youtube.com/watch?v=ZpKoLvqOWyc) to correctly tune your antennas, as well as a more [in depth tutorial of how to use VNAs](https://www.youtube.com/watch?v=_pjcEKQY_Tk). It is important to remember however, that VNAs can only tell you if the antenna is well-matched, not how well it is transmitting. A 50 ohm resistor across the transmitter output would show as ideally matched, but it would be useless at transmitting a signal. There are a number of VNAs now available for less than $100, making this no longer out of reach for most hobbyists, unlike expensive spectrum analyzers.

3
docs/hardware/overview.md
View file

@ -19,8 +19,9 @@ The following ESP32 devices are supported:
:::caution
Supported but not encouraged:
- Lilygo TTGO T-Beam - version 0.7 -- Very old, no power management chip, difficulty with GPS module and is freqeuntly confused with other devices.
:::
:::
## nRF52

2
docs/hardware/supported/heltec.md
View file

@ -19,7 +19,7 @@ sidebar_label: Heltec
- No GPS
- Firmware file: `firmware-heltec-1.x.x.bin`
- [Purchase link](https://heltec.org/project/wifi-lora-32/)
- [Purchase link](https://heltec.org/project/wifi-lora-32)
[<img src="Heltec WiFi LoRa 32 (V2)" src="/img/hardware/heltec-v2.png" style={{zoom:'25%'}} />](/img/hardware/heltec-v2.png)

2
docs/hardware/supported/lora.md
View file

@ -21,7 +21,6 @@ sidebar_label: LILYGO® Lora
[<img alt="LILYGO® TTGO Lora V1" src="/img/hardware/lora-v1.png" style={{zoom:'25%'}} />](/img/hardware/lora-v1.png)
## Lora V1.3
- ESP32 - Wifi & Bluetooth
@ -59,7 +58,6 @@ sidebar_label: LILYGO® Lora
[<img alt="LILYGO® TTGO Lora V2" src="/img/hardware/lora-v2.0.png" style={{zoom:'25%'}} />](/img/hardware/lora-v2.0.png)
## Lora V2.1-1.6
- ESP32 - Wifi & Bluetooth

3
docs/hardware/supported/tbeam.md
View file

@ -24,7 +24,6 @@ sidebar_label: LILYGO® T-Beam
[<img alt="LILYGO® TTGO T-Beam Meshtastic" src="/img/hardware/t-beam-meshtastic.png" style={{zoom:'25%'}} />](/img/hardware/t-beam-meshtastic.png)
## T-Beam - v0.7
:::note
@ -50,7 +49,6 @@ This is an earlier version of the T-Beam board, and due to changes in the design
[<img alt="LILYGO TTGO T-Beam v0.7" src="/img/hardware/t-beam-v0.7.png" style={{zoom:'25%'}} />](/img/hardware/t-beam-v0.7.png)
[<img alt="LILYGO TTGO T-Beam v0.7 pinmap" src="/img/hardware/t-beam_v0.7_pinmap.jpeg" style={{zoom:'25%'}} />](/img/hardware/t-beam_v0.7_pinmap.jpeg)
## T-Beam - V1.1
- ESP32 - Wifi & Bluetooth
@ -71,7 +69,6 @@ This is an earlier version of the T-Beam board, and due to changes in the design
[<img alt="LILYGO® TTGO T-Beam v1.1" src="/img/hardware/t-beam-v1.1.png" style={{zoom:'35%'}} />](/img/hardware/t-beam-v1.1.png)
[<img alt="LILYGO® TTGO T-Beam v1.1 pinmap" src="/img/hardware/t-beam_v1.1_pinmap.webp" style={{zoom:'35%'}} />](/img/hardware/t-beam_v1.1_pinmap.webp)
## T-Beam - M8N
- ESP32 - Wifi & Bluetooth

1
docs/legal/licensing.md
View file

@ -3,6 +3,7 @@ id: licensing
title: Licensing & Commercial Projects Usage
sidebar_label: Licensing
---
You are hereby granted a two-year non-exclusive license to use the Meshtastic® logo and trademark on your product/project. No fee is required for this usage, though if you wish keeping $1/unit set-aside so that it can eventually fund [meshtastic.org](https://meshtastic.org) it would be appreciated.
We only ask that you include a line in your support text that states:

5
docs/legal/overview.md
View file

@ -4,12 +4,13 @@ title: Legal
sidebar_label: Legal
slug: /legal
---
## Disclaimers
This project is still pretty young but moving at a pretty good pace. Not all features are fully implemented in the current alpha builds.
* We don't make these devices and they haven't been tested by UL or the FCC. If you use them, you are experimenting and we can't promise they won't burn your house down ;-)
* The encryption implementation is good but see this list of [caveats](/docs/developers/device/encryption#summary-of-strengthsweaknesses-of-our-current-implementation) to determine risks you might face.
- We don't make these devices and they haven't been tested by UL or the FCC. If you use them, you are experimenting and we can't promise they won't burn your house down ;-)
- The encryption implementation is good but see this list of [caveats](/docs/developers/firmware/encryption#summary-of-strengthsweaknesses-of-our-current-implementation) to determine risks you might face.
## Legal FAQ

6
docs/legal/privacy.md
View file

@ -9,10 +9,10 @@ We don't collect any personal identifying information. We never capture username
If you opt-in to analytics on the Android app (thank you - that helps us know what things we need to improve), we will receive anonymized information about user behavior. This includes crash reports, screens used in the app, etc... Analytics is provided by [Firebase Crashlytics](https://firebase.google.com/products/crashlytics).
Maps provided by Mapbox require analytics to work. For more information about what they collect, please see the [Mapbox privacy policy](https://www.mapbox.com/legal/privacy/).
Maps provided by Mapbox require analytics to work. For more information about what they collect, please see the [Mapbox privacy policy](https://www.mapbox.com/legal/privacy).
The search engine for this website is provided by Algolia, please see their [privacy policy](https://www.algolia.com/policies/privacy/) for details of what information they collect.
The search engine for this website is provided by Algolia, please see their [privacy policy](https://www.algolia.com/policies/privacy) for details of what information they collect.
This is an open-source project run by hobbyists, and we try to be completely transparent. If you have questions on this policy, please post on the forum, and we'll reply/clarify/correct.
This is an open-source project run by hobbyists, and we try to be completely transparent. If you have questions on this policy, please post on the forum, and we'll reply/clarify/correct.
Keep being awesome!

1
docs/legal/trademark.md
View file

@ -3,4 +3,5 @@ id: trademark
title: Trademark Rules & Brand Guidelines
sidebar_label: Trademark
---
Meshtastic® is a registered trademark of Geeksville Industries LLC. Meshtastic software components are released under various licenses, see GitHub for details. No warranty is provided - use at your own risk.

184
docs/settings/canned-message-plugin.md → docs/settings/canned-message-module.md
View file

@ -1,8 +1,9 @@
---
id: canned-message-plugin
title: Canned Message Plugin
sidebar_label: Canned Message Plugin
id: canned-message-module
title: Canned Message Module
sidebar_label: Canned Message Module
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -11,54 +12,58 @@ GPIO access is fundamentally dangerous because invalid options can physically da
:::
<!--- TODO add link to hardware setup to admonition--->
:::note
This plugin requires attaching a peripheral accessory to your device. It will not work without one. It also requires use of the [Rotary Encoder Plugin](rotary-encoder-plugin) to configure the input source.
This module requires attaching a peripheral accessory to your device. It will not work without one. It also requires use of the [Rotary Encoder Module](rotary-encoder-module) to configure the input source.
:::
## Overview
The CannedMessage Plugin will allow you to send messages to the mesh network from the device without using the phone app. You can predefine text messages to choose from.
The CannedMessage Module will allow you to send messages to the mesh network from the device without using the phone app. You can predefine text messages to choose from.
:::tip
Once plugin settings are changed, a **reset** is required for them to take effect.
Once module settings are changed, a **reset** is required for them to take effect.
:::
## Settings
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| canned_message_plugin_allow_input_source | `rotEnc1`, `_any` | `_any` |
| canned_message_plugin_enabled | `true`, `false` | `false` |
| canned_message_plugin_messages | `string` | `""` |
| canned_message_plugin_send_bell | `true`, `false` | `false` |
| Setting | Acceptable Values | Default |
| :--------------------------------------: | :---------------: | :-----: |
| canned_message_module_allow_input_source | `rotEnc1`, `_any` | `_any` |
| canned_message_module_enabled | `true`, `false` | `false` |
| canned_message_module_messages | `string` | `""` |
| canned_message_module_send_bell | `true`, `false` | `false` |
### canned_message_plugin_allow_input_source
### canned_message_module_allow_input_source
Input event source accepted by the canned message plugin.
Input event source accepted by the canned message module.
| Value | Description |
| :---: | :---------: |
| `_any` | Default. Allows any peripheral input device connected to the device. |
| `rotEnc1` | Hardcoded value naming the input device that this plugin listens to. This could allow multiple input devices to be named with future software development. At present, this doesn't do anything differently than the default setting. |
| Value | Description |
| :-------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `_any` | Default. Allows any peripheral input device connected to the device. |
| `rotEnc1` | Hardcoded value naming the input device that this module listens to. This could allow multiple input devices to be named with future software development. At present, this doesn't do anything differently than the default setting. |
#### Set input source
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set Allowed Input Source"
meshtastic --set canned_message_plugin_allow_input_source "_any"
meshtastic --set canned_message_module_allow_input_source "_any"
```
```bash title="Specify Allowed Input Source"
meshtastic --set canned_message_plugin_allow_input_source "rotEnc1"
meshtastic --set canned_message_module_allow_input_source "rotEnc1"
```
</TabItem>
<TabItem value="android">
@ -83,31 +88,35 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### canned_message_plugin_enabled
### canned_message_module_enabled
Enables the plugin.
Enables the module.
:::tip
Using the canned message plugin requires you set up the [rotary encoder plugin](rotary-encoder-plugin). See [prerequisites](#prerequisites) below.
Using the canned message module requires you set up the [Rotary Encoder Module](rotary-encoder-module). See [prerequisites](#prerequisites) below.
:::
#### Enable/Disable the plugin
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable Canned Message Plugin"
meshtastic --set canned_message_plugin_enabled true
#### Enable/Disable the module
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable Canned Message Module"
meshtastic --set canned_message_module_enabled true
```
```bash title="Disable Canned Message Plugin"
meshtastic --set canned_message_plugin_enabled false
```bash title="Disable Canned Message Module"
meshtastic --set canned_message_module_enabled false
```
</TabItem>
<TabItem value="android">
@ -132,27 +141,29 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### canned_message_plugin_messages
### canned_message_module_messages
Predefined messages for CannedMessagePlugin separated by `|` characters.
Predefined messages for CannedMessageModule separated by `|` characters.
You can define up to 50 messages with a total length 1024 bytes.
#### Set canned messages
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set Canned Messages"
meshtastic --set canned_message_plugin_messages "I'm fine|I'm out|I'm back|Need helping hand|Help me with saw|I need an alpinist|I need ambulance|Keep Calm|On my way|I will be late|I'm already waiting|We have company|Beer is cold|Roger"
meshtastic --set canned_message_module_messages "I'm fine|I'm out|I'm back|Need helping hand|Help me with saw|I need an alpinist|I need ambulance|Keep Calm|On my way|I will be late|I'm already waiting|We have company|Beer is cold|Roger"
```
</TabItem>
<TabItem value="android">
@ -177,29 +188,32 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### canned_message_plugin_send_bell
### canned_message_module_send_bell
CannedMessagePlugin also sends a bell character with the messages.
The [External Notification Plugin](external-notification-plugin) can benefit from this feature as it utilizes the bell character.
CannedMessageModule also sends a bell character with the messages.
The [External Notification Module](external-notification-module) can benefit from this feature as it utilizes the bell character.
#### Enable/Disable bell character
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable Bell Character"
meshtastic --set canned_message_plugin_send_bell true
meshtastic --set canned_message_module_send_bell true
```
```bash title="Disable Bell Character"
meshtastic --set canned_message_plugin_send_bell false
meshtastic --set canned_message_module_send_bell false
```
</TabItem>
<TabItem value="android">
@ -229,20 +243,22 @@ Configuring this setting is not yet available for the selected platform. If this
### Prerequisites
<!--- TODO add link to hardware pages to first bullet point --->
- Attach a compatible peripheral device. Take note of the GPIO numbers you use, as they will be used in the following step.
- Once attached, configure peripheral device with [Rotary Encoder Plugin Settings](rotary-encoder-plugin).
- Once attached, configure peripheral device with [Rotary Encoder Module](rotary-encoder-module) Settings.
:::note
Replace each `GPIO` (x3) below with the GPIO numbers from hardware setup.
```bash title="Canned Message Plugin - Required Rotary Encoder Plugin Settings"
meshtastic --set rotary1_pin_a GPIO
meshtastic --set rotary1_pin_b GPIO
meshtastic --set rotary1_pin_press GPIO
meshtastic --set rotary1_event_cw KEY_UP
meshtastic --set rotary1_event_ccw KEY_DOWN
meshtastic --set rotary1_event_press KEY_SELECT
meshtastic --set rotary1_enabled True
```
```bash title="Canned Message Module - Required Rotary Encoder Module Settings"
meshtastic --set rotary1_pin_a GPIO
meshtastic --set rotary1_pin_b GPIO
meshtastic --set rotary1_pin_press GPIO
meshtastic --set rotary1_event_cw KEY_UP
meshtastic --set rotary1_event_ccw KEY_DOWN
meshtastic --set rotary1_event_press KEY_SELECT
meshtastic --set rotary1_enabled True
```
:::
That's it! With a functioning and enabled rotary encoder, you're ready to begin configuring the Canned Message Plugin.
That's it! With a functioning and enabled rotary encoder, you're ready to begin configuring the Canned Message Module.

138
docs/settings/channel-advanced.md
View file

@ -3,6 +3,7 @@ id: channel-advanced
title: Channel Settings - Advanced
sidebar_label: Channel
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -16,14 +17,14 @@ Most users should not need to change these settings. The default [modem_config](
## Settings
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| bandwidth | `10.4`, `15.6`, `20.8`, `31.25`, `41.7`, `62.5`, `125`, `250`, `500` | `125` |
| channel_num | Depends on Region | Region Channel Number Default |
| coding_rate | `5`, `6`, `7`, `8` | `5` |
| frequency_offset | real numbers | `0` |
| spread_factor | `7`, `8`, `9`, `10`, `11`, `12` | `7` |
| tx_power | `0`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, (dBm) | `0` |
| Setting | Acceptable Values | Default |
| :--------------: | :------------------------------------------------------------------------------------------------: | :---------------------------: |
| bandwidth | `10.4`, `15.6`, `20.8`, `31.25`, `41.7`, `62.5`, `125`, `250`, `500` | `125` |
| channel_num | Depends on Region | Region Channel Number Default |
| coding_rate | `5`, `6`, `7`, `8` | `5` |
| frequency_offset | real numbers | `0` |
| spread_factor | `7`, `8`, `9`, `10`, `11`, `12` | `7` |
| tx_power | `0`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, (dBm) | `0` |
### bandwidth
@ -32,15 +33,15 @@ Total amount of spectrum used for the transmission.
#### Set Bandwidth
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash
meshtastic --ch-set bandwidth 125 --ch-index 0
@ -77,15 +78,15 @@ An abstraction that maps to a specific center frequency used for transmission.
#### Set Channel Number
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
@ -122,15 +123,15 @@ The amount of forward error correction applied to allow for us to automatically
#### Set Coding Rate
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash
meshtastic --ch-set coding_rate 8 --ch-index 0
@ -167,15 +168,15 @@ This parameter is for advanced users with advanced test equipment, we do not rec
#### Configure frequency_offset
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
@ -212,15 +213,15 @@ LoRa is a spread spectrum technology. spread_factor is how much the signal is sp
#### Set Spread Factor
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash
meshtastic --ch-set spread_factor 12 --ch-index 0
@ -263,22 +264,23 @@ Ensure that you are not exceeding your country's regulations.
#### Set TX Power
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set Default"
meshtastic --ch-set tx_power 0 --ch-index 0
```
```bash title="Set to 2dBM"
meshtastic --ch-set tx_power 2 --ch-index 0
```
```bash title="Set Default"
meshtastic --ch-set tx_power 0 --ch-index 0
```
```bash title="Set to 2dBM"
meshtastic --ch-set tx_power 2 --ch-index 0
```
</TabItem>
<TabItem value="android">

246
docs/settings/channel.md
View file

@ -3,6 +3,7 @@ id: channel
title: Channel Settings
sidebar_label: Channel
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -14,33 +15,34 @@ Channel settings are an integral part of the way your devices communicate across
<!--- TODO add other channel settings --->
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| id | `integer` | `0` |
| modem_config | `Bw125Cr45Sf128`, `Bw500Cr45Sf128`, `Bw31_25Cr48Sf512`, `Bw125Cr48Sf4096` | `Bw125Cr48Sf4096` |
| name | `string` | `""` |
| psk | `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `none`, `default`, `random` | `1` |
| region | `Unset`, `US`, `EU433`, `EU865`, `CN`, `JP`, `ANZ`, `KR`, `TW`, `RU` | `Unset` |
| Setting | Acceptable Values | Default |
| :----------: | :---------------------------------------------------------------------------: | :---------------: |
| id | `integer` | `0` |
| modem_config | `Bw125Cr45Sf128`, `Bw500Cr45Sf128`, `Bw31_25Cr48Sf512`, `Bw125Cr48Sf4096` | `Bw125Cr48Sf4096` |
| name | `string` | `""` |
| psk | `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `none`, `default`, `random` | `1` |
| region | `Unset`, `US`, `EU433`, `EU865`, `CN`, `JP`, `ANZ`, `KR`, `TW`, `RU` | `Unset` |
### id
<!--- Used to construct a globally unique channel ID. The full globally unique ID will be: "name.id" where ID is shown as base36. Assuming that the number of meshtastic users is below 20K (true for a long time) the chance of this 64 bit random number colliding with anyone else is super low. And the penalty for collision is low as well, it just means that anyone trying to decrypt channel messages might need to try multiple candidate channels. Any time a non wire compatible change is made to a channel, this field should be regenerated. There are a small number of 'special' globally known (and fairly) insecure standard channels. Those channels do not have a numeric id included in the settings, but instead it is pulled from a table of well known IDs. (see Well Known Channels FIXME) --->
#### Set Channel ID
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set the PRIMARY channel ID"
meshtastic --ch-set id 1234 --ch-index 0
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set the PRIMARY channel ID"
meshtastic --ch-set id 1234 --ch-index 0
```
</TabItem>
<TabItem value="android">
@ -70,33 +72,34 @@ Configuring this setting is not yet available for the selected platform. If this
The channel `id` must be an integer.
:::
### modem_config
| Setting | Name (Range/Speed) | Bandwidth | Coding Rate | Spread Factor | Speed |
| :-----: | :--: | :-------: | :---------: | :-----------: | :-----: |
| `Bw500Cr45Sf128` | Short/Fast | 500 kHz | 4/5 | 7 = 128chips/symbol | 18.89 kbps |
| `Bw125Cr45Sf128` | Short/Slow | 125 kHz | 4/5 | 7 = 128chips/symbol | 4.69 kbps |
| `Bw250Cr47Sf1024` | Medium/Fast | 250 kHz | 4/7 | 10 = 1024chips/symbol | 1.2 kbps |
| `Bw250Cr46Sf2048` | Medium/Slow | 250 kHz | 4/6 | 11 = 2048chips/symbol | 0.75 kbps |
| `Bw31_25Cr48Sf512` | Long/Fast | 31.25 kHz | 4/8 | 9 = 512chips/symbol | 0.19 kbps |
| `Bw125Cr48Sf4096` | Long/Slow | 125 kHz | 4/8 | 12 = 4096chips/symbol | 0.13 kbps |
| Setting | Name (Range/Speed) | Bandwidth | Coding Rate | Spread Factor | Speed |
| :----------------: | :----------------: | :-------: | :---------: | :-------------------: | :--------: |
| `Bw500Cr45Sf128` | Short/Fast | 500 kHz | 4/5 | 7 = 128chips/symbol | 18.89 kbps |
| `Bw125Cr45Sf128` | Short/Slow | 125 kHz | 4/5 | 7 = 128chips/symbol | 4.69 kbps |
| `Bw250Cr47Sf1024` | Medium/Fast | 250 kHz | 4/7 | 10 = 1024chips/symbol | 1.2 kbps |
| `Bw250Cr46Sf2048` | Medium/Slow | 250 kHz | 4/6 | 11 = 2048chips/symbol | 0.75 kbps |
| `Bw31_25Cr48Sf512` | Long/Fast | 31.25 kHz | 4/8 | 9 = 512chips/symbol | 0.19 kbps |
| `Bw125Cr48Sf4096` | Long/Slow | 125 kHz | 4/8 | 12 = 4096chips/symbol | 0.13 kbps |
#### Set Modem
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set Modem - LongSlow"
meshtastic --ch-set modem_config Bw125Cr48Sf4096 --ch-index 0
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set Modem - LongSlow"
meshtastic --ch-set modem_config Bw125Cr48Sf4096 --ch-index 0
```
</TabItem>
<TabItem value="android">
@ -130,24 +133,26 @@ For advanced modem configuration, see [Channel Settings - Advanced](channel-adva
The name of the channel. If this is left an empty string it is assumed that this channel is the special (minimally secure) "Default" channel. Channel Names should be short (less than 12 bytes).
#### Set Channel Name
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set channel name for the PRIMARY channel"
meshtastic --ch-set name MyChannel --ch-index 0
```
```bash title="Set channel name for the PRIMARY channel"
meshtastic --ch-set name MyChannel --ch-index 0
```
```bash title="Set channel name for the PRIMARY channel with spaces"
meshtastic --ch-set name "My Channel" --ch-index 0
```
```bash title="Set channel name for the PRIMARY channel with spaces"
meshtastic --ch-set name "My Channel" --ch-index 0
```
</TabItem>
<TabItem value="android">
@ -182,44 +187,50 @@ A channel `id` must be set in order to name a channel.
Selecting a `default` or any of the `simple` values from the following table will use publicly known encryption keys. They're shipped with Meshtastic source code and thus, anyone can listen to messages encrypted by them. They're great for testing and public channels.
:::
| Setting | Behavior |
| :-----: | :------: |
| `none` | Disable Encryption |
| `default` | Default Encryption (use the weak encryption key) |
| `random` | Generate a secure 256-bit encryption key. Use this setting for private communication. |
| `simple0`- `simple254` | Uses a single byte encoding for encryption |
| Setting | Behavior |
| :--------------------: | :-----------------------------------------------------------------------------------: |
| `none` | Disable Encryption |
| `default` | Default Encryption (use the weak encryption key) |
| `random` | Generate a secure 256-bit encryption key. Use this setting for private communication. |
| `simple0`- `simple254` | Uses a single byte encoding for encryption |
:::tip
If you use Meshtastic for exchanging messages you don't want other people to see, `random` is the setting you should use.
:::
#### Set/Disable Encryption
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set encryption to default on PRIMARY channel"
meshtastic --ch-set psk default --ch-index 0
```
```bash title="Set encryption to random on PRIMARY channel"
meshtastic --ch-set psk random --ch-index 0
```
```bash title="Set encryption to single byte on PRIMARY channel"
meshtastic --ch-set psk simple15 --ch-index 0
```
```bash title="Set encryption to your own key on PRIMARY channel"
meshtastic --ch-set psk 0x1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b --ch-index 0
```
```bash title="Disable encryption on PRIMARY channel"
meshtastic --ch-set psk none --ch-index 0
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set encryption to default on PRIMARY channel"
meshtastic --ch-set psk default --ch-index 0
```
```bash title="Set encryption to random on PRIMARY channel"
meshtastic --ch-set psk random --ch-index 0
```
```bash title="Set encryption to single byte on PRIMARY channel"
meshtastic --ch-set psk simple15 --ch-index 0
```
```bash title="Set encryption to your own key on PRIMARY channel"
meshtastic --ch-set psk 0x1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b --ch-index 0
```
```bash title="Disable encryption on PRIMARY channel"
meshtastic --ch-set psk none --ch-index 0
```
</TabItem>
<TabItem value="android">
@ -248,40 +259,43 @@ Configuring this setting is not yet available for the selected platform. If this
The `region` variable sets which region your radio is configured to work in. It is important to ensure that you've set it to the correct region. If left `Unset`, it will default to `US` settings.
| Name | Center Frequency | Spacing | Number of Channels | Power Limit |
| :--: | :-------: | :-----: | :----------------: | :---------: |
| US | 903.08 | 2.16 | 13 | 0 |
| EU433 | 433.175 | 0.2 | 8 | 0 |
| EU868 | 865.2 | 0.3 | 10 | 0 |
| CN | 470.0 | 2.0 | 20 | 0 |
| JP | 920.0 | 0.5 | 10 | 13 |
| ANZ | 916.0 | 0.5 | 20 | 0 |
| KR | 921.9 | 0.2 | 8 | 0 |
| TW | 923.0 | 0.2 | 10 | 0 |
| RU | 868.9 | 0.2 | 2 | 20 |
| Unset | 903.08 | 2.16 | 13 | 0 |
| Name | Center Frequency | Spacing | Number of Channels | Power Limit |
| :---: | :--------------: | :-----: | :----------------: | :---------: |
| US | 903.08 | 2.16 | 13 | 0 |
| EU433 | 433.175 | 0.2 | 8 | 0 |
| EU868 | 865.2 | 0.3 | 10 | 0 |
| CN | 470.0 | 2.0 | 20 | 0 |
| JP | 920.0 | 0.5 | 10 | 13 |
| ANZ | 916.0 | 0.5 | 20 | 0 |
| KR | 921.9 | 0.2 | 8 | 0 |
| TW | 923.0 | 0.2 | 10 | 0 |
| RU | 868.9 | 0.2 | 2 | 20 |
| Unset | 903.08 | 2.16 | 13 | 0 |
:::note
For more details about `region` settings, you can see the source code [here](https://github.com/meshtastic/Meshtastic-device/blob/master/src/mesh/RadioInterface.cpp)
:::
#### Set Region
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Unset Region"
meshtastic --set region Unset
```
```bash title="Set Region"
meshtastic --set region US
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Unset Region"
meshtastic --set region Unset
```
```bash title="Set Region"
meshtastic --set region US
```
</TabItem>
<TabItem value="android">

293
docs/settings/environmental-measurment-plugin.md → docs/settings/environmental-measurment-module.md
View file

@ -1,8 +1,9 @@
---
id: environmental-measurement-plugin
title: Environmental Measurement Plugin Settings
sidebar_label: Environmental Measurement Plugin
id: environmental-measurement-module
title: Environmental Measurement Module Settings
sidebar_label: Environmental Measurement Module
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -11,52 +12,55 @@ GPIO access is fundamentally dangerous because invalid options can physically da
:::
<!--- TODO add link to hardware setup to admonition--->
:::note
This plugin requires attaching a peripheral accessory to your device. It will not work without one.
This module requires attaching a peripheral accessory to your device. It will not work without one.
:::
## Overview
The Environment Measurement Plugin will allow nodes to send a specific message with information from connected environmental sensors. Currently supported sensors are BME280, BME680, DHT11, DHT12, DHT21, DHT22 and Dallas 1-wire DS18B20.
The Environment Measurement Module will allow nodes to send a specific message with information from connected environmental sensors. Currently supported sensors are BME280, BME680, DHT11, DHT12, DHT21, DHT22 and Dallas 1-wire DS18B20.
:::tip
Once plugin settings are changed, a **reset** is required for them to take effect.
Once module settings are changed, a **reset** is required for them to take effect.
:::
## Settings
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| environmental_measurement_plugin_display_farenheit | `true`, `false` | `false` |
| environmental_measurement_plugin_measurement_enabled | `true`, `false` | `false` |
| environmental_measurement_plugin_read_error_count_threshold | `integer` | `0` |
| environmental_measurement_plugin_recovery_interval | `integer` (seconds) | `0` |
| environmental_measurement_plugin_screen_enabled | `true`, `false` | `0` |
| environmental_measurement_plugin_sensor_pin | `integer` | `0` |
| environmental_measurement_plugin_sensor_type | `0-6` | `0` |
| environmental_measurement_plugin_update_interval | `integer` (seconds) | `0` |
| Setting | Acceptable Values | Default |
| :-----------------------------------------: | :-----------------: | :-----: |
| telemetry_module_display_farenheit | `true`, `false` | `false` |
| telemetry_module_measurement_enabled | `true`, `false` | `false` |
| telemetry_module_read_error_count_threshold | `integer` | `0` |
| telemetry_module_recovery_interval | `integer` (seconds) | `0` |
| telemetry_module_screen_enabled | `true`, `false` | `0` |
| telemetry_module_sensor_pin | `integer` | `0` |
| telemetry_module_sensor_type | `0-6` | `0` |
| telemetry_module_update_interval | `integer` (seconds) | `0` |
### environmental_measurement_plugin_display_farenheit
### telemetry_module_display_farenheit
The sensor is always read in Celsius, but the user can opt to view the temperature display in Fahrenheit using this setting.
#### Display Farenheit/Celsius
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Display Farenheit"
meshtastic --set environmental_measurement_plugin_display_farenheit true
meshtastic --set telemetry_module_display_farenheit true
```
```bash title="Display Celsius"
meshtastic --set environmental_measurement_plugin_display_farenheit false
meshtastic --set telemetry_module_display_farenheit false
```
</TabItem>
@ -83,28 +87,31 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### environmental_measurement_plugin_measurement_enabled
### telemetry_module_measurement_enabled
Enables the plugin.
Enables the module.
#### Enable/Disable the module
#### Enable/Disable the plugin
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable Plugin"
meshtastic --set environmental_measurement_plugin_measurement_enabled true
```bash title="Enable Module"
meshtastic --set telemetry_module_measurement_enabled true
```
```bash title="Disable Plugin"
meshtastic --set environmental_measurement_plugin_measurement_enabled false
```bash title="Disable Module"
meshtastic --set telemetry_module_measurement_enabled false
```
</TabItem>
<TabItem value="android">
@ -129,25 +136,27 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### environmental_measurement_plugin_read_error_count_threshold
### telemetry_module_read_error_count_threshold
Sometimes sensor reads can fail. If this happens, we will retry a configurable number of attempts. Each attempt will be delayed by the minimum required refresh rate for that sensor
#### Configure environmental_measurement_plugin_read_error_count_threshold
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
#### Configure telemetry_module_read_error_count_threshold
```bash title="Configure environmental_measurement_plugin_read_error_count_threshold to 3 tries"
meshtastic --set environmental_measurement_plugin_read_error_count_threshold 3
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Configure telemetry_module_read_error_count_threshold to 3 tries"
meshtastic --set telemetry_module_read_error_count_threshold 3
```
</TabItem>
<TabItem value="android">
@ -172,25 +181,27 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### environmental_measurement_plugin_recovery_interval
### telemetry_module_recovery_interval
Sometimes we can end up with more than read_error_count_threshold failures. In this case, we will stop trying to read from the sensor for a while. Wait this long until trying to read from the sensor again.
#### Configure environmental_measurement_plugin_recovery_interval
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
#### Configure telemetry_module_recovery_interval
```bash title="Configure environmental_measurement_plugin_recovery_interval to 120 seconds"
meshtastic --set environmental_measurement_plugin_recovery_interval 120
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Configure telemetry_module_recovery_interval to 120 seconds"
meshtastic --set telemetry_module_recovery_interval 120
```
</TabItem>
<TabItem value="android">
@ -215,28 +226,31 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### environmental_measurement_plugin_screen_enabled
### telemetry_module_screen_enabled
Enable/Disable the environmental measurement plugin on-device display.
Enable/Disable the environmental measurement module on-device display.
#### Enable/Disable the module on device screen
#### Enable/Disable the plugin on device screen
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable on device screen"
meshtastic --set environmental_measurement_plugin_screen_enabled true
meshtastic --set telemetry_module_screen_enabled true
```
```bash title="Disable on device screen"
meshtastic --set environmental_measurement_plugin_screen_enabled false
meshtastic --set telemetry_module_screen_enabled false
```
</TabItem>
<TabItem value="android">
@ -261,10 +275,10 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### environmental_measurement_plugin_sensor_pin
### telemetry_module_sensor_pin
:::note
The preferred setup is using I2C, so the `environmental_measurement_plugin_sensor_pin` may not be needed.
The preferred setup is using I2C, so the `telemetry_module_sensor_pin` may not be needed.
:::
Specify the preferred GPIO Pin for sensor readings. May not be needed if using I2C.
@ -273,20 +287,21 @@ Specify the preferred GPIO Pin for sensor readings. May not be needed if using I
To prevent damaging your device, double check your device's schematics before attaching to the GPIO pins and setting this value.
:::
#### Set plugin sensor pin
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
#### Set module sensor pin
```bash title="Set plugin sensor pin"
meshtastic --set environmental_measurement_plugin_sensor_pin PINNUMBER
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set module sensor pin"
meshtastic --set telemetry_module_sensor_pin PINNUMBER
```
</TabItem>
@ -313,43 +328,44 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### environmental_measurement_plugin_sensor_type
### telemetry_module_sensor_type
Specify the sensor type.
| Value | Description | Sensor Features |
| :---: | :---------: | :-------------: |
| `0` | DHT11 | Temperature, Humidity |
| `1` | DS18B20 (Dallas 1-wire) | Temperature |
| `2` | DHT12 | Temperature, Humidity |
| `3` | DHT21 | Temperature, Humidity |
| `4` | DHT22 | Temperature, Humidity |
| `5` | BME280 | Temperature, Humidity, Pressure |
| `6` | BME680 | Temperature, Humidity, Pressure, VOC Gas |
| `7` | MCP9808 | Precision Temperature |
| Value | Description | Sensor Features |
| :---: | :---------------------: | :--------------------------------------: |
| `0` | DHT11 | Temperature, Humidity |
| `1` | DS18B20 (Dallas 1-wire) | Temperature |
| `2` | DHT12 | Temperature, Humidity |
| `3` | DHT21 | Temperature, Humidity |
| `4` | DHT22 | Temperature, Humidity |
| `5` | BME280 | Temperature, Humidity, Pressure |
| `6` | BME680 | Temperature, Humidity, Pressure, VOC Gas |
| `7` | MCP9808 | Precision Temperature |
#### Set sensor type
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
:::note
The CLI is able to take the `value` or the `name` of the sensor from the table above.
:::
```bash title="Set sensor type to DS18B20"
meshtastic --set environmental_measurement_plugin_sensor_type 1
meshtastic --set telemetry_module_sensor_type 1
```
```bash title="Set sensor type to DS18B20"
meshtastic --set environmental_measurement_plugin_sensor_type DS18B20
meshtastic --set telemetry_module_sensor_type DS18B20
```
</TabItem>
@ -376,24 +392,25 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### environmental_measurement_plugin_update_interval
### telemetry_module_update_interval
Interval in seconds of how often we should try to send our measurements to the mesh.
#### Set plugin update interval
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
#### Set module update interval
```bash title="Set plugin update interval to 15 seconds"
meshtastic --set environmental_measurement_plugin_update_interval 15
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set module update interval to 15 seconds"
meshtastic --set telemetry_module_update_interval 15
```
</TabItem>
@ -428,4 +445,4 @@ The sensors can be wired differently, here's [one example](https://randomnerdtut
### Known Problems
* No default configuration values are currently set, so this must be done when enabling the plugin.
- No default configuration values are currently set, so this must be done when enabling the module.

197
docs/settings/external-notification-plugin.md → docs/settings/external-notification-module.md
View file

@ -1,8 +1,9 @@
---
id: external-notification-plugin
title: External Notification Plugin Settings
sidebar_label: External Notification Plugin
id: external-notification-module
title: External Notification Module Settings
sidebar_label: External Notification Module
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -11,30 +12,31 @@ GPIO access is fundamentally dangerous because invalid options can physically da
:::
<!--- TODO add link to hardware setup to admonition--->
:::note
This plugin requires attaching a peripheral accessory to your device. It will not work without one.
This module requires attaching a peripheral accessory to your device. It will not work without one.
:::
## Overview
The External Notification Plugin will allow you to connect a speaker, LED, or other device to notify you when a message has been received from the mesh network.
The External Notification Module will allow you to connect a speaker, LED, or other device to notify you when a message has been received from the mesh network.
:::tip
Once plugin settings are changed, a **reset** is required for them to take effect.
Once module settings are changed, a **reset** is required for them to take effect.
:::
## Settings
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| ext_notification_plugin_active | `true`, `false` | `false` |
| ext_notification_plugin_alert_bell | `true`, `false` | `false` |
| ext_notification_plugin_alert_message | `true`, `false` | `false` |
| ext_notification_plugin_enabled | `true`, `false` | `false` |
| ext_notification_plugin_output | `integer` | `0` |
| ext_notification_plugin_output_ms | `integer` (milliseconds) | `0` |
| Setting | Acceptable Values | Default |
| :-----------------------------------: | :----------------------: | :-----: |
| ext_notification_module_active | `true`, `false` | `false` |
| ext_notification_module_alert_bell | `true`, `false` | `false` |
| ext_notification_module_alert_message | `true`, `false` | `false` |
| ext_notification_module_enabled | `true`, `false` | `false` |
| ext_notification_module_output | `integer` | `0` |
| ext_notification_module_output_ms | `integer` (milliseconds) | `0` |
### ext_notification_plugin_active
### ext_notification_module_active
Specifies whether the external circuit is triggered when the device's GPIO is low or high.
@ -43,23 +45,26 @@ To prevent damaging your device, double check your device's schematics before at
:::
#### Specify High/Low GPIO triggers circuit
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="GPIO active high"
meshtastic --set ext_notification_plugin_active true
meshtastic --set ext_notification_module_active true
```
```bash title="GPIO active low (default)"
meshtastic --set ext_notification_plugin_active false
meshtastic --set ext_notification_module_active false
```
</TabItem>
<TabItem value="android">
@ -84,28 +89,31 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### ext_notification_plugin_alert_bell
### ext_notification_module_alert_bell
Specifies if an alert should be sent when receiving an incoming bell.
#### Enable/Disable alert on incoming bell
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable alert on incoming bell"
meshtastic --set ext_notification_plugin_alert_bell true
meshtastic --set ext_notification_module_alert_bell true
```
```bash title="Disable alert on incoming bell"
meshtastic --set ext_notification_plugin_alert_bell false
meshtastic --set ext_notification_module_alert_bell false
```
</TabItem>
<TabItem value="android">
@ -130,28 +138,31 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### ext_notification_plugin_alert_message
### ext_notification_module_alert_message
Specifies if an alert should be sent when receiving an incoming message.
#### Enable/Disable Alert on incoming message
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable alert on incoming message"
meshtastic --set ext_notification_plugin_alert_message true
meshtastic --set ext_notification_module_alert_message true
```
```bash title="Disable alert on incoming message"
meshtastic --set ext_notification_plugin_alert_message false
meshtastic --set ext_notification_module_alert_message false
```
</TabItem>
<TabItem value="android">
@ -176,28 +187,31 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### ext_notification_plugin_enabled
### ext_notification_module_enabled
Enables the plugin.
Enables the module.
#### Enable/Disable the module
#### Enable/Disable the plugin
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable Plugin"
meshtastic --set ext_notification_plugin_enabled true
```bash title="Enable Module"
meshtastic --set ext_notification_module_enabled true
```
```bash title="Disable Plugin"
meshtastic --set ext_notification_plugin_enabled false
```bash title="Disable Module"
meshtastic --set ext_notification_module_enabled false
```
</TabItem>
<TabItem value="android">
@ -222,7 +236,7 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### ext_notification_plugin_output
### ext_notification_module_output
Specifies the GPIO that your external circuit is attached to on the device.
@ -231,24 +245,26 @@ To prevent damaging your device, double check your device's schematics before at
:::
#### Specify GPIO for circuit to monitor
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
:::note
Replace `GPIO` in the below command with the GPIO number your circuit is attached to.
:::
```bash title="Specify GPIO that circuit is connected to"
meshtastic --set ext_notification_plugin_output GPIO
meshtastic --set ext_notification_module_output GPIO
```
</TabItem>
<TabItem value="android">
@ -273,28 +289,31 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### ext_notification_plugin_output_ms
### ext_notification_module_output_ms
Specifies how long in milliseconds you would like your external circuit triggered. Default is `1000`. (Because of the way that defaults are handled in the protobufs `0` is interpreted as `1000`)
#### Specify how many milliseconds to trigger circuit
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set to default (1000ms)"
meshtastic --set ext_notification_plugin_output_ms 0
meshtastic --set ext_notification_module_output_ms 0
```
```bash title="Set to other value"
meshtastic --set ext_notification_plugin_output_ms 1500
meshtastic --set ext_notification_module_output_ms 1500
```
</TabItem>
<TabItem value="android">

513
docs/settings/gps.md
View file

@ -3,6 +3,7 @@ id: gps
title: GPS Settings
sidebar_label: GPS
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -16,19 +17,19 @@ GPS is provided by either the device or your paired phone. More than likely, you
## Settings
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| fixed_position | `true`, `false` | `false` |
| gps_accept_2d | `true`, `false` | `false` |
| gps_attempt_time | `integer` (seconds) | `0` (see note) |
| gps_format | `GpsFormatDec`, `GpsFormatDMS`, `GpsFormatUTM`, `GpsFormatMGRS`, `GpsFormatOLC`, `GpsFormatOSGR` | `GpsFormatDec` |
| gps_max_dop | `integer` | `0` |
| gps_operation | `GpsOpUnset`, ~~`GpsOpStationary`~~, `GpsOpMobile`, `GpsOpTimeOnly`, `GpsOpDisabled` | `GpsOpUnset` |
| gps_update_interval | `integer` (seconds) | `0` (see note) |
| location_share | `LocUnset`, `LocEnabled`, `LocDisabled` | `LocUnset` |
| position_broadcast_secs | `integer` (seconds) | `0` (see note) |
| position_broadcast_smart | `true`, `false` | `false` |
| position_flags | `POS_UNDEFINED`, `POS_ALTITUDE`, `POS_ALT_MSL`, `POS_GEO_SEP`, `POS_DOP`, `POS_HVDOP`, `PDOP`, `POS_BATTERY`, `POS_SATINVIEW`, `POS_SEQ_NOS`, `POS_TIMESTAMP` | `POS_UNDEFINED` |
| Setting | Acceptable Values | Default |
| :----------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------: |
| fixed_position | `true`, `false` | `false` |
| gps_accept_2d | `true`, `false` | `false` |
| gps_attempt_time | `integer` (seconds) | `0` (see note) |
| gps_format | `GpsFormatDec`, `GpsFormatDMS`, `GpsFormatUTM`, `GpsFormatMGRS`, `GpsFormatOLC`, `GpsFormatOSGR` | `GpsFormatDec` |
| gps_max_dop | `integer` | `0` |
| gps_operation | `GpsOpUnset`, ~~`GpsOpStationary`~~, `GpsOpMobile`, `GpsOpTimeOnly`, `GpsOpDisabled` | `GpsOpUnset` |
| gps_update_interval | `integer` (seconds) | `0` (see note) |
| location_share | `LocUnset`, `LocEnabled`, `LocDisabled` | `LocUnset` |
| position_broadcast_secs | `integer` (seconds) | `0` (see note) |
| position_broadcast_smart | `true`, `false` | `false` |
| position_flags | `POS_UNDEFINED`, `POS_ALTITUDE`, `POS_ALT_MSL`, `POS_GEO_SEP`, `POS_DOP`, `POS_HVDOP`, `PDOP`, `POS_BATTERY`, `POS_SATINVIEW`, `POS_SEQ_NOS`, `POS_TIMESTAMP` | `POS_UNDEFINED` |
:::note
On `gps_attempt_time`, `gps_update_interval`, & `position_broadcast_secs` when you set these to `0` you are not disabling these features.
@ -43,34 +44,39 @@ If you wish to disable any GPS features, see below for more information.
If set, this node is at a fixed position. The device will generate GPS updates at the regular `gps_update_interval`, but use whatever the last lat/lon/alt it saved for the node. The lat/lon/alt can be set by an internal GPS or with the help of the mobile device's GPS.
#### Set/Unset Fixed Position
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set Fixed Position - Current Location"
meshtastic --set fixed_position true
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set Fixed Position - Current Location"
meshtastic --set fixed_position true
```
:::note
The device will continue to acquire GPS coordinates according to the `gps_update_interval`, but will use the last saved coordinates as its fixed point.
:::
```bash title="Set Fixed Position - User Defined"
meshtastic --setlat 37.8651 --setlon -119.5383
```
```bash title="Unset Fixed Position"
meshtastic --set fixed_position false
```
```bash title="Set Fixed Position - User Defined"
meshtastic --setlat 37.8651 --setlon -119.5383
```
```bash title="Unset Fixed Position"
meshtastic --set fixed_position false
```
:::note
It may take some time to see that the change has taken effect. The GPS location is updated according to the value specified on `gps_update_interval` and the mesh will be notified of the new position in relation to the `position_broadcast_secs` value.
:::
</TabItem>
<TabItem value="android">
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
@ -98,23 +104,25 @@ Configuring this setting is not yet available for the selected platform. If this
Determines whether the device should accept 2D GPS fixes. By default, only 3D fixes are accepted (during a 2D fix, altitude values are unreliable and will be excluded).
#### Enable/Disable 2D GPS Fixes
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable 2D GPS Fixes"
meshtastic --set gps_accept_2d true
```
```bash title="Disable 2D GPS Fixes"
meshtastic --set gps_accept_2d false
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable 2D GPS Fixes"
meshtastic --set gps_accept_2d true
```
```bash title="Disable 2D GPS Fixes"
meshtastic --set gps_accept_2d false
```
</TabItem>
<TabItem value="android">
@ -145,23 +153,25 @@ Configuring this setting is not yet available for the selected platform. If this
Determines the amount of time that a GPS fix should be allowed to take. The default is every 30 seconds. If you increase this value, it will allow the device that amount of time in seconds to acquire coordinates. If the device is unable to get a fix, it will turn off until the next interval. GPS coordinates are updated every [`gps_update_interval`](#gps_update_interval) seconds.
#### Change GPS attempt time frequency
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set GPS attempt time to default (30 seconds)"
meshtastic --set gps_attempt_time 0
```
```bash title="Set GPS attempt time to 45 seconds"
meshtastic --set gps_attempt_time 45
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set GPS attempt time to default (30 seconds)"
meshtastic --set gps_attempt_time 0
```
```bash title="Set GPS attempt time to 45 seconds"
meshtastic --set gps_attempt_time 45
```
</TabItem>
<TabItem value="android">
@ -191,30 +201,31 @@ Configuring this setting is not yet available for the selected platform. If this
Determines how the GPS coordinates are displayed on the OLED screen.
| Value | Description |
| :---: | :---------: |
| GpsFormatDec | GPS coordinates are displayed in the normal decimal degrees format: DD.DDDDDD DDD.DDDDDD |
| GpsFormatDMS | GPS coordinates are displayed in the degrees minutes seconds format: DD°MM'SS"C DDD°MM'SS"C, where C is the compass point representing the locations quadrant |
| GpsFormatUTM | GPS coordinates are displayed in Universal Transverse Mercator format: ZZB EEEEEE NNNNNNN, where Z is zone, B is band, E is easting, N is northing |
| GpsFormatMGRS | GPS coordinates are displayed in Military Grid Reference System format: ZZB CD EEEEE NNNNN, where Z is zone, B is band, C is the east 100k square, D is the north 100k square, E is easting, N is northing |
| GpsFormatOLC | GPS coordinates are displayed in Open Location Code (aka Plus Codes) |
| Value | Description |
| :-----------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| GpsFormatDec | GPS coordinates are displayed in the normal decimal degrees format: DD.DDDDDD DDD.DDDDDD |
| GpsFormatDMS | GPS coordinates are displayed in the degrees minutes seconds format: DD°MM'SS"C DDD°MM'SS"C, where C is the compass point representing the locations quadrant |
| GpsFormatUTM | GPS coordinates are displayed in Universal Transverse Mercator format: ZZB EEEEEE NNNNNNN, where Z is zone, B is band, E is easting, N is northing |
| GpsFormatMGRS | GPS coordinates are displayed in Military Grid Reference System format: ZZB CD EEEEE NNNNN, where Z is zone, B is band, C is the east 100k square, D is the north 100k square, E is easting, N is northing |
| GpsFormatOLC | GPS coordinates are displayed in Open Location Code (aka Plus Codes) |
| GpsFormatOSGR | GPS coordinates are displayed in Ordnance Survey Grid Reference (the National Grid System of the UK). Format: AB EEEEE NNNNN, where A is the east 100k square, B is the north 100k square, E is the easting, N is the northing |
#### Specify GPS Screen Display
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Specify GPS format on device screen"
meshtastic --set gps_format GpsFormatUTM
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Specify GPS format on device screen"
meshtastic --set gps_format GpsFormatUTM
```
</TabItem>
<TabItem value="android">
@ -245,26 +256,29 @@ Configuring this setting is not yet available for the selected platform. If this
Determines GPS maximum DOP accepted (dilution of precision) Set a rejection threshold for GPS readings based on their precision, relative to the GPS rated accuracy (which is typically ~3m) Solutions above this value will be treated as retryable errors! Useful range is between 1 - 64 (3m - <~200m) By default (if zero), accept all GPS readings
#### Change maximum GPS dilution of precision
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set GPS max DOP to default (accept all GPS readings)"
meshtastic --set gps_max_dop 0
```
```bash title="Set GPS max DOP to 3m"
meshtastic --set gps_max_dop 1
```
```bash title="Set GPS max DOP to < ~200m"
meshtastic --set gps_max_dop 64
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set GPS max DOP to default (accept all GPS readings)"
meshtastic --set gps_max_dop 0
```
```bash title="Set GPS max DOP to 3m"
meshtastic --set gps_max_dop 1
```
```bash title="Set GPS max DOP to < ~200m"
meshtastic --set gps_max_dop 64
```
</TabItem>
<TabItem value="android">
@ -291,20 +305,21 @@ Configuring this setting is not yet available for the selected platform. If this
</Tabs>
#### Specify GPS Screen Display
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Specify GPS format on device screen"
meshtastic --set gps_format GpsFormatUTM
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Specify GPS format on device screen"
meshtastic --set gps_format GpsFormatUTM
```
</TabItem>
<TabItem value="android">
@ -338,35 +353,38 @@ How the GPS hardware in the device is operated.
This is independent of how our location is shared with other devices. For that see [`location_share`](#location_share).
:::
| Value | Description |
| :---: | :---------: |
| GpsOpUnset | **Default**: operates the same as `GpsOpMobile`. |
| Value | Description |
| :-----------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| GpsOpUnset | **Default**: operates the same as `GpsOpMobile`. |
| ~~GpsOpStationary~~ | Note: This mode was removed, because it is identical go `GpsOpMobile` with a `gps_update_interval` of once per day This node is mostly stationary, we should try to get location only once per day, Once we have that position we should turn the GPS to sleep mode This is the recommended configuration for stationary 'router' nodes |
| GpsOpMobile | This node is mobile and we should get GPS position at a rate governed by `gps_update_interval` |
| GpsOpTimeOnly | We should only use the GPS to get time (no location data should be acquired/stored) Once we have the time we treat `gps_update_interval` as MAXINT (i.e. sleep forever) |
| GpsOpDisabled | GPS is always turned off - this mode is not recommended - use `GpsOpTimeOnly` instead. |
| GpsOpMobile | This node is mobile and we should get GPS position at a rate governed by `gps_update_interval` |
| GpsOpTimeOnly | We should only use the GPS to get time (no location data should be acquired/stored) Once we have the time we treat `gps_update_interval` as MAXINT (i.e. sleep forever) |
| GpsOpDisabled | GPS is always turned off - this mode is not recommended - use `GpsOpTimeOnly` instead. |
#### Enable/Disable GPS
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set GPS to default settings"
meshtastic --set gps_operation GpsOpUnset
```
```bash title="Set GPS to only be used for time"
meshtastic --set gps_operation GpsOpTimeOnly
```
```bash title="Disable GPS Completely"
meshtastic --set gps_operation GpsOpDisabled
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set GPS to default settings"
meshtastic --set gps_operation GpsOpUnset
```
```bash title="Set GPS to only be used for time"
meshtastic --set gps_operation GpsOpTimeOnly
```
```bash title="Disable GPS Completely"
meshtastic --set gps_operation GpsOpDisabled
```
</TabItem>
<TabItem value="android">
@ -401,23 +419,25 @@ Configuring this setting is not yet available for the selected platform. If this
Determines how often should the device should attempt to acquire a GPS position (in seconds). The length of time the device is allowed to attempt to acquire GPS coordinates each interval is set using [`gps_attempt_time`](#gps_attempt_time). The default is every 30 seconds.
#### Specify GPS update interval
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set GPS update interval to default settings (every 30 seconds)"
meshtastic --set gps_update_interval 0
```
```bash title="Set GPS update interval to every 45 seconds"
meshtastic --set gps_update_interval 45
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set GPS update interval to default settings (every 30 seconds)"
meshtastic --set gps_update_interval 0
```
```bash title="Set GPS update interval to every 45 seconds"
meshtastic --set gps_update_interval 45
```
</TabItem>
<TabItem value="android">
@ -447,27 +467,28 @@ Configuring this setting is not yet available for the selected platform. If this
Determines whether location is shared with other nodes. See more details.
| Value | Description |
| :---: | :---------: |
| LocUnset | **Default**: operates the same as `LocEnabled`|
| LocEnabled | The device is sharing its location (or the paired phone's location) |
| Value | Description |
| :---------: | :--------------------------------------------------------------------------------------------------------------------------------------: |
| LocUnset | **Default**: operates the same as `LocEnabled` |
| LocEnabled | The device is sharing its location (or the paired phone's location) |
| LocDisabled | The device is not sharing its location (if the unit has a GPS it will default to only get time - i.e. [`GpsOpTimeOnly`](#gps_operation)) |
#### Disable Location Sharing
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Disable Location Sharing"
meshtastic --set location_share LocDisabled
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Disable Location Sharing"
meshtastic --set location_share LocDisabled
```
</TabItem>
<TabItem value="android">
@ -504,23 +525,25 @@ How often our position is sent to the mesh (but only if it has changed significa
The GPS updates will be sent out every `position_broadcast_secs`, with either the actual GPS location, or an empty location if no GPS fix was achieved. This defaults to broadcast every 15 minutes.
#### Specify GPS position broadcast frequency
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set GPS update interval to default settings (every 15 minutes)"
meshtastic --set position_broadcast_secs 0
```
```bash title="Set GPS update interval to every 60 seconds"
meshtastic --set position_broadcast_secs 60
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set GPS update interval to default settings (every 15 minutes)"
meshtastic --set position_broadcast_secs 0
```
```bash title="Set GPS update interval to every 60 seconds"
meshtastic --set position_broadcast_secs 60
```
</TabItem>
<TabItem value="android">
@ -558,37 +581,39 @@ As an example, if you configure your radio to use **Long Range / Fast**, if you
The table below is a summary computed values from the algorithm.
| Long Name | Update every x-seconds | Update distance traveled (meters) |
| :---: | :---------: | :---------: |
| Long Range / Slow | 88 | 150 |
| Long Range / Fast | 61 | 144 |
| Medium Range / Slow | 30 | 41 |
| Medium Range / Fast | 30 | 30 |
| Short Range / Slow | 30 | 30 |
| Short Range / Fast | 30 | 30 |
| Long Name | Update every x-seconds | Update distance traveled (meters) |
| :-----------------: | :--------------------: | :-------------------------------: |
| Long Range / Slow | 88 | 150 |
| Long Range / Fast | 61 | 144 |
| Medium Range / Slow | 30 | 41 |
| Medium Range / Fast | 30 | 30 |
| Short Range / Slow | 30 | 30 |
| Short Range / Fast | 30 | 30 |
:::tip
A person walking in a straight line will take about 90 seconds to travel 150 meters. That walking speed estimate was used as the baseline for the formula used.
:::
#### Enable/Disable Smart Position Broadcast
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable smart position broadcast"
meshtastic --set position_broadcast_smart true
```
```bash title="Disable smart position broadcast"
meshtastic --set position_broadcast_smart false
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable smart position broadcast"
meshtastic --set position_broadcast_smart true
```
```bash title="Disable smart position broadcast"
meshtastic --set position_broadcast_smart false
```
</TabItem>
<TabItem value="android">
@ -618,41 +643,43 @@ Configuring this setting is not yet available for the selected platform. If this
Bit field of boolean configuration options for POSITION messages (bitwise OR of PositionFlags)
| Value | Description |
| :---: | :---------: |
| POS_UNDEFINED | Required for compilation |
| POS_ALTITUDE | Include an altitude value (if available) |
| POS_ALT_MSL | Altitude value is MSL |
| POS_GEO_SEP | Include geoidal separation |
| POS_DOP | Include the DOP value ; PDOP used by default, see below |
| POS_HVDOP | If POS_DOP set, send separate HDOP / VDOP values instead of | PDOP
| POS_BATTERY | Include battery level |
| POS_SATINVIEW | Include number of "satellites in view" |
| POS_SEQ_NOS | Include a sequence number incremented per packet |
| POS_TIMESTAMP | Include positional timestamp (from GPS solution) |
| Value | Description |
| :-----------: | :---------------------------------------------------------: | ---- |
| POS_UNDEFINED | Required for compilation |
| POS_ALTITUDE | Include an altitude value (if available) |
| POS_ALT_MSL | Altitude value is MSL |
| POS_GEO_SEP | Include geoidal separation |
| POS_DOP | Include the DOP value ; PDOP used by default, see below |
| POS_HVDOP | If POS_DOP set, send separate HDOP / VDOP values instead of | PDOP |
| POS_BATTERY | Include battery level |
| POS_SATINVIEW | Include number of "satellites in view" |
| POS_SEQ_NOS | Include a sequence number incremented per packet |
| POS_TIMESTAMP | Include positional timestamp (from GPS solution) |
#### Set/Unset Position Flags
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
:::tip
Include each flag desired from the table above separated by a single space.
:::
```bash title="Set Position Flags"
meshtastic --pos-fields POS_ALTITUDE POS_ALT_MSL
```
```bash title="Unset Position Flags"
meshtastic --pos-fields POS_UNDEFINED
```
```bash title="Set Position Flags"
meshtastic --pos-fields POS_ALTITUDE POS_ALT_MSL
```
```bash title="Unset Position Flags"
meshtastic --pos-fields POS_UNDEFINED
```
</TabItem>
<TabItem value="android">

46
docs/settings/ham.md
View file

@ -3,6 +3,7 @@ id: ham
title: Licensed (HAM) Operation
sidebar_label: Licensed (HAM) Operation
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -18,15 +19,15 @@ This written US only, may or may not be applicable elsewhere.
Meshtastic can be used by both unlicensed people and licensed operators. If you use Meshtastic with your ham radio license, there are additional privileges and restrictions to consider.
| Privileges | Restrictions |
|:----------:|:------------:|
| Privileges | Restrictions |
| :-------------------------------------------------------------: | :-----------------------------------------------------------: |
| <ul><li>Additional Power</li><li>Higher gain antennas</li></ul> | <ul><li>Unencrypted</li><li>Identified with your ID</li></ul> |
## Settings
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| set-ham | `string`| `""`|
| set-ham | `string` | `""` |
### set-ham
@ -37,20 +38,21 @@ By changing these settings, you are self certifying that you are licensed to ope
:::
#### Set HAM ID
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set HAM ID"
meshtastic --set-ham KI1345
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set HAM ID"
meshtastic --set-ham KI1345
```
</TabItem>
<TabItem value="android">
@ -80,9 +82,9 @@ Configuring this setting is not yet available for the selected platform. If this
Toggling `set-ham` changes your device settings in the following ways.
| Setting | `set-ham` Default | Normal Default |
| :-----: | :-----------------: | :------------: |
| `is_licensed` (Protobuf) | `true` | `false` |
| `long_name` (Protobuf) | `id` | User Defined |
| `psk` (Protobuf) | `""` | See [Channel Settings - psk](channel#psk) |
| `short_name` (Protobuf) | TODO | User Defined |
| Setting | `set-ham` Default | Normal Default |
| :----------------------: | :---------------: | :---------------------------------------: |
| `is_licensed` (Protobuf) | `true` | `false` |
| `long_name` (Protobuf) | `id` | User Defined |
| `psk` (Protobuf) | `""` | See [Channel Settings - psk](channel#psk) |
| `short_name` (Protobuf) | TODO | User Defined |

200
docs/settings/misc.md
View file

@ -3,25 +3,22 @@ id: misc
title: Miscellaneous Settings
sidebar_label: Miscellaneous
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
## Overview
## Settings
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| auto_screen_carousel_secs | `integer` (seconds) | `0` |
| debug_log_enabled | `true`, `false` | `false` |
| factory_reset | `true`, `false` | `false` |
| ignore_incoming | `string` – list of node nums to ignore | `0` |
| hop_limit | `0`-`7` | `0` |
| serial_disabled | `true`, `false` | `false` |
| Setting | Acceptable Values | Default |
| :-----------------------: | :------------------------------------: | :-----: |
| auto_screen_carousel_secs | `integer` (seconds) | `0` |
| debug_log_enabled | `true`, `false` | `false` |
| factory_reset | `true`, `false` | `false` |
| ignore_incoming | `string` – list of node nums to ignore | `0` |
| hop_limit | `0`-`7` | `0` |
| serial_disabled | `true`, `false` | `false` |
### auto_screen_carousel_secs
@ -30,22 +27,23 @@ Automatically toggles to the next page on the screen like a carousel, based the
#### Configure auto_screen_carousel_secs
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set auto_screen_carousel_secs to default"
meshtastic --set auto_screen_carousel_secs 0
```
```bash title="Set auto_screen_carousel_secs to 120 seconds"
meshtastic --set auto_screen_carousel_secs 120
```
```bash title="Set auto_screen_carousel_secs to default"
meshtastic --set auto_screen_carousel_secs 0
```
```bash title="Set auto_screen_carousel_secs to 120 seconds"
meshtastic --set auto_screen_carousel_secs 120
```
</TabItem>
<TabItem value="android">
@ -78,22 +76,23 @@ By default we turn off logging as soon as an API client connects (to keep shared
#### Enable/Disable Debug Log
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable debug log"
meshtastic --set debug_log_enabled true
```
```bash title="Disable debug log"
meshtastic --set debug_log_enabled false
```
```bash title="Enable debug log"
meshtastic --set debug_log_enabled true
```
```bash title="Disable debug log"
meshtastic --set debug_log_enabled false
```
</TabItem>
<TabItem value="android">
@ -126,19 +125,19 @@ This setting is never saved to disk, but if set, all device settings will be ret
#### Factory reset
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Example - Factory reset"
meshtastic --set factory_reset true
```
```bash title="Example - Factory reset"
meshtastic --set factory_reset true
```
</TabItem>
<TabItem value="android">
@ -171,22 +170,23 @@ If true, radio should not try to be smart about what packets to queue to the pho
#### Enable/Disable ignore_incoming
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable ignore_incoming"
meshtastic --set ignore_incoming true
```
```bash title="Disable ignore_incoming"
meshtastic --set ignore_incoming false
```
```bash title="Enable ignore_incoming"
meshtastic --set ignore_incoming true
```
```bash title="Disable ignore_incoming"
meshtastic --set ignore_incoming false
```
</TabItem>
<TabItem value="android">
@ -219,22 +219,23 @@ If set, this will disable the SerialConsole by not initializing the StreamAPI.
#### Enable/Disable Serial
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable serial"
meshtastic --set serial_disabled false
```
```bash title="Disable serial"
meshtastic --set serial_disabled true
```
```bash title="Enable serial"
meshtastic --set serial_disabled false
```
```bash title="Disable serial"
meshtastic --set serial_disabled true
```
</TabItem>
<TabItem value="android">
@ -271,22 +272,23 @@ Meshtastic allows a maximum of 7 hops (this is a limit of the protocol). Setting
#### Configure hop_limit
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set hop_limit to default (3 hops)"
meshtastic --set hop_limit 0
```
```bash title="Set hop_limit to max (7 hops)"
meshtastic --set hop_limit 7
```
```bash title="Set hop_limit to default (3 hops)"
meshtastic --set hop_limit 0
```
```bash title="Set hop_limit to max (7 hops)"
meshtastic --set hop_limit 7
```
</TabItem>
<TabItem value="android">

311
docs/settings/mqtt.md
View file

@ -19,48 +19,52 @@ You may want to change your [GPS location sharing settings](gps#location_share)
If your device is connected to WiFi you can enable it to forward messages along to an MQTT server. This allows users on the local mesh to communicate with users on the internet.
Be sure to checkout this [MQTT](https://meshtastic.org/docs/software/other/mqtt) too.
Be sure to checkout this [MQTT](/docs/software/other/mqtt) too.
## Settings
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| downlink_enabled | `true`, `false` | `false` |
| mqtt_disabled | `true`, `false` | `false` |
| mqtt_encryption_enabled | `true`, `false` | `false` |
| mqtt_password | `string` | `""` |
| mqtt_server | `string` | `""` |
| mqtt_username | `string` | `""` |
| uplink_enabled | `true`, `false` | `false` |
| Setting | Acceptable Values | Default |
| :---------------------: | :---------------: | :-----: |
| downlink_enabled | `true`, `false` | `false` |
| mqtt_disabled | `true`, `false` | `false` |
| mqtt_encryption_enabled | `true`, `false` | `false` |
| mqtt_password | `string` | `""` |
| mqtt_server | `string` | `""` |
| mqtt_username | `string` | `""` |
| uplink_enabled | `true`, `false` | `false` |
### downlink_enabled
This is a channel specific setting. If your channel has this set to `true` and you are connected to WiFi, the device will forward along messages from the MQTT server specified [here](#mqtt_server) to the mesh from this device.
#### Enable/Disable downlink_enabled
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable downlink_enabled on PRIMARY channel"
meshtastic --ch-set downlink_enabled true --ch-index 0
```
```bash title="Disable downlink_enabled on PRIMARY channel"
meshtastic --ch-set downlink_enabled false --ch-index 0
```
```bash title="Enable downlink_enabled on OTHER channel"
meshtastic --ch-set downlink_enabled true --ch-index 1
```
```bash title="Disable downlink_enabled on OTHER channel"
meshtastic --ch-set downlink_enabled false --ch-index 1
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable downlink_enabled on PRIMARY channel"
meshtastic --ch-set downlink_enabled true --ch-index 0
```
```bash title="Disable downlink_enabled on PRIMARY channel"
meshtastic --ch-set downlink_enabled false --ch-index 0
```
```bash title="Enable downlink_enabled on OTHER channel"
meshtastic --ch-set downlink_enabled true --ch-index 1
```
```bash title="Disable downlink_enabled on OTHER channel"
meshtastic --ch-set downlink_enabled false --ch-index 1
```
</TabItem>
<TabItem value="android">
@ -91,23 +95,25 @@ Configuring this setting is not yet available for the selected platform. If this
If a meshtastic node is able to reach the internet it will normally attempt to gateway any channels that are marked as `uplink_enabled` or `downlink_enabled`. But if this flag is set, all MQTT features will be disabled and no servers will be contacted.
#### Enable/Disable MQTT
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable MQTT (Default)"
meshtastic --set mqtt_disabled false
```
```bash title="Disable MQTT"
meshtastic --set mqtt_disabled true
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable MQTT (Default)"
meshtastic --set mqtt_disabled false
```
```bash title="Disable MQTT"
meshtastic --set mqtt_disabled true
```
</TabItem>
<TabItem value="android">
@ -142,23 +148,25 @@ If you are using the default Meshtastic MQTT server, this setting will take no e
:::
#### Enable/Disable MQTT Encryption
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Publish decrypted packets to MQTT (Default)"
meshtastic --set mqtt_encryption_enabled false
```
```bash title="Publish encrypted packets to MQTT"
meshtastic --set mqtt_encryption_enabled true
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Publish decrypted packets to MQTT (Default)"
meshtastic --set mqtt_encryption_enabled false
```
```bash title="Publish encrypted packets to MQTT"
meshtastic --set mqtt_encryption_enabled true
```
</TabItem>
<TabItem value="android">
@ -189,26 +197,29 @@ Configuring this setting is not yet available for the selected platform. If this
MQTT password to use (most useful for a custom MQTT server). If using a custom server, this will be honoured even if empty. If using the default server, this will only be honoured if set, otherwise the device will use the default password `large4cats`.
#### Configure mqtt_password
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set mqtt_password"
meshtastic --set mqtt_password mypassword
```
```bash title="Set mqtt_password (with spaces)"
meshtastic --set mqtt_password "my password"
```
```bash title="Unset mqtt_password (Default)"
meshtastic --set mqtt_password ""
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set mqtt_password"
meshtastic --set mqtt_password mypassword
```
```bash title="Set mqtt_password (with spaces)"
meshtastic --set mqtt_password "my password"
```
```bash title="Unset mqtt_password (Default)"
meshtastic --set mqtt_password ""
```
</TabItem>
<TabItem value="android">
@ -239,30 +250,33 @@ Configuring this setting is not yet available for the selected platform. If this
The server to use for our MQTT global message gateway feature. If not set, the default server will be used
#### Enable/Disable MQTT Server
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
:::tip
When the mqtt_server is set to `""`, it will default to `mqtt.meshtastic.org`
:::
```bash title="Enable MQTT Server - Public Meshtastic MQTT Server (Default)"
meshtastic --set mqtt_server ""
```
```bash title="Enable MQTT Server - Personal MQTT Server (by IP)"
meshtastic --set mqtt_server 198.168.0.2
```
```bash title="Enable MQTT Server - Personal MQTT Server (by URL)"
meshtastic --set mqtt_server mqtt.mydomain.com
```
```bash title="Enable MQTT Server - Public Meshtastic MQTT Server (Default)"
meshtastic --set mqtt_server ""
```
```bash title="Enable MQTT Server - Personal MQTT Server (by IP)"
meshtastic --set mqtt_server 198.168.0.2
```
```bash title="Enable MQTT Server - Personal MQTT Server (by URL)"
meshtastic --set mqtt_server mqtt.mydomain.com
```
</TabItem>
<TabItem value="android">
@ -293,26 +307,29 @@ Configuring this setting is not yet available for the selected platform. If this
MQTT username to use (most useful for a custom MQTT server). If using a custom server, this will be honoured even if empty. If using the default server, this will only be honoured if set, otherwise the device will use the default username `meshdev`.
#### Configure mqtt_username
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set mqtt_username"
meshtastic --set mqtt_username myusername
```
```bash title="Set mqtt_username (with spaces)"
meshtastic --set mqtt_username "my username"
```
```bash title="Unset mqtt_username (Default)"
meshtastic --set mqtt_username ""
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set mqtt_username"
meshtastic --set mqtt_username myusername
```
```bash title="Set mqtt_username (with spaces)"
meshtastic --set mqtt_username "my username"
```
```bash title="Unset mqtt_username (Default)"
meshtastic --set mqtt_username ""
```
</TabItem>
<TabItem value="android">
@ -343,29 +360,33 @@ Configuring this setting is not yet available for the selected platform. If this
This is a channel specific setting. If your channel has this set to `true` and you are connected to WiFi, the device will forward along messages to whatever MQTT server is specified in [mqtt_server](#mqtt_server).
#### Enable/Disable uplink_enabled
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable uplink_enabled on PRIMARY channel"
meshtastic --ch-set uplink_enabled true --ch-index 0
```
```bash title="Disable uplink_enabled on PRIMARY channel"
meshtastic --ch-set uplink_enabled false --ch-index 0
```
```bash title="Enable uplink_enabled on OTHER channel"
meshtastic --ch-set uplink_enabled true --ch-index 1
```
```bash title="Disable uplink_enabled on OTHER channel"
meshtastic --ch-set uplink_enabled false --ch-index 1
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable uplink_enabled on PRIMARY channel"
meshtastic --ch-set uplink_enabled true --ch-index 0
```
```bash title="Disable uplink_enabled on PRIMARY channel"
meshtastic --ch-set uplink_enabled false --ch-index 0
```
```bash title="Enable uplink_enabled on OTHER channel"
meshtastic --ch-set uplink_enabled true --ch-index 1
```
```bash title="Disable uplink_enabled on OTHER channel"
meshtastic --ch-set uplink_enabled false --ch-index 1
```
</TabItem>
<TabItem value="android">
@ -406,7 +427,7 @@ values={[
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
<TabItem value="cli">
```bash title="Set server"
meshtastic --set mqtt_server 192.168.123.234
@ -423,8 +444,8 @@ mosquitto_sub -h 192.168.123.234 -v -t msh/#
:::note
FIXME some documentation says msh/# , some says mesh/# . As of 1.2.39 the messages are on msh/#
:::
</TabItem>
<TabItem value="android">
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.

27
docs/settings/overview.md
View file

@ -4,6 +4,7 @@ title: Device Settings
sidebar_label: Device Settings
slug: /settings
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -32,25 +33,27 @@ Whether you're using the upcoming [web interface](software/web/web-app-software)
## Examples
At the bottom of each setting page, examples will be available displaying how to adjust settings using the various platforms available to interface with your device. The examples will look like this:
### Introducing Examples
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
:::note
The CLI examples will require you to utilize the Command line Interface that is available through Meshtastic-python. Installation instructions can be found [here](software/python/python-installation).
:::
```bash title="Example - Set Region (an important first step!)"
meshtastic --set region Unset
```
```bash title="Example - Set Region (an important first step!)"
meshtastic --set region Unset
```
</TabItem>
<TabItem value="android">

678
docs/settings/power.md
View file

@ -15,24 +15,25 @@ For a description and more information on what exactly all of these mean, please
## Settings
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| charge_current | `MAUnset`, `MA100`, `MA190`, `MA280`, `MA360`, `MA450`, `MA550`, `MA630`, `MA700`, `MA780`, `MA880`, `MA960`, `MA1000`, `MA1080`, `MA1160`, `MA1240`, `MA1320`: | `MAUnset` |
| is_always_powered | `true`, `false` | `false` |
| is_low_power | `true`, `false` | `false` |
| is_router | `true`, `false` | `false` |
| ls_secs | `integer` (seconds) | `0` |
| mesh_sds_timeout_secs | `integer` (seconds) | `0` |
| min_wake_secs | `integer` (seconds) | `0` |
| on_battery_shutdown_after_secs | `integer` (seconds) | `0` |
| phone_sds_timeout_sec | `integer` (seconds) | `0` |
| phone_timeout_secs | `integer` (seconds) | `0` |
| screen_on_secs | `integer` (seconds) | `0` |
| sds_secs | `integer` (seconds) | `0` |
| send_owner_interval | `integer` (sent every x network pings) | `4` |
| wait_bluetooth_secs | `integer` (seconds) | `0` |
| Setting | Acceptable Values | Default |
| :----------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------: |
| charge_current | `MAUnset`, `MA100`, `MA190`, `MA280`, `MA360`, `MA450`, `MA550`, `MA630`, `MA700`, `MA780`, `MA880`, `MA960`, `MA1000`, `MA1080`, `MA1160`, `MA1240`, `MA1320`: | `MAUnset` |
| is_always_powered | `true`, `false` | `false` |
| is_low_power | `true`, `false` | `false` |
| is_router | `true`, `false` | `false` |
| ls_secs | `integer` (seconds) | `0` |
| mesh_sds_timeout_secs | `integer` (seconds) | `0` |
| min_wake_secs | `integer` (seconds) | `0` |
| on_battery_shutdown_after_secs | `integer` (seconds) | `0` |
| phone_sds_timeout_sec | `integer` (seconds) | `0` |
| phone_timeout_secs | `integer` (seconds) | `0` |
| screen_on_secs | `integer` (seconds) | `0` |
| sds_secs | `integer` (seconds) | `0` |
| send_owner_interval | `integer` (sent every x network pings) | `4` |
| wait_bluetooth_secs | `integer` (seconds) | `0` |
:::note
When you change the following settings to `0` they assume the following defaults:
- `ls_secs`: 1 hour
@ -43,7 +44,7 @@ When you change the following settings to `0` they assume the following defaults
- `screen_on_secs`: 1 minute
- `sds_secs`: 1 year
- `wait_bluetooth_secs`: 1 minute
:::
:::
### charge_current
@ -52,44 +53,33 @@ Sets the current of the battery charger.
#### Specify charge_current
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Unset charge current"
meshtastic --set charge_current MAUnset
```
```bash title="Set charge current"
meshtastic --set charge_current MA100
```
```bash title="Unset charge current"
meshtastic --set charge_current MAUnset
```
```bash title="Set charge current"
meshtastic --set charge_current MA100
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
@ -98,45 +88,35 @@ Configuring this setting is not yet available for the selected platform. If this
Circumvents the logic block for determining whether the device is powered or not. Useful for devices with finicky ADC issues on the battery sense pins.
#### Enable/Disable is_always_powered
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable is_always_powered"
meshtastic --set is_always_powered true
```
```bash title="Disable is_always_powered"
meshtastic --set is_always_powered false
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable is_always_powered"
meshtastic --set is_always_powered true
```
```bash title="Disable is_always_powered"
meshtastic --set is_always_powered false
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
@ -145,49 +125,41 @@ Configuring this setting is not yet available for the selected platform. If this
If set, we are powered from a low-current source (i.e. solar), so even if it looks like we have power flowing in we should try to minimize power consumption as much as possible.
:::note
You do **not** need to set this if you've set `is_router` (it is implied in that case).
:::
#### Enable/Disable is_low_power
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable is_low_power"
meshtastic --set is_low_power true
```
```bash title="Disable is_low_power"
meshtastic --set is_low_power false
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable is_low_power"
meshtastic --set is_low_power true
```
```bash title="Disable is_low_power"
meshtastic --set is_low_power false
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
@ -195,47 +167,36 @@ Configuring this setting is not yet available for the selected platform. If this
Are we operating as a router. Changes behavior in the following ways: The device will only sleep for critically low battery level (i.e. always tries to stay alive for the mesh) In the future routing decisions will preferentially route packets through nodes with this attribute (because assumed good line of sight).
#### Enable/Disable is_router
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable is_router"
meshtastic --set is_router true
```
```bash title="Disable is_router"
meshtastic --set is_router false
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable is_router"
meshtastic --set is_router true
```
```bash title="Disable is_router"
meshtastic --set is_router false
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
@ -244,45 +205,35 @@ Configuring this setting is not yet available for the selected platform. If this
Power management state machine option. See the [power page](/docs/software/other/power) for details. 0 for default of 3600.
#### Configure ls_secs
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set ls_secs to default (1 hour/3600 seconds)"
meshtastic --set ls_secs 0
```
```bash title="Set ls_secs to 120 seconds"
meshtastic --set ls_secs 120
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set ls_secs to default (1 hour/3600 seconds)"
meshtastic --set ls_secs 0
```
```bash title="Set ls_secs to 120 seconds"
meshtastic --set ls_secs 120
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
@ -291,48 +242,39 @@ Configuring this setting is not yet available for the selected platform. If this
Power management state machine option. See the [power page](/docs/software/other/power) for details. 0 for default of two hours, use the MAXUINT or 4294967295 to disable.
#### Configure mesh_sds_timeout_secs
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set mesh_sds_timeout_secs to default (2 hour/7200 seconds)"
meshtastic --set mesh_sds_timeout_secs 0
```
```bash title="Set mesh_sds_timeout_secs to 120 seconds"
meshtastic --set mesh_sds_timeout_secs 120
```
```bash title="Disable mesh_sds_timeout_secs (using MAXUINT)"
meshtastic --set mesh_sds_timeout_secs 4294967295
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set mesh_sds_timeout_secs to default (2 hour/7200 seconds)"
meshtastic --set mesh_sds_timeout_secs 0
```
```bash title="Set mesh_sds_timeout_secs to 120 seconds"
meshtastic --set mesh_sds_timeout_secs 120
```
```bash title="Disable mesh_sds_timeout_secs (using MAXUINT)"
meshtastic --set mesh_sds_timeout_secs 4294967295
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
@ -343,44 +285,33 @@ Power management state machine option. See the [power page](/docs/software/other
#### Configure min_wake_secs
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set min_wake_secs to default (10 seconds)"
meshtastic --set min_wake_secs 0
```
```bash title="Set min_wake_secs to 120 seconds"
meshtastic --set min_wake_secs 120
```
```bash title="Set min_wake_secs to default (10 seconds)"
meshtastic --set min_wake_secs 0
```
```bash title="Set min_wake_secs to 120 seconds"
meshtastic --set min_wake_secs 120
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
@ -389,45 +320,35 @@ Configuring this setting is not yet available for the selected platform. If this
If non-zero, the device will fully power off this many seconds after external power is removed.
#### Enable/Disable on_battery_shutdown_after_secs
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Disable on_battery_shutdown_after_secs"
meshtastic --set on_battery_shutdown_after_secs 0
```
```bash title="Set device to shutdown after 120 seconds on battery"
meshtastic --set on_battery_shutdown_after_secs 120
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Disable on_battery_shutdown_after_secs"
meshtastic --set on_battery_shutdown_after_secs 0
```
```bash title="Set device to shutdown after 120 seconds on battery"
meshtastic --set on_battery_shutdown_after_secs 120
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
@ -436,48 +357,39 @@ Configuring this setting is not yet available for the selected platform. If this
Power management state machine option. See the [power page](/docs/software/other/power) for details. 0 for default of two hours, use the MAXUINT or 4294967295 to disable.
#### Enable/Disable phone_sds_timeout_sec
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set phone_sds_timeout_sec to default (2 hours)"
meshtastic --set phone_sds_timeout_sec 0
```
```bash title="Disable phone_sds_timeout_sec"
meshtastic --set phone_sds_timeout_sec 4294967295
```
```bash title="Set phone_sds_timeout_sec to 120 seconds"
meshtastic --set phone_sds_timeout_sec 120
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set phone_sds_timeout_sec to default (2 hours)"
meshtastic --set phone_sds_timeout_sec 0
```
```bash title="Disable phone_sds_timeout_sec"
meshtastic --set phone_sds_timeout_sec 4294967295
```
```bash title="Set phone_sds_timeout_sec to 120 seconds"
meshtastic --set phone_sds_timeout_sec 120
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
@ -488,44 +400,33 @@ Power management state machine option. See the [power page](/docs/software/other
#### Configure phone_timeout_secs
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set phone_timeout_secs to default (15 minutes)"
meshtastic --set phone_timeout_secs 0
```
```bash title="Set phone_timeout_secs to 120 seconds"
meshtastic --set phone_timeout_secs 120
```
```bash title="Set phone_timeout_secs to default (15 minutes)"
meshtastic --set phone_timeout_secs 0
```
```bash title="Set phone_timeout_secs to 120 seconds"
meshtastic --set phone_timeout_secs 120
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
@ -536,44 +437,33 @@ Power management state machine option. See the [power page](/docs/software/other
#### Configure screen_on_secs
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set screen_on_secs to default (1 minute)"
meshtastic --set screen_on_secs 0
```
```bash title="Set screen_on_secs to 120 seconds"
meshtastic --set screen_on_secs 120
```
```bash title="Set screen_on_secs to default (1 minute)"
meshtastic --set screen_on_secs 0
```
```bash title="Set screen_on_secs to 120 seconds"
meshtastic --set screen_on_secs 120
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
@ -584,44 +474,33 @@ Power management state machine option. See the [power page](/docs/software/other
#### Configure sds_secs
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set sds_secs to default (1 year)"
meshtastic --set sds_secs 0
```
```bash title="Set sds_secs to 120 seconds"
meshtastic --set sds_secs 120
```
```bash title="Set sds_secs to default (1 year)"
meshtastic --set sds_secs 0
```
```bash title="Set sds_secs to 120 seconds"
meshtastic --set sds_secs 120
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
@ -632,44 +511,33 @@ This sets how often to send the database of node owner information with other no
#### Configure send_owner_interval
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set send_owner_interval to default (every 4 network pings)"
meshtastic --set send_owner_interval 0
```
```bash title="Set send_owner_interval to every 10 network pings"
meshtastic --set send_owner_interval 10
```
```bash title="Set send_owner_interval to default (every 4 network pings)"
meshtastic --set send_owner_interval 0
```
```bash title="Set send_owner_interval to every 10 network pings"
meshtastic --set send_owner_interval 10
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
@ -680,44 +548,34 @@ For instance the default interval of 4 will send the node owner information for
Wait number of seconds for Bluetooth - Power management state machine option. See the [power page](/docs/software/other/power) for details. 0 for default of 1 minute.
#### Configure wait_bluetooth_secs
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set wait_bluetooth_secs to default (60 seconds)"
meshtastic --set wait_bluetooth_secs 0
```
```bash title="Set wait_bluetooth_secs to 120 seconds"
meshtastic --set wait_bluetooth_secs 120
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set wait_bluetooth_secs to default (60 seconds)"
meshtastic --set wait_bluetooth_secs 0
```
```bash title="Set wait_bluetooth_secs to 120 seconds"
meshtastic --set wait_bluetooth_secs 120
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>

146
docs/settings/range-test-plugin.md → docs/settings/range-test-module.md
View file

@ -1,7 +1,7 @@
---
id: range-test-plugin
title: Range Test Plugin Settings
sidebar_label: Range Test Plugin
id: range-test-module
title: Range Test Module Settings
sidebar_label: Range Test Module
---
import Tabs from '@theme/Tabs';
@ -9,42 +9,44 @@ import TabItem from '@theme/TabItem';
## Overview
This plugin allows you to test the range of your Meshtastic nodes. It requires at least two nodes, a sender and a receiver. The receiving node then saves the messages along with the GPS coordinates at which they were received into a .csv file. This .csv file can then be integrated into [Google Earth](https://earth.google.com), [Google Maps - My Maps](https://mymaps.google.com), or any other program capable of processing .csv files. This can enable you to visualize your mesh.
This module allows you to test the range of your Meshtastic nodes. It requires at least two nodes, a sender and a receiver. The receiving node then saves the messages along with the GPS coordinates at which they were received into a .csv file. This .csv file can then be integrated into [Google Earth](https://earth.google.com), [Google Maps - My Maps](https://mymaps.google.com), or any other program capable of processing .csv files. This can enable you to visualize your mesh.
:::tip
Once plugin settings are changed, a **reset** is required for them to take effect.
Once module settings are changed, a **reset** is required for them to take effect.
:::
## Settings
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| range_test_plugin_enabled | `true`, `false` | `false` |
| range_test_plugin_save | `true`, `false` | `false` |
| range_test_plugin_sender | `integer` (Seconds) | `0` |
| Setting | Acceptable Values | Default |
| :-----------------------: | :-----------------: | :-----: |
| range_test_module_enabled | `true`, `false` | `false` |
| range_test_module_save | `true`, `false` | `false` |
| range_test_module_sender | `integer` (Seconds) | `0` |
### range_test_plugin_enabled
### range_test_module_enabled
Enables the plugin.
Enables the module.
#### Enable/Disable the module
#### Enable/Disable the plugin
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable the plugin"
meshtastic --set range_test_plugin_enabled true
```
```bash title="Disable the plugin"
meshtastic --set range_test_plugin_enabled true
```
```bash title="Enable the module"
meshtastic --set range_test_module_enabled true
```
```bash title="Disable the module"
meshtastic --set range_test_module_enabled true
```
</TabItem>
<TabItem value="android">
@ -70,28 +72,30 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### range_test_plugin_save
### range_test_module_save
If enabled, we will save a log of all received messages to `/static/rangetest.csv` which you can access from the web server. We will abort writing if there is less than 50k of space on the filesystem to prevent filling up the storage.
#### Enable/Disable range test save `csv`
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable range test save"
meshtastic --set range_test_plugin_save true
```
```bash title="Disable range test save"
meshtastic --set range_test_plugin_save false
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable range test save"
meshtastic --set range_test_module_save true
```
```bash title="Disable range test save"
meshtastic --set range_test_module_save false
```
</TabItem>
<TabItem value="android">
@ -117,28 +121,30 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### range_test_plugin_sender
### range_test_module_sender
Number of seconds to wait between sending packets. Using the long_slow channel configuration, it's best not to go more frequent than once every 60 seconds. You can be more aggressive with faster settings. `0` is default which disables sending messages.
#### Enable/Disable range test sender
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable range test sender (send every 60 seconds)"
meshtastic --set range_test_plugin_sender 60
```
```bash title="Disable range test sender"
meshtastic --set range_test_plugin_sender 0
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable range test sender (send every 60 seconds)"
meshtastic --set range_test_module_sender 60
```
```bash title="Disable range test sender"
meshtastic --set range_test_module_sender 0
```
</TabItem>
<TabItem value="android">
@ -166,14 +172,14 @@ Configuring this setting is not yet available for the selected platform. If this
## Details
While a minimum of two radios is required, more can be used. You can have any number of receivers and senders that your mesh is able to handle. You can test having a single sender with multiple receivers or a single receiver with multiple senders. Let us know on the [forum thread](https://meshtastic.discourse.group/t/new-plugin-rangetestplugin/2591/) the results of your configuration.
While a minimum of two radios is required, more can be used. You can have any number of receivers and senders that your mesh is able to handle. You can test having a single sender with multiple receivers or a single receiver with multiple senders. Let us know on the [forum thread](https://meshtastic.discourse.group/t/new-plugin-rangetestplugin/2591) the results of your configuration.
Be sure to turn off either the plugin configured as a sender or the device where the plugin setup as sender when not in use. This will use a lot of time on air and will spam your channel.
Be sure to turn off either the module configured as a sender or the device where the module setup as sender when not in use. This will use a lot of time on air and will spam your channel.
Also be mindful of your space usage on the file system. It has protections from filling up the space but it's best to delete old range test results.
:::note
Leaving this plugin on can slow down your mesh. Currently, the messages are sent using the same `TEXT_MESSAGE_APP` [port that all other messages](/docs/developers/protobufs/api#portnumsproto) are sent on.
Leaving this module on can slow down your mesh. Currently, the messages are sent using the same `TEXT_MESSAGE_APP` [port that all other messages](/docs/developers/protobufs/api#portnumsproto) are sent on.
:::
### Accessing your CSV
@ -187,7 +193,7 @@ http://198.168.0.X/static/rangetest.csv
### Recommended Sender Settings
| Radio Setting | `range_test_plugin_sender` |
| Radio Setting | `range_test_module_sender` |
| :-----------: | :------------------------: |
| Long Slow | 60 |
| Long Alt | 30 |
@ -210,8 +216,8 @@ values={[
<TabItem value="cli">
```bash title="Example - Sender Node"
meshtastic --set range_test_plugin_enabled true
meshtastic --set range_test_plugin_sender 60
meshtastic --set range_test_module_enabled true
meshtastic --set range_test_module_sender 60
```
</TabItem>
@ -252,8 +258,8 @@ values={[
<TabItem value="cli">
```bash title="Example - Receiver Node"
meshtastic --set range_test_plugin_enabled true
meshtastic --set range_test_plugin_save true
meshtastic --set range_test_module_enabled true
meshtastic --set range_test_module_save true
```
</TabItem>

292
docs/settings/rotary-encoder-plugin.md → docs/settings/rotary-encoder-module.md
View file

@ -1,8 +1,9 @@
---
id: rotary-encoder-plugin
id: rotary-encoder-module
title: Rotary Encoder
sidebar_label: Rotary Encoder
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -11,8 +12,9 @@ GPIO access is fundamentally dangerous because invalid options can physically da
:::
<!--- TODO add link to hardware setup to admonition--->
:::note
This plugin requires attaching a peripheral accessory to your device. It will not work without one.
This module requires attaching a peripheral accessory to your device. It will not work without one.
:::
## Overview
@ -22,42 +24,45 @@ Currently, one rotary encoder (`rotary1`) is defined, but later more rotary enco
can be added (if needed) the same way.
:::tip
Once plugin settings are changed, a **reset** is required for them to take effect.
Once module settings are changed, a **reset** is required for them to take effect.
:::
## Settings
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| rotary1_enabled | `true`, `false` | `false` |
| rotary1_event_cw | `InputEventChar` | (not defined) |
| rotary1_event_ccw | `InputEventChar` | (not defined) |
| rotary1_event_press | `InputEventChar` | (not defined) |
| rotary1_pin_a | `integer` | (not defined) |
| rotary1_pin_b | `integer` | (not defined) |
| rotary1_pin_press | `integer` | (not defined) |
| Setting | Acceptable Values | Default |
| :-----------------: | :---------------: | :-----------: |
| rotary1_enabled | `true`, `false` | `false` |
| rotary1_event_cw | `InputEventChar` | (not defined) |
| rotary1_event_ccw | `InputEventChar` | (not defined) |
| rotary1_event_press | `InputEventChar` | (not defined) |
| rotary1_pin_a | `integer` | (not defined) |
| rotary1_pin_b | `integer` | (not defined) |
| rotary1_pin_press | `integer` | (not defined) |
### rotary1_enabled
Enable the rotary encoder #1
#### Enable/Disable rotary1
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable rotary1"
meshtastic --set rotary1_enabled true
```
```bash title="Disable rotary1"
meshtastic --set rotary1_enabled true
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable rotary1"
meshtastic --set rotary1_enabled true
```
```bash title="Disable rotary1"
meshtastic --set rotary1_enabled true
```
</TabItem>
<TabItem value="android">
@ -81,30 +86,33 @@ Configuring this setting is not yet available for the selected platform. If this
</Tabs>
### rotary1_event_cw
Generate input event on CW of this kind.
:::tip
For using with CannedMessagePlugin you must choose value `KEY_UP` here.
For using with CannedMessageModule you must choose value `KEY_UP` here.
:::
#### Specify rotary1 event cw
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set rotary1 event cw to 'KEY_UP'"
meshtastic --set rotary1_event_press KEY_UP
```
```bash title="Unset rotary1 event cw"
meshtastic --set rotary1_event_press ""
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set rotary1 event cw to 'KEY_UP'"
meshtastic --set rotary1_event_press KEY_UP
```
```bash title="Unset rotary1 event cw"
meshtastic --set rotary1_event_press ""
```
</TabItem>
<TabItem value="android">
@ -128,30 +136,33 @@ Configuring this setting is not yet available for the selected platform. If this
</Tabs>
### rotary1_event_ccw
Generate input event on CCW of this kind.
:::tip
For using with CannedMessagePlugin you must choose value `KEY_DOWN` here.
For using with CannedMessageModule you must choose value `KEY_DOWN` here.
:::
#### Specify rotary1 event ccw
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set rotary1 event ccw to 'KEY_DOWN'"
meshtastic --set rotary1_event_ccw KEY_DOWN
```
```bash title="Unset rotary1 event ccw"
meshtastic --set rotary1_event_ccw ""
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set rotary1 event ccw to 'KEY_DOWN'"
meshtastic --set rotary1_event_ccw KEY_DOWN
```
```bash title="Unset rotary1 event ccw"
meshtastic --set rotary1_event_ccw ""
```
</TabItem>
<TabItem value="android">
@ -175,30 +186,33 @@ Configuring this setting is not yet available for the selected platform. If this
</Tabs>
### rotary1_event_press
Generate input event on Press of this kind.
:::tip
For using with CannedMessagePlugin you must choose value `KEY_SELECT` here.
For using with CannedMessageModule you must choose value `KEY_SELECT` here.
:::
#### Specify rotary1 event press
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set rotary1 event press to 'KEY_SELECT'"
meshtastic --set rotary1_event_press KEY_SELECT
```
```bash title="Unset rotary1 event press"
meshtastic --set rotary1_event_press ""
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set rotary1 event press to 'KEY_SELECT'"
meshtastic --set rotary1_event_press KEY_SELECT
```
```bash title="Unset rotary1 event press"
meshtastic --set rotary1_event_press ""
```
</TabItem>
<TabItem value="android">
@ -222,6 +236,7 @@ Configuring this setting is not yet available for the selected platform. If this
</Tabs>
### rotary1_pin_a
GPIO pin for rotary encoder A port.
:::caution
@ -229,24 +244,25 @@ To prevent damaging your device, double check your device's schematics before at
:::
#### Specify rotary1 pin a
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
:::note
Replace `GPIO` below with the GPIO number from hardware setup.
:::
```bash title="Specify rotary1 pin a"
meshtastic --set rotary1_pin_a GPIO
```
```bash title="Specify rotary1 pin a"
meshtastic --set rotary1_pin_a GPIO
```
</TabItem>
<TabItem value="android">
@ -270,6 +286,7 @@ Configuring this setting is not yet available for the selected platform. If this
</Tabs>
### rotary1_pin_b
GPIO pin for rotary encoder B port.
:::caution
@ -277,24 +294,25 @@ To prevent damaging your device, double check your device's schematics before at
:::
#### Specify rotary1 pin b
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
:::note
Replace `GPIO` below with the GPIO number from hardware setup.
:::
```bash title="Specify rotary1 pin b"
meshtastic --set rotary1_pin_b GPIO
```
```bash title="Specify rotary1 pin b"
meshtastic --set rotary1_pin_b GPIO
```
</TabItem>
<TabItem value="android">
@ -318,6 +336,7 @@ Configuring this setting is not yet available for the selected platform. If this
</Tabs>
### rotary1_pin_press
GPIO pin for rotary encoder Press port.
:::caution
@ -325,24 +344,25 @@ To prevent damaging your device, double check your device's schematics before at
:::
#### Specify rotary1 pin press
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
:::note
Replace `GPIO` below with the GPIO number from hardware setup.
:::
```bash title="Specify rotary1 pin press"
meshtastic --set rotary1_pin_press GPIO
```
```bash title="Specify rotary1 pin press"
meshtastic --set rotary1_pin_press GPIO
```
</TabItem>
<TabItem value="android">
@ -369,35 +389,37 @@ Configuring this setting is not yet available for the selected platform. If this
<!--- TODO add link to hardware page --->
Configuring the rotary encoder plugin require attaching the compatible hardware.
Configuring the rotary encoder module require attaching the compatible hardware.
## Examples
### Configure rotary encoder for Canned Message Plugin
### Configure rotary encoder for Canned Message Module
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
:::note
Replace each `GPIO` (x3) below with the GPIO numbers from hardware setup.
:::
```bash title="Canned Message Plugin - Required Rotary Encoder Plugin Settings"
meshtastic --set rotary1_pin_a GPIO
meshtastic --set rotary1_pin_b GPIO
meshtastic --set rotary1_pin_press GPIO
meshtastic --set rotary1_event_cw KEY_UP
meshtastic --set rotary1_event_ccw KEY_DOWN
meshtastic --set rotary1_event_press KEY_SELECT
meshtastic --set rotary1_enabled True
```
```bash title="Canned Message Module - Required Rotary Encoder Module Settings"
meshtastic --set rotary1_pin_a GPIO
meshtastic --set rotary1_pin_b GPIO
meshtastic --set rotary1_pin_press GPIO
meshtastic --set rotary1_event_cw KEY_UP
meshtastic --set rotary1_event_ccw KEY_DOWN
meshtastic --set rotary1_event_press KEY_SELECT
meshtastic --set rotary1_enabled True
```
</TabItem>
<TabItem value="android">
:::info

63
docs/settings/router.md
View file

@ -3,42 +3,42 @@ id: router
title: Router Settings
sidebar_label: Router
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
## Overview
## Settings
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| is_router | `true`, `false` | `false` |
| Setting | Acceptable Values | Default |
| :-------: | :---------------: | :-----: |
| is_router | `true`, `false` | `false` |
### is_router
Are we operating as a router. Changes behavior in the following ways: The device will only sleep for critically low battery level (i.e. always tries to stay alive for the mesh) In the future routing decisions will preferentially route packets through nodes with this attribute (because assumed good line of sight)
#### Enable/Disable router mode
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable router mode"
meshtastic --set is_router true
```
```bash title="Disable router mode"
meshtastic --set is_router false
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable router mode"
meshtastic --set is_router true
```
```bash title="Disable router mode"
meshtastic --set is_router false
```
</TabItem>
<TabItem value="android">
@ -64,20 +64,21 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
## Details
Toggling `is_router` changes your device settings in the following ways.
| Setting | `is_router` Default | Normal Default |
| :-----: | :-----------------: | :------------: |
| `send_owner_interval` | 2 | 4 |
| `position_broadcast_secs` | 12 hours | 15 minutes |
| `wait_bluetooth_secs` | 1 | 60 |
| `mesh_sds_timeout_secs` | NODE_DELAY_FOREVER | 2 hours |
| `phone_sds_timeout_sec` | NODE_DELAY_FOREVER | 2 hours |
| `ls_secs` | 1 day | 5 minutes |
| Setting | `is_router` Default | Normal Default |
| :-----------------------: | :-----------------: | :------------: |
| `send_owner_interval` | 2 | 4 |
| `position_broadcast_secs` | 12 hours | 15 minutes |
| `wait_bluetooth_secs` | 1 | 60 |
| `mesh_sds_timeout_secs` | NODE_DELAY_FOREVER | 2 hours |
| `phone_sds_timeout_sec` | NODE_DELAY_FOREVER | 2 hours |
| `ls_secs` | 1 day | 5 minutes |
### Altered Behaviors
#### Screen Wake
#### Bluetooth

193
docs/settings/serial-plugin.md → docs/settings/serial-module.md
View file

@ -1,8 +1,9 @@
---
id: serial-plugin
title: Serial Plugin Settings
sidebar_label: Serial Plugin
id: serial-module
title: Serial Module Settings
sidebar_label: Serial Module
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -11,7 +12,7 @@ GPIO access is fundamentally dangerous because invalid options can physically da
:::
:::note
This plugin requires attaching a peripheral accessory to your device. It will not work without one.
This module requires attaching a peripheral accessory to your device. It will not work without one.
:::
## Overview
@ -19,41 +20,42 @@ This plugin requires attaching a peripheral accessory to your device. It will no
This is a simple interface to send messages over the mesh network by sending strings over a serial port.
:::tip
Once plugin settings are changed, a **reset** is required for them to take effect.
Once module settings are changed, a **reset** is required for them to take effect.
:::
## Settings
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| serialplugin_enabled | `true`, `false` | `false` |
| serialplugin_echo | `true`, `false` | `false` |
| serialplugin_mode | `integer` | `0` |
| serialplugin_rxd | `integer` (GPIO) | `0` |
| serialplugin_timeout | `integer` (seconds) | `0` |
| serialplugin_txd | `integer` (GPIO) | `0` |
| Setting | Acceptable Values | Default |
| :-------------------: | :-----------------: | :-----: |
| serial_module_enabled | `true`, `false` | `false` |
| serial_module_echo | `true`, `false` | `false` |
| serial_module_mode | `integer` | `0` |
| serial_module_rxd | `integer` (GPIO) | `0` |
| serial_module_timeout | `integer` (seconds) | `0` |
| serial_module_txd | `integer` (GPIO) | `0` |
### serialplugin_enabled
### serial_module_enabled
Enables the plugin.
Enables the module.
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable plugin"
meshtastic --set serialplugin_enabled true
```
```bash title="Disable plugin"
meshtastic --set serialplugin_enabled false
```
```bash title="Enable module"
meshtastic --set serial_module_enabled true
```
```bash title="Disable module"
meshtastic --set serial_module_enabled false
```
</TabItem>
<TabItem value="android">
@ -79,27 +81,28 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### serialplugin_echo
### serial_module_echo
If set, any packets you send will be echoed back to your device.
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable serialplugin_echo"
meshtastic --set serialplugin_echo true
```
```bash title="Disable serialplugin_echo"
meshtastic --set serialplugin_echo false
```
```bash title="Enable serial_module_echo"
meshtastic --set serial_module_echo true
```
```bash title="Disable serial_module_echo"
meshtastic --set serial_module_echo false
```
</TabItem>
<TabItem value="android">
@ -125,20 +128,20 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### serialplugin_mode
### serial_module_mode
<!--- TODO --->
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
@ -168,7 +171,7 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### serialplugin_rxd
### serial_module_rxd
Set the GPIO pin to the RXD pin you have set up.
@ -177,23 +180,23 @@ To prevent damaging your device, double check your device's schematics before at
:::
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
:::note
Replace `GPIO` in the below command with the GPIO number your circuit is attached to.
:::
```bash title="Set RXD to GPIO pin number"
meshtastic --set serialplugin_rxd GPIO
```
```bash title="Set RXD to GPIO pin number"
meshtastic --set serial_module_rxd GPIO
```
</TabItem>
<TabItem value="android">
@ -219,24 +222,24 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### serialplugin_timeout
### serial_module_timeout
The amount of time to wait before we consider your packet as "done".
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set serialplugin_timeout to 15 seconds"
meshtastic --set serialplugin_timeout 15
```
```bash title="Set serial_module_timeout to 15 seconds"
meshtastic --set serial_module_timeout 15
```
</TabItem>
<TabItem value="android">
@ -262,7 +265,7 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### serialplugin_txd
### serial_module_txd
Set the GPIO pin to the TXD pin you have set up.
@ -271,23 +274,23 @@ To prevent damaging your device, double check your device's schematics before at
:::
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
:::note
Replace `GPIO` in the below command with the GPIO number your circuit is attached to.
:::
```bash title="Set TXD to GPIO pin number"
meshtastic --set serialplugin_txd GPIO
```
```bash title="Set TXD to GPIO pin number"
meshtastic --set serial_module_txd GPIO
```
</TabItem>
<TabItem value="android">

239
docs/settings/store-and-forward-plugin.md → docs/settings/store-and-forward-module.md
View file

@ -1,15 +1,16 @@
---
id: store-and-forward-plugin
id: store-and-forward-module
title: Store and Forward Settings
sidebar_label: Store and Forward
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
:::info
Currently only available for ESP32 based devices with external PSRAM. Requires the device to be set as a router.
**Don't enable Store and Forward Plugin on multiple [routers](router).**
**Don't enable Store and Forward Module on multiple [routers](router).**
:::
## Overview
@ -18,45 +19,46 @@ Currently only available for ESP32 based devices with external PSRAM. Requires t
This is a work in progress and is partially available. Stability is not guaranteed.
:::
The Store Forward Plugin 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.
The Store Forward Module is an implementation of a Store and Forward system to enable resilient messaging in the event that a client device is disconnected from the main network.
Because of the increased network traffic for this overhead, it's not advised to use this if you are duty cycle limited for your airtime usage nor is it advised to use this for SF12 (Long Range / Slow).
:::tip
Once plugin settings are changed, a **reset** is required for them to take effect.
Once module settings are changed, a **reset** is required for them to take effect.
:::
## Settings
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| store_forward_plugin_enabled | `true`, `false` | `false` |
| store_forward_plugin_heartbeat | `true`, `false` | `false` |
| store_forward_plugin_history_return_max | `integer` | `0` |
| store_forward_plugin_history_return_window | `integer` | `0` |
| store_forward_plugin_records | `integer` | `0` |
| Setting | Acceptable Values | Default |
| :----------------------------------------: | :---------------: | :-----: |
| store_forward_module_enabled | `true`, `false` | `false` |
| store_forward_module_heartbeat | `true`, `false` | `false` |
| store_forward_module_history_return_max | `integer` | `0` |
| store_forward_module_history_return_window | `integer` | `0` |
| store_forward_module_records | `integer` | `0` |
### store_forward_plugin_enabled
### store_forward_module_enabled
Enables the plugin.
Enables the module.
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable the plugin"
meshtastic --set store_forward_plugin_enabled true
```
```bash title="Disable the plugin"
meshtastic --set store_forward_plugin_enabled false
```
```bash title="Enable the module"
meshtastic --set store_forward_module_enabled true
```
```bash title="Disable the module"
meshtastic --set store_forward_module_enabled false
```
</TabItem>
<TabItem value="android">
@ -82,24 +84,24 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### store_forward_plugin_heartbeat
### store_forward_module_heartbeat
The Store & Forward Router sends a periodic message onto the network. This allows connected devices to know that a router is in range and listening to received messages. A client like Android, iOS, or Web can (if supported) indicate to the user whether a store and forward router is available.
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set store_forward_plugin_heartbeat to default"
meshtastic --set store_forward_plugin_heartbeat 0
```
```bash title="Set store_forward_module_heartbeat to default"
meshtastic --set store_forward_module_heartbeat 0
```
</TabItem>
<TabItem value="android">
@ -125,28 +127,28 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### store_forward_plugin_history_return_max
### store_forward_module_history_return_max
Sets the maximum number of messages to return to a client device.
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set store_forward_plugin_history_return_max to default"
meshtastic --set store_forward_plugin_history_return_max 0
```
```bash title="Set store_forward_plugin_history_return_max to 100 messages"
meshtastic --set store_forward_plugin_history_return_max 100
```
```bash title="Set store_forward_module_history_return_max to default"
meshtastic --set store_forward_module_history_return_max 0
```
```bash title="Set store_forward_module_history_return_max to 100 messages"
meshtastic --set store_forward_module_history_return_max 100
```
</TabItem>
<TabItem value="android">
@ -172,28 +174,28 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### store_forward_plugin_history_return_window
### store_forward_module_history_return_window
Limits the time period (in minutes) a client device can request.
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set store_forward_plugin_history_return_window to default"
meshtastic --set store_forward_plugin_history_return_window 0
```
```bash title="Set store_forward_plugin_history_return_window to 1 day (1440 minutes)"
meshtastic --set store_forward_plugin_history_return_window 1440
```
```bash title="Set store_forward_module_history_return_window to default"
meshtastic --set store_forward_module_history_return_window 0
```
```bash title="Set store_forward_module_history_return_window to 1 day (1440 minutes)"
meshtastic --set store_forward_module_history_return_window 1440
```
</TabItem>
<TabItem value="android">
@ -219,28 +221,28 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
### store_forward_module_records
### store_forward_plugin_records
Set this to the maximum number of records to save. Best to leave this at the default (`0`) where the plugin will use 2/3 of your device's available PSRAM. This is about 11,000 records.
Set this to the maximum number of records to save. Best to leave this at the default (`0`) where the module will use 2/3 of your device's available PSRAM. This is about 11,000 records.
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set store_forward_plugin_records to default (≈11,000 records)"
meshtastic --set store_forward_plugin_records 0
```
```bash title="Set store_forward_plugin_records to 100 records"
meshtastic --set store_forward_plugin_records 100
```
```bash title="Set store_forward_module_records to default (≈11,000 records)"
meshtastic --set store_forward_module_records 0
```
```bash title="Set store_forward_module_records to 100 records"
meshtastic --set store_forward_module_records 100
```
</TabItem>
<TabItem value="android">
@ -266,37 +268,36 @@ Configuring this setting is not yet available for the selected platform. If this
</TabItem>
</Tabs>
## Details
### How it works
![Store & Forward - Overview](/img/plugins/store_and_forward/store_and_forward-overview.png)
![Store & Forward - Overview](/img/modules/store_and_forward/store_and_forward-overview.png)
### Requirements
Initial Requirements:
* Must be installed on a router node.
* This is an artificial limitation, but is in place to enforce best practices.
* Router nodes are intended to be always online. If this plugin misses any messages, the reliability of the stored messages will be reduced.
* Esp32 Processor based device with external PSRAM. (tbeam v1.0 and tbeamv1.1, and maybe others)
- Must be installed on a router node.
- This is an artificial limitation, but is in place to enforce best practices.
- Router nodes are intended to be always online. If this module misses any messages, the reliability of the stored messages will be reduced.
- Esp32 Processor based device with external PSRAM. (tbeam v1.0 and tbeamv1.1, and maybe others)
### Usage Overview
* To use / test this you will want at least 3 devices
* One device will (currently) need be a tbeam v1.0 and tbeamv1.1 configured as a Meshtastic router. Other devices with built in PSRAM will be supported at some point.
* Two others will be regular clients. Nothing special required.
- To use / test this you will want at least 3 devices
- One device will (currently) need be a tbeam v1.0 and tbeamv1.1 configured as a Meshtastic router. Other devices with built in PSRAM will be supported at some point.
- Two others will be regular clients. Nothing special required.
### Meshtastic channel configuration
Don't use this on the "Long Range / Slow" or "Long Range / Fast" channel settings. You're welcome to try and report back, but those channels have a [very low bitrate](/docs/developers/device/radio-settings#pre-defined).
Don't use this on the "Long Range / Slow" or "Long Range / Fast" channel settings. You're welcome to try and report back, but those channels have a [very low bitrate](/docs/developers/firmware/radio-settings#pre-defined).
Either use a custom channel configuration with at an at least 1kbit data rate or use "Medium Range / Fast".
Recommended channel setting is for 1.343kbps:
```bash title="Recommended channel setting for S&F plugin"
```bash title="Recommended channel setting for S&F module"
meshtastic --setchan spread_factor 11 --setchan coding_rate 4 --setchan bandwidth 500
```
@ -305,21 +306,21 @@ With an aftermarket coaxial antenna or moxon antenna, that will give you roughly
### Router setup
:::warning
Don't enable the Store and Forward plugin on multiple routers!
Don't enable the Store and Forward module on multiple routers!
:::
* Configure your device as a [meshtastic router](router).
* Name your router node something that makes it easily identifiable, aka "Router".
* Configure the Store and Forward plugin
```bash title="Required - Enable the plugin"
meshtastic --set store_forward_plugin_enabled true
- Configure your device as a [meshtastic router](router).
- Name your router node something that makes it easily identifiable, aka "Router".
- Configure the Store and Forward module
```bash title="Required - Enable the module"
meshtastic --set store_forward_module_enabled true
```
```bash title="Optional - Set maximum number of records to save to device"
meshtastic --set store_forward_plugin_records 100
meshtastic --set store_forward_module_records 100
```
:::tip
Best to leave `store_forward_plugin_records` at the default (`0`) where the plugin will use 2/3 of your device's available PSRAM. This is about 11,000 records.
:::
:::tip
Best to leave `store_forward_module_records` at the default (`0`) where the module will use 2/3 of your device's available PSRAM. This is about 11,000 records.
:::
### Client Usage
@ -327,9 +328,9 @@ Currently, no special configuration is required. To request your history sent to
Available Commands:
| Command | Definition |
| :-----: | :---------------: |
| SF | Send the last few messages I may have missed |
| SFm | Send a 240 byte payload (Used for testing) |
| Command | Definition |
| :-----: | :------------------------------------------: |
| SF | Send the last few messages I may have missed |
| SFm | Send a 240 byte payload (Used for testing) |
The Store and Forward plugin 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.
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.

206
docs/settings/wifi.md
View file

@ -3,6 +3,7 @@ id: wifi
title: WiFi Settings
sidebar_label: WiFi
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -24,11 +25,11 @@ The first time your device restarts after enabling the WiFi access point, it wil
## Settings
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| wifi_ap_mode | `true`, `false` | `false` |
| wifi_password | string | `""` |
| wifi_ssid | string | `""` |
| Setting | Acceptable Values | Default |
| :-----------: | :---------------: | :-----: |
| wifi_ap_mode | `true`, `false` | `false` |
| wifi_password | string | `""` |
| wifi_ssid | string | `""` |
:::note
`wifi_ssid` & `wifi_password` are both **case sensitive** values.
@ -39,23 +40,25 @@ The first time your device restarts after enabling the WiFi access point, it wil
A boolean value that toggles the [Software Access Point](#software-access-point)
#### Enable/Disable Software Access Point
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable SoftAP"
meshtastic --set wifi_ap_mode true
```
```bash title="Disable SoftAP"
meshtastic --set wifi_ap_mode false
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enable SoftAP"
meshtastic --set wifi_ap_mode true
```
```bash title="Disable SoftAP"
meshtastic --set wifi_ap_mode false
```
</TabItem>
<TabItem value="android">
@ -86,22 +89,23 @@ Configuring this setting is not yet available for the selected platform. If this
In [SoftAP](#software-access-point) mode, this is the password to access your device's WiFi. In [Client](#wifi-client) mode, this is your WiFi Networks password. This string is case sensitive.
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set WiFi password"
meshtastic --set wifi_password mypassword
```
```bash title="Set WiFi password (with spaces)"
meshtastic --set wifi_password "my password"
```
```bash title="Set WiFi password"
meshtastic --set wifi_password mypassword
```
```bash title="Set WiFi password (with spaces)"
meshtastic --set wifi_password "my password"
```
</TabItem>
<TabItem value="android">
@ -132,22 +136,24 @@ Configuring this setting is not yet available for the selected platform. If this
In [SoftAP](#software-access-point) mode, this is the SSID broadcast to access your device's WiFi. In [Client](#wifi-client) mode, this is your WiFi Networks SSID. This string is case sensitive.
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Set WiFi network"
meshtastic --set wifi_ssid mynetwork
```
```bash title="Set WiFi network (with spaces)"
meshtastic --set wifi_ssid "my network"
```
```bash title="Set WiFi network"
meshtastic --set wifi_ssid mynetwork
```
```bash title="Set WiFi network (with spaces)"
meshtastic --set wifi_ssid "my network"
```
</TabItem>
<TabItem value="android">
@ -194,10 +200,10 @@ You should then be able to connect to the node using either the displayed IP add
You can also enable the SoftAP by following these directions:
* Hold down the user button
* Press and release the reset button
* Count to two
* Let go of the user button
- Hold down the user button
- Press and release the reset button
- Count to two
- Let go of the user button
This will reboot the device with the SSID set to `meshtasticAdmin` and the password set to `12345678`. Using the Force SoftAP method, once you reboot, the SoftAP will be turned off.
@ -236,29 +242,32 @@ To disable WiFi completely, set `wifi_ap_mode` to `false`, and both `wifi_ssid`
## Examples
### Enable WiFi (as client)
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enabling WiFi Client"
meshtastic --set wifi_ap_mode false --set wifi_ssid mywifissid --set wifi_password mywifipassword
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Enabling WiFi Client"
meshtastic --set wifi_ap_mode false --set wifi_ssid mywifissid --set wifi_password mywifipassword
```
:::note
If your `wifi_ssid` or `wifi_password` contain spaces, be sure to put quotation marks around the whole thing:
```bash title="Example with spaces"
meshtastic --set wifi_ssid "my wifi ssid" --set wifi_password "my wifi password"
```
:::
</TabItem>
<TabItem value="android">
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
@ -284,30 +293,31 @@ Configuring this setting is not yet available for the selected platform. If this
In the above example, the device will join a network with the SSID `mywifissid` and the password `mywifipassword`.
### Enable WiFi (as SoftAP)
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Software Access Point Example"
meshtastic --set wifi_ap_mode true --set wifi_ssid mywifissid --set wifi_password mywifipassword
```
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Software Access Point Example"
meshtastic --set wifi_ap_mode true --set wifi_ssid mywifissid --set wifi_password mywifipassword
```
:::note
If your `wifi_ssid` or `wifi_password` contain spaces, be sure to put quotation marks around the whole thing:
```bash title="Example with spaces"
meshtastic --set wifi_ssid "my wifi ssid" --set wifi_password "my wifi password"
```
:::
</TabItem>
<TabItem value="android">
@ -335,21 +345,21 @@ Configuring this setting is not yet available for the selected platform. If this
In the above example, the device will broadcast a network with the SSID `mywifissid` and the password `mywifipassword`.
### Disable WiFi Completely
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Example - Disabling WiFi"
meshtastic --set wifi_ap_mode false --set wifi_ssid "" --set wifi_password ""
```
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
```bash title="Example - Disabling WiFi"
meshtastic --set wifi_ap_mode false --set wifi_ssid "" --set wifi_password ""
```
</TabItem>
<TabItem value="android">

5
docs/software/android/installation.md
View file

@ -3,9 +3,10 @@ id: android-installation
title: Android application installation
sidebar_label: Installation
---
Our Android application is available to download on Google Play Store.
<p align="center"><a href="https://play.google.com/store/apps/details?id=com.geeksville.mesh&referrer=utm_source%3Dgithub-homepage"><img alt="Download at https://play.google.com/store/apps/details?id=com.geeksville.mesh" src="https://play.google.com/intl/en_us/badges/static/images/badges/en_badge_web_generic.png" style={{zoom:'35%'}} /></a></p>
<p align="center"><a href="https://play.google.com/store/apps/details?id=com.geeksville.mesh"><img alt="Download at https://play.google.com/store/apps/details?id=com.geeksville.mesh" src="https://play.google.com/intl/en_us/badges/static/images/badges/en_badge_web_generic.png" style={{zoom:'35%'}} /></a></p>
The app is also available on the Amazon [Appstore](https://www.amazon.com/Geeksville-Industries-Meshtastic/dp/B08CY9394Q). You will need to install the Amazon Appstore onto your phone in order to install the Meshtastic application.
@ -30,7 +31,7 @@ Click on the image to see a quick video of where I found it on my phone.
There is a [beta program](https://play.google.com/apps/testing/com.geeksville.mesh) for the app, which will let you test the cutting edge changes, though this may come with extra bugs. You can join this via Google Play. It is recommended that you follow the [Meshtastic Discourse Alpha Testers](https://meshtastic.discourse.group/c/development/alpha-testers) channel if you decide to join this.
The app uses anonymous usage statistics and crash reports to allow us to catch problems with Meshtastic and fix them. Analytics are also required to be able to use the "free" plan of our map provider [Mapbox](https://docs.mapbox.com/help/how-mapbox-works/). You can disable this by unticking the checkbox on the settings page.
The app uses anonymous usage statistics and crash reports to allow us to catch problems with Meshtastic and fix them. Analytics are also required to be able to use the "free" plan of our map provider [Mapbox](https://docs.mapbox.com/help/how-mapbox-works). You can disable this by unticking the checkbox on the settings page.
[![Settings page with statistics consent box highlighted](/img/android/android-stats-consent-sm.png)](/img/android/android-stats-consent.png)

36
docs/software/android/location-access.md
View file

@ -1,13 +1,13 @@
# Location access and meshtastic
Google Play has some newish requirements for access to background location. This doc is a collection of work items needed to meet those requirements.
Google Play has some newish requirements for access to background location. This doc is a collection of work items needed to meet those requirements.
The app is currently removed from the Play Store ([broken store link](https://play.google.com/store/apps/details?id=com.geeksville.mesh)), and some kind Googlers inside of Google are helping with this problem. **Hopefully** it will be
relisted soon (while we address these newish requirements), but we've got to do a bit of code to add a new dialog (and make a video for Google). It will take about a week to make these changes (including testing time with the [alpha-tester group](https://meshtastic.discourse.group/c/development/alpha-testers/) on the forum).
The app is currently removed from the Play Store ([broken store link](https://play.google.com/store/apps/details?id=com.geeksville.mesh)), and some kind Googlers inside of Google are helping with this problem. **Hopefully** it will be
relisted soon (while we address these newish requirements), but we've got to do a bit of code to add a new dialog (and make a video for Google). It will take about a week to make these changes (including testing time with the [alpha-tester group](https://meshtastic.discourse.group/c/development/alpha-testers) on the forum).
Until relisted in the Play Store (hopefully they can relist while we make these fixes), you'll need to install [raw APKs from GitHub](https://github.com/meshtastic/Meshtastic-Android/releases). Which is not ideal, but works.
Until relisted in the Play Store (hopefully they can relist while we make these fixes), you'll need to install [raw APKs from GitHub](https://github.com/meshtastic/Meshtastic-Android/releases). Which is not ideal, but works.
Sorry ya'll.
Sorry ya'll.
(The remainder of this public document is mostly for Googlers)
@ -15,18 +15,18 @@ Sorry ya'll.
We need foreground location access for two reasons:
* (Primarily) [This app](https://github.com/meshtastic/Meshtastic-Android) is a navigation app that uses long range LoRa mesh radios for communication in the back country. These radios can run for weeks on a charge and talk to the user's phone over USB or Bluetooth to provide the UX. We need foreground location so we can show the user's current position on the same map that is showing positions of the other users.
* (Secondarily) Using the old Bluetooth BLE API (which we need to use to support older devices), scanning for Bluetooth low energy devices requires this permission (because 'beacons' etc... could leak location info to the app). Without this permission (on older phones) the BLE discovery results are always empty.
- (Primarily) [This app](https://github.com/meshtastic/Meshtastic-Android) is a navigation app that uses long range LoRa mesh radios for communication in the back country. These radios can run for weeks on a charge and talk to the user's phone over USB or Bluetooth to provide the UX. We need foreground location so we can show the user's current position on the same map that is showing positions of the other users.
- (Secondarily) Using the old Bluetooth BLE API (which we need to use to support older devices), scanning for Bluetooth low energy devices requires this permission (because 'beacons' etc... could leak location info to the app). Without this permission (on older phones) the BLE discovery results are always empty.
If it is helpful, [here](https://meshtastic.org/docs/software/android/android-usage) is a slightly stale set of screenshots/instructions showing how the user uses our application.
If it is helpful, [here](/docs/software/android/android-usage) is a slightly stale set of screenshots/instructions showing how the user uses our application.
## Why this app needs "background location access"
When the user has the LoRa device in their pocket occasionally (every 15 minutes ish), the Android sister app background service will acquire the GPS position and provide it to the LoRa [firmware](https://github.com/meshtastic/Meshtastic-device). Without background location access, this core (the primary feature) of our app would not work (because you wouldn't be able to see the last known position of the hikers/skiers/users in your group).
When the user has the LoRa device in their pocket occasionally (every 15 minutes ish), the Android sister app background service will acquire the GPS position and provide it to the LoRa [firmware](https://github.com/meshtastic/Meshtastic-device). Without background location access, this core (the primary feature) of our app would not work (because you wouldn't be able to see the last known position of the hikers/skiers/users in your group).
This location is shared only over an [encrypted](https://meshtastic.org/docs/developers/device/encryption) link and each group of users has their own AES256 key for their 'channel'. Our privacy policy is [here](https://meshtastic.org/docs/legal/privacy).
This location is shared only over an [encrypted](/docs/developers/firmware/encryption) link and each group of users has their own AES256 key for their 'channel'. Our privacy policy is [here](/docs/legal/privacy).
(This description has been simplified a bit: This project works with a [variety](https://meshtastic.org/docs/hardware) of LoRa devices, some of which have their own built-in GPS. For the devices that have a GPS built-in, we do not use Android to get the user's location)
(This description has been simplified a bit: This project works with a [variety](/docs/hardware) of LoRa devices, some of which have their own built-in GPS. For the devices that have a GPS built-in, we do not use Android to get the user's location)
## Fixes needed for these new Play Store background position requirements
@ -39,17 +39,17 @@ per https://support.google.com/googleplay/android-developer/answer/9799150
The existing text explains what the app does, but it needs to be even more explicit:
Requirements from Google site:
If you plan to use location in the background in your app, you should communicate this to users in the Google Play Store Listing via your app description, screenshots and (if applicable) title or icon.
If you plan to use location in the background in your app, you should communicate this to users in the Google Play Store Listing via your app description, screenshots and (if applicable) title or icon.
Here are some suggestions on how to highlight use of location in the background to users:
Provide a short description to signal 'location' (for example, 'find anywhere' or 'always know where').
Include an in-app screenshot that shows a map/user location or geotagged images.
Include an in-app screenshot that shows a map/user location or geotagged images.
If applicable, your app title or icon may also signal the location feature of your app.
## TODO: In app dialog
We currently explain why we need location access on the settings page and in the help. But we need a new dialog at launch, which needs to be **super** explicit:
We currently explain why we need location access on the settings page and in the help. But we need a new dialog at launch, which needs to be **super** explicit:
Requirements from Google site:
Must be within the app itself, not only in the app description or on a website;
@ -68,7 +68,7 @@ If you extend permitted usage to ads, you must include the following: 'used to p
Example disclosure statements
Below are two example statements that can be used in your disclosure; the latter includes the use of location for ads for which you can choose the most relevant phrasing):
'[This app] collects location data to enable "feature", "feature" and "feature" even when the app is closed or not in use'.
'[This app] collects location data to enable "feature", "feature" and "feature" even when the app is closed or not in use'.
'[This app] collects location data to enable "feature", "feature" and "feature" even when the app is closed or not in use and it is also used to support advertising'.
The prominent disclosure may include other information to ensure compliance to policy requirements and clarity for users but must at least include the above, where relevant.
@ -76,15 +76,15 @@ Note: If the feature does not have a user-facing interface when location in the
## TODO: Video demonstration
I'm awful at making videos, so I'll ask someone from the [forum](https://meshtastic.discourse.group/) to help with this!
I'm awful at making videos, so I'll ask someone from the [forum](https://meshtastic.discourse.group) to help with this!
Requirements from Google site:
As part of the permissions declaration, you must provide a link to a short video that demonstrates the location-based feature in your app that requires access to location in the background (while the app is not in use).
As part of the permissions declaration, you must provide a link to a short video that demonstrates the location-based feature in your app that requires access to location in the background (while the app is not in use).
You can see an example of what this video demonstration should look like below.
See an example video demonstration
As part of the permissions declaration, you must provide a link to a short video that demonstrates the location-based feature in your app that requires access to location in the background (while the app is not in use). The video should demonstrate the background location feature and the required steps to encounter and enable this feature in-app. The video should show: 1. Runtime prompt, 2. the prominent in-app disclosure dialog displayed to users (described below), and the feature being activated from the background. 3. The recommended duration is 30 seconds or less. A YouTube link is the preferred video format, but Google Drive storage links to an mp4 or other common video file formats are also supported. Note: If the feature does not have a user-facing interface when location in the background is active, please note this in your declaration and demonstrate the feature or its impacts as much as possible in the video. Ensure your video is made using an Android device.
As part of the permissions declaration, you must provide a link to a short video that demonstrates the location-based feature in your app that requires access to location in the background (while the app is not in use). The video should demonstrate the background location feature and the required steps to encounter and enable this feature in-app. The video should show: 1. Runtime prompt, 2. the prominent in-app disclosure dialog displayed to users (described below), and the feature being activated from the background. 3. The recommended duration is 30 seconds or less. A YouTube link is the preferred video format, but Google Drive storage links to an mp4 or other common video file formats are also supported. Note: If the feature does not have a user-facing interface when location in the background is active, please note this in your declaration and demonstrate the feature or its impacts as much as possible in the video. Ensure your video is made using an Android device.
Video requirements
The video should demonstrate the background location feature and the required steps to encounter and enable this feature in-app. The video should show:

28
docs/software/android/usage.md
View file

@ -47,7 +47,6 @@ The cloud icon at the top right corner indicates if you are connected to a devic
![Sleeping](/img/android/android-cloud-up.png) Cloud with an up arrow in it: Device is connected, but currently sleeping or out of range.
## Common tasks
Once you are connected to a device, the App will work, and you can test it by "sending" a message. However, you will need to join or create a new mesh network so you have someone to communicate with. If you have been sent a QR code or link for Meshtastic, then skip ahead to [Join a Channel](#join-a-channel), otherwise you will need to Setup a Channel.
@ -107,14 +106,14 @@ You can test changing channels with the QR code shown below.
Various data-rates are selectable when configuring a channel and are inversely proportional to the theoretical range of the devices:
| Channel setting | Data-rate |
|------------------------|----------------------|
| Short Range / Fast | 19346.94 bps |
| Short Range / Slow | 4800.00 bps |
| Medium Range / Fast | 1227.18 bps |
| Medium Range / Slow | 763.29 bps |
| Long Range / Fast | 196.74 bps |
| long Range / Slow | 136.71 bps (default) |
| Channel setting | Data-rate |
| ------------------- | -------------------- |
| Short Range / Fast | 19346.94 bps |
| Short Range / Slow | 4800.00 bps |
| Medium Range / Fast | 1227.18 bps |
| Medium Range / Slow | 763.29 bps |
| Long Range / Fast | 196.74 bps |
| long Range / Slow | 136.71 bps (default) |
### Send a message
@ -122,10 +121,10 @@ The message window operates like any chat applications. Note that any messages s
With LoRa (or any radio) there is some uncertainty that the messages has been received, so there is a confirmation built-in to the protocol. There are small cloud icons shown to the right of the messages you send:
* Cloud with an up arrow: the application is waiting for the device to some out of sleep mode (or come back into Bluetooth range), to upload the message to the device.
* Cloud only: message has been sent via Bluetooth and transmitted via LoRa.
* Cloud with a check mark: message has been delivered to at least one node in the mesh and at least one node sent back a confirmation (successfully received by the initial sender).
* Cloud crossed out: message may have been delivered to at least one node in the mesh. The initial sender did not receive at least one node's confirmation within a certain timeout.
- Cloud with an up arrow: the application is waiting for the device to some out of sleep mode (or come back into Bluetooth range), to upload the message to the device.
- Cloud only: message has been sent via Bluetooth and transmitted via LoRa.
- Cloud with a check mark: message has been delivered to at least one node in the mesh and at least one node sent back a confirmation (successfully received by the initial sender).
- Cloud crossed out: message may have been delivered to at least one node in the mesh. The initial sender did not receive at least one node's confirmation within a certain timeout.
Thus, in a group size of 3 and up, confirmations could be from any one device (not person), so it is good practice to respond, so the initial sender knows you have read their message.
@ -147,8 +146,7 @@ The Map tab will show a local map with an icon for each active mesh node that ha
[![Mapping provided by Mapbox](/img/android/android-map-sm.png)](/img/android/android-map.png)
The map is not developed by the Meshtastic project, and the source of the mapping system is [Mapbox](https://docs.mapbox.com/help/how-mapbox-works/) (free-tier), and the map data is sourced from [OpenStreetMap OSM](https://www.openstreetmap.org/). Mapbox currently requires analytics to be enabled for you to use their mapping system. There is currently no off-line maps (phone needs mobile data or Wifi), although this will be improved in the future. If you don't see the features that you'd expect on the map then head over to [OpenStreetMap OSM](https://www.openstreetmap.org/) where you can contribute new data to the map.
The map is not developed by the Meshtastic project, and the source of the mapping system is [Mapbox](https://docs.mapbox.com/help/how-mapbox-works) (free-tier), and the map data is sourced from [OpenStreetMap OSM](https://www.openstreetmap.org). Mapbox currently requires analytics to be enabled for you to use their mapping system. There is currently no off-line maps (phone needs mobile data or Wifi), although this will be improved in the future. If you don't see the features that you'd expect on the map then head over to [OpenStreetMap OSM](https://www.openstreetmap.org) where you can contribute new data to the map.
## Configuration options

21
docs/software/community/atak.md
View file

@ -1,24 +1,23 @@
---
id: community-atak
title: ATAK plugin
sidebar_label: ATAK plugin
title: ATAK module
sidebar_label: ATAK module
---
:::note
This is a community project maintained by @paulmandal.
Development can be followed on [GitHub](https://github.com/paulmandal/atak-forwarder/).
Development can be followed on [GitHub](https://github.com/paulmandal/atak-forwarder).
Support should be sought from the respective authors.
:::
This is a plugin for ATAK (Android Team Awareness Kit) that uses Meshtastic to provide off-grid communications. This includes plotting the position of others on the map, transmission of markers and routes, and chat messages. It has been signed by the TAK Product Center for use with the Play Store version of ATAK. He is currently distributing development builds via [Google Drive](https://drive.google.com/drive/folders/1xeKJnn9tmzkkmuDbMp0LCLOV9OzHU-Ex), aiming to publish it to the Play Store in the future.
This is a module for ATAK (Android Team Awareness Kit) that uses Meshtastic to provide off-grid communications. This includes plotting the position of others on the map, transmission of markers and routes, and chat messages. It has been signed by the TAK Product Center for use with the Play Store version of ATAK. He is currently distributing development builds via [Google Drive](https://drive.google.com/drive/folders/1xeKJnn9tmzkkmuDbMp0LCLOV9OzHU-Ex), aiming to publish it to the Play Store in the future.
![ATAK Plugin](/img/atak-animation.gif)
![ATAK Module](/img/atak-animation.gif)
The builds of the plugin on the Google Drive are now signed for the Play Store version of ATAK, as of 6/3/2021.
The builds of the module on the Google Drive are now signed for the Play Store version of ATAK, as of 6/3/2021.
The ATAK plugin requires the Meshtastic Android app to be installed.
* A walk-through on how to [set up ATAK](https://paul-mandal.medium.com/atak-for-hikers-d96d5246193e).
* The plugin source is available on [GitHub](https://github.com/paulmandal/atak-forwarder/), along with instructions for setting it up.
* Development builds are available on [Google Drive](https://drive.google.com/drive/folders/1xeKJnn9tmzkkmuDbMp0LCLOV9OzHU-Ex).
The ATAK module requires the Meshtastic Android app to be installed.
- A walk-through on how to [set up ATAK](https://paul-mandal.medium.com/atak-for-hikers-d96d5246193e).
- The module source is available on [GitHub](https://github.com/paulmandal/atak-forwarder), along with instructions for setting it up.
- Development builds are available on [Google Drive](https://drive.google.com/drive/folders/1xeKJnn9tmzkkmuDbMp0LCLOV9OzHU-Ex).

1
docs/software/community/go.md
View file

@ -44,5 +44,6 @@ GLOBAL OPTIONS:
--help, -h show help (default: false)
--version, -v print the version (default: false)
```
Further information is available on the project's GitHub [Readme.md](https://github.com/lmatte7/meshtastic-go/blob/main/README.md).
The latest executables can be downloaded from [GitHub](https://github.com/lmatte7/meshtastic-go/releases/latest).

9
docs/software/community/overview.md
View file

@ -4,11 +4,12 @@ title: Community applications
sidebar_label: Community apps
---
The Meshtastic ecosystem is highly extensible, and a number of community projects have been made to fit different people's needs. If you wish to create your own application or plugin, please read the information in the developers section, and tell us about your project on the forum.
The Meshtastic ecosystem is highly extensible, and a number of community projects have been made to fit different people's needs. If you wish to create your own application or module, please read the information in the developers section, and tell us about your project on the forum.
Current community projects:
* [Meshtastic plugin for ATAK](/docs/software/community/community-atak) (Android Team Awareness Kit)
* [PyGUI](/docs/software/community/community-pygui) - Platform independent graphical user interface for Meshtastic devices
* [Go CLI](/docs/software/community/community-go) - A command line interface using Go that requires no pre-requisites to be installed
- [Meshtastic module for ATAK](/docs/software/community/community-atak) (Android Team Awareness Kit)
- [PyGUI](/docs/software/community/community-pygui) - Platform independent graphical user interface for Meshtastic devices
- [Go CLI](/docs/software/community/community-go) - A command line interface using Go that requires no pre-requisites to be installed
Support for these projects should be sought from their respective authors.

22
docs/software/device/critical-faults.md
View file

@ -10,14 +10,14 @@ The device might report these fault codes on the screen, but it will also be out
This table is derived from the [protobufs](/docs/developers/protobufs/api#criticalerrorcode)
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| TxWatchdog | 1 | A software bug was detected while trying to send LoRa |
| SleepEnterWait | 2 | A software bug was detected on entry to sleep |
| NoRadio | 3 | No LoRa radio hardware could be found |
| Unspecified | 4 | Not normally used |
| UBloxInitFailed | 5 | We failed while configuring a UBlox GPS |
| NoAXP192 | 6 | This board was expected to have a power management chip and it is missing or broken |
| InvalidRadioSetting | 7 | The channel tried to set a radio setting which is not supported by this chipset, radio comms settings are now undefined |
| TransmitFailed | 8 | Radio transmit hardware failure. We sent data to the radio chip, but it did not reply with an interrupt |
| Brownout | 9 | We detected that the main CPU voltage dropped below the minimum acceptable value |
| Name | Number | Description |
| ------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| TxWatchdog | 1 | A software bug was detected while trying to send LoRa |
| SleepEnterWait | 2 | A software bug was detected on entry to sleep |
| NoRadio | 3 | No LoRa radio hardware could be found |
| Unspecified | 4 | Not normally used |
| UBloxInitFailed | 5 | We failed while configuring a UBlox GPS |
| NoAXP192 | 6 | This board was expected to have a power management chip and it is missing or broken |
| InvalidRadioSetting | 7 | The channel tried to set a radio setting which is not supported by this chipset, radio comms settings are now undefined |
| TransmitFailed | 8 | Radio transmit hardware failure. We sent data to the radio chip, but it did not reply with an interrupt |
| Brownout | 9 | We detected that the main CPU voltage dropped below the minimum acceptable value |

11
docs/software/device/ham.md
View file

@ -4,6 +4,7 @@ title: Licensed (HAM) Operation
sidebar_label: Licensed (HAM) Operation
slug: /software/device/ham
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -17,13 +18,13 @@ Having a ham radio license grants you addition privilages and restrictions.
# Additional privilages
* Additional power
* Higher gain antennas
- Additional power
- Higher gain antennas
# Restrictions
* Unencrypted
* Identified with your ID
- Unencrypted
- Identified with your ID
# Let's do it!
@ -39,4 +40,4 @@ mydir$ meshtastic --port /dev/ttyUSB1 --set-ham KI1345
Connected to radio
Setting Ham ID to KI1345 and turning off encryption
Writing modified channels to device
```
```

32
docs/software/device/power.md
View file

@ -11,26 +11,26 @@ Long battery life is one of the main goals of this project. Based on initial mea
From lower to higher power consumption.
- Super-Deep-Sleep (SDS) - Everything is off, CPU, radio, Bluetooth, and GPS. It only wakes due to timer or button press. We enter this mode only after no radio comms for a few hours - used to put the device into what is effectively "off" mode.
* onEntry: setBluetoothOn(false), call doDeepSleep
* onExit: (standard bootup code, starts in DARK)
- onEntry: setBluetoothOn(false), call doDeepSleep
- onExit: (standard bootup code, starts in DARK)
- Deep-Sleep (DS) - CPU is off, radio is on, Bluetooth and GPS are off. Note: This mode is never used currently, because it only saves 1.5mA vs Light-Sleep - (Not currently used).
- Light-Sleep (LS) - CPU is suspended (RAM stays alive), radio is on, Bluetooth is off, and GPS is off. Note: currently GPS is not turned off during light sleep, but there is a TODO item to fix this.
* NOTE: On NRF52 platforms (because CPU current draw is so low), light-sleep state is never used.
* onEntry: setBluetoothOn(false), setGPSPower(false), doLightSleep()
* onIdle: (if we wake because our led blink timer has expired) blink the led then go back to sleep until we sleep for ls_secs
* onExit: setGPSPower(true), start trying to get GPS lock: gps.startLock(), once lock arrives service.sendPosition(BROADCAST)
- NOTE: On NRF52 platforms (because CPU current draw is so low), light-sleep state is never used.
- onEntry: setBluetoothOn(false), setGPSPower(false), doLightSleep()
- onIdle: (if we wake because our led blink timer has expired) blink the led then go back to sleep until we sleep for ls_secs
- onExit: setGPSPower(true), start trying to get GPS lock: gps.startLock(), once lock arrives service.sendPosition(BROADCAST)
- No Bluetooth (NB) - CPU is running, radio is on, GPS is on, Bluetooth is off, and screen is off.
* onEntry: setBluetoothOn(false)
* onExit:
- onEntry: setBluetoothOn(false)
- onExit:
- Running Dark (DARK) - Everything is on except screen.
* onEntry: setBluetoothOn(true)
* onExit:
- onEntry: setBluetoothOn(true)
- onExit:
- Serial API usage (SERIAL) - Screen is on, device doesn't sleep, and Bluetooth is off.
* onEntry: setBluetooth off, screen on
* onExit:
- onEntry: setBluetooth off, screen on
- onExit:
- Full On (ON) - Everything is on, can eventually timeout and transition to a lower power state.
* onEntry: setBluetoothOn(true), screen.setOn(true)
* onExit: screen->setOn(false)
- onEntry: setBluetoothOn(true), screen.setOn(true)
- onExit: screen->setOn(false)
- Has Power (POWER) - Screen is on, device doesn't sleep, Bluetooth on, and will stay in this state as long as we have power.
* onEntry: setBluetooth off, screen on
* onExit:
- onEntry: setBluetooth off, screen on
- onExit:

4
docs/software/device/remote-admin.md
View file

@ -144,8 +144,8 @@ Completed getting preferences
For further reading, I recommend starting out with [Meshtastic-python](/docs/software/python/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
[Complete list of user settings in Protobufs](https://meshtastic.org/docs/developers/protobufs/api#radioconfiguserpreferences)
[Settings Overview](/docs/settings) and
[Complete list of user settings in Protobufs](/docs/developers/protobufs/api#radioconfiguserpreferences)
## Areas for future development

53
docs/software/device/remote-hardware-service.md
View file

@ -9,7 +9,7 @@ GPIO access is fundamentally dangerous because invalid options can physically da
:::
:::note
This feature uses a preinstalled plugin in the device code and associated command line flags/classes in the python code. You'll need to be running at least version 1.2.23 (or later) of the python and device code to use this feature.
This feature uses a preinstalled module in the device code and associated command line flags/classes in the python code. You'll need to be running at least version 1.2.23 (or later) of the python and device code to use this feature.
:::
You can get the latest python tool/library with `pip3 install --upgrade meshtastic` on Windows/Linux/OS-X. See the [python section](/docs/software/python/python-installation) for more details.
@ -22,34 +22,33 @@ You can get the latest python tool/library with `pip3 install --upgrade meshtast
## Setup
To prevent access from untrusted users, you must first make a `gpio` channel that is used for authenticated access to this feature. You'll need to install this channel on both the local and remote node.
To prevent access from untrusted users, you must first make a `gpio` channel that is used for authenticated access to this feature. You'll need to install this channel on both the local and remote node.
The procedure using the python command line tool is:
1. Connect local device via USB
2. Create a gpio channel
```bash
meshtastic --ch-add gpio
```
```bash
meshtastic --ch-add gpio
```
:::tip
If doing local testing, may want to change the speed of the channel at this time, too. (ex: "meshtastic --ch-mediumfast")
:::
3. Check the channel has been created and copy the long "Complete URL" that contains all the channels on that device
```bash
meshtastic --info
```
```bash
meshtastic --info
```
4. Connect the remote device via USB (or use the [remote admin](device-remote-admin) feature to reach it through the mesh)
5. Set it to join the gpio channel you created
```bash
meshtastic --seturl theurlyoucopiedinstep3
```
```bash
meshtastic --seturl theurlyoucopiedinstep3
```
Now both devices should be able to talk over the `gpio` channel. Send a text message from one the other other verify. Also run "--nodes" to verify the second node shows up.
@ -112,32 +111,34 @@ GPIO:44 mask:0x100000000000
You can add a simple LED and resistor to validate that the GPIO operations work as expected. Used the tutorial at https://www.instructables.com/Slide-Switch-With-Arduino-Uno-R3/ as a guide.
Need:
* 2 Meshtastic devices (one device could be on a local computer, and the other one just has to be powered and is the one with the LED to be connected to it)
* 2 wires (black and yellow; they can be any color but typically black is used for ground)
* breadboard (optional)
* 1 LED
* 1 220Ω resistor (somewhat optional, but recommended)
- 2 Meshtastic devices (one device could be on a local computer, and the other one just has to be powered and is the one with the LED to be connected to it)
- 2 wires (black and yellow; they can be any color but typically black is used for ground)
- breadboard (optional)
- 1 LED
- 1 220Ω resistor (somewhat optional, but recommended)
Prep:
* disconnect the remote device from power (battery/usb)
* add a resistor from yellow wire to the one end of the LED (either end of the resistor is ok, either end of the LED is ok)
* add the yellow wire from a GPIO pin that will not cause any issues (ex: for TLoraV1, we can use GPIO21)
* add the black "ground" wire from the ground pin on the device (ex: for TLoraV1 it is the end pin next to the RST button) to the other end of the LED
* power on the device
- disconnect the remote device from power (battery/usb)
- add a resistor from yellow wire to the one end of the LED (either end of the resistor is ok, either end of the LED is ok)
- add the yellow wire from a GPIO pin that will not cause any issues (ex: for TLoraV1, we can use GPIO21)
- add the black "ground" wire from the ground pin on the device (ex: for TLoraV1 it is the end pin next to the RST button) to the other end of the LED
- power on the device
Validation:
By default, the pin may be "off" or "on". (It will most likely "off".) See the steps below for running commands. In the example of GPIO21, the mask would be 0x200000.
[<img alt="T-Lora v1 with LED on GPIO 21" src="/img/LED_on_TLoraV1.jpg" style={{zoom:'25%'}} />](/img/LED_on_TLoraV1.jpg)
## Doing GPIO operations
You can programmatically do operations from your own python code by using the Meshtastic `RemoteHardwareClient` class. See the [python API](https://meshtastic.org/docs/software/python/python-installation) documentation for more details.
You can programmatically do operations from your own python code by using the Meshtastic `RemoteHardwareClient` class. See the [python API](/docs/software/python/python-installation) documentation for more details.
## Using GPIOs from the python CLI
Writing a GPIO (ex: turn "on" GPIO4):
```bash title="Expected output"
$ meshtastic --port /dev/ttyUSB0 --gpio-wrb 4 1 --dest \!28979058
Connected to radio
@ -145,6 +146,7 @@ Writing GPIO mask 0x10 with value 0x10 to !28979058
```
Reading a GPIO (ex: read GPIO4):
```bash title="Expected output"
$ meshtastic --port /dev/ttyUSB0 --gpio-rd 0x10 --dest \!28979058
Connected to radio
@ -157,6 +159,7 @@ If the mask and the gpio_value match, then the value is "on". If the gpio_value
:::
Watching for GPIO changes (ex: watching GPIO4 for changes):
```bash title="Expected output"
$ meshtastic --port /dev/ttyUSB0 --gpio-watch 0x10 --dest \!28979058
Connected to radio

8
docs/software/ios/development.md
View file

@ -4,11 +4,11 @@ title: iOS application development
sidebar_label: App development
---
The Meshtastic iOS app is currently available in TestFlight as a public beta with a projected App Store release in early 2022.
The Meshtastic iOS app is currently available in TestFlight as a public beta with a projected App Store release in early 2022.
There are plenty of remaining beta spaces available and there are no codes.
iOS 15 is required and you can sign up by opening the following link on any iOS device with TestFlight installed.
iOS 15 is required and you can sign up by opening the following link on any iOS device with TestFlight installed.
https://testflight.apple.com/join/c8nNl8q1
@ -16,5 +16,5 @@ An alpha MacOS application is available in the beta TestFlight app for MacOS cur
Code from two previous community projects is also available.
* https://github.com/jeksys/Meshtastic-iOS
* https://github.com/thepoweroftwo/meshtastic-ios
- https://github.com/jeksys/Meshtastic-iOS
- https://github.com/thepoweroftwo/meshtastic-ios

28
docs/software/js/connecting.md
View file

@ -4,17 +4,21 @@ title: Connecting to a device
sidebar_label: Connecting
---
Currently, two connection methods are supported, HTTP and BLE.
## HTTP
## BLE
```typescript
//connection method
```
```tsx
//connection button
const a = <connectButton method={someMethod} />;
import type React from "React";
import { IHTTPConnection } from "@meshtastic/meshtasticjs";
export const Connection = (): JSX.Element => {
const connection = new IHTTPConnection();
const connect = (): void => {
void connection.connect({
address: "10.0.0.10",
fetchInterval: 3000,
});
};
return <button onClick={connect}>Connect Bluetooth</button>;
};
```

2
docs/software/js/getting-started.md
View file

@ -12,7 +12,7 @@ Full API documentation is available at [js.meshtastic.org](https://js.meshtastic
Meshtastic.js is a JavaScript library that provides an interface to Meshtastic devices. It can be used to build applications to interface with a Meshtastic network. Currently, HTTP(S) and Bluetooth connections are supported.
If you wish to view the code or contribute to development of the library, please visit the JavaScript code <a href="https://github.com/meshtastic/meshtastic.js">GitHub page</a>.
If you wish to view the code or contribute to development of the library, please visit the JavaScript code [GitHub page](https://github.com/meshtastic/meshtastic.js).
## Connection methods

12
docs/software/js/http-api.md
View file

@ -27,9 +27,13 @@ const connection = client.createHTTPConnection();
connection.connect("192.168.x.x");
const restartDevice: Promise<void> = connection.restartDevice();
const getStatistics: Promise<void | Types.WebSPIFFSResponse> = connection.getStatistics();
const getNetworks: Promise<void | Types.WebNetworkResponse> = connection.getNetworks();
const getSPIFFS: Promise<void | Types.WebSPIFFSResponse> = connection.getSPIFFS();
const deleteSPIFFS: Promise<void | Types.WebSPIFFSResponse> = connection.deleteSPIFFS();
const getStatistics: Promise<void | Types.WebSPIFFSResponse> =
connection.getStatistics();
const getNetworks: Promise<void | Types.WebNetworkResponse> =
connection.getNetworks();
const getSPIFFS: Promise<void | Types.WebSPIFFSResponse> =
connection.getSPIFFS();
const deleteSPIFFS: Promise<void | Types.WebSPIFFSResponse> =
connection.deleteSPIFFS();
const blinkLED: Promise<void | any> = connection.blinkLED();
```

75
docs/software/plugins/canned-message.md → docs/software/modules/canned-message.md
View file

@ -1,11 +1,12 @@
---
id: canned-message-plugin
id: canned-message-module
title: Canned messages
sidebar_label: Canned messages
---
## About
The CannedMessage Plugin will allow you to send messages to the mesh network
The Canned Message Module will allow you to send messages to the mesh network
from the device without using the phone app.
You can predefine text messages to choose from.
@ -13,13 +14,13 @@ You can predefine text messages to choose from.
To navigate through messages and select one, you will require some
hardware attached to your device.
Currently, the plugin is tested with a generic rotary encoder, but this is
Currently, the module is tested with a generic rotary encoder, but this is
not a limitation further input methods can be added in the future.
### Rotary encoder
Meshtastic supports hardwired rotary encoders as input devices.
(Technically CannedMessage plugin is independent of rotary
(Technically the Canned Message Module is independent of rotary
encoders. It is described here, because no other module utilizes rotary encoders just yet.)
You will need a generic rotary encoder. The types listed below has five legs
@ -28,11 +29,11 @@ but any other types will likely do the job. You can also use a
three-legged version, where the "press" action should be wired from
an independent switch.
* [Amazon link](https://www.amazon.com/Rotary-Encoder-Washers-Digital-Potentiometer/dp/B07Y619CZR/ref=sr_1_21?keywords=rotary+encoder&qid=1642317807&sprefix=rotary+enco%2Caps%2C186&sr=8-21)
* [Amazon.DE link](https://www.amazon.de/-/en/sourcing-Degree-Rotary-Encoder-Digital/dp/B07RLZPX5K/ref=sr_1_12?keywords=rotary+encoder&qid=1642320025&sprefix=rotary%2Caps%2C105&sr=8-12)
* [Aliexpress link1](https://www.aliexpress.com/item/32992227812.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-23&pdp_ext_f=%7B%22sku_id%22%3A%2266940265509%22%7D&pdp_pi=-1%3B1.66%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch)
* [Aliexpress link2](https://www.aliexpress.com/item/32946444853.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&aem_p4p_detail=2022011523263276283624312400022072680&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-6&pdp_ext_f=%7B%22sku_id%22%3A%2266223434642%22%7D&pdp_pi=-1%3B1.91%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch)
* [Aliexpress link3](https://www.aliexpress.com/item/10000056483250.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-9&pdp_ext_f=%7B%22sku_id%22%3A%2220000000116682147%22%7D&pdp_pi=-1%3B2.51%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch)
- [Amazon link](https://www.amazon.com/Rotary-Encoder-Washers-Digital-Potentiometer/dp/B07Y619CZR/ref=sr_1_21?keywords=rotary+encoder&qid=1642317807&sprefix=rotary+enco%2Caps%2C186&sr=8-21)
- [Amazon.DE link](https://www.amazon.de/-/en/sourcing-Degree-Rotary-Encoder-Digital/dp/B07RLZPX5K/ref=sr_1_12?keywords=rotary+encoder&qid=1642320025&sprefix=rotary%2Caps%2C105&sr=8-12)
- [Aliexpress link1](https://www.aliexpress.com/item/32992227812.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-23&pdp_ext_f=%7B%22sku_id%22%3A%2266940265509%22%7D&pdp_pi=-1%3B1.66%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch)
- [Aliexpress link2](https://www.aliexpress.com/item/32946444853.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&aem_p4p_detail=2022011523263276283624312400022072680&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-6&pdp_ext_f=%7B%22sku_id%22%3A%2266223434642%22%7D&pdp_pi=-1%3B1.91%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch)
- [Aliexpress link3](https://www.aliexpress.com/item/10000056483250.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-9&pdp_ext_f=%7B%22sku_id%22%3A%2220000000116682147%22%7D&pdp_pi=-1%3B2.51%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch)
Connect your rotary encoder as follows. The rotary encoder has two
rows of legs. One of the rows contains two legs, the other contains three
@ -46,7 +47,7 @@ The two legs is to sense the press action (or push). Connect
one of the two to GROUND and the other to a GPIO pin. (No matter which one
goes where.) Let's call this connected ports 'PRESS'.
The three legs is to sense the rotation action.
The three legs is to sense the rotation action.
Connect the middle leg to GROUND and the ones on the side
to GPIO pins. Let's call these ports 'A' and 'B', according to
the scheme below.
@ -57,10 +58,10 @@ the scheme below.
Recommended GPIO pins for connecting a rotary encoder.
* TTGO LoRa V1:
* A - GPIO-22
* B - GPIO-23
* PRESS - GPIO-21
- TTGO LoRa V1:
- A - GPIO-22
- B - GPIO-23
- PRESS - GPIO-21
There is a reference case 3D-design utilizing the rotary encoder for TTGO LoRa V1:
[Case for TTGO-ESP32-LORA-OLED-v1.0 with rotary encoder](https://www.thingiverse.com/thing:5178495)
@ -81,35 +82,35 @@ There is a reference case 3D-design utilizing the rotary encoder for TTGO LoRa V
rotary1_event_cw
Generate input event on CW of this kind.
For using with CannedMessagePlugin you must choose value "UP" here!
For using with CannedMessageModule you must choose value "UP" here!
rotary1_event_ccw
Generate input event on CCW of this kind.
For using with CannedMessagePlugin you must choose value "DOWN" here!
For using with CannedMessageModule you must choose value "DOWN" here!
rotary1_event_press
Generate input event on Press of this kind.
For using with CannedMessagePlugin you must choose value "SELECT" here!
For using with CannedMessageModule you must choose value "SELECT" here!
The rotary encoder #1 will send input events under name "rotEnc1".
## Configuration of the plugin
## Configuration of the module
Following configuration can be set for the plugin.
Following configuration can be set for the module.
canned_message_plugin_enabled
Enable/disable CannedMessagePlugin.
canned_message_module_enabled
Enable/disable CannedMessageModule.
canned_message_plugin_allow_input_source
Input event origin accepted by the canned message plugin.
canned_message_module_allow_input_source
Input event origin accepted by the Canned Message Module.
Can be e.g. "rotEnc1" or keyword "_any"
canned_message_plugin_messages
Predefined messages for CannedMessagePlugin separated by '|' characters.
canned_message_module_messages
Predefined messages for CannedMessageModule separated by '|' characters.
canned_message_plugin_send_bell
CannedMessagePlugin also sends a bell character with the messages.
ExternalNotificationPlugin can benefit from this feature.
canned_message_module_send_bell
CannedMessagemodule also sends a bell character with the messages.
ExternalNotificationModule can benefit from this feature.
## Usage Notes
@ -124,13 +125,13 @@ need to execute a sequence like this:
meshtastic --set rotary1_event_press KEY_SELECT
meshtastic --set rotary1_enabled True
For setting up the plugin you will
For setting up the module you will
need to execute a sequence like this:
meshtastic --set canned_message_plugin_allow_input_source "_any"
meshtastic --set canned_message_plugin_messages "I'm fine|I'm out|I'm back|Need helping hand|Help me with saw|I need an alpinist|I need ambulance|Keep Calm|On my way|I will be late|I'm already waiting|We have company|Beer is cold|Roger"
meshtastic --set canned_message_plugin_send_bell False
meshtastic --set canned_message_plugin_enabled True
meshtastic --set canned_message_module_allow_input_source "_any"
meshtastic --set canned_message_module_messages "I'm fine|I'm out|I'm back|Need helping hand|Help me with saw|I need an alpinist|I need ambulance|Keep Calm|On my way|I will be late|I'm already waiting|We have company|Beer is cold|Roger"
meshtastic --set canned_message_module_send_bell False
meshtastic --set canned_message_module_enabled True
:::note
You can define up to 50 messages with a total length 200 bytes.
@ -139,11 +140,11 @@ Use short texts as end of line will be truncated on the screen.
:::
:::note
The device must be restarted after the settings have been changed for the plugin to take effect.
The device must be restarted after the settings have been changed for the module to take effect.
:::
## Known Problems
* Rotary encoder input uses a technology called "interrupts". Using the
rotary encoder might cause unexpected software problems. This needs to be
tested.
- Rotary encoder input uses a technology called "interrupts". Using the
rotary encoder might cause unexpected software problems. This needs to be
tested.

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