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

Merge pull request #171 from linagee/master

Browse source 
Fixed typos and links
This commit is contained in:
Jm Casler 2022-01-05 13:34:41 -08:00 committed by GitHub
parent 4caded9d47 273732d96e
commit 69e58c3731
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
44 changed files with 197 additions and 196 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -36,7 +36,7 @@ Meshtastic® is a project that lets you use inexpensive LoRa radios as a long ra
The radios automatically create a mesh to forward packets as needed, so everyone in the group can receive messages from even the furthest member. The radios will optionally work with your phone, but no phone is required.
Meshtastic uses LoRa for the long range communications and depending on settings used the maximum theoretical group size ranges from 30-200 device nodes. Currently each device can only support a connection from a single user at a time.
Meshtastic uses LoRa for the long range communications and depending on settings used, the maximum theoretical group size ranges from 30-200 device nodes. Currently each device can only support a connection from a single user at a time.
Please see our [website](https://meshtastic.org) for more information about Meshtastic.

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

@ -9,7 +9,7 @@ sidebar_label: Building Android App
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
* 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:
```
@ -50,4 +50,4 @@ 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

16
docs/developers/device/device-api.md
View file

@ -10,7 +10,7 @@ The Device API is design to have only a simple stream of ToRadio and FromRadio p
## Streaming version
This protocol is **almost** identical when it is deployed over BLE, Serial/USB or TCP (our three currently supported transports for connecting to phone/PC). Most of this document is in terms of the original BLE version, but this section describes the small changes when this API is exposed over a Streaming (non datagram) transport. The streaming version has the following changes:
This protocol is **almost** identical when it is deployed over BLE, Serial/USB, or TCP (our three currently supported transports for connecting to phone/PC). Most of this document is in terms of the original BLE version, but this section describes the small changes when this API is exposed over a Streaming (non datagram) transport. The streaming version has the following changes:
- We assume the stream is reliable (though the protocol will resynchronize if bytes are lost or corrupted). i.e. we do not include CRCs or error correction codes.
- Packets always have a four byte header (described below) prefixed before each packet. This header provides framing characters and length.
@ -28,15 +28,15 @@ The receiver will validate length and if >512 it will assume the packet is corru
## MeshBluetoothService (the BLE API)
This is the main Bluetooth service for the device and provides the API your app should use to get information about the mesh, send packets or provision the radio.
This is the main Bluetooth service for the device and provides the API your app should use to get information about the mesh, send packets, or provision the radio.
For a reference implementation of a client that uses this service see [RadioInterfaceService](https://github.com/meshtastic/Meshtastic-Android/blob/master/app/src/main/java/com/geeksville/mesh/service/RadioInterfaceService.kt).
Typical flow when a phone connects to the device should be the following (if you want to watch this flow from the python app just run "meshtastic --debug --info" - the flow over BLE is identical):
Typical flow when a phone connects to the device should be the following (if you want to watch this flow from the python app just run `meshtastic --debug --info` - the flow over BLE is identical):
- There are only three relevant endpoints (and they have built in BLE documentation - so use a BLE tool of your choice to watch them): FromRadio, FromNum (sends notifies when new data is available in FromRadio) and ToRadio
- SetMTU size to 512
- Write a ToRadio.startConfig protobuf to the "ToRadio" endpoint" - this tells the radio you are a new connection and you need the entire NodeDB sent down.
- Write a ToRadio.startConfig protobuf to the "ToRadio" endpoint - this tells the radio you are a new connection and you need the entire NodeDB sent down.
- Read repeatedly from the "FromRadio" endpoint. Each time you read you will get back a FromRadio protobuf (see Meshtatastic-protobuf). Keep reading from this endpoint until you get back and empty buffer.
- See below for the expected sequence for your initial download.
- After the initial download, you should subscribe for BLE "notify" on the "FromNum" endpoint. If a notification arrives, that means there are now one or more FromRadio packets waiting inside FromRadio. Read from FromRadio until you get back an empty packet.
@ -49,7 +49,7 @@ Expected sequence for initial download:
- Read a User from "user" - to get the username for this node
- Read a MyNodeInfo from "mynode" to get information about this local device
- Read a series of NodeInfo packets to build the phone's copy of the current NodeDB for the mesh
- Read a endConfig packet that indicates that the entire state you need has been sent.
- Read a endConfig packet that indicates that the entire state you need has been sent
- Read a series of MeshPackets until it returns empty to get any messages that arrived for this node while the phone was away
For definitions (and documentation) on FromRadio, ToRadio, MyNodeInfo, NodeInfo and User protocol buffers see [mesh.proto](https://github.com/meshtastic/Meshtastic-protobufs/blob/master/mesh.proto)
@ -82,13 +82,13 @@ When the ESP32 advances fromnum, it will delay doing the notify by 100ms, in the
Note: that if the phone ever sees this number decrease, it means the ESP32 has rebooted.
Re: queue management
Not all messages are kept in the fromradio queue (filtered based on SubPacket):
Re: Queue management,
not all messages are kept in the fromradio queue (filtered based on SubPacket):
- only the most recent Position and User messages for a particular node are kept
- all Data SubPackets are kept
- No WantNodeNum / DenyNodeNum messages are kept
A variable keepAllPackets, if set to true will suppress this behavior and instead keep everything for forwarding to the phone (for debugging)
- A variable keepAllPackets, if set to true will suppress this behavior and instead keep everything for forwarding to the phone (for debugging)
### A note on MTU sizes

4
docs/developers/device/http-api.md
View file

@ -12,8 +12,8 @@ This is a mini-spec on a HTTP API which can be used by browser based clients to
- No need for JSON parsing on the resource constrained embedded server.
- Small.
- Already in use for all other transports (so shared testing/tooling coverage)
- Backwards and forward compatible
- Already in use for all other transports (so shared testing/tooling coverage).
- Backwards and forward compatible.
## Request headers

20
docs/developers/device/mesh-alg.md
View file

@ -6,23 +6,23 @@ 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
Because we want our devices to work across various vendors and implementations, we use [Protocol Buffers](https://github.com/meshtastic/Meshtastic-protobufs) pervasively. For information on how the protocol buffers are used with respect to API clients see [sw-design](/docs/software/other/sw-design), for purposes of this document you mostly only
Because we want our devices to work across various vendors and implementations, we use [Protocol Buffers](https://github.com/meshtastic/Meshtastic-protobufs) pervasively. For information on how the protocol buffers are used with respect to API clients see [sw-design](/software/other/sw-design.md), for purposes of this document you mostly only
need to consider the MeshPacket and Subpacket message types.
### Layer 1: Non reliable zero hop messaging
### Layer 1: Non-reliable zero hop messaging
This layer is conventional non-reliable LoRa packet transmission. The transmitted packet has the following representation on the ether:
- A 32 bit LoRa preamble (to allow receiving radios to synchronize clocks and start framing). We use a longer than minimum (8 bit) preamble to maximize the amount of time the LoRa receivers can stay asleep, which dramatically lowers power consumption.
- A 256-bit LoRa preamble (to allow receiving radios to synchronize clocks and start framing). We use a longer than minimum (8 bit) preamble to maximize the amount of time the LoRa receivers can stay asleep, which dramatically lowers power consumption.
After the preamble the 16 byte packet header is transmitted. This header is described directly by the PacketHeader class in the C++ source code. But indirectly it matches the first portion of the "MeshPacket" protobuf definition. But notably: this portion of the packet is sent directly as the following 16 bytes (rather than using the protobuf encoding). We do this to both save airtime and to allow receiving radio hardware the option of filtering packets before even waking the main CPU.
After the preamble and the syncWord of 0x2b, the 16 byte packet header is transmitted. This header is described directly by the PacketHeader class in the C++ source code. But indirectly it matches the first portion of the "MeshPacket" protobuf definition. But notably: this portion of the packet is sent directly as the following 16 bytes (rather than using the protobuf encoding). We do this to both save airtime and to allow receiving radio hardware the option of filtering packets before even waking the main CPU.
- to (4 bytes): the unique NodeId of the destination (or 0xffffffff for NodeNum_BROADCAST)
- from (4 bytes): the unique NodeId of the sender)
- from (4 bytes): the unique NodeId of the sender
- id (4 bytes): the unique (with respect to the sending node only) packet ID number for this packet. We use a large (32 bit) packet ID to ensure there is enough unique state to protect any encrypted payload from attack.
- flags (4 bytes): Only a few bits are currently used - 3 bits for the "HopLimit" (see below) and 1 bit for "WantAck"
@ -30,7 +30,7 @@ After the packet header, the actual packet is placed onto the the wire. These by
NodeIds are constructed from the bottom four bytes of the macaddr of the Bluetooth address. Because the OUI is assigned by the IEEE, and we currently only support a few CPU manufacturers, the upper byte is defacto guaranteed unique for each vendor. The bottom 3 bytes are guaranteed unique by that vendor.
To prevent collisions all transmitters will listen before attempting to send. If they hear some other node transmitting, they will reattempt transmission in x milliseconds. This retransmission delay is random between FIXME and FIXME (these two numbers are currently hardwired, but really should be scaled based on expected packet transmission time at current channel settings).
To prevent collisions all transmitters will listen before attempting to send. If they hear some other node transmitting, they will reattempt transmission in x milliseconds. This retransmission delay is random between 20 and 22 seconds. (these two numbers are currently hardwired, but really should be scaled based on expected packet transmission time at current channel settings).
### Layer 2: Reliable zero hop messaging
@ -163,7 +163,7 @@ TODO:
- REJECTED - seems dying - possibly dash7? <https://www.slideshare.net/MaartenWeyn1/dash7-alliance-protocol-technical-presentation> <https://github.com/MOSAIC-LoPoW/dash7-ap-open-source-stack> - does the open source stack implement multi-hop routing? flooding? their discussion mailing list looks dead-dead
- update duty cycle spreadsheet for our typical use case
a description of DSR: <https://tools.ietf.org/html/rfc4728> good slides here: <https://www.slideshare.net/ashrafmath/dynamic-source-routing>
a description of DSR: <https://tools.ietf.org/html/rfc4728>, good slides here: <https://www.slideshare.net/ashrafmath/dynamic-source-routing>,
good description of batman protocol: <https://www.open-mesh.org/projects/open-mesh/wiki/BATMANConcept>
interesting paper on LoRa mesh: <https://portal.research.lu.se/portal/files/45735775/paper.pdf>
@ -203,7 +203,7 @@ If Y were to die, at least the neighbor nodes of Y would have their last known p
- when a node X wants to know other nodes positions, it broadcasts its position with want_replies=true. Then each of the nodes that received that request broadcast their replies (possibly by using special timeslots?)
- all nodes constantly update their local db based on replies they witnessed.
- after 10s (or whatever) if node Y notices that it didn't hear a reply from node Z (that Y has heard from recently ) to that initial request, that means Z never heard the request from X. Node Y will reply to X on Z's behalf.
- after 10s (or whatever) if node Y notices that it didn't hear a reply from node Z (that Y has heard from recently) to that initial request, that means Z never heard the request from X. Node Y will reply to X on Z's behalf.
- could this work for more than one hop? Is more than one hop needed? Could it work for sending messages (i.e. for a message sent to Z with want-reply set).
## approach 4
@ -218,5 +218,5 @@ look into the literature for this idea specifically.
- Occasionally, a node might broadcast saying "anyone have anything newer than time X?" If someone does, they send the diffs since that date.
- essentially everything in this variant becomes broadcasts of "request db updates for >time X - for _all_ or for a particular nodenum" and nodes sending (either due to request or because they changed state) "here's a set of db updates". Every node is constantly trying to
build the most recent version of reality, and if some nodes are too far, then nodes closer in will eventually forward their changes to the distributed db.
- construct non ambiguous rules for who broadcasts to request db updates. ideally the algorithm should nicely realize node X can see most other nodes, so they should just listen to all those nodes and minimize the # of broadcasts. the distributed picture of nodes RSSI could be useful here?
- construct non-ambiguous rules for who broadcasts to request db updates. Ideally the algorithm should nicely realize node X can see most other nodes, so they should just listen to all those nodes and minimize the # of broadcasts. The distributed picture of nodes RSSI could be useful here?
- possibly view the BLE protocol to the radio the same way - just a process of reconverging the node/msgdb database.

4
docs/developers/device/plugin-api.md
View file

@ -52,7 +52,7 @@ The easiest way to get started is:
- 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)
- 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.
- 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
@ -72,7 +72,7 @@ If you are making a new app using meshtastic, please send in a pull request to a
- **0-63** Core Meshtastic use; do not use for third party apps
- **64-127** Registered 3rd party apps. Send in a pull request that adds a new entry to portnums.proto to register your application
- **256-511** Use one of these portnums for your private applications that you don't want to register publicly
- **1024-66559** Are reserved for use by IP tunneling (see _FIXME_ for more information)
- **1024-66559** Are reserved for use by IP tunneling (see [here](/docs/developers/device/portnum) for more information)
All other values are reserved.

1
docs/developers/device/radio-settings.md
View file

@ -5,6 +5,7 @@ sidebar_label: Radio Settings
---
We use the same channel maps as LoRaWAN (though this is not LoRaWAN).
(Note, not the same channel map as TTN for US frequences.)
![freq table](/img/LoRa-Frequency-Bands.jpg)

6
docs/developers/overview.md
View file

@ -6,10 +6,10 @@ 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.
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 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
@ -24,7 +24,7 @@ There are many technologies (and repositories) used in creating the Meshtastic e
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.
## 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 to interact is developed. It is mainly C and C++ code.Think Arduino. It is where the first level of hardware interaction begins and ends.
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.

4
docs/developers/publish.md
View file

@ -47,7 +47,7 @@ storeFile=nononononono.jks
* Go to Actions / Make Release / Run Workflow
* Pick the Releases branch
* Enter the version found in app/gradle.build
*
## iOS
TBD
@ -83,4 +83,4 @@ TBD
:::note
You need permissions in the GitHub project to make a build
:::
:::

7
docs/getting-started/concepts.md
View file

@ -7,7 +7,6 @@ slug: /getting-started/concepts
Various high level concepts used in the Meshtastic meta verse:
* mesh networking: 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 network 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.
* 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 or on a mountain or if there is a major power/internet outage such as in a storm or other disaster.
* Meshtastic channels: Can create a *somewhat* secure method of communication on the same mesh network. They channel can be encrypted, to prevent normal people from listening in on the traffic. But, it could probably be easily cracked by determined individuals. See [Channel Config](https://meshtastic.org/docs/software/settings/channel) for more info.
* LoRaWAN: If you add a LoRa gateway, then you can interact with more networks, such as the internet.
* 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.
* 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.
* 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.

27
docs/getting-started/faq.md
View file

@ -4,11 +4,10 @@ title: Frequently Asked Questions (FAQ)
sidebar_label: Frequently Asked Questions
slug: /getting-started/faq
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<!--
<!--
**** FAQ Contributors, README ***
*
@ -25,9 +24,9 @@ import TabItem from '@theme/TabItem';
Q: What is Meshtastic?
- Meshtastic is most awesome long range, low power communications service on the planet earth! That's not even an exaggeration!
- Meshtastic is the most awesome long range, low power communications service on the planet earth! That's not even an exaggeration!
Q: Where can I get additional help, ask questions or bond with the Meshtastic community?
Q: Where can I get additional help, ask questions, or bond with the Meshtastic community?
- After reading this FAQ and checking out the links on the left, there are two places... The preferred place is to check out the [Forum](https://meshtastic.discourse.group). There you can be part of our growing community and search for previous posts that may be similar to what you're looking for. We also have the [Meshtastic Discord](https://discord.com/invite/UQJ5QuM7vq) server where you may connect with like-minded people.
@ -59,11 +58,11 @@ Q: My device has gone to sleep and I can't send any messages.
Q: How do I turn off an ESP32 t-beam based device?
- Hold down the middle button for about 10 seconds.
- Hold down the left PWR button for about 10 seconds and the display should turn off.
Q: How do I turn on an ESP32 t-beam based device?
- Push the power button for about 1 second.
- Push the left PWR button for about 1 second.
Q: How can I tell the device not to sleep?
@ -88,14 +87,14 @@ Q: I'd like to write a plugin. How do I get started?
Q: What versions of Android does the Meshtastic Android App require?
- Answer TBD
- Android 5.0 is the current minSdkVersion (21).
Q: What's the cloud icon next to the message?
- Empty Cloud - In route to your device.
- Up Arrow - Queued to be sent over the mesh.
- Empty Cloud - Queued on the app to be sent to your device.
- Up Arrow - Queued on the device to be sent over the mesh.
- Check Mark - Delivered over the mesh.
- Cross Mark - Error
- Cross Mark - Error.
Q: How can I clear the message history?
@ -115,7 +114,7 @@ Q: How do I get the Meshtastic iOS App?
Q: How do I pair my phone to the device if my device doesn't have a screen?
- Answer TBD (perhaps consider using web if ESP32)
- Use [Wifi](https://meshtastic.org/docs/software/device/device-wifi) or use Bluetooth with [screenless pairing](https://github.com/meshtastic/Meshtastic-device/issues/26). When prompted to pair, double click on the device button and the password will be set to `123456`.
Q: Can I have Bluetooth enabled and use WiFi radio?
@ -147,11 +146,11 @@ Q: I've Flashed my device but I can't access the Web UI
Q: What is a Meshtastic Channel?
- This is the LoRa channel you're broadcasting on, the modem configuration (spreading factor, bandwidth and error correction), along with a special identifier for your group and optional encryption.
- This is the LoRa channel you're broadcasting on, the modem configuration (spreading factor, bandwidth and error correction), along with a special identifier for your group, and optional encryption.
Q: What is a LoRa channel?
- This is the LoRa frequency within the Frequency band your device is configured to use.
- This is the LoRa frequency within the frequency band your device is configured to use.
Q: How do I share my Meshtastic Channel with other people?
@ -163,7 +162,7 @@ Q: What is a Primary Channel?
Q: What is a Secondary Channel?
- As this is a new feature, secondary Channels work on the device and the Python Script. Support for secondary channels by other clients are pending. For more information: https://meshtastic.org/docs/software/device/device-channels#how-to-use-secondary-channels
- As this is a new feature, secondary channels work on the device and the Python Script. Support for secondary channels by other clients is pending. For more information: https://meshtastic.org/docs/software/device/device-channels#how-to-use-secondary-channels
## Command Line / Python

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

@ -52,7 +52,7 @@ values={[
### Download Latest Firmware
Firmware can be downloaded from the [Firmware](/firmware) page. Your initial installation has to happen over USB from your Mac, Windows or Linux PC. Once our software is installed, all future software updates happen over Bluetooth from your phone.
Firmware can be downloaded from the [Firmware](/firmware) page. Your initial installation has to happen over USB from your Mac, Windows, or Linux PC. Once our software is installed, all future software updates happen over Bluetooth from your phone.
:::note
The [T-Beam 0.7](/docs/hardware/supported/tbeam#t-beam---v07) board is an earlier version of the T-Beam board, and due to changes in the design in subsequent iterations this board uses a specific firmware file different from the other T-Beam boards.
@ -78,7 +78,7 @@ values={[
>
> ```bash
> python3 --version
> pip3 --version
> pip3 --version
> ```
>
> If `python3` is not installed, install with
@ -207,7 +207,7 @@ Hard resetting via RTS pin...
`cd` into the directory where you unzipped the latest release. For example:
```bash title="Example"
cd /Downloads/firmware/
cd ~/Downloads/firmware/
```
### Install/Update Firmware
@ -278,7 +278,7 @@ values={[
Browse to the previously downloaded firmware and select the correct firmware based on the board type and frequency.
:::caution
Be very careful to install the correct load for your board. In particular the popular 'T-BEAM' radio from TTGO is not called 'TTGO-Lora' (that is a different board). So don't install the 'TTGO-Lora' build on a TBEAM, it won't work correctly.
Be very careful to install the correct load for your board. In particular the popular 'T-BEAM' radio from TTGO is not called 'TTGO-Lora' (that is a different board). So don't install the 'TTGO-Lora' build on a TBEAM, it won't work correctly. If you flash the incorrect firmware: It may appear to flash correctly, but if your device has a screen it might stay blank. On-board radio peripherals might be damaged because of GPIO pin direction, but you should just try to flash with the correct version.
:::
### Flash Firmware

6
docs/getting-started/flashing-nrf52.md
View file

@ -39,12 +39,12 @@ With the latest versions of MacOS, the USB Serial driver is built-in. Do _NOT_ d
<summary>Removing the CH34x (CH340/CH341) USB Drivers</summary>
<div>
<div>
If you have already downloaded/installed the MacOS WCH-IC CH340 ("CH341SER_MAC") drivers via the `CH34x_Install_V1.5.pkg`, you will have to Uninstall the kernel extension:
If you have already downloaded/installed the MacOS WCH-IC CH340 ("CH341SER_MAC") drivers via the CH34x_Install_V1.5.pkg, you will have to Uninstall the kernel extension:
<br />
<br />
1. Unplug your T-Echo<br />
2. Open the Terminal and run:<br />
3. sudo -rf /Library/Extensions/usbserial.kext`<br />
3. sudo -rf /Library/Extensions/usbserial.kext<br />
4. Reboot
</div>
</div>
@ -75,7 +75,7 @@ Be careful to install the correct load for your board. While it is unlikely that
:::
- Connect your device to your computer with a USB cable. If your computer complains about needing to format a new drive, cancel the format command.
- Double click the `Reset` button on your device, this will put it into boot loader mode.
- Double click the `Reset` button on your device, this will put it into bootloader mode.
[<img alt="LILYGO T-Echo" src="/img/hardware/t-echo-lilygo.jpg" style={{zoom:'25%'}} />](/img/hardware/t-echo-lilygo.jpg)

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

@ -11,7 +11,7 @@ Meshtastic® is a project that lets you use inexpensive LoRa radios as a long ra
The radios automatically create a mesh to forward packets as needed, so everyone in the group can receive messages from even the furthest member. The radios will optionally work with your phone, but no phone is required.
Meshtastic uses LoRa for the long range communications and depending on settings used the maximum theoretical group size ranges from 30-200 device nodes. Currently, each device can only support a connection from a single user at a time.
Meshtastic uses LoRa for the long range communications and depending on settings used, the maximum theoretical group size ranges from 30-200 device nodes. Currently, each device can only support a connection from a single user at a time.
## Purchase a Radio
@ -27,11 +27,11 @@ Make sure not to power the radio on without first attaching the antenna! You cou
## Download Firmware
Firmware can be downloaded from the [Firmware](/firmware) page. Your initial installation has to happen over USB from your Mac, Windows or Linux PC. Once our software is installed, all future software updates happen over Bluetooth from your phone.
Firmware can be downloaded from the [Firmware](/firmware) page. Your initial installation has to happen over USB from your Mac, Windows, or Linux PC. Once our software is installed, all future software updates happen over Bluetooth from your phone.
## Flashing Firmware
If your device already has Meshtastic flashed to it, You can update it over the air (OTA). Otherwise, you'll need a computer and a **data** USB cable. This can be done in the following ways:
If your device already has Meshtastic flashed to it, you can update it over the air (OTA). Otherwise, you'll need a computer and a **data** USB cable. This can be done in the following ways:
- Install using the command line interface (CLI)
- Install using a graphical user interface (GUI)
@ -50,15 +50,15 @@ There are many ways to connect to your new radio!
## A good first test (connect via USB and CLI)
If you have at least two radios with the Meshtastic firmware, you may consider connecting one via USB and the other simply powered. Communicate with the USB radio using a CLI like [Meshtastic-python](https://meshtastic.org/docs/software/python/python-installation).
If you have at least two radios with the Meshtastic firmware, you may consider connecting one via USB and the other battery powered. Communicate with the USB radio using a CLI like [Meshtastic-python](https://meshtastic.org/docs/software/python/python-installation).
- Ensure you can run "meshtastic --info".
- Ensure the region is set appropriately. If the radios are 915 MHz and you are in the US, then no region changes/settings are necessary. If you are in another region, you may need to run something like: "meshtastic --set region EU865".
- Send a message "meshtastic --sendtext hello1"
- Ensure you can run `meshtastic --info`.
- Ensure the region is set appropriately. If the radios are 915 MHz and you are in the US, then no region changes/settings are necessary. If you are in another region, you may need to run something like: `meshtastic --set region EU865`.
- Send a message `meshtastic --sendtext hello1`
- The radio connected via USB should show the message almost instantly.
- Other radios may take a few seconds before they show the message. You may need to press one of the buttons on the other radio to see if the message arrived.
- Run "meshtastic --nodes" to see if other nodes show in the display.
- Messages sent from the USB radio should be sent to the other radio(s) via LoRa. The default settings should have this work by default
- Run `meshtastic --nodes` to see if other nodes show in the display.
- Messages sent from the USB radio should be sent to the other radio(s) via LoRa. The default settings should allow this to work.
## A good second test (connect via Bluetooth)
@ -68,22 +68,22 @@ The Android app is currently more robust than the iOS app. But, they both should
- Start Meshtastic app
- Connect to radio(s) from inside the app
- Pair with radio(s). A paring code should show on the radio. Enter that value when prompted to pair a Bluetooth device.
- Note: May want to set the Bluetooth timeout (ex: "meshtastic --set wait_bluetooth_secs 28800")
- Note: May want to set the Bluetooth timeout (ex: `meshtastic --set wait_bluetooth_secs 28800`)
- Send message(s) from inside the app.
- Verify that all radios are receiving the messages. Might have to click on the button on the radio to see most recent message.
## A good third test (connect via Wifi/HTTP)
- Configure the _wifi_ssid_ and _wifi_password_. "meshtastic --set wifi_ssid 'xxx' --set wifi_password 'yyy'" (where xxx and yyy are the appropriate values for your network)
- Configure the _wifi_ssid_ and _wifi_password_. `meshtastic --set wifi_ssid 'xxx' --set wifi_password 'yyy'` (where xxx and yyy are the appropriate values for your network)
- Reboot radio by either removing power or pressing the power button.
- Click on the button to cycle through to the screen with IP address and verify that there was a connection to the Wifi access point.
- Send message(s). "meshtastic --host 192.168.1.200 --sendtext hello"
- Send message(s). `meshtastic --host 192.168.1.200 --sendtext hello`
- Verify that all radios are receiving the messages. Might have to click on the button on the radio(s) to see most recent message.
- Open up a browser to http://meshtastic.local to view the web UI (currently under development). You may need to open http://meshtastic.local/static )
- If you want to switch back to Bluetooth, you will need to set the _wifi_ssid_ and _wifi_password_ values to blank values (ex: '').
- If you want to switch back to Bluetooth, you will need to set the _wifi_ssid_ and _wifi_password_ values to blank values (ex: `meshtastic --set wifi_ssid '' --set wifi_password ''`).
## Troubleshooting
For any issues during setup, search [our forum](https://meshtastic.discourse.group) to find a solution. If you can't find one, please post your problem, providing as much detail as possible.
For any issues during setup, search [our forum](https://meshtastic.discourse.group) to find a solution. If you can't find one, please post your problem and provide as much detail as possible.
We are also on [Discord](https://discord.gg/UQJ5QuM7vq).

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

@ -5,14 +5,15 @@ sidebar_label: Aerial selection
slug: /hardware/aerials
---
The stock aerials provided bundled with the t-Beam and other boards are, in general a 'mixed bag'. They may not have been selected for your given frequency range, tuned or of a quality design.
The stock aerials provided bundled with the t-Beam and other boards are a 'mixed bag'. They may not have been designed or tuned for your given frequency range, and they may not be of a quality design.
Matching an aerial to the frequency of transmission is important, as is choosing an appropriate design.
Matching an aerial to the transceiver frequency is important, as is choosing an appropriate design.
The aerial's design will affect:
- proportion of the signal which leaves the aerial (efficiency),
- directions in which it's transmitted, and whether it will be affected by horizontal / vertical polarization,
- proportion of signal which is reflected back within the device itself.
- directions in which it's transmitted,
- whether it will be affected by horizontal or vertical polarization,
- and proportion of signal which is reflected back within the device itself.
:::caution
While the LoRa devices we are using for Meshtastic are relatively low power radios, care should be taken _not_ to operate any radio transmission device without an aerial or with a poorly matched aerial. Un-transmitted radio signal reflected back to the transmitter can damage the device.
@ -29,14 +30,14 @@ While the LoRa devices we are using for Meshtastic are relatively low power radi
- Many antennas, especially quarter wave stubby antennas, require the use of ground planes to transmit at peak performance.
- Do you want transmission in all directions?
- While humans (mostly water) don't attenuate signal greatly (at LoRa frequencies), buildings & walls do.
- If your aerial is permanently positioned against a building, signal transmitted towards the wall will be largely lost.
- Does my Meshtastic device have the right power range, impedance & connector for the aerial?
- For the LoRa devices it should be 50 Ohm impedance, with SMA connector. Many antennas will be recommended for LoRa use in their technical details.
- By contrast, a close range, contact-less Personal Area Network antenna, or a huge aerial at the end of length of coax designed for a 100W transmitter are not going to be operable.
- Cost, quality and supply service?
- The perfect aerial on paper, sourced from the other side of the world with mixed reviews doesn't compare to a local supplier who has spent time carefully collating all of the aerial data-sheets for comparison _and_ holds stock immediately available - personally I prefer to pay significantly more for a time saving, quality service.
- If your aerial is permanently positioned against a building, signal transmitted towards the wall will be largely lost or attenuated.
- Does my Meshtastic device have the right power range, impedance, and connector for the aerial?
- For the LoRa devices, it should be 50 Ohm impedance with SMA connector. Many antennas will be recommended for LoRa use in their technical details.
- By contrast, a close range, contactless Personal Area Network antenna, or a huge aerial at the end of length of coax designed for a 100W transmitter, are not going to be operable.
- Cost, quality, and supply service?
- The perfect aerial on paper, sourced from the other side of the world with mixed reviews, doesn't compare to a local supplier who has spent time carefully collating all of the aerial data-sheets for comparison _and_ holds stock immediately available. Personally, I prefer to pay significantly more for a time saving, quality service.
- How close will the antenna be to my Meshtastic device?
- Most cables will significantly degrade the signal strength over any significant distance. It is often more effective to place a node outside, than to have it indoors with the antenna outside.
- Most cables will significantly degrade the signal strength over any significant distance. It is often more effective to place a node outside, than to have it indoors with the antenna outside. (The exception might be if there is extreme heat, cold, or humidity, and if the shortest possible low loss cable is used. Still, a proper enclosure should mitigate bad weather.)
## Terminology / references

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

@ -14,15 +14,15 @@ If you have sufficient range with your existing aerial, skip this section. If y
- Caution, avoid suppliers who:
- don't state the aerial's tuned frequency and its specific purpose (LoRa network)
- claim huge gain figures on omni-directional aerials
- don't provide boringly professional data-sheets.
- don't provide boringly professional datasheets
If you want more range, directionality, or specificity read on.
## General guidance
The Meshtastic system is designed to be simple and intuitive to use. However, its LoRa radios rely on point-to-point communications, unit to unit, aerial to aerial; quite different to the near ubiquitous radio coverage of today's cellphone & Wifi connections.
The Meshtastic system is designed to be simple and intuitive to use. However, its LoRa radios rely on point-to-point communications, unit-to-unit, aerial-to-aerial; quite different to the near ubiquitous radio coverage of today's cellphone & Wifi connections.
Some understanding of the factors affecting radio communications will help achieve substantially better service, faster transmission, over a greater range with your devices. Here, we'll attempt to provide a top-level set of guidance for use and aerial selection, how to test the aerials, and a set of resources for further research and plenty of opportunity for going deeper.
Some understanding of the factors affecting radio communications will help achieve substantially better service and faster transmission over a greater range with your devices. Here, we'll attempt to provide a top-level set of guidance for use and aerial selection, how to test the aerials, a set of resources for further research, and plenty of opportunity for going deeper.
The Meshtastic devices (of various flavors) lend themselves to experimentation, not only because you can replace their aerials, but also because of their mesh operation. All nodes will, without alteration, relay communications from any other members of the mesh around obstacles and over greater distances. The cost of aerial investment should be weighed against investment in additional low-cost nodes.
@ -36,4 +36,4 @@ The information collected here is by no means definitive, and necessarily abbrev
To comment on / join in antenna range [Meshtastic discourse](https://meshtastic.discourse.group/t/antenna-improved-range/227/35?u=sens8tion)
There, you will also find reference to Meshtastic range achievements, aerial recommendations (note we've stopped short of making specific supplier aerial recommendations in this wiki).
There, you will also find reference to Meshtastic range achievements and aerial recommendations. (Note we've stopped short of making specific supplier aerial recommendations in this wiki.)

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

@ -5,13 +5,14 @@ sidebar_label: Non-aerial factors
slug: /hardware/non-aerial
---
Unless you're using your devices in a vacuum with clear line of sight between aerials the following will have an affect:
- Weather (temperature, humidity & air pressure),
- Transmission power, spreading and other associated channel factors,
- Number of nodes within reach in the mesh (affects retries consequent duty cycle hit),
Unless you're using your devices in a vacuum, with clear line of sight between aerials the following will have an effect:
- Weather (temperature, humidity, and air pressure),
- Transmission power, bandwidth, spreading factor, and other associated channel factors,
- Number of nodes within reach of the mesh (affects retries consequent duty cycle hit),
- Absorption by materials (with varying degrees attenuation, by material and depth),
- Reflection off surfaces (and channeled through material tunnels, including warm / cold air tunnels commonly present in the atmosphere),
- Reflection off surfaces (and channeling through material tunnels, including warm / cold air tunnels commonly present in the atmosphere),
- Diffraction around obstacles (over forests and around corners).
- [Fresnel Zone](They may not have been selected for your given frequency range, tuned or of a quality design.) - Football shape between antennas that must be clear of obstructions or else the signal is attenuated.
### Environmental factors
@ -21,4 +22,4 @@ For a bit of light reading on environmental research:
- This one by ITU again is very detailed in its [analysis of the drivers of attenuation](https://web.archive.org/web/20211005174833/https://www.itu.int/dms_pubrec/itu-r/rec/p/R-REC-P.2040-1-201507-I!!PDF-E.pdf) (I wasn’t aware that all EMF radiation exhibits reflection / transmission characteristics akin to light hitting a material boundary. So, depending on the angle of incidence, material and the EMF wavelength, it will be reflected and / or transmitted through).
- These RF bands are also made more [noisy by adjacent LTE](https://www.ofcom.org.uk/__data/assets/pdf_file/0023/55922/lte-coexistence.pdf)
In summary - wavelengths in Europe fair well in plain sight, curve over not-so-tall obstacles (including trees), reflect of surfaces at low angles of incidence. They go through humans without much attenuation; but not brick or stone or anything much above glass / Kevlar. Oh, and don’t sit under an LTE tower and expect it to be plain sailing.
In summary - wavelengths in Europe fair well in plain sight, curve over not-so-tall obstacles (including trees), and they reflect off surfaces at low angles of incidence. They go through humans without much attenuation; but not brick, stone, or anything with more attenuation than glass / Kevlar. Oh, and don’t sit under an LTE tower and expect it to be plain sailing. RF emissions at adjacent frequencies can interfere at a high enough power.

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

@ -12,7 +12,7 @@ slug: /hardware/resources
### Coverage prediction
* [Tower Coverage.com](https://www.towercoverage.com/)
* Commercial but has free options
* Commercial, but has free options
* [HeyWhat'sThat](http://www.heywhatsthat.com/)

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

@ -4,15 +4,15 @@ title: Antenna testing
sidebar_label: Testing
---
Testing of antennas can be both simple and complex. At its simplest, testing involves sending messages from different locations and seeing which ones are received and then comparing the results against other antennas. This ranges up to using expensive test chambers and equipment to measure the signal strength, gain and radiation patterns. However, it seems that a reasonable job can be done with cheaper methods.
Testing of antennas can be both simple and complex. At its simplest, testing involves sending messages from different locations and seeing which ones are received, and then comparing the results against other antennas. At the complex end, this can be using expensive test chambers and equipment to measure the signal strength, gain, and radiation patterns. However, it seems that a reasonable job can be done with cheaper methods.
## Range testing
As mentioned, while stating the obvious, the simplest way of performing test is:
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 & contrast.
- 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.
@ -30,6 +30,6 @@ Here are a [couple](https://medium.com/home-wireless/testing-lora-antennas-at-91
## 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.
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/linux.md
View file

@ -6,7 +6,7 @@ sidebar_label: Linux
This page is a place holder.
The device software can run on Hardware that runs Linux to execute unit tests.
The device software can run on hardware that runs Linux to execute unit tests.
Fledgling support for a LoRa USB dongle has been in the works.

10
docs/hardware/supported/rak4631.md
View file

@ -6,17 +6,17 @@ sidebar_label: RAK WisBlock
The RAK WisBlock is a low power modular hardware system that can be used to build Meshtastic devices. Soldering is only required for the optional OLED screen.
You will need a [base board](https://store.rakwireless.com/collections/wisblock-base), a [core 4631 LPWAN module](https://store.rakwireless.com/collections/wisblock-core/products/rak4631-lpwan-node) and optionally a GPS Sensor to build a Meshtastic device.
You will need a [base board](https://store.rakwireless.com/collections/wisblock-base), a [core 4631 LPWAN module](https://store.rakwireless.com/collections/wisblock-core/products/rak4631-lpwan-node), and optionally a GPS Sensor to build a Meshtastic device.
Both available base boards ([5005](https://store.rakwireless.com/collections/wisblock-base/products/rak5005-o-base-board) & [19003](https://store.rakwireless.com/collections/wisblock-base/products/wisblock-base-board-rak19003)) have a reset button, support an OLED screen, and have built in connectors for a 3.7V LIPO battery (max 4.3V) and 5V Solar panel (max 5.5V)
A user button is not possible with the 19003 base board, it may be possible to add a user button to the 5005 base board using the [13002 IO module](https://store.rakwireless.com/collections/wisblock-interface/products/adapter-module-rak13002).
A user button is not possible with the 19003 base board. It may be possible to add a user button to the 5005 base board using the [13002 IO module](https://store.rakwireless.com/collections/wisblock-interface/products/adapter-module-rak13002).
To add a GPS to the 5005 base board you need the [1910 GPS sensor](https://store.rakwireless.com/collections/wisblock-sensor/products/rak1910-max-7q-gnss-location-sensor) it is supported on slot A of the 5005 board via UART.
To add a GPS to the 5005 base board, you need the [1910 GPS sensor](https://store.rakwireless.com/collections/wisblock-sensor/products/rak1910-max-7q-gnss-location-sensor). It is supported on slot A of the 5005 board via UART.
To add a GPS to the 19003 base board you need the [12500 GPS sensor](https://store.rakwireless.com/products/wisblock-gnss-location-module-rak12500) it is supported via I2C on slot B for firmware versions 1.49 and above.
To add a GPS to the 19003 base board, you need the [12500 GPS sensor](https://store.rakwireless.com/products/wisblock-gnss-location-module-rak12500). It is supported via I2C on slot B for firmware versions 1.49 and above.
Flashing the firmware is a simple process connect your device via USB and click the reset button twice and a drive will appear on Windows Linux or Mac drag the appropriate .uf2 firmware file onto the root of the drive and the firmware will be updated.
Flashing the firmware is a simple process. Connect your device via USB, click the reset button twice, and a drive will appear. On Windows, Linux, or Mac, drag the appropriate .uf2 firmware file onto the root of the drive and the firmware will be updated.
There is currently no pin required to pair RAK devices via BLE.

2
docs/legal/privacy.md
View file

@ -8,7 +8,7 @@ We don't collect any personal identifying information.
If you have opted-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, which screens you used in the app etc... Analytics is provided by [Crashlytics](https://firebase.google.com/products/crashlytics).
We never capture usernames, the contents of your texts or your location.
We never capture usernames, the contents of your texts, or your location.
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/).

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

@ -22,11 +22,11 @@ If it is helpful, [here](https://meshtastic.org/docs/software/android/android-us
## 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 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](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)
## Fixes needed for these new Play Store background position requirements

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

@ -8,7 +8,7 @@ sidebar_label: Usage
The Meshtastic Android app handles the communication and shows the location of everyone in your private group. Each member of your private mesh can always see the location and distance of all other members and any text messages sent to your group chat.
Open the App and you should see a screen like this. You can move through the tabs but nothing much will be visible until you connect to a radio device.
Open the App and you should see a screen like this. Notice the cloud with a slash through it in the upper right, showing no device connection. You can move through the tabs but nothing much will be visible until you connect to a radio device.
[![No device connected](/img/android/android-settings-none-sm.png)](/img/android/android-settings-none.png)
@ -50,13 +50,13 @@ The cloud icon at the top right corner indicates if you are connected to a devic
## 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, otherwise you will need to Setup a Channel.
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.
### Setup a channel
To use Meshtastic you need to setup a Channel, and share the details with your group. The group is private and only those who have the details can join the group and see the messages. You will need to do this once initially, and then only when you want to change or make a new mesh network group. For a new device you will see there is a default setting, shown as `#LongSlow-1, Very long range (but slow)`. It is OK to use this initially.
To use Meshtastic, you need to setup a Channel and share the details with your group. The group is private and only those who have the details can join the group and see the messages. You will need to do this once initially, and then only when you want to change or make a new mesh network group. For a new device you will see there is a default setting, shown as `#LongSlow-1, Very long range (but slow)`. It is OK to use this initially.
The Channel tab allows you to do this. This screen is initially locked, so that you don't change it accidentally. Press the lock symbol, and you will be able to edit. First, select the Channel options, as shown here, and chose the most appropriate option:
The Channel tab allows you to do this. This screen is initially locked so that you don't change it accidentally. Press the lock symbol, and you will be able to edit. First, select the Channel options, as shown here, and chose the most appropriate option:
[![Changing channel settings](/img/android/android-change-channel-sm.png)](/img/android/android-change-channel.png)
@ -68,7 +68,7 @@ You will see a warning because changing the Channel will break communications wi
[![Do you want to change the channel?](/img/android/android-new-channel-sm.png)](/img/android/android-new-channel.png)
The app will generate a new QR code on the screen, and this encodes the channel details and a random 256-bit key for sharing with the new group. You can share the QR code with other Meshtastic users, or use the Share button and share the link via chat message, SMS, email (the link is a very long code, for example: https://www.meshtastic.org/d/#CgUYAyIBAQ
The app will generate a new QR code on the screen, and this encodes the channel details and a random 256-bit key for sharing with the new group. You can share the QR code with other Meshtastic users, or use the Share button and share the link via chat message, SMS, or email. The link is a very long code, for example: https://www.meshtastic.org/d/#CgUYAyIBAQ
### Join a channel
@ -96,7 +96,7 @@ Accept this, and the app will change to this new channel. You will lose any curr
[![Accept new channel](/img/android/android-accept-channel-c.png)](/img/android/android-accept-channel.png)
:::note
Setting the same Name and Options will not work as there is also a unique pre-shared key encoded in the channel.
Setting the same Name and Options directly will not work as there is also a unique pre-shared key encoded in the QR code or link.
:::
You can test changing channels with the QR code shown below.
@ -109,12 +109,12 @@ Various data-rates are selectable when configuring a channel and are inversely p
| 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) |
| 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
@ -135,9 +135,9 @@ There is no long-term store-and-forward of messages, so messages not received wi
### View your network
The network list shows all the users (devices) that have connected to the same Channel. For each entry, it shows the last time they were active, their distance, and their last known power status (battery & percentage, or external power). In the example below, Lora V2 is the local user, m8n was last heard from 3 minutes ago and is 29m away, and 25C is active and 498m away.
The network list shows all the users (devices) that have connected to the same Channel. For each entry, it shows the last time they were active, their distance, and their last known power status (battery and percentage, or external power). In the example below, Lora V2 is the local user, m8n was last heard from 3 minutes ago and is 29m away, and 25C is active and 498m away.
This is a list of network nodes, rather than users, so where there is a named user connected to the device, you will see the user name, otherwise the node is shown as `Unknown a3c9` (where `a3c9` is the last 4 hex digits from the MAC address.)
This is a list of network nodes, rather than users, so where there is a named user connected to the device, you will see the user name. Otherwise the node is shown as `Unknown a3c9` (where `a3c9` is the last 4 hex digits from the MAC address.)
[![Local Meshtastic network](/img/android/android-nodes-sm.png)](/img/android/android-nodes.png)
@ -166,13 +166,13 @@ This allows you to change the frequency with which your location is broadcast ac
#### Device sleep period
By default, ESP32 devices will enter sleep mode after 300 seconds of inactivity to save battery power. Unfortunately, this will also turn off the Bluetooth radio. They can be woken by either receiving a message over LoRa (the LoRa receiver never switches off), or by pressing a program button when there is one on the device. For example, to keep the Bluetooth link awake for eight hours (any usage of the Bluetooth protocol from your phone will reset this timer), set this to 28800 seconds.
By default, ESP32 devices will enter sleep mode after 300 seconds of inactivity to save battery power. Unfortunately, this will also turn off the Bluetooth radio. They can be woken by either receiving a message over LoRa (the LoRa receiver never switches off), or by pressing a program button if there is one on the device. For example, to keep the Bluetooth link awake for eight hours (any usage of the Bluetooth protocol from your phone will reset this timer), set this to 28800 seconds.
### Debug page
[![Debug page](/img/android/android-debug-sm.png)](/img/android/android-debug.png)
The debug page allows you to see all packets sent between the application and the device. This can then be used for debugging purposes.
The debug page allows you to see all packets sent between the application and the device. This can be useful for debugging purposes.
### Save messages as CSV

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

@ -7,8 +7,8 @@ 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.
Current community projects:
* Meshtastic plugin for ATAK (Android Team Awareness Kit)
* PyGUI - Platform independent graphical user interface for Meshtastic devices
* Go CLI - A command line interface using Go that requires no pre-requisites to be installed
* [Meshtastic plugin for ATAK](/docs/software/community/community-atak) (Android Team Awareness Kit)
* [PyGUI](/docs/software/community/community-pygui) - Platform independent graphical user interface for Meshtastic devices
* [Go CLI](/docs/software/community/community-go) - A command line interface using Go that requires no pre-requisites to be installed
Support for these projects should be sought from their respective authors.
Support for these projects should be sought from their respective authors.

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

@ -18,6 +18,6 @@ This table is derived from the [protobufs](/docs/developers/protobufs/api#critic
| Unspecified | 4 | Not normally used |
| UBloxInitFailed | 5 | We failed while configuring a UBlox GPS |
| NoAXP192 | 6 | This board was expected to have a power management chip and it is missing or broken |
| InvalidRadioSetting | 7 | The channel tried to set a radio setting which is not supported by this chipset, radio comms settings are now undefined. |
| TransmitFailed | 8 | Radio transmit hardware failure. We sent data to the radio chip, but it did not reply with an interrupt. |
| InvalidRadioSetting | 7 | The channel tried to set a radio setting which is not supported by this chipset, radio comms settings are now undefined |
| TransmitFailed | 8 | Radio transmit hardware failure. We sent data to the radio chip, but it did not reply with an interrupt |
| Brownout | 9 | We detected that the main CPU voltage dropped below the minimum acceptable value |

14
docs/software/device/firmware.md
View file

@ -12,9 +12,9 @@ The latest firmware can be downloaded from the [Firmware](/firmware) page. If yo
### Buttons
A number of devices support buttons that can be used to interact with the firmware. These buttons have a number of different functions:
A number of devices have buttons that can be used to interact with the firmware. These buttons have a number of different functions:
- Reset button - This is present on most devices
- Reset button - This is present on most devices.
- Power button - This is present on some devices. A long press powers the device off or turns it back on again.
- Program button - This is present of some devices and has a number of functions:
- Single press - This changes the page of information displayed on the screen.
@ -24,7 +24,7 @@ A number of devices support buttons that can be used to interact with the firmwa
### Screens
A number of devices have screens capable of displaying the messages received and information about the mesh and other details. On powering the device it will display the Meshtastic splash screen for a couple of seconds:
A number of devices have screens capable of displaying the messages received, information about the mesh, and other details. On powering the device it will display the Meshtastic splash screen with the version number for a couple of seconds:
![Splash screen](/img/screen/mesh-splash.jpg)
@ -32,19 +32,19 @@ The screen is split up into pages, through which you can navigate using the prog
![Message page](/img/screen/mesh-message.jpg)
The next pages display information about the nodes that are currently on the mesh. This includes the distance and direction to that node, along with signal strength and time last seen.
The next pages display information about the nodes that are currently on the mesh. This includes the distance and direction to that node, the signal strength, and the time last seen.
![Node page](/img/screen/mesh-node1.jpg) ![Node page](/img/screen/mesh-node2.jpg)
The next page shows information about the device, battery power, number of nodes and how many are connected current, number of GPS satellites being received, channel name, last digits of the MAC address, and names of the last nodes to join the mesh.
The next page shows information about the device, battery power, current / total nodes, number of GPS satellites seen, channel name, last digits of the MAC address, and a brief log including the names of the last nodes to join the mesh.
![Channel page](/img/screen/mesh-channel.jpg)
The final page shows current battery voltage and capacity, as well as noting how long the device has been online and the current GPS time and GPS location.
The final page shows current battery voltage and percent charge, as well as noting how long the device has been online and the current GPS time, and GPS location.
![GPS page](/img/screen/mesh-gps.jpg)
If the device Wifi has been enabled (only possible on ESP32 devices), another page appears displaying information about the WiFi settings, IP address and number of devices connected to the WiFi.
If the device Wifi has been enabled (only possible on ESP32 devices), another page appears displaying information about the WiFi settings, IP address, and number of devices connected to the WiFi.
![Wifi page](/img/screen/mesh-wifi.jpg)

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

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

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

@ -4,7 +4,7 @@ title: Remote node administration
sidebar_label: Remote node administration
---
This feature will allow you to use the multiple channels feature to enable remote administration of meshtastic nodes. This will let you talk through the mesh to some far away node and change that node's settings. This is an advanced feature that (currently) few users would need. Also, keep in mind it is possible (if you are not careful) to assign settings to that remote node that cause it to completely drop off of your mesh. We advise network admins have a test node to test settings with before applying changes to a remote node to prevent this.
This feature will allow you to use the multiple channels feature to enable remote administration of Meshtastic nodes. This will let you talk through the mesh to some far away node and change that node's settings. This is an advanced feature that (currently) few users would need. Also, keep in mind it is possible (if you are not careful) to assign settings to that remote node that cause it to completely drop off of your mesh. We advise network admins have a test node to test settings with before applying changes to a remote node to prevent this.
## Creating the admin channel
@ -132,7 +132,7 @@ Complete URL (includes all channels): https://www.meshtastic.org/d/#CgUYAyIBAQop
## Admin Channel Setup is Complete
You've finished setting up and adding 2 devices to the admin channel. Remember, because this is a mesh network, it doesn't matter which node you are at; you could administer your first device we set up from the second one we added to the channel. And the settings and examples on this page are just a taste of the other settings you can set. Also, if you ever want to view a setting without having to read through the `--info`, you can always do the following:
You've finished setting up and adding two devices to the admin channel. Remember, because this is a mesh network, it doesn't matter which node you are at; you could administer your first device we set up from the second one we added to the channel. And the settings and examples on this page are just a taste of the other settings you can set. Also, if you ever want to view a setting without having to read through the `--info`, you can always do the following:
```bash title="--get vs. --info"
$ meshtastic --dest \!28979058 --get ls_secs
@ -144,9 +144,9 @@ 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)
[Settings Overview](/docs/settings) and
[Complete list of user settings in Protobufs](https://meshtastic.org/docs/developers/protobufs/api#radioconfiguserpreferences)
## Areas for future development
In the future we will add a "deadman timer" to this feature so that the remote node will revert any changes if you fail to send a special "commit changes" command. This will protect against sending bad settings to nodes that you can't physically access. Instead, if the node does not receive a commit message within 10 minutes it will revert all changes and (hopefully) rejoin the mesh.
In the future we will add a "dead man's timer" to this feature so that the remote node will revert any changes if you fail to send a special "commit changes" command. This will protect against sending bad settings to nodes that you can't physically access. Instead, if the node does not receive a commit message within 10 minutes it will revert all changes and (hopefully) rejoin the mesh.

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

@ -18,13 +18,13 @@ You can get the latest python tool/library with `pip3 install --upgrade meshtast
- Set any GPIO
- Read any GPIO
- Receive notification of changes in any GPIO.
- Receive notification of changes in any GPIO
## 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:
@ -33,7 +33,7 @@ The procedure using the python command line tool is:
```bash
meshtastic --ch-add gpio
```
3. Check the channel has been created and copy the long "Complete URL" that contains all the channels on that device.
3. Check the channel has been created and copy the long "Complete URL" that contains all the channels on that device
```bash
meshtastic --info
```
@ -47,18 +47,18 @@ Now both devices can talk over the `gpio` channel.
## 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](https://meshtastic.org/docs/software/python/python-installation) documentation for more details.
## Using GPIOs from the python CLI
Writing a GPIO
Writing a GPIO:
```bash title="Expected output"
$ meshtastic --port /dev/ttyUSB0 --gpio-wrb 4 1 --dest \!28979058
Connected to radio
Writing GPIO mask 0x10 with value 0x10 to !28979058
```
Reading a GPIO
Reading a GPIO:
```bash title="Expected output"
$ meshtastic --port /dev/ttyUSB0 --gpio-rd 0x10 --dest \!28979058
Connected to radio

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

@ -10,7 +10,7 @@ If you encounter any problems, please post a question in [our forum](https://mes
## GUI
1. Purchase a suitable [radio](https://github.com/meshtastic/Meshtastic-device/wiki/Hardware-Information).
1. Purchase a suitable [radio](/docs/hardware).
2. Install [Python](https://www.python.org/downloads/).
3. Install [Git](https://git-scm.com/downloads).
4. Reboot your computer.
@ -27,7 +27,7 @@ Note - To get a clean build you may have to delete the auto-generated file `./.v
## Command Line
1. Purchase a suitable [radio](https://github.com/meshtastic/Meshtastic-device/wiki/Hardware-Information).
1. Purchase a suitable [radio](/docs/hardware).
2. Install [PlatformIO](https://platformio.org/platformio-ide)
3. Download this git repo and cd into it:
@ -37,8 +37,8 @@ Note - To get a clean build you may have to delete the auto-generated file `./.v
```
4. Run `git submodule update --init --recursive` to pull in dependencies this project needs.
5. If you are outside the USA, run "export COUNTRY=EU865" (or whatever) to set the correct frequency range for your country. Options are provided for `EU433`, `EU865`, `CN`, `JP` and `US` (default). Pull-requests eagerly accepted for other countries.
6. Plug the radio into your USB port
5. If you are outside the USA, run `export COUNTRY=EU865` (or whatever) to set the correct frequency range for your country. Options are provided for `EU433`, `EU865`, `CN`, `JP` and `US` (default). Pull-requests eagerly accepted for other countries.
6. Plug the radio into your USB port.
7. Type `pio run --environment XXX -t upload` (This command will fetch dependencies, build the project and install it on the board via USB). For XXX, use the board type you have (either `tlora-v2, tlora-v1, tlora-v2-1-1.6, tbeam, heltec, tbeam0.7`).
8. PlatformIO also installs a very nice VisualStudio Code based IDE, see their [tutorial](https://docs.platformio.org/en/latest/tutorials/espressif32/arduino_debugging_unit_testing.html) if you'd like to use it.

2
docs/software/plugins/range-test.md
View file

@ -88,7 +88,7 @@ Steps:
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.
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.

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

@ -6,12 +6,12 @@ sidebar_label: Store and Forward
## About
:::caution
This is a work in progress and is partially available. Stability is not gaurenteed.
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 but Slow).
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
@ -23,20 +23,20 @@ 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, maybe others)
* * 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.
* * 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 "Very long range (but slow)" or "Long range (but slower)" channel settings. You're welcome to try and report back, but those channels have a very low bitrate.
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 (but fast)".
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:
@ -44,7 +44,7 @@ Recommended channel setting is for 1.343kbps:
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 (but slow)" and 5x the bitrate.
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
@ -96,7 +96,7 @@ Story: Carol has been away from the mesh with device turned off. She would like
* * 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.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)
@ -114,9 +114,9 @@ Story: Carol has been away from the mesh with device turned off. She would like
* * 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.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
* * * StoreAndForward.history.LastRequest = (timestamp) // Last time carol requested the history.
### Store & Forward Router Heartbeat
@ -126,7 +126,7 @@ Story: The Store & Forward Router sends a periodic message onto the network. Thi
* * Packet (Port: STORE_FORWARD_APP)
* * * To: Broadcast
* * * StoreAndForward.rr.ROUTER_HEARTBEAT
* * * StoreAndForward.heartbeat.Period = 120 // Expect a heartbeat every 2 minutes
* * * 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
@ -178,9 +178,9 @@ Not necessarily in this order:
* 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)
* 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
* 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.
@ -200,7 +200,7 @@ Not necessarily in this order:
* Set number of max messages from the history.
* Calculate a new channel with 250MHz bandwidth and ~1.5kbit.
* Calculate a new channel with 250kHz bandwidth and ~1.5kbit.
*** Done
@ -208,7 +208,7 @@ Not necessarily in this order:
* 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
* Allow max history to be defined by radioConfig.preferences.store_forward_plugin_records.
* Add a starting to send / finished sending message
* Add a starting to send / finished sending message.

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

4
docs/software/settings/channel.md
View file

@ -40,9 +40,9 @@ This is in active development and not ready for casual users. Testing only.
| Setting | Name | Bandwidth | Coding Rate | Spread Factor | Speed |
| :-----: | :--: | :-------: | :---------: | :-----------: | :-----: |
| `Bw125Cr45Sf128` | Medium | 125 kHz | 4/5 | 7 = 128chips/symbol | 5.469 kbps |
| `Bw125Cr45Sf128` | ShortSlow | 125 kHz | 4/5 | 7 = 128chips/symbol | 5.469 kbps |
| `Bw500Cr45Sf128` | ShortFast | 500 kHz | 4/5 | 7 = 128chips/symbol | 21.875 kbps |
| `Bw31_25Cr48Sf512` | LongAlt | 31.25 kHz | 4/8 | 9 = 512chips/symbol | 275 bps |
| `Bw31_25Cr48Sf512` | LongFast | 31.25 kHz | 4/8 | 9 = 512chips/symbol | 275 bps |
| `Bw125Cr48Sf4096` | LongSlow | 125 kHz | 4/8 | 12 = 4096chips/symbol | 183 bps |
### name

6
docs/software/settings/environmental-measurment-plugin.md
View file

@ -38,11 +38,11 @@ The sensor is always read in Celsius, but the user can opt to view the temperatu
### environmental_measurement_plugin_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
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
### environmental_measurement_plugin_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
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.
### environmental_measurement_plugin_screen_enabled
@ -54,7 +54,7 @@ Specify the preferred GPIO Pin for sensor readings.
### environmental_measurement_plugin_sensor_type
Specify the sensor type
Specify the sensor type.
### environmental_measurement_plugin_update_interval

4
docs/software/settings/external-notification-plugin.md
View file

@ -9,7 +9,7 @@ import TabItem from '@theme/TabItem';
## 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 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.
## Settings
@ -24,7 +24,7 @@ The External Notification Plugin will allow you to connect a speaker, LED or oth
### ext_notification_plugin_enabled
Enables the plugin
Enables the plugin.
### ext_notification_plugin_active

2
docs/software/settings/overview.md
View file

@ -27,7 +27,7 @@ For most, GPS is a really cool, desirable feature. Knowing where everyone on you
### WiFi Settings
Whether you're using the upcoming [web interface](software/web/web-app-software) or you're interested in broadcasting messages to/from the internet using [MQTT](software/settings/mqtt), the [WiFi settings](software/settings/wifi) are your first stop towards an IOT radio.
Whether you're using the upcoming [web interface](software/web/web-app-software) or you're interested in broadcasting messages to/from the internet using [MQTT](software/settings/mqtt), the [WiFi settings](software/settings/wifi) are your first stop towards an IoT radio.
## Examples

2
docs/software/settings/store-and-forward-plugin.md
View file

@ -15,7 +15,7 @@ This is a work in progress and is not yet available.
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 but Slow).
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).
## Settings

4
docs/software/web/config.md
View file

@ -40,14 +40,14 @@ The first time your device restarts after enabling WiFi, it will take an additio
### Wifi configuration
To enable the WiFi to access the web interface, you must at minimum set two preferences:
To enable WiFi to access the web interface, you must at minimum set two preferences:
`wifi_ssid`
`wifi_password`
For the Wifi features to be enabled, those two properties must be set.
To turn it off, either of preference must be set as an empty string, that is a pair of double quotes each:
To turn it off, either preference must be set as an empty string, that is a pair of double quotes each:
`wifi_ssid ""`
`wifi_password ""`

6
docs/software/web/development.md
View file

@ -7,9 +7,9 @@ sidebar_label: Development
## Considerations
We have a total of 458752 bytes (448KB) available on the SPIFFS (Serial Peripheral Interface Flash File System) -- the on board storage of the ESP32. Of that space, let's not use more than half of that (224KB) in order to leave space for other uses.
We have a total of 458,752 bytes (448KB) available on the SPIFFS (Serial Peripheral Interface Flash File System) -- the on-board storage of the ESP32. Of that space, let's not use more than half of that (224KB) in order to leave space for other uses.
Right now, the Meshtastic Device Preferences as well as SSL keys use that space. We can imagine other future uses as well such as logging chat messages and possibly saving received signal strength with GPS coordinates to create coverage heat maps.
Right now, the Meshtastic Device Preferences as well as SSL keys use that space. We can imagine other future uses as well, such as logging chat messages and possibly saving received signal strength with GPS coordinates to create coverage heat maps.
## Static Files
@ -62,7 +62,7 @@ Used by the Apple Captive Portal Assistant.
### /upload
End point to upload files. Used by the file manager.
Endpoint to upload files. Used by the file manager.
### /json/report

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

@ -26,7 +26,7 @@ https://meshtastic.discourse.group/t/solved-help-installing-with-other-than-esph
```powershell
pio run --target erase --environment tbeam
```
Then re-install the firmware ie using ESPHome Flasher
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).
@ -42,7 +42,7 @@ esptool.py --baud 921600 write_flash 0x10000 firmware-tbeam-EU865-1.1.42.bin
Requires: [Python](https://www.python.org/) and [esptool.py](https://github.com/espressif/esptool)
### Visual Studio & PlatformIO
There is also the method of using the Visual Studio IDE. This requires having Visual Studio and PlatformIO installed, along with having cloned the meshtastic-device code as per the [build instructions](https://meshtastic.org/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.
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)
@ -54,4 +54,4 @@ Requires: [Visual Studio Code](https://code.visualstudio.com/), [PlatformIO](htt
Once it has been successfully erased and re-flashed, visiting https://192.168.42.1/static should leave you with free space on the order of 300,000 bytes, rather than the ~48,000 bytes you currently have. You can then upload the files from the meshtastic-web release.
Occasionally this may glitch when uploading the larger app.js.gz file, but a further erase and flash typically solves this.
Occasionally, this may glitch may appear when uploading the larger app.js.gz file, but a further erase and flash typically solves this.

2
docs/software/web/usage.md
View file

@ -24,7 +24,7 @@ Cause: This most likely means that the file system for the web server has not be
Solutions:
Option 1) Flash the device with the `device-install.sh` script that comes packaged with the firmware zip file (you'll lose previous settings). Then follow the instructions under configuration to upload the web interface
Option 1) Flash the device with the `device-install.sh` script that comes packaged with the firmware zip file (you'll lose previous settings). Then follow the instructions under configuration to upload the web interface.
Option 2) Flash the device with the OTA update from within the Android application.

2
docs/software/web/web-app.md
View file

@ -7,5 +7,5 @@ sidebar_label: Overview
The Meshtastic firmware incorporates an embedded web server using the [ESP32 HTTPS Server](https://github.com/fhessel/esp32_https_server) project. This allows the Wifi supporting ESP32 devices to run our web interface to access Meshtastic directly from your browser. This imports the [Meshtastic.js library](/docs/software/js/getting-started) to provide a web page capable of interacting with the device.
:::caution
Please note that this is under active development and liable to change
Please note that this is under active development and liable to change.
:::