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

Simplify build instrucions and rename plugins.

Browse source
This commit is contained in:
Sacha Weatherstone 2022-03-09 18:10:41 +11:00
parent 7712748154
commit 7f56825c40
63 changed files with 2161 additions and 2043 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.

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/software/settings/channel) for more info. It is also possible that your location could be triangulated by determined individuals.
## Channels

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

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

90
docs/developers/build.md
View file

@ -1,88 +1,20 @@
---
id: build-env
title: Creating a build/development environment
title: Creating a build environment
sidebar_label: Building Meshtastic
---
This project uses the simple PlatformIO build system. PlatformIO is an extension to Microsoft VSCode.
Meshtastic uses the [PlatformIO](https://platformio.org) development environment, that enables easy multiplatform development and centralized tooling.
## GUI Installation
## Setup
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.
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. Some utilities and scripts use the Python programming language, Downloads available [here](https://www.python.org/downloads).
:::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.
:::
## Building
## 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'
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`

2
docs/developers/device/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.

6
docs/developers/device/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.

60
docs/developers/device/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
@ -55,20 +55,20 @@ This layer is conventional non-reliable LoRa packet transmission. The transmitte
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).

40
docs/developers/device/plugin-api.md → docs/developers/device/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 MeshPlugin. 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).
@ -19,12 +19,12 @@ 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.
- [SinglePortPlugin](http://github.com/meshtastic/meshtastic-device/tree/master/src/mesh/SinglePortPlugin.h) (in src/mesh/SinglePortPlugin.h) - for modules 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 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.
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)
- 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

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.

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/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`.
### Can I have Bluetooth enabled and use WiFi radio?

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)

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.

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

@ -0,0 +1,18 @@
---
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/modus).
### I'd like to write a module. How do I get started?
API documentation for creating modules is available [here](/docs/developers/device/module-api).

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

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

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.

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)

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!

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.

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

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.

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

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

237
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,27 +268,26 @@ 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
@ -296,7 +297,7 @@ Either use a custom channel configuration with at an at least 1kbit data rate or
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.

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

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

@ -4,10 +4,10 @@ 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)
* [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

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

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

@ -4,17 +4,24 @@ 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

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.

222
docs/software/modules/environment.md Normal file
View file

@ -0,0 +1,222 @@
---
id: environment-module
title: Environment measurement
sidebar_label: Environment measurement
---
## About
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`, Dallas 1-wire `DS18B20`, and `MCP9808`.
The preferred setup is using I2C, so the `telemetry_module_sensor_pin` may not be needed.
## Configuration
These are the settings that can be configured.
telemetry_module_enabled
Is the module enabled?
0 = Disabled (Default)
1 = Enabled
telemetry_module_screen_enabled
Show received sensor readings on device screen.
0 = Disabled (Default)
1 = Enabled
telemetry_module_read_error_count_threshold
Error count threshold for failed sensor readings.
Default = 0
preferences.telemetry_module_update_interval
How often (in seconds) should sensor readings be broadcasted?
Default = 0
telemetry_module_recovery_interval
For how long should we wait (in seconds) before trying to read sensors again upon exceeded error threshold?
Default = 0
telemetry_module_display_fahrenheit
Should temperature readings be converted to fahrenheit?
0 = Disabled (Default)
1 = Enabled
telemetry_module_sensor_type
What sensor is connected?
0 = DHT11 (Default)
1 = Dallas 1-wire DS18B20
2 = DHT12
3 = DHT21
4 = DHT22
5 = BME280
6 = BME680
7 = MCP9808
telemetry_module_sensor_pin
Which pin is the sensor connected to?
Default = 0
## Usage Notes
For basic usage, start with:
```bash
telemetry_module_enabled = 1
telemetry_module_screen_enabled = 1
```
Depending on which pin your sensor is connected to, set it accordingly:
```bash
telemetry_module_sensor_pin = 13
```
:::note
The device must be restarted after the settings have been changed for the module to take effect.
:::
## Hardware
The sensors can be wired differently, here's one example for sensor DS18B20 https://randomnerdtutorials.com/esp32-ds18b20-temperature-arduino-ide
## Example of T-LoraV1 with DHT22 temperature sensor
Setup of a T-LoraV1 with DHT22 temperature sensor.
[<img src="T-LoraV1 with DHT22" src="/img/hardware/lora_v1_with_DHT22.jpg" style={{zoom:'25%'}} />](/img/hardware/lora_v1_with_DHT22.jpg)
Requirements:
- T-LoraV1 (but any esp32 should work, just be sure to double check which GPIO to use)
- DHT22 sensor
- 10 Kohm resistor (optional, but recommended)
- breadboard (optional)
- two red wires (could be a different color, but 5V is typically red)
- two yellow wires for GPIO (could be a different color)
- one black wire (could be a different color, but GROUND is typically black)
Steps:
- disconnect power/battery
- connect black wire from GROUND to "-" on the DHT22
- connect yellow wire from middle PIN to a row on bread board
- connect red wire from 5V to a row on breadboard
- connect resistor between red and yellow rows
- connect red wire from row with red to "+" on DHT22
- connect yellow wire from yellow row to GPIO on device (ex: GPIO21)
- double check the cabling (if you get it wrong, you can damage the device and/or the DHT22 sensor)
- plug in device
- configure the device:
```bash
meshtastic --set telemetry_module_measurement_enabled true --set telemetry_module_screen_enabled true --set telemetry_module_update_interval 15 --set telemetry_module_display_farenheit true --set telemetry_module_sensor_type DHT22 --set telemetry_module_sensor_pin 21
```
:::tip
You can change the values above to suit your needs. The commands can be run one at a time or in a group as show above.
:::
- reboot/reset the device (press the RST button or unplug/plug in the device)
- when the device boots it should say "Environment" and it may show the sensor data
- if "no data", then triple check the wiring
- if still "no data", run:
```bash
meshtastic --info
```
and verify the the `telemetry_module_sensor_type and` `telemetry_module_sensor_pin`
## Example of T-LoraV1 with Dallas DS18B20 temperature sensor
Setup of a T-LoraV1 with DS18B20 temperature sensor.
[<img src="T-LoraV1 with DS18B20" src="/img/hardware/lora_v1_with_DS18B20.jpg" style={{zoom:'25%'}} />](/img/hardware/lora_v1_with_DS18B20.jpg)
Requirements:
- T-LoraV1 (but any esp32 should work, just be sure to double check which GPIO to use)
- DS18B20 sensor
- 10 Kohm resistor (optional, but recommended)
- breadboard (optional)
- two red wires (could be a different color, but 5V is typically red)
- two yellow wires for GPIO (could be a different color)
- one black wire (could be a different color, but GROUND is typically black)
Steps:
- disconnect power/battery
- connect black wire from GROUND to "-" on the DS18B20
- connect yellow wire from DAT pin to a row on bread board
- connect red wire from 5V to a row on breadboard
- connect resistor between red and yellow rows
- connect red wire from row with red to "VCC" on DS18B20
- connect yellow wire from yellow row to GPIO on device (ex: GPIO21)
- double check the cabling (if you get it wrong, you can damage the device and/or the sensor)
- plug in device
- configure the device:
```bash
meshtastic --set telemetry_module_measurement_enabled true --set telemetry_module_screen_enabled true --set telemetry_module_update_interval 15 --set telemetry_module_display_farenheit true --set telemetry_module_sensor_type DS18B20 --set telemetry_module_sensor_pin 21
```
:::tip
You can change the values above to suit your needs. The commands can be run one at a time or in a group as show above.
:::
- reboot/reset the device (press the RST button or unplug/plug in the device)
- when the device boots it should say "Environment" and it may show the sensor data
- if "no data", then triple check the wiring
- if still "no data", run:
```bash
meshtastic --info
```
and verify the the `telemetry_module_sensor_type` and `telemetry_module_sensor_pin`
## Example of RAK 4631 with Environment Sensor
Setup of a RAK 4631 with Environment Sensor
[<img src="RAK4631_with_EnvSensor" src="/img/hardware/rak/RAK4631_with_EnvSensor.jpg" style={{zoom:'25%'}} />](/img/hardware/rak/RAK4631_with_EnvSensor.jpg)
Requirements:
- RAK4631
- Environment Sensor
Steps:
- configure the device:
```bash
meshtastic --set telemetry_module_measurement_enabled true --set telemetry_module_screen_enabled true --set telemetry_module_update_interval 15 --set telemetry_module_display_farenheit true --set telemetry_module_sensor_type 6
```
:::tip
You can change the values above to suit your needs. The commands can be run one at a time or in a group as show above.
:::
- reboot/reset the device (press the button or unplug/plug in the device)
- when the device boots it should say "Environment" and it may show the sensor data
- if still "no data", run:
```bash
meshtastic --info
```
and verify the the `telemetry_module_sensor_type`
## Known Problems
- No default configuration values are currently set, so this must be done when enabling the module.

62
docs/software/plugins/external-notifications.md → docs/software/modules/external-notifications.md
View file

@ -1,93 +1,93 @@
---
id: ext-notif-plugin
id: ext-notif-module
title: External notifications
sidebar_label: External notifications
---
## About
The ExternalNotification 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 ExternalNotification 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.
## Configuration
These are the settings that can be configured.
ext_notification_plugin_enabled
Is the plugin enabled?
ext_notification_module_enabled
Is the module enabled?
0 = Disabled (Default)
1 = Enabled
ext_notification_plugin_active
ext_notification_module_active
Is your external circuit triggered when our GPIO is low or high?
0 = Active Low (Default)
1 = Active High
ext_notification_plugin_alert_message
ext_notification_module_alert_message
Do you want to be notified on an incoming message?
0 = Disabled (Default)
1 = Alert when a text message comes
ext_notification_plugin_alert_bell
ext_notification_module_alert_bell
Do you want to be notified on an incoming bell?
0 = Disabled (Default)
1 = Alert when the bell character is received
ext_notification_plugin_output
ext_notification_module_output
What GPIO is your external circuit attached?
GPIO of the output. (Default = 13)
ext_notification_plugin_output_ms
ext_notification_module_output_ms
How long do you want us to trigger your external circuit?
Amount of time in ms for the alert. Default is 1000.
Amount of time in ms for the alert. Default is 1000.
## Usage Notes
For basic usage, start with:
ext_notification_plugin_enabled = 1
ext_notification_module_enabled = 1
ext_notification_module_alert_message = 1
ext_notification_plugin_alert_message = 1
Depending on how your external circuit is configured, you may need to set the active state to true.
ext_notification_plugin_active = 1
ext_notification_module_active = 1
:::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.
:::
### Alert Types
We support being alerted on two events:
1) Incoming Text Message
1. Incoming Text Message
2) Incoming Text Message that contains the ASCII bell character. At present, only the Python API can send an ASCII bell character, but more support may be added in the future.
2. Incoming Text Message that contains the ASCII bell character. At present, only the Python API can send an ASCII bell character, but more support may be added in the future.
#### Bell Character
The bell character is ASCII 0x07. Include 0x07 anywhere in the text message and with ext_notification_plugin_alert_bell enabled, we will issue an external notification.
The bell character is ASCII 0x07. Include 0x07 anywhere in the text message and with ext_notification_module_alert_bell enabled, we will issue an external notification.
## External Hardware
Be mindful of the max current sink and source of the ESP32 GPIO. The easiest devices to interface with would be either an LED or Active Buzzer.
Ideas for external hardware:
* LED
* Active Buzzer
* Flame thrower
* Strobe Light
* Siren
- LED
- Active Buzzer
- Flame thrower
- Strobe Light
- Siren
## Known Problems
* This won't directly support a passive (normal) speaker as it does not generate any audio wave forms.
* This currently only supports the ESP32. Other targets may be possible, I just don't have to test with.
* This plugin only monitors text messages. We won't trigger on any other packet types.
- This won't directly support a passive (normal) speaker as it does not generate any audio wave forms.
- This currently only supports the ESP32. Other targets may be possible, I just don't have to test with.
- This module only monitors text messages. We won't trigger on any other packet types.

0
docs/software/plugins/plugin-api.md → docs/software/modules/module-api.md
View file

10
docs/software/plugins/plugins.md → docs/software/modules/modules.md
View file

@ -1,17 +1,17 @@
---
id: plugins
title: Plugins overview
id: modules
title: Modules overview
sidebar_label: Overview
---
There are a number of plugins that have been integrated into the device firmware. These can be turned on using the Meshtastic python command line program. Please note that these plugins require the device to be rebooted once they have been enabled for them to start running.
There are a number of modules that have been integrated into the device firmware. These can be turned on using the Meshtastic python command line program. Please note that these modules require the device to be rebooted once they have been enabled for them to start running.
These plugins are currently integrated into the firmware:
These modules are currently integrated into the firmware:
* Range test - Allows automated testing of communication range of nodes
* External notifications - Allows a speaker, LED or other device to indicate when a message has been received
* Canned messages - Device can be used without the phone to send a message by choosing a predefined text
* Serial - Allows messages to be sent across the mesh by sending strings across a serial port
These plugins are currently in development:
These modules are currently in development:
* Store and forward - Allows a node to store messages and resend them to nodes that have intermittent connection to the mesh
* Environment measurement - Allows a node to measure it's local environment and report across the mesh

104
docs/software/plugins/range-test.md → docs/software/modules/range-test.md
View file

@ -1,75 +1,75 @@
---
id: range-test-plugin
title: Range test plugin
sidebar_label: Range test
id: range-test-module
title: Range Test Module
sidebar_label: Range Test
---
This plugin allows you to test the range of your Meshtastic nodes. It uses two nodes, one to send a message every minute, and another to receive the messages. 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, for example, Google Earth, allowing you to see where you have coverage.
This module allows you to test the range of your Meshtastic nodes. It uses two nodes, one to send a message every minute, and another to receive the messages. 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, for example, Google Earth, allowing you to see where you have coverage.
## Configuration
These are the settings that can be configured.
range_test_plugin_enabled
Is the plugin enabled?
range_test_module_enabled
Is the Module enabled?
0 = Disabled (Default)
1 = Enabled
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 webserver. We will abort
writing if there is less than 50k of space on the filesystem to prevent filling up the storage.
0 = Disabled (Default)
1 = Enabled
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 agressive with faster settings. 0 is default which disables sending messages.
:::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.
:::
### Usage Notes
For basic usage, you will need two devices both with a GPS. A device with a paired phone with GPS may work, I have not tried it.
The first thing to do is to turn on the plugin. The device will need to be restarted after applying the settings. With the plugin turned on, the other settings will be available:
The first thing to do is to turn on the module. The device will need to be restarted after applying the settings. With the module turned on, the other settings will be available:
range_test_plugin_enabled = 1
range_test_module_enabled = 1
If you want to send a message every 60 seconds:
range_test_plugin_sender = 60
range_test_module_sender = 60
To save a log of the messages:
range_test_plugin_save = 1
range_test_module_save = 1
Recommended settings for a sender at different radio settings:
Long Slow ... range_test_plugin_sender = 60
Long Alt ... range_test_plugin_sender = 30
Medium ... range_test_plugin_sender = 15
Short Fast ... range_test_plugin_sender = 15
Long Slow ... range_test_module_sender = 60
Long Alt ... range_test_module_sender = 30
Medium ... range_test_module_sender = 15
Short Fast ... range_test_module_sender = 15
### Python API Examples
Sender
`meshtastic --set range_test_plugin_enabled 1`
`meshtastic --set range_test_module_enabled 1`
`meshtastic --set range_test_plugin_sender 60`
`meshtastic --set range_test_module_sender 60`
Receiver
`meshtastic --set range_test_plugin_enabled 1`
`meshtastic --set range_test_module_enabled 1`
`meshtastic --set range_test_plugin_save 1`
`meshtastic --set range_test_module_save 1`
### Other things to keep in mind
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.
@ -80,21 +80,21 @@ Also, be mindful of your space usage on the file system. It has protections from
Steps:
1. [Download](https://www.google.com/earth/versions/#download-pro) and open Google Earth
1. Select File > Import
2. Select CSV
3. Select Delimited, Comma
4. Make sure the button that states “This dataset does not contain latitude/longitude information, but street addresses” is unchecked
5. Select “rx lat” & “rx long” for the appropriate lat/lng fields
6. Click finish
1. Select File > Import
2. Select CSV
3. Select Delimited, Comma
4. Make sure the button that states “This dataset does not contain latitude/longitude information, but street addresses” is unchecked
5. Select “rx lat” & “rx long” for the appropriate lat/lng fields
6. Click finish
2. When it prompts you to create a style template, click yes.
1. Set the name field to whichever column you want to be displayed on the map (don’t worry about this too much, when you click on an icon, all the relevant data appears)
2. Select a color, icon, etc. and hit OK.
1. Set the name field to whichever column you want to be displayed on the map (don’t worry about this too much, when you click on an icon, all the relevant data appears)
2. Select a color, icon, etc. and hit OK.
Your data will load onto the map, make sure to click the checkbox next to your dataset in the sidebar to view it.
### My Maps
You can use [My Maps](http://mymaps.google.com/). It takes CSVs and the whole interface is much easier to work with.
You can use [My Maps](http://mymaps.google.com). It takes CSVs and the whole interface is much easier to work with.
Google has instructions on how to do that [here](https://support.google.com/mymaps/answer/3024836?co=GENIE.Platform%3DDesktop&hl=en#zippy=%2Cstep-prepare-your-info%2Cstep-import-info-into-the-map).
@ -110,26 +110,34 @@ Right now range test messages go over the `TEXT_MESSAGE_APP` port. We need a tog
## FAQ
Q: Where is rangetest.csv saved?
* Turn on the WiFi on your device as either a WiFi client or a WiFi AP. Once you can connect to your device, go to /static and you will see rangetest.csv.
Q: Where is rangetest.csv saved?
Q: Do I need to have WiFi turned on for the file to be saved?
* Nope, it'll just work.
- Turn on the WiFi on your device as either a WiFi client or a WiFi AP. Once you can connect to your device, go to /static and you will see rangetest.csv.
Q: Do I need a phone for this plugin?
* There's no need for a phone.
Q: Do I need to have WiFi turned on for the file to be saved?
Q: Can I use this as a message logger?
* While it's not the intended purpose, sure, why not. Do it!
- Nope, it'll just work.
Q: What will happen if I run out of space on my device?
* We have a protection in place to keep you from completely filling up your device. This will make sure that other device critical functions will continue to work. We will reserve at least 50k of free space.
Q: Do I need a phone for this module?
Q: What do I do with the rangetest.csv file when I'm done?
* Go to /static and delete the file.
- There's no need for a phone.
Q: Can I use this as a sender while on battery power?
* Yes, but your battery will run down quicker than normal. While sending, we tell the device not to go into low-power mode since it needs to keep to a fairly strict timer.
Q: Can I use this as a message logger?
Q: Why is this operating on incoming messages instead of the existing location discovery protocol?
* This plugin is still young and currently supports monitoring just one port at a time. I decided to use the existing message port because that is easy to test with. A future version will listen to multiple ports to be more promiscuous.
- While it's not the intended purpose, sure, why not. Do it!
Q: What will happen if I run out of space on my device?
- We have a protection in place to keep you from completely filling up your device. This will make sure that other device critical functions will continue to work. We will reserve at least 50k of free space.
Q: What do I do with the rangetest.csv file when I'm done?
- Go to /static and delete the file.
Q: Can I use this as a sender while on battery power?
- Yes, but your battery will run down quicker than normal. While sending, we tell the device not to go into low-power mode since it needs to keep to a fairly strict timer.
Q: Why is this operating on incoming messages instead of the existing location discovery protocol?
- This module is still young and currently supports monitoring just one port at a time. I decided to use the existing message port because that is easy to test with. A future version will listen to multiple ports to be more promiscuous.

40
docs/software/modules/serial.md Normal file
View file

@ -0,0 +1,40 @@
---
id: serial-module
title: Serial communication module
sidebar_label: Serial communication
---
## About
This is a simple interface to send messages over the mesh network by sending strings over a serial port.
Default is to use RX GPIO 16 and TX GPIO 17.
## Basic Usage:
1. Enable the module by setting `serial_module_enabled` to `1`.
2. Set the pins (`serial_module_rxd` / `serial_module_rxd`) for your preferred RX and TX GPIO pins. On tbeam boards it is recommended to use:
- RXD 35
- TXD 15
3. Set `serial_module_timeout` to the amount of time to wait before we consider your packet as "done".
4. (Optional) In serial_module.h set the port to `PortNum_TEXT_MESSAGE_APP`if you want to send messages to/from the general text message channel.
5. Connect to your device over the serial interface at `38400 8N1`.
6. Send a packet up to 240 bytes in length. This will get relayed over the mesh network.
7. (Optional) Set `serial_module_echo` to `1` and any message you send out will be echoed back to your device.
:::note
The device must be restarted after the settings have been changed for the module to take effect.
:::
## TODO (in this order):
- Define a verbose RX mode to report on mesh and packet information.
:::note
This won't happen any time soon.
:::
## Known Problems
- Until the module is initialized by the startup sequence, the TX pin is in a floating state. Device connected to that pin may see this as "noise".
- Will not work on NRF and the Linux device targets.

213
docs/software/modules/store-forward.md Normal file
View file

@ -0,0 +1,213 @@
---
id: store-forward-module
title: Store and Forward Module
sidebar_label: Store and Forward
---
## About
:::caution
This is a work in progress and is partially available. Stability is not guaranteed.
:::
The Store Forward Module is an implementation of a Store and Forward system to enable resilient messaging in the event that a client device is disconnected from the main network.
Because of the increased network traffic for this overhead, it's not advised to use this if you are duty cycle limited for your airtime usage nor is it advised to use this for SF12 (Long Range / Slow).
### About - How it works
![Store & Forward - Overview](/img/modules/store_and_forward/store_and_forward-overview.png)
## Requirements
Initial Requirements:
- Must be installed on a router 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.
### 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).
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
meshtastic --setchan spread_factor 11 --setchan coding_rate 4 --setchan bandwidth 500
```
With an aftermarket coaxial antenna or moxon antenna, that will give you roughly the same range as "Long Range / Slow" and 5x the bitrate.
### Router setup
- Configure your device as a meshtastic router.
- - https://meshtastic.org/docs/software/settings/router
- Configure the Store and Forward Module
- - Required configuration
- - - store_forward_module_enabled - Set this to true to enable the module. False to disable the module.
- - Optional configuration
- - - store_forward_module_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.
- Name your router node something that makes it easily identifiable, aka "Router".
Don't enable the Store and Forward module on multiple routers!
### Client Usage
Currently, no special configuration is required. To request your history sent to you, send the command into the message field "SF". That's it. This will eventually change to make it easier. At the moment, that message will be sent to everyone on the mesh but we'll (eventually) make it easier to use where there'll be a button (or maybe it'll be transparent) and the command isn't sent as a text message to the mesh.
Available Commands:
| Command | Definition |
| :-----: | :------------------------------------------: |
| SF | Send the last few messages I may have missed |
| SFm | Send a 240 byte payload (Used for testing) |
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.
## Settings
| Setting | Acceptable Values | Default |
| :-------------------------------------------: | :---------------: | :-----: |
| store_forward_module_enabled | `true`, `false` | `false` |
| store_forward_module_records | integer | `0` |
| store_forward_module_replay_max_records (tbd) | integer | `0` |
| store_forward_module_replay_max_time (tbd) | integer | `0` |
## Example Request/Response
### Request History (Use Router Defaults)
Story: Carol has been away from the mesh with device turned off. She would like to get a replay of what she has missed. The router will return the messages.
- Carol
- - Packet (Port: STORE_FORWARD_APP)
- - - To: Broadcast (Optionally, direct to router)
- - - StoreAndForward.rr.CLIENT_HISTORY
- Router
- - Packet (Port: STORE_FORWARD_APP)
- - - To: Carol
- - - StoreAndForward.rr.ROUTER_HISTORY
- - - StoreAndForward.history.HistoryMessages = 42 // Router has 42 messages that will be sent to Carol.
- - - StoreAndForward.history.Window = 120 // Router searched for messages over the last two hours.
- - - StoreAndForward.history.LastRequest = 0 // Carol has never asked for the history.
- - Packet (Port: TEXT_MESSAGE_APP)
- - - ... a series of 42 text messages
### Request History (No history available)
Story: Carol has been away from the mesh with device turned off. She would like to get a replay of what she has missed but the router indicates there are no messages available.
- Carol
- - Packet (Port: STORE_FORWARD_APP)
- - - To: Broadcast (Optionally, direct to router)
- - - StoreAndForward.rr.CLIENT_HISTORY
- Router
- - Packet (Port: STORE_FORWARD_APP)
- - - To: Carol
- - - StoreAndForward.rr.ROUTER_HISTORY
- - - StoreAndForward.history.HistoryMessages = 0 // Router has no messages to be sent to Carol.
- - - StoreAndForward.history.Window = 120 // Router searched for messages over the last two hours.
- - - StoreAndForward.history.LastRequest = (timestamp) // Last time carol requested the history.
### Store & Forward Router Heartbeat
Story: 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. Client will not respond to network but (optionally) indicate to the user that a S&F router is available or not available.
- Router
- - Packet (Port: STORE_FORWARD_APP)
- - - To: Broadcast
- - - StoreAndForward.rr.ROUTER_HEARTBEAT
- - - StoreAndForward.heartbeat.Period = 120 // Expect a heartbeat every 2 minutes.
- - - StoreAndForward.heartbeat.Secondary = false // If true, this is a secondary "backup" S&F node. Will be (eventually) used for router election in the event there are multiple S&F Routers.
## Meshpacket
To support functionality of Store and Forward, a new enum has been added to the MeshPacket.
```
typedef enum _MeshPacket_Delayed {
MeshPacket_Delayed_NO_DELAY = 0,
MeshPacket_Delayed_DELAYED_BROADCAST = 1,
MeshPacket_Delayed_DELAYED_DIRECT = 2
} MeshPacket_Delayed;
```
- NO_DELAY - The packet was sent in real time. Store and Forward had no hand in this message. This is the default case.
- DELAYED_BROADCAST - This is a delayed message. The 'to' of the packet has been directed at a named user but was previously a broadcast packet.
- DELAYED_DIRECT - This is a delayed message. The 'to' of the packet has been directed at a named user but was previously a direct packet.
As a reminder, broadcast messages are messages where the "to" of a payload is directed at NODENUM_BROADCAST or (0xFFFFFFFF).
Example Cases:
- Real time :: BROADCAST
- - Delayed = MeshPacket_Delayed_NO_DELAY
- - From: Ann
- - To: BROADCAST
- Real time :: Direct
- - Delayed = MeshPacket_Delayed_NO_DELAY
- - From: Ann
- - To: Bob
- Delayed :: BROADCAST
- - Delayed = MeshPacket_Delayed_DELAYED_BROADCAST
- - From: Ann
- - To: Bob
- Delayed :: Direct
- - Delayed = MeshPacket_Delayed_DELAYED_DIRECT
- - From: Ann
- - To: Bob
When a message is 'real time', time a message is sent is the same as the time the message was received. In the case the message is delayed, there is no timestamp available for the message.
Where the message is a delayed broadcast, the "To" is _not_ a broadcast address but rather the address of the device that requested the messages to be replayed. This is to allow the message to be routed over the mesh network and not displayed in the message screen of other devices.
## Developer TODO
Not necessarily in this order:
- Client Interface (Web, Android, Python or iOS when that happens) to request packets be resent.
- Router sends a heartbeat so the client knows there is a router in range.
- Support for a mesh to have multiple routers that have the store & forward functionality (for redundancy).
- Add a default channel at about 1.5kbit / sec.
- Eventually we could add a "want_store_and_forward" bit to MeshPacket and that could be nicer than whitelists in this module. Initially we'd only set that bit in text messages (and any other module messages that can cope with this). This change would be backward wire compatible so can add easily later.
- Have a "cool down" period to disallow a client to request the history too often.
- Message with SF status on requests.
- Be able to identify if you're within range of a router.
- Be able to specify the HOP MAX to reduce airtime. Is this necessary?
- Restrict operation of S&F on the slow channel configurations.
- Create a TX queue to prevent the history from being modified in flight.
- Only allow n-number of requests to the router at any one time.
- Set number of max messages from the history.
- Calculate a new channel with 250kHz bandwidth and ~1.5kbit.
\*\*\* Done
- Disable ACK. If the router is within range, so is the requester.
- Currently the way we allocate messages in the device code is super inefficient. It always allocates the worst case message size. Really we should dynamically allocate just the # of bytes we need. This would allow many more MeshPackets to be kept in RAM.
- Allow max history to be defined by radioConfig.preferences.store_forward_module_records.
- Add a starting to send / finished sending message.

2
docs/software/other/build-instructions.md
View file

@ -11,7 +11,7 @@ If you encounter any problems, please post a question in [our forum](https://mes
## GUI
1. Purchase a suitable [radio](/docs/hardware).
2. Install [Python](https://www.python.org/downloads/).
2. Install [Python](https://www.python.org/downloads).
3. Install [Git](https://git-scm.com/downloads).
4. Reboot your computer.
5. Install [PlatformIO](https://platformio.org/platformio-ide).

2
docs/software/other/install-OSX.md
View file

@ -42,7 +42,7 @@ After I installed that, esptool.py was completely happy and the firmware loaded
brew install openssl
```
- Set some flags in your bash/zsh/whichever profile for `esptool` to install [cryptography](https://cryptography.io/en/latest/installation/) as a dependency correctly:
- Set some flags in your bash/zsh/whichever profile for `esptool` to install [cryptography](https://cryptography.io/en/latest/installation) as a dependency correctly:
```
export LDFLAGS="-L/usr/local/opt/openssl/lib"

68
docs/software/other/mqtt.md
View file

@ -5,29 +5,30 @@ sidebar_label: MQTT
---
## MQTT
Meshtastic devices with wifi hardware (ESP32) are able to connect to an MQTT broker to uplink and downlink mesh packets. This is useful for a number of purposes:
- Connecting your mesh to the official Meshtastic MQTT broker. This makes your devices appear on the world map, and provides a limited copy of your mesh traffic, translated into JSON.
Meshtastic devices with wifi hardware (ESP32) are able to connect to an MQTT broker to uplink and downlink mesh packets. This is useful for a number of purposes:
- Connecting your mesh to the official Meshtastic MQTT broker. This makes your devices appear on the world map, and provides a limited copy of your mesh traffic, translated into JSON.
- Using a custom MQTT broker to bridge several mesh networks together, via the internet (or just a local IP network)
- Using a custom MQTT broker and a translator program to decode the raw protobuf packets and translate them into a plain text form for use in other systems. eg plotting temperature readings in Grafana, or device positions in Traccar.
- Using a custom MQTT broker and a translator program to decode the raw protobuf packets and translate them into a plain text form for use in other systems. eg plotting temperature readings in Grafana, or device positions in Traccar.
When MQTT enabled, the Meshtastic device simply uplinks and/or downlinks every raw protobuf packet that it sees to the MQTT broker. All packets are sent to the broker, whether they originate from another device on the mesh, or the gateway node itself.
When MQTT enabled, the Meshtastic device simply uplinks and/or downlinks every raw protobuf packet that it sees to the MQTT broker. All packets are sent to the broker, whether they originate from another device on the mesh, or the gateway node itself.
Packets may be encrypted. If you use the default meshtastic MQTT server, packets are always encrypted. If you use a custom MQTT broker (ie set `mqtt_server`), the `mqtt_encryption_enabled` setting applies, which by default is false.
Packets may be encrypted. If you use the default meshtastic MQTT server, packets are always encrypted. If you use a custom MQTT broker (ie set `mqtt_server`), the `mqtt_encryption_enabled` setting applies, which by default is false.
IMPORTANT: When MQTT is turned on, you are potentially broadcasting your entire mesh traffic onto the public internet. This includes messages and position information.
IMPORTANT: When MQTT is turned on, you are potentially broadcasting your entire mesh traffic onto the public internet. This includes messages and position information.
### MQTT Topic
The device will uplink and downlink packets to the `msh/` prefix:
`msh/1/c/ShortFast/!12345678` where
`msh/1/c/ShortFast/!12345678` where
- `!12345678` is the address of the gateway device.
- `ShortFast` is the channel name.
The payload is a raw protobuf. Looking at the MQTT traffic with a program like `mosquitto_sub` will tell you it's working, but you won't get much useful information out of it. For example:
The payload is a raw protobuf. Looking at the MQTT traffic with a program like `mosquitto_sub` will tell you it's working, but you won't get much useful information out of it. For example:
```
苓????"!
!937bed1cTanksTnk"D???05??=???aP`
@ -36,36 +37,34 @@ The payload is a raw protobuf. Looking at the MQTT traffic with a program like
### Basic Configuration
Check out [MQTT Settings](https://meshtastic.org/docs/software/settings/mqtt) for full information. For quick start instructions, read on.
Check out [MQTT Settings](/docs/software/settings/mqtt) for full information. For quick start instructions, read on.
- Connect your gateway node to wifi, by setting the `wifi_ssid` and `wifi_password` preferences.
- Configure your broker settings: `mqtt_server`, `mqtt_username`, and `mqtt_password`. If all are left blank, the device will connect to the Meshtastic broker.
- Set `uplink_enabled` and `downlink_enabled` as appropriate for each channel. Most users will just have a single channel (at channel index 0). `meshtastic --ch-index 0 --ch-set uplink_enabled true`
- Configure your broker settings: `mqtt_server`, `mqtt_username`, and `mqtt_password`. If all are left blank, the device will connect to the Meshtastic broker.
- Set `uplink_enabled` and `downlink_enabled` as appropriate for each channel. Most users will just have a single channel (at channel index 0). `meshtastic --ch-index 0 --ch-set uplink_enabled true`
`uplink_enabled` will tell the device to publish mesh packets to MQTT.
`downlink_enabled` will tell the device to subscribe to MQTT, and forward any packets from there onto the mesh.
### Getting plain data out of the mesh
As of firmware 1.2.53, it is possible for the device to decrypt the protobufs before publishing to MQTT. To translate this into a plain format:
As of firmware 1.2.53, it is possible for the device to decrypt the protobufs before publishing to MQTT. To translate this into a plain format:
- Set up a gateway node to uplink packets to your MQTT broker:
- `meshtastic --set wifi_ssid XXXX`
- `meshtastic --set wifi_password XXXX`
- `meshtastic --set mqtt_server 192.168.1.1`
- `meshtastic --set mqtt_username XXXX`
- `meshtastic --set mqtt_password XXXX`
- `meshtastic --set mqtt_encryption_enabled false`
- `meshtastic --ch-index 0 --ch-set uplink_enabled true`
- `meshtastic --set wifi_ssid XXXX`
- `meshtastic --set wifi_password XXXX`
- `meshtastic --set mqtt_server 192.168.1.1`
- `meshtastic --set mqtt_username XXXX`
- `meshtastic --set mqtt_password XXXX`
- `meshtastic --set mqtt_encryption_enabled false`
- `meshtastic --ch-index 0 --ch-set uplink_enabled true`
- Grab the meshtastic-mqtt script from [here](https://github.com/joshpirihi/meshtastic-mqtt)
- `git clone https://github.com/joshpirihi/meshtastic-mqtt && cd meshtastic-mqtt`
- Edit `meshtastic_mqtt/meshtastic_mqtt.py` and enter your mqtt broker details
- Install the script with `pip install .`
- Run `meshtastic-mqtt`. It will print some debug output by default, and publish the plain values to the `meshtastic/` prefix.
- View the plain data with `mosquitto_sub -h YOUR_MQTT_SERVER -t meshtastic/# -v`
- You can then consume the data easily in other systems. For example, nodered->influx db->grafana.
- `git clone https://github.com/joshpirihi/meshtastic-mqtt && cd meshtastic-mqtt`
- Edit `meshtastic_mqtt/meshtastic_mqtt.py` and enter your mqtt broker details
- Install the script with `pip install .`
- Run `meshtastic-mqtt`. It will print some debug output by default, and publish the plain values to the `meshtastic/` prefix.
- View the plain data with `mosquitto_sub -h YOUR_MQTT_SERVER -t meshtastic/# -v`
- You can then consume the data easily in other systems. For example, nodered->influx db->grafana.
#Original brainstorming for MQTT:
@ -82,7 +81,7 @@ This is a mini-doc/RFC sketching out a development plan to satisfy a number of 1
- A text messaging bridge when a node in the mesh can gateway to the internet. Issue #[353](https://github.com/meshtastic/Meshtastic-device/issues/353) and this nicely documented [android issue](https://github.com/meshtastic/Meshtastic-Android/issues/2).
- An easy way to let desktop app developers remotely control GPIOs. Issue #[182](https://github.com/meshtastic/Meshtastic-device/issues/182)
- Remote attribute access (to change settings of distant nodes). Issue #182
- Be sure to checkout [MQTT Settings](https://meshtastic.org/docs/software/settings/mqtt)
- Be sure to checkout [MQTT Settings](/docs/software/settings/mqtt)
## Short term goals
@ -118,7 +117,7 @@ Any gateway-device will contact the MQTT broker.
### Topics
The "mesh/crypt/CHANNELID/NODEID/PORTID" [topic](https://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices/) will be used for messages sent from/to a mesh.
The "mesh/crypt/CHANNELID/NODEID/PORTID" [topic](https://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices) will be used for messages sent from/to a mesh.
Gateway nodes will forward any MeshPacket from a local mesh channel with uplink_enabled. The packet (encapsulated in a ServiceEnvelope) will remain encrypted with the key for the specified channel.
@ -132,7 +131,7 @@ FIXME, discuss possible attacks by griefers and how they can be prevented
#### Service Envelope
The payload published on mesh/... will always be wrapped in a [ServiceEnvelope protobuf](https://meshtastic.org/docs/developers/protobufs/api#serviceenvelope).
The payload published on mesh/... will always be wrapped in a [ServiceEnvelope protobuf](/docs/developers/protobufs/api#serviceenvelope).
ServiceEnvelope will include the message, and full information about arrival time, who forwarded it, source channel, source mesh id, etc...
@ -161,7 +160,7 @@ deduplicate if needed by using the packet ID of each message.
#### Public MQTT broker service
An existing public [MQTT broker](https://mosquitto.org/) will be the default for this service, but clients can use any MQTT broker they choose.
An existing public [MQTT broker](https://mosquitto.org) will be the default for this service, but clients can use any MQTT broker they choose.
FIXME - figure out how to avoid impersonation (because we are initially using a public MQTT server with no special security options). FIXME, include some ideas on this in the ServiceEnvelope documentation.
@ -169,7 +168,7 @@ FIXME - figure out how to avoid impersonation (because we are initially using a
@Geeksville will run a riot.im bridge that talks to the public MQTT broker and sends/receives into the riot.im network.
There is apparently [already](https://github.com/derEisele/tuple) a riot.im [bridge](https://matrix.org/bridges/) for MQTT. That will possibly need to be customized a bit. But by doing this, we should be able to let random riot.im users send/receive messages to/from any meshtastic device. (FIXME ponder security). See this [issue](https://github.com/meshtastic/Meshtastic-Android/issues/2#issuecomment-645660990) with discussion with the dev.
There is apparently [already](https://github.com/derEisele/tuple) a riot.im [bridge](https://matrix.org/bridges) for MQTT. That will possibly need to be customized a bit. But by doing this, we should be able to let random riot.im users send/receive messages to/from any meshtastic device. (FIXME ponder security). See this [issue](https://github.com/meshtastic/Meshtastic-Android/issues/2#issuecomment-645660990) with discussion with the dev.
### Deprecated concepts
@ -282,12 +281,13 @@ mosquitto_pub -h localhost -q 0 -t test/hello -m 'yo!'
```
5. For Meshtastic to be able to access that server, two settings need to be changed in the
`/usr/local/etc/mosquitto/mosquitto.conf` file:
`/usr/local/etc/mosquitto/mosquitto.conf` file:
```
listener 1883 0.0.0.0
allow_anonymous true
```
6. Restart the service:
```

2
docs/software/other/sw-design.md
View file

@ -7,7 +7,7 @@ sidebar_label: Software Design
This is a mini design doc for developing the meshtastic software.
- [Build instructions](build-instructions.md)
- [On device plugin API](/docs/developers/device/plugin-api) - a tutorial on how to write small Plugins which run on the device and can message other nodes.
- [On device module API](/docs/developers/device/module-api) - a tutorial on how to write small modules which run on the device and can message other nodes.
- Our [project board](https://github.com/orgs/meshtastic/projects/1) - shows what things we are currently working on and remaining work items for the current release.
- [Power Management](power.md)
- [Mesh algorithm](/docs/developers/device/mesh-alg)

16
docs/software/overview.md
View file

@ -13,15 +13,15 @@ The following applications are available to support your Meshtastic network:
- [Meshtastic.js](/docs/software/js/getting-started) provides a JavaScript library to interface with devices
- [Meshtastic-python](/docs/software/python/python-installation) provides access from desktop computers including a command line interface
- A [web interface](/docs/software/web/web-app-software) can be accessed over Wifi on ESP32 devices
- Pre-installed device plugins for:
- [Range testing](/docs/software/plugins/range-test-plugin)
- [External notifications](/docs/software/plugins/ext-notif-plugin)
- [Canned messages](/docs/software/plugins/canned-message-plugin)
- [Serial communication](/docs/software/plugins/serial-plugin)
- [Store and forwarding messages](/docs/software/plugins/store-forward-plugin) (in development)
- [Environment measurement](/docs/software/plugins/environment-plugin) (in development)
- Pre-installed device modules for:
- [Range testing](/docs/software/modules/range-test-module)
- [External notifications](/docs/software/modules/ext-notif-module)
- [Canned messages](/docs/software/modules/canned-message-module)
- [Serial communication](/docs/software/modules/serial-module)
- [Store and forwarding messages](/docs/software/modules/store-forward-module) (in development)
- [Environment measurement](/docs/software/modules/environment-module) (in development)
- Community projects include:
- A [plugin](/docs/software/community/community-atak) for the [Android Team Awareness Kit (ATAK)](https://play.google.com/store/apps/details?id=com.atakmap.app.civ)
- A [module](/docs/software/community/community-atak) for the [Android Team Awareness Kit (ATAK)](https://play.google.com/store/apps/details?id=com.atakmap.app.civ)
- [PyGUI](/docs/software/community/community-pygui), a platform agnostic graphical user interface for devices
The devices running Meshtastic have many preferences that can be set, see the [Settings](/docs/settings) pages for more details.

215
docs/software/plugins/environment.md
View file

@ -1,215 +0,0 @@
---
id: environment-plugin
title: Environment measurement
sidebar_label: Environment measurement
---
## About
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, Dallas 1-wire DS18B20, and MCP9808.
The preferred setup is using I2C, so the `environmental_measurement_plugin_sensor_pin` may not be needed.
## Configuration
These are the settings that can be configured.
environmental_measurement_plugin_enabled
Is the plugin enabled?
0 = Disabled (Default)
1 = Enabled
environmental_measurement_plugin_screen_enabled
Show received sensor readings on device screen.
0 = Disabled (Default)
1 = Enabled
environmental_measurement_plugin_read_error_count_threshold
Error count threshold for failed sensor readings.
Default = 0
preferences.environmental_measurement_plugin_update_interval
How often (in seconds) should sensor readings be broadcasted?
Default = 0
environmental_measurement_plugin_recovery_interval
For how long should we wait (in seconds) before trying to read sensors again upon exceeded error threshold?
Default = 0
environmental_measurement_plugin_display_fahrenheit
Should temperature readings be converted to fahrenheit?
0 = Disabled (Default)
1 = Enabled
environmental_measurement_plugin_sensor_type
What sensor is connected?
0 = DHT11 (Default)
1 = Dallas 1-wire DS18B20
2 = DHT12
3 = DHT21
4 = DHT22
5 = BME280
6 = BME680
7 = MCP9808
environmental_measurement_plugin_sensor_pin
Which pin is the sensor connected to?
Default = 0
## Usage Notes
For basic usage, start with:
environmental_measurement_plugin_enabled = 1
environmental_measurement_plugin_screen_enabled = 1
Depending on which pin your sensor is connected to, set it accordingly:
environmental_measurement_plugin_sensor_pin = 13
:::note
The device must be restarted after the settings have been changed for the plugin to take effect.
:::
## Hardware
The sensors can be wired differently, here's one example for sensor DS18B20 https://randomnerdtutorials.com/esp32-ds18b20-temperature-arduino-ide
## Example of T-LoraV1 with DHT22 temperature sensor
Setup of a T-LoraV1 with DHT22 temperature sensor.
[<img src="T-LoraV1 with DHT22" src="/img/hardware/lora_v1_with_DHT22.jpg" style={{zoom:'25%'}} />](/img/hardware/lora_v1_with_DHT22.jpg)
Requirements:
* T-LoraV1 (but any esp32 should work, just be sure to double check which GPIO to use)
* DHT22 sensor
* 10 Kohm resistor (optional, but recommended)
* breadboard (optional)
* two red wires (could be a different color, but 5V is typically red)
* two yellow wires for GPIO (could be a different color)
* one black wire (could be a different color, but GROUND is typically black)
Steps:
* disconnect power/battery
* connect black wire from GROUND to "-" on the DHT22
* connect yellow wire from middle PIN to a row on bread board
* connect red wire from 5V to a row on breadboard
* connect resistor between red and yellow rows
* connect red wire from row with red to "+" on DHT22
* connect yellow wire from yellow row to GPIO on device (ex: GPIO21)
* double check the cabling (if you get it wrong, you can damage the device and/or the DHT22 sensor)
* plug in device
* configure the device:
```
meshtastic --set environmental_measurement_plugin_measurement_enabled true --set environmental_measurement_plugin_screen_enabled true --set environmental_measurement_plugin_update_interval 15 --set environmental_measurement_plugin_display_farenheit true --set environmental_measurement_plugin_sensor_type DHT22 --set environmental_measurement_plugin_sensor_pin 21
```
:::tip
You can change the values above to suit your needs. The commands can be run one at a time or in a group as show above.
:::
* reboot/reset the device (press the RST button or unplug/plug in the device)
* when the device boots it should say "Environment" and it may show the sensor data
* if "no data", then triple check the wiring
* if still "no data", run:
```
meshtastic --info
```
and verify the the environmental_measurement_plugin_sensor_type and environmental_measurement_plugin_sensor_pin
## Example of T-LoraV1 with Dallas DS18B20 temperature sensor
Setup of a T-LoraV1 with DS18B20 temperature sensor.
[<img src="T-LoraV1 with DS18B20" src="/img/hardware/lora_v1_with_DS18B20.jpg" style={{zoom:'25%'}} />](/img/hardware/lora_v1_with_DS18B20.jpg)
Requirements:
* T-LoraV1 (but any esp32 should work, just be sure to double check which GPIO to use)
* DS18B20 sensor
* 10 Kohm resistor (optional, but recommended)
* breadboard (optional)
* two red wires (could be a different color, but 5V is typically red)
* two yellow wires for GPIO (could be a different color)
* one black wire (could be a different color, but GROUND is typically black)
Steps:
* disconnect power/battery
* connect black wire from GROUND to "-" on the DS18B20
* connect yellow wire from DAT pin to a row on bread board
* connect red wire from 5V to a row on breadboard
* connect resistor between red and yellow rows
* connect red wire from row with red to "VCC" on DS18B20
* connect yellow wire from yellow row to GPIO on device (ex: GPIO21)
* double check the cabling (if you get it wrong, you can damage the device and/or the sensor)
* plug in device
* configure the device:
```
meshtastic --set environmental_measurement_plugin_measurement_enabled true --set environmental_measurement_plugin_screen_enabled true --set environmental_measurement_plugin_update_interval 15 --set environmental_measurement_plugin_display_farenheit true --set environmental_measurement_plugin_sensor_type DS18B20 --set environmental_measurement_plugin_sensor_pin 21
```
:::tip
You can change the values above to suit your needs. The commands can be run one at a time or in a group as show above.
:::
* reboot/reset the device (press the RST button or unplug/plug in the device)
* when the device boots it should say "Environment" and it may show the sensor data
* if "no data", then triple check the wiring
* if still "no data", run:
```
meshtastic --info
```
and verify the the environmental_measurement_plugin_sensor_type and environmental_measurement_plugin_sensor_pin
## Example of RAK 4631 with Environment Sensor
Setup of a RAK 4631 with Environment Sensor
[<img src="RAK4631_with_EnvSensor" src="/img/hardware/rak/RAK4631_with_EnvSensor.jpg" style={{zoom:'25%'}} />](/img/hardware/rak/RAK4631_with_EnvSensor.jpg)
Requirements:
* RAK4631
* Environment Sensor
Steps:
* configure the device:
```
meshtastic --set environmental_measurement_plugin_measurement_enabled true --set environmental_measurement_plugin_screen_enabled true --set environmental_measurement_plugin_update_interval 15 --set environmental_measurement_plugin_display_farenheit true --set environmental_measurement_plugin_sensor_type 6
```
:::tip
You can change the values above to suit your needs. The commands can be run one at a time or in a group as show above.
:::
* reboot/reset the device (press the button or unplug/plug in the device)
* when the device boots it should say "Environment" and it may show the sensor data
* if still "no data", run:
```
meshtastic --info
```
and verify the the environmental_measurement_plugin_sensor_type
## Known Problems
* No default configuration values are currently set, so this must be done when enabling the plugin.

40
docs/software/plugins/serial.md
View file

@ -1,40 +0,0 @@
---
id: serial-plugin
title: Serial communication plugin
sidebar_label: Serial communication
---
## About
This is a simple interface to send messages over the mesh network by sending strings over a serial port.
Default is to use RX GPIO 16 and TX GPIO 17.
## Basic Usage:
1. Enable the plugin by setting `serialplugin_enabled` to `1`.
2. Set the pins (`serialplugin_rxd` / `serialplugin_rxd`) for your preferred RX and TX GPIO pins. On tbeam boards it is recommended to use:
* RXD 35
* TXD 15
3. Set `serialplugin_timeout` to the amount of time to wait before we consider your packet as "done".
4. (Optional) In SerialPlugin.h set the port to `PortNum_TEXT_MESSAGE_APP`if you want to send messages to/from the general text message channel.
5. Connect to your device over the serial interface at `38400 8N1`.
6. Send a packet up to 240 bytes in length. This will get relayed over the mesh network.
7. (Optional) Set `serialplugin_echo` to `1` and any message you send out will be echoed back to your device.
:::note
The device must be restarted after the settings have been changed for the plugin to take effect.
:::
## TODO (in this order):
* Define a verbose RX mode to report on mesh and packet information.
:::note
This won't happen any time soon.
:::
## Known Problems
* Until the plugin is initialized by the startup sequence, the TX pin is in a floating state. Device connected to that pin may see this as "noise".
* Will not work on NRF and the Linux device targets.

214
docs/software/plugins/store-forward.md
View file

@ -1,214 +0,0 @@
---
id: store-forward-plugin
title: Store and Forward plugin
sidebar_label: Store and Forward
---
## About
:::caution
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.
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).
### About - How it works
![Store & Forward - Overview](/img/plugins/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)
## 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.
### 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).
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
meshtastic --setchan spread_factor 11 --setchan coding_rate 4 --setchan bandwidth 500
```
With an aftermarket coaxial antenna or moxon antenna, that will give you roughly the same range as "Long Range / Slow" and 5x the bitrate.
### Router setup
* Configure your device as a meshtastic router.
* * https://meshtastic.org/docs/software/settings/router
* Configure the Store and Forward plugin
* * Required configuration
* * * store_forward_plugin_enabled - Set this to true to enable the plugin. False to disable the plugin.
* * Optional configuration
* * * 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.
* Name your router node something that makes it easily identifiable, aka "Router".
Don't enable the Store and Forward plugin on multiple routers!
### Client Usage
Currently, no special configuration is required. To request your history sent to you, send the command into the message field "SF". That's it. This will eventually change to make it easier. At the moment, that message will be sent to everyone on the mesh but we'll (eventually) make it easier to use where there'll be a button (or maybe it'll be transparent) and the command isn't sent as a text message to the mesh.
Available Commands:
| Command | Definition |
| :-----: | :---------------: |
| SF | Send the last 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.
## Settings
| Setting | Acceptable Values | Default |
| :-----: | :---------------: | :-----: |
| store_forward_plugin_enabled | `true`, `false` | `false` |
| store_forward_plugin_records | integer | `0` |
| store_forward_plugin_replay_max_records (tbd) | integer | `0` |
| store_forward_plugin_replay_max_time (tbd) | integer | `0` |
## Example Request/Response
### Request History (Use Router Defaults)
Story: Carol has been away from the mesh with device turned off. She would like to get a replay of what she has missed. The router will return the messages.
* Carol
* * Packet (Port: STORE_FORWARD_APP)
* * * To: Broadcast (Optionally, direct to router)
* * * StoreAndForward.rr.CLIENT_HISTORY
* Router
* * Packet (Port: STORE_FORWARD_APP)
* * * To: Carol
* * * StoreAndForward.rr.ROUTER_HISTORY
* * * StoreAndForward.history.HistoryMessages = 42 // Router has 42 messages that will be sent to Carol.
* * * StoreAndForward.history.Window = 120 // Router searched for messages over the last two hours.
* * * StoreAndForward.history.LastRequest = 0 // Carol has never asked for the history.
* * Packet (Port: TEXT_MESSAGE_APP)
* * * ... a series of 42 text messages
### Request History (No history available)
Story: Carol has been away from the mesh with device turned off. She would like to get a replay of what she has missed but the router indicates there are no messages available.
* Carol
* * Packet (Port: STORE_FORWARD_APP)
* * * To: Broadcast (Optionally, direct to router)
* * * StoreAndForward.rr.CLIENT_HISTORY
* Router
* * Packet (Port: STORE_FORWARD_APP)
* * * To: Carol
* * * StoreAndForward.rr.ROUTER_HISTORY
* * * StoreAndForward.history.HistoryMessages = 0 // Router has no messages to be sent to Carol.
* * * StoreAndForward.history.Window = 120 // Router searched for messages over the last two hours.
* * * StoreAndForward.history.LastRequest = (timestamp) // Last time carol requested the history.
### Store & Forward Router Heartbeat
Story: 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. Client will not respond to network but (optionally) indicate to the user that a S&F router is available or not available.
* Router
* * Packet (Port: STORE_FORWARD_APP)
* * * To: Broadcast
* * * StoreAndForward.rr.ROUTER_HEARTBEAT
* * * StoreAndForward.heartbeat.Period = 120 // Expect a heartbeat every 2 minutes.
* * * StoreAndForward.heartbeat.Secondary = false // If true, this is a secondary "backup" S&F node. Will be (eventually) used for router election in the event there are multiple S&F Routers.
## Meshpacket
To support functionality of Store and Forward, a new enum has been added to the MeshPacket.
```
typedef enum _MeshPacket_Delayed {
MeshPacket_Delayed_NO_DELAY = 0,
MeshPacket_Delayed_DELAYED_BROADCAST = 1,
MeshPacket_Delayed_DELAYED_DIRECT = 2
} MeshPacket_Delayed;
```
* NO_DELAY - The packet was sent in real time. Store and Forward had no hand in this message. This is the default case.
* DELAYED_BROADCAST - This is a delayed message. The 'to' of the packet has been directed at a named user but was previously a broadcast packet.
* DELAYED_DIRECT - This is a delayed message. The 'to' of the packet has been directed at a named user but was previously a direct packet.
As a reminder, broadcast messages are messages where the "to" of a payload is directed at NODENUM_BROADCAST or (0xFFFFFFFF).
Example Cases:
* Real time :: BROADCAST
* * Delayed = MeshPacket_Delayed_NO_DELAY
* * From: Ann
* * To: BROADCAST
* Real time :: Direct
* * Delayed = MeshPacket_Delayed_NO_DELAY
* * From: Ann
* * To: Bob
* Delayed :: BROADCAST
* * Delayed = MeshPacket_Delayed_DELAYED_BROADCAST
* * From: Ann
* * To: Bob
* Delayed :: Direct
* * Delayed = MeshPacket_Delayed_DELAYED_DIRECT
* * From: Ann
* * To: Bob
When a message is 'real time', time a message is sent is the same as the time the message was received. In the case the message is delayed, there is no timestamp available for the message.
Where the message is a delayed broadcast, the "To" is *not* a broadcast address but rather the address of the device that requested the messages to be replayed. This is to allow the message to be routed over the mesh network and not displayed in the message screen of other devices.
## Developer TODO
Not necessarily in this order:
* Client Interface (Web, Android, Python or iOS when that happens) to request packets be resent.
* Router sends a heartbeat so the client knows there is a router in range.
* Support for a mesh to have multiple routers that have the store & forward functionality (for redundancy).
* Add a default channel at about 1.5kbit / sec.
* Eventually we could add a "want_store_and_forward" bit to MeshPacket and that could be nicer than whitelists in this plugin. Initially we'd only set that bit in text messages (and any other plugin messages that can cope with this). This change would be backward wire compatible so can add easily later.
* Have a "cool down" period to disallow a client to request the history too often.
* Message with SF status on requests.
* Be able to identify if you're within range of a router.
* Be able to specify the HOP MAX to reduce airtime. Is this necessary?
* Restrict operation of S&F on the slow channel configurations.
* Create a TX queue to prevent the history from being modified in flight.
* Only allow n-number of requests to the router at any one time.
* Set number of max messages from the history.
* Calculate a new channel with 250kHz bandwidth and ~1.5kbit.
*** Done
* Disable ACK. If the router is within range, so is the requester.
* Currently the way we allocate messages in the device code is super inefficient. It always allocates the worst case message size. Really we should dynamically allocate just the # of bytes we need. This would allow many more MeshPackets to be kept in RAM.
* Allow max history to be defined by radioConfig.preferences.store_forward_plugin_records.
* Add a starting to send / finished sending message.

261
docs/software/python/installation.md
View file

@ -3,6 +3,7 @@ id: python-installation
title: Meshtastic-python installation
sidebar_label: Installation
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -10,11 +11,11 @@ This library provides a command line interface (CLI) for Meshtastic nodes and pr
The [Meshtastic-python repo](https://github.com/meshtastic/Meshtastic-python) and [API documentation](https://python.meshtastic.org) are excellent sources of information.
If you wish to view the code or contribute to development of the python library or the command line interface, please visit the Meshtastic python <a href="https://github.com/meshtastic/Meshtastic-python">GitHub page</a>.
If you wish to view the code or contribute to development of the python library or the command line interface, please visit the Meshtastic python [GitHub page](https://github.com/meshtastic/Meshtastic-python).
There are standalone executables for Mac, Windows and Ubuntu if you do not want to install python and/or the python libraries required to run the mestastic CLI tool. See [Standalone](https://meshtastic.org/docs/software/python/python-standalone) for more information.
There are standalone executables for Mac, Windows and Ubuntu if you do not want to install python and/or the python libraries required to run the mestastic CLI tool. See [Standalone](/docs/software/python/python-standalone) for more information.
Installation can also be easily done through the [Python package installer pip](https://pypi.org/project/meshtastic/):
Installation can also be easily done through the [Python package installer pip](https://pypi.org/project/meshtastic):
:::note
You must use pip version 20 or later. To upgrade to the latest pip, do: `pip install --upgrade pip`
:::
@ -28,163 +29,167 @@ Some newer boards may require the drivers for the [CH9102](http://www.wch.cn/dow
:::
<Tabs
groupId="operating-system"
defaultValue="linux"
values={[
{label: 'Linux', value: 'linux'},
{label: 'macOS', value: 'macos'},
{label: 'Windows', value: 'windows'},
{label: 'Termux for Android', value: 'termux'},
]}>
groupId="operating-system"
defaultValue="linux"
values={[
{label: 'Linux', value: 'linux'},
{label: 'macOS', value: 'macos'},
{label: 'Windows', value: 'windows'},
{label: 'Termux for Android', value: 'termux'},
]}>
<TabItem value="linux">
* Check that your computer has the required serial drivers installed
* Connect your Meshtastic device to your USB port
* Use the command
```bash
lsusb
```
* You should see something like:
* `ID 10c4:ea60 Silicon Labs CP210x UART Bridge` for CP210X
* `ID 1a86:55d4 QinHeng Electronics USB Single Serial` for CH9102
- Check that your computer has the required serial drivers installed
* Check that your computer has Python 3 installed.
* Use the command
```bash
python3 -V
```
* If this does not return a version, install python
```bash
sudo apt-get update
sudo apt-get install python3
```
* Pip is typically installed if you are using python 3 version >= 3.4
* Check that pip is installed using this command
```bash
pip3 -V
```
* If this does not return a version, install pip
```bash
sudo apt-get install python3-pip
```
* Optional: use a python virtual environment (otherwise jump to step "Install pytap2")
* Install python-virtualenvwrapper (arch based distros as an example)
```bash
sudo pacman -Syu python-virtualenvwrapper
```
* Create a virtual environment
```bash
source /usr/bin/virtualenvwrapper.sh
mkvirtualenv meshtastic
workon meshtastic
```
* Install pytap2
- Connect your Meshtastic device to your USB port
- Use the command
```bash
pip3 install --upgrade pytap2
lsusb
```
* Install meshtastic:
- You should see something like:
- `ID 10c4:ea60 Silicon Labs CP210x UART Bridge` for CP210X
- `ID 1a86:55d4 QinHeng Electronics USB Single Serial` for CH9102
- Check that your computer has Python 3 installed.
- Use the command
```bash
pip3 install --upgrade meshtastic
python3 -V
```
- If this does not return a version, install python
```bash
sudo apt-get update
sudo apt-get install python3
```
- Pip is typically installed if you are using python 3 version >= 3.4
- Check that pip is installed using this command
```bash
pip3 -V
```
- If this does not return a version, install pip
```bash
sudo apt-get install python3-pip
```
- Optional: use a python virtual environment (otherwise jump to step "Install pytap2")
- Install python-virtualenvwrapper (arch based distros as an example)
```bash
sudo pacman -Syu python-virtualenvwrapper
```
- Create a virtual environment
```bash
source /usr/bin/virtualenvwrapper.sh
mkvirtualenv meshtastic
workon meshtastic
```
- Install pytap2
```bash
pip3 install --upgrade pytap2
```
- Install meshtastic:
```bash
pip3 install --upgrade meshtastic
```
</TabItem>
<TabItem value="macos">
* Check that your computer has the required serial drivers installed
* Connect your Meshtastic device to your USB port
* Navigate to `Apple Menu  > About This Mac > System Report... > Hardware > USB`
* You should see something like `CP210X USB to UART Bridge Controller`
* If not download the drivers from [Silicon Labs](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers).
* Check that your computer has Python 3 installed.
* Use the command
```bash
python3 -V
```
* If this does not return a version, install [python](https://www.python.org)
* The following uses Homebrew to install `python3` which includes `pip3`.
* Check if you have Homebrew installed with the following command
```bash
brew -v
```
If it's not installed, follow the instructions on the [Homebrew website](https://brew.sh) before continuing.
* Install Python3
```bash
brew install python3
```
* Pip is typically installed if you are using python 3 version >= 3.4
* Check that pip is installed using this command
```bash
pip3 -V
```
* If this does not return a version, install [pip](https://pip.pypa.io/en/stable/installing/)
- Check that your computer has the required serial drivers installed
- Connect your Meshtastic device to your USB port
- Navigate to `Apple Menu  > About This Mac > System Report... > Hardware > USB`
- You should see something like `CP210X USB to UART Bridge Controller`
- If not download the drivers from [Silicon Labs](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers).
- Check that your computer has Python 3 installed.
- Use the command
```bash
python3 -V
```
- If this does not return a version, install [python](https://www.python.org)
- The following uses Homebrew to install `python3` which includes `pip3`.
- Check if you have Homebrew installed with the following command
```bash
brew -v
```
If it's not installed, follow the instructions on the [Homebrew website](https://brew.sh) before continuing.
- Install Python3
```bash
brew install python3
```
- Pip is typically installed if you are using python 3 version >= 3.4
* Install pytap2
- Check that pip is installed using this command
```bash
sudo pip3 install --upgrade pytap2
```
* Install meshtastic:
```bash
sudo pip3 install --upgrade meshtastic
pip3 -V
```
- If this does not return a version, install [pip](https://pip.pypa.io/en/stable/installing)
- Install pytap2
```bash
sudo pip3 install --upgrade pytap2
```
- Install meshtastic:
```bash
sudo pip3 install --upgrade meshtastic
```
</TabItem>
<TabItem value="windows">
* Check that your computer has the required serial drivers installed
* Connect your Meshtastic device to your USB port
* Open Device Manager
* Under `Ports (COM & LPT)` you should see something like `Silicon Labs CP210X USB to UART Bridge (COM5)`
* If not download the drivers from [Silicon Labs](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers) or use the direct link below.
- Check that your computer has the required serial drivers installed
- Connect your Meshtastic device to your USB port
- Open Device Manager
- Under `Ports (COM & LPT)` you should see something like `Silicon Labs CP210X USB to UART Bridge (COM5)`
- If not download the drivers from [Silicon Labs](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers) or use the direct link below.
:::warning
You must install the [CP210x Universal Windows Driver](https://www.silabs.com/documents/public/software/CP210x_Universal_Windows_Driver.zip). If you do not install this driver, your device may not work and the driver may need to be uninstalled from device manager before installing the correct driver.
:::
* Check that your computer has Python 3 installed.
* Use the command
```powershell
py -V
```
* If this does not return a version, install [python](https://www.python.org)
* Pip is typically installed if you are using python 3 version >= 3.4
* Check that pip is installed using this command
```powershell
pip3 -V
```
* If this does not return a version, install [pip](https://pip.pypa.io/en/stable/installing/)
* Install pytap2
- Check that your computer has Python 3 installed.
- Use the command
```powershell
pip3 install --upgrade pytap2
py -V
```
* Install meshtastic:
- If this does not return a version, install [python](https://www.python.org)
- Pip is typically installed if you are using python 3 version >= 3.4
- Check that pip is installed using this command
```powershell
pip3 install --upgrade meshtastic
pip3 -V
```
- If this does not return a version, install [pip](https://pip.pypa.io/en/stable/installing)
- Install pytap2
```powershell
pip3 install --upgrade pytap2
```
- Install meshtastic:
```powershell
pip3 install --upgrade meshtastic
```
</TabItem>
<TabItem value="termux">
:::note
Wifi connection is currently under development and may not be working properly just yet. If you would like to provide feedback or test this feature, please visit our [forum](https://meshtastic.discourse.group/) or join our [Discord server](https://discord.gg/RjQKWHmzPZ) for more information.
Wifi connection is currently under development and may not be working properly just yet. If you would like to provide feedback or test this feature, please visit our [forum](https://meshtastic.discourse.group) or join our [Discord server](https://discord.gg/RjQKWHmzPZ) for more information.
:::
* Install [Termux](https://f-droid.org/en/packages/com.termux/) from the F-Droid app store (Google play does not currently support the latest builds)
* Load Termux and update the package list
```
pkg update
```
* Upgrade the installed packages
```
pkg upgrade
```
* Install python
```
pkg install python
```
* Upgrade pip and installed meshtastic and some of its dependencies
```
pip install --upgrade pip pygatt pytap2 wheel mesthtastic
```
- Install [Termux](https://f-droid.org/en/packages/com.termux) from the F-Droid app store (Google play does not currently support the latest builds)
- Load Termux and update the package list
```
pkg update
```
- Upgrade the installed packages
```
pkg upgrade
```
- Install python
```
pkg install python
```
- Upgrade pip and installed meshtastic and some of its dependencies
```
pip install --upgrade pip pygatt pytap2 wheel mesthtastic
```
:::note
Be aware that the Meshtastic CLI is not able to control the nodes over USB through termux, but you can control devices over Wifi using the `--host x.x.x.x` option with the device IP address. However, only ESP32 devices can use Wifi currently.

2
docs/software/python/uses.md
View file

@ -7,7 +7,7 @@ sidebar_label: Uses
This section covers using the "meshtastic" command line executable, which displays packets sent over the network as JSON and lets you see serial debugging information from the Meshtastic devices.
:::note
The `meshtastic` command is not run within python but is a script run from your operating system shell prompt. When you type "meshtastic" and the prompt is unable to find the command in Windows, check that the python "scripts" directory [is in your path](https://datatofish.com/add-python-to-windows-path/).
The `meshtastic` command is not run within python but is a script run from your operating system shell prompt. When you type "meshtastic" and the prompt is unable to find the command in Windows, check that the python "scripts" directory [is in your path](https://datatofish.com/add-python-to-windows-path).
:::
## Getting a list of User Preferences

12
docs/software/web/overview.md
View file

@ -6,7 +6,7 @@ sidebar_label: Overview
<!--- FIXME add self hosting details link --->
Meshtastic Web is a [Progressive Web App](https://web.dev/progressive-web-apps/) that runs directly in your browser.
Meshtastic Web is a [Progressive Web App](https://web.dev/progressive-web-apps) that runs directly in your browser.
There are three ways of accessing the app:
1. Served directly from an ESP32 based node via [meshtastic.local](http://meshtastic.local) or the device's IP Address.
@ -15,7 +15,7 @@ There are three ways of accessing the app:
## Compatibility
The application will work in all major browsers, but specific functionality is limited in some cases, for the best experience we reccomend using [Google Chrome](https://www.google.com/chrome/)
The application will work in all major browsers, but specific functionality is limited in some cases, for the best experience we reccomend using [Google Chrome](https://www.google.com/chrome)
### HTTP
@ -34,15 +34,13 @@ You have two primary options for accessing your device over HTTP, those being [C
### Bluetooth
Bluetooth support is governed by the availability of the [Web Bluetooth API](https://web.dev/bluetooth/) as illustrated blow, support is primarily available in Chromium browsers
Bluetooth support is governed by the availability of the [Web Bluetooth API](https://web.dev/bluetooth) as illustrated blow, support is primarily available in Chromium browsers
![Web Bluetooth compatability matrix](https://caniuse.bitsofco.de/image/web-bluetooth.png)
### Serial (USB)
The method with the least platform support, uses the [Web Serial API](https://web.dev/serial/) allows us to connect directly to a Meshtastic node over USB, accessing it directly within your browser.
The method with the least platform support, uses the [Web Serial API](https://web.dev/serial) allows us to connect directly to a Meshtastic node over USB, accessing it directly within your browser.
![Web Serial compatability matrix](https://caniuse.bitsofco.de/image/web-serial.png)
@ -50,8 +48,6 @@ The method with the least platform support, uses the [Web Serial API](https://we
The web interface is now included in firmware releases. There is active development ongoing to fix some issues with updating the web interface from the web interface directly. Please be patient with us as we work on this. Use [Meshtastic-flasher](/docs/getting-started/meshtastic-flasher) to update your device to the current stable build which includes the web interface.
:::warning
Old documentation below.

12
docs/software/web/partitions.md
View file

@ -3,6 +3,7 @@ id: web-partitions-software
title: Managing ESP32 partitions
sidebar_label: ESP32 partitions
---
:::caution
It has been reported that some of this information is out of date. Flashing the device with [Meshtastic-flasher](/docs/getting-started/meshtastic-flasher) should fix these partition issues and update you to the current web interface.
@ -28,15 +29,19 @@ The most reliable way to fix this problem is to use the install script that is i
https://meshtastic.discourse.group/t/solved-help-installing-with-other-than-esphome-flasher/2214/9
### Using Pio in Windows
```powershell
pio run --target erase --environment tbeam
```
Then re-install the firmware ie using ESPHome Flasher.
Requires: [Python](https://www.python.org/), [Pio](https://pypi.org/project/pio/), command to be run in the root directory of the meshtastic-device project once you’ve cloned it (this last requirement is an assumption based on pio not knowing what a tbeam is, may also require Visual Studio Code and PlatformIO as these were installed during use).
Requires: [Python](https://www.python.org), [Pio](https://pypi.org/project/pio), command to be run in the root directory of the meshtastic-device project once you’ve cloned it (this last requirement is an assumption based on pio not knowing what a tbeam is, may also require Visual Studio Code and PlatformIO as these were installed during use).
### Esptool.py
@1984 posted another method using the python based esptool.py to erase and re-flash the firmware:
```bash
esptool.py --baud 921600 erase_flash
esptool.py --baud 921600 write_flash 0x1000 system-info.bin
@ -44,16 +49,17 @@ esptool.py --baud 921600 write_flash 0x00390000 spiffs-*.bin
esptool.py --baud 921600 write_flash 0x10000 firmware-tbeam-EU865-1.1.42.bin
```
Requires: [Python](https://www.python.org/) and [esptool.py](https://github.com/espressif/esptool)
Requires: [Python](https://www.python.org) and [esptool.py](https://github.com/espressif/esptool)
### Visual Studio & PlatformIO
There is also the method of using the Visual Studio IDE. This requires having Visual Studio and PlatformIO installed, along with having cloned the meshtastic-device code as per the [build instructions](/docs/software/other/build-instructions). After loading the project in Visual Studio, select the PlatformIO alien icon, then find the appropriate device, and then click the Erase Flash command.
![Erasing the flash using PlatformIO in Visual Studio Code](/img/platformio-erase.png)
https://meshtastic.discourse.group/t/configuring-channel-via-python-api/1948/17
Requires: [Visual Studio Code](https://code.visualstudio.com/), [PlatformIO](https://platformio.org/), cloned copy of the Meshtastic-device project
Requires: [Visual Studio Code](https://code.visualstudio.com), [PlatformIO](https://platformio.org), cloned copy of the Meshtastic-device project
## How do I know it's worked?

107
sidebars.js
View file

@ -3,7 +3,7 @@ module.exports = {
"About Meshtastic": [
"about/overview",
{
"Concepts": [
Concepts: [
"about/concepts/overview",
"about/concepts/channels",
"about/concepts/clients",
@ -14,13 +14,13 @@ module.exports = {
},
"about/expectations",
{
"FAQs": [
FAQs: [
"faq/faq",
"faq/antenna",
"faq/bluetooth",
"faq/channel",
{
"Clients": [
Clients: [
"faq/client-android",
"faq/client-python-cli",
"faq/client-ios",
@ -30,10 +30,10 @@ module.exports = {
"faq/device",
"faq/mesh",
"faq/mqtt",
"faq/plugins",
"faq/modules",
"faq/wifi",
],
}
},
],
},
Software: {
@ -88,14 +88,14 @@ module.exports = {
],
},
{
Plugins: [
"software/plugins/plugins",
"software/plugins/range-test-plugin",
"software/plugins/ext-notif-plugin",
"software/plugins/canned-message-plugin",
"software/plugins/serial-plugin",
"software/plugins/store-forward-plugin",
"software/plugins/environment-plugin",
Modules: [
"software/modules/modules",
"software/modules/range-test-module",
"software/modules/ext-notif-module",
"software/modules/canned-message-module",
"software/modules/serial-module",
"software/modules/store-forward-module",
"software/modules/environment-module",
],
},
{
@ -130,12 +130,12 @@ module.exports = {
},
],
"Additional Documentation": [
{type: "ref", id: "getting-started/overview"},
{type: "ref", id: "settings/overview"},
{type: "ref", id: "hardware/overview"},
{type: "ref", id: "developers/overview"},
{type: "ref", id: "developers/maintaining-documentation/overview"},
{type: "ref", id: "legal/overview"},
{ type: "ref", id: "getting-started/overview" },
{ type: "ref", id: "settings/overview" },
{ type: "ref", id: "hardware/overview" },
{ type: "ref", id: "developers/overview" },
{ type: "ref", id: "developers/maintaining-documentation/overview" },
{ type: "ref", id: "legal/overview" },
],
},
Configuration: {
@ -154,9 +154,7 @@ module.exports = {
],
},
{
"Connect to Device": [
"getting-started/clients",
],
"Connect to Device": ["getting-started/clients"],
},
"getting-started/first-steps",
],
@ -171,27 +169,24 @@ module.exports = {
"settings/router",
"settings/wifi",
{
Plugins: [
"settings/canned-message-plugin",
"settings/environmental-measurement-plugin",
"settings/external-notification-plugin",
"settings/range-test-plugin",
"settings/rotary-encoder-plugin",
"settings/serial-plugin",
"settings/store-and-forward-plugin",
],
Advanced: [
"settings/channel-advanced",
"settings/misc",
Modules: [
"settings/canned-message-module",
"settings/environmental-measurement-module",
"settings/external-notification-module",
"settings/range-test-module",
"settings/rotary-encoder-module",
"settings/serial-module",
"settings/store-and-forward-module",
],
Advanced: ["settings/channel-advanced", "settings/misc"],
},
],
"Additional Documentation": [
{type: "ref", id: "hardware/overview"},
{type: "ref", id: "software/overview"},
{type: "ref", id: "developers/overview"},
{type: "ref", id: "developers/maintaining-documentation/overview"},
{type: "ref", id: "legal/overview"},
{ type: "ref", id: "hardware/overview" },
{ type: "ref", id: "software/overview" },
{ type: "ref", id: "developers/overview" },
{ type: "ref", id: "developers/maintaining-documentation/overview" },
{ type: "ref", id: "legal/overview" },
],
},
Hardware: {
@ -220,12 +215,12 @@ module.exports = {
},
],
"Additional Documentation": [
{type: "ref", id: "getting-started/overview"},
{type: "ref", id: "settings/overview"},
{type: "ref", id: "software/overview"},
{type: "ref", id: "developers/overview"},
{type: "ref", id: "developers/maintaining-documentation/overview"},
{type: "ref", id: "legal/overview"},
{ type: "ref", id: "getting-started/overview" },
{ type: "ref", id: "settings/overview" },
{ type: "ref", id: "software/overview" },
{ type: "ref", id: "developers/overview" },
{ type: "ref", id: "developers/maintaining-documentation/overview" },
{ type: "ref", id: "legal/overview" },
],
},
Contribute: {
@ -244,7 +239,7 @@ module.exports = {
"developers/device/mesh-alg",
"developers/device/encryption",
"developers/device/portnum",
"developers/device/plugin-api",
"developers/device/module-api",
"developers/device/http-api",
"developers/device/documents",
],
@ -277,11 +272,11 @@ module.exports = {
},
],
"Additional Documentation": [
{type: "ref", id: "getting-started/overview"},
{type: "ref", id: "settings/overview"},
{type: "ref", id: "hardware/overview"},
{type: "ref", id: "software/overview"},
{type: "ref", id: "legal/overview"},
{ type: "ref", id: "getting-started/overview" },
{ type: "ref", id: "settings/overview" },
{ type: "ref", id: "hardware/overview" },
{ type: "ref", id: "software/overview" },
{ type: "ref", id: "legal/overview" },
],
},
Legal: {
@ -292,11 +287,11 @@ module.exports = {
"legal/privacy",
],
"Additional Documentation": [
{type: "ref", id: "getting-started/overview"},
{type: "ref", id: "settings/overview"},
{type: "ref", id: "hardware/overview"},
{type: "ref", id: "software/overview"},
{type: "ref", id: "developers/overview"},
{ type: "ref", id: "getting-started/overview" },
{ type: "ref", id: "settings/overview" },
{ type: "ref", id: "hardware/overview" },
{ type: "ref", id: "software/overview" },
{ type: "ref", id: "developers/overview" },
],
},
};

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

@ -7,12 +7,12 @@ import Layout from '@theme/Layout';
import { Release } from '../../utils/github';
import { fetcher } from '../../utils/swr';
import { DownloadCard } from './_components/DownloadCard';
import {
FirmwareCard,
PlaceholderFirmwareCard,
} from './_components/FirmwareCard';
import { HeaderText } from './_components/HeaderText'
import { DownloadCard } from './_components/DownloadCard'
import { HeaderText } from './_components/HeaderText';
const Firmware = (): JSX.Element => {
const { data, error } = useSWR<Release[]>(
@ -30,10 +30,7 @@ const Firmware = (): JSX.Element => {
>
<main className="margin-vert--xl">
<div className="container">
<HeaderText
type="h1"
text="Downloads"
/>
<HeaderText type="h1" text="Downloads" />
</div>
<div className="container">
<HeaderText
@ -46,7 +43,13 @@ const Firmware = (): JSX.Element => {
buttonText="Download Meshtastic Flasher"
url="https://github.com/meshtastic/Meshtastic-gui-installer/releases/latest"
notes={[
"To download using ", <code>pip</code>, " follow ",<a href="https://meshtastic.org/docs/getting-started/meshtastic-flasher#install-using-pip">these instructions</a>,"."
"To download using ",
<code>pip</code>,
" follow ",
<a href="/docs/getting-started/meshtastic-flasher#install-using-pip">
these instructions
</a>,
".",
]}
/>
</div>
@ -69,7 +72,17 @@ const Firmware = (): JSX.Element => {
client="Android"
imgUrl="https://play.google.com/intl/en_us/badges/static/images/badges/en_badge_web_generic.png"
url="https://play.google.com/store/apps/details?id=com.geeksville.mesh&referrer=utm_source=downloads-page"
notes={["To sideload, ",<a href="https://github.com/meshtastic/Meshtastic-Android/releases/latest" rel="noreferrer" target="_blank">download the latest .apk</a>," from Github", ]}
notes={[
"To sideload, ",
<a
href="https://github.com/meshtastic/Meshtastic-Android/releases/latest"
rel="noreferrer"
target="_blank"
>
download the latest .apk
</a>,
" from Github",
]}
/>
<DownloadCard
client="iOS"
@ -134,10 +147,36 @@ const Firmware = (): JSX.Element => {
</>
)}
</ul>
Once downloaded, follow the flashing instructions for <a href="https://meshtastic.org/docs/getting-started/flashing-esp32" rel="noreferrer" target="_blank">ESP32 chipsets</a>, <a href="https://meshtastic.org/docs/getting-started/flashing-nrf52" rel="noreferrer" target="_blank">NRF52 chipsets</a>, or the <a href="https://meshtastic.org/docs/getting-started/meshtastic-flasher" rel="noreferrer" target="_blank">GUI instructions for Meshtastic Flasher</a>.
Once downloaded, follow the flashing instructions for{" "}
<a
href="/docs/getting-started/flashing-esp32"
rel="noreferrer"
target="_blank"
>
ESP32 chipsets
</a>
,{" "}
<a
href="/docs/getting-started/flashing-nrf52"
rel="noreferrer"
target="_blank"
>
NRF52 chipsets
</a>
, or the{" "}
<a
href="/docs/getting-started/meshtastic-flasher"
rel="noreferrer"
target="_blank"
>
GUI instructions for Meshtastic Flasher
</a>
.
</div>
<div className="container">
<i>Google Play and the Google Play logo are trademarks of Google LLC.</i>
<i>
Google Play and the Google Play logo are trademarks of Google LLC.
</i>
</div>
</main>
</Layout>

0
static/img/plugins/store_and_forward/store_and_forward-overview.png → static/img/modules/store_and_forward/store_and_forward-overview.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 43 KiB

After

Width:  |  Height:  |  Size: 43 KiB