mirror of
https://github.com/meshtastic/meshtastic.git
synced 2024-12-27 14:39:54 -08:00
Merge pull request #365 from meshtastic/delete_broken_pages
Delete broken and duplicate pages, consolidate all firmware module documentation in one place
This commit is contained in:
Garth Vander Houwen
GitHub
commit
12c7ffd310
|
|
@ -1,17 +0,0 @@
|
|||
Modules are included in the firmware and allow users to extend the functionality of their mesh or device.
|
||||
|
||||
The list of current modules is as follows:
|
||||
|
||||
| Name | Description |
|
||||
|:----:|:-----------:|
|
||||
| Canned Message Module | Set a number of predefined messages to send out directly from the device with the use of an input device like a rotary encoder. |
|
||||
| External Notification Module | Incoming messages are able to alert you using circuits you attach to the device (LEDs, Buzzers, etc) |
|
||||
| Input Broker Module | Attach and define input devices such as external keyboards and rotary encoders. |
|
||||
| Range Test Module | Send messages with GPS location at an interval to test the distance your devices can communicate. Requires (at least) one device set up as a sender and one as a receiver. The receiver(s) will log all incoming messages to a CSV. |
|
||||
| Serial Module | Send messages across the mesh by sending strings over a serial port. |
|
||||
| Store and Forward Module | Set a designated node to store messages and resend them to nodes with intermittent connection to a mesh. |
|
||||
| Telemetry Module | Attach sensors to the device and transmit readings on a regular interval to the mesh. |
|
||||
|
||||
:::tip
|
||||
Once module settings are changed, a **reset** is required for them to take effect.
|
||||
:::
|
||||
|
|
@ -41,7 +41,7 @@ A number of [key services](http://github.com/meshtastic/meshtastic-device/tree/m
|
|||
|
||||
- [TextMessageModule](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules/TextMessageModule.h) - receives text messages and displays them on the LCD screen/stores them in the local DB
|
||||
- [NodeInfoModule](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules/NodeInfoModule.h) - receives/sends User information to other nodes so that usernames are available in the databases
|
||||
- [RemoteHardwareModule](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules/RemoteHardwareModule.h) - a module that provides easy remote access to device hardware (for things like turning GPIOs on or off). Intended to be a more extensive example and provide a useful feature of its own. See [remote-hardware](/docs/software/other/remote-hardware-service) for details.
|
||||
- [RemoteHardwareModule](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules/RemoteHardwareModule.h) - a module that provides easy remote access to device hardware (for things like turning GPIOs on or off). Intended to be a more extensive example and provide a useful feature of its own. See [remote-hardware](/docs/software/device/remote-hardware-service) for details.
|
||||
- [ReplyModule](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules/ReplyModule.h) - a simple module that just replies to any packet it receives (provides a 'ping' service).
|
||||
|
||||
## Getting started
|
||||
|
|
@ -57,7 +57,7 @@ The easiest way to get started is:
|
|||
## Threading
|
||||
|
||||
It is very common that you would like your module to be invoked periodically.
|
||||
We use a crude/basic cooperative threading system to allow this on any of our supported platforms. Simply inherit from OSThread and implement runOnce(). See the OSThread [documentation](http://github.com/meshtastic/meshtastic-device/tree/master/src/concurrency/OSThread.h) for more details. For an example consumer of this API see RemoteHardwareModule::runOnce.
|
||||
We use a crude/basic cooperative threading system to allow this on any of our supported platforms. Simply inherit from OSThread and implement runOnce(). See the OSThread [documentation](http://github.com/meshtastic/meshtastic-device/tree/master/src/concurrency/OSThread.h) for more details.
|
||||
|
||||
## Sending messages
|
||||
|
||||
|
|
@ -80,6 +80,6 @@ All other values are reserved.
|
|||
|
||||
If you would like to use protocol buffers to define the structures you send over the mesh (recommended), here's how to do that.
|
||||
|
||||
- Create a new .proto file in the protos directory. You can use the existing [remote_hardware.proto](https://github.com/meshtastic/Meshtastic-protobufs/blob/master/remote_hardware.proto) file as an example.
|
||||
- Create a new .proto file in the protos directory.
|
||||
- Run "bin/regen-protos.sh" to regenerate the C code for accessing the protocol buffers. If you don't have the required nanopb tool, follow the instructions printed by the script to get it.
|
||||
- Done! You can now use your new protobuf just like any of the existing protobufs in meshtastic.
|
||||
|
|
|
|||
|
|
@ -4,4 +4,5 @@ label: 'Developers'
|
|||
collapsible: true # make the category collapsible
|
||||
link:
|
||||
type: generated-index
|
||||
title: Developers
|
||||
title: Developers
|
||||
slug: /developers
|
||||
|
|
@ -30,7 +30,7 @@ The [Meshtastic-device](https://github.com/meshtastic/Meshtastic-device) is wher
|
|||
|
||||
## Modules
|
||||
|
||||
[Modules](/docs/software/modules) are also implemented mainly in the Meshtastic-device repo above. Typically, you would add functionality in the protobufs repo and the device repo to implement module functionality. You probably also want to have some client/device use/interact with the module and that is where the Device support comes into play.
|
||||
[Modules](/docs/settings/moduleconfig) are also implemented mainly in the Meshtastic-device repo above. Typically, you would add functionality in the protobufs repo and the device repo to implement module functionality. You probably also want to have some client/device use/interact with the module and that is where the Device support comes into play.
|
||||
|
||||
## Device Support
|
||||
|
||||
|
|
|
|||
|
|
@ -24,4 +24,4 @@ This is the first channel that's created for you when you initially setup your M
|
|||
|
||||
### 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 is pending. [See further details here](/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.
|
||||
|
|
|
|||
|
|
@ -34,4 +34,4 @@ After reading this FAQ and checking out the links on the left, there are two pla
|
|||
|
||||
### How can I contribute to Meshtastic?
|
||||
|
||||
Everyone contributes in a different way. Join the [Forum](https://meshtastic.discourse.group) and/or the [Meshtastic Discord](https://discord.gg/ktMAKGBnBs) and introduce yourself. We're all very friendly. If you'd like to pitch in some code, check out the [Developers](/docs/category/developers) menu on the left.
|
||||
Everyone contributes in a different way. Join the [Forum](https://meshtastic.discourse.group) and/or the [Meshtastic Discord](https://discord.gg/ktMAKGBnBs) and introduce yourself. We're all very friendly. If you'd like to pitch in some code, check out the [Developers](/docs/developers) menu on the left.
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ Modules are features that expand the basic device functionality and/or integrate
|
|||
|
||||
### What modules do we have available?
|
||||
|
||||
A list of available modules is available [here](/docs/software/modules).
|
||||
A list of available modules is available [here](/docs/settings/moduleconfig).
|
||||
|
||||
### I'd like to write a module. How do I get started?
|
||||
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ As mentioned, while stating the obvious, the simplest way of performing a test i
|
|||
- Change aerials, repeat, and evaluate results.
|
||||
|
||||
:::note
|
||||
The [range test module](/docs/software/modules/range-test-module) has been designed for exactly this purpose. It allows one node to transmit a frequent message, and another node to record which messages were received. This data is saved and can be imported to applications such as Google Earth.
|
||||
The [range test module](/docs/settings/moduleconfig/range-test) has been designed for exactly this purpose. It allows one node to transmit a frequent message, and another node to record which messages were received. This data is saved and can be imported to applications such as Google Earth.
|
||||
:::
|
||||
|
||||
On the topic of testing - performing your own testing and providing feedback is the lifeblood of Meshtastic and open source projects.
|
||||
|
|
|
|||
|
|
@ -88,3 +88,37 @@ Toggling `set-ham` changes your device settings in the following ways.
|
|||
| `long_name` (Protobuf) | `id` | User Defined |
|
||||
| `psk` (Protobuf) | `""` | See [Channel Settings - psk](channel#psk) |
|
||||
| `short_name` (Protobuf) | TODO | User Defined |
|
||||
|
||||
# Ham Operators
|
||||
|
||||
(This written US only, may be applicable elsewhere)
|
||||
|
||||
Meshtastic can be used by both unlicensed people and licensed operators.
|
||||
|
||||
Having a ham radio license grants you addition privilages and restrictions.
|
||||
|
||||
# Additional privilages
|
||||
|
||||
- Additional power
|
||||
- Higher gain antennas
|
||||
|
||||
# Restrictions
|
||||
|
||||
- Unencrypted
|
||||
- Identified with your ID
|
||||
|
||||
# Let's do it!
|
||||
|
||||
Remember, by doing this you are self certifying that you are licensed operate in the mode you have chosen. Failure to comply with your local regulations may result in fines.
|
||||
|
||||
## Use the Python CLI
|
||||
|
||||
Meshtastic is designed to be used without a radio operator license. If you do have a license you can set your operator ID and turn off encryption with the [Python CLI](/docs/software/python/python-uses#ham-radio-support):
|
||||
|
||||
```shell title="Expected Output"
|
||||
# You should see a result similar to this:
|
||||
mydir$ meshtastic --port /dev/ttyUSB1 --set-ham KI1345
|
||||
Connected to radio
|
||||
Setting Ham ID to KI1345 and turning off encryption
|
||||
Writing modified channels to device
|
||||
```
|
||||
|
|
|
|||
|
|
@ -274,3 +274,49 @@ meshtastic --set rotary1_enabled True
|
|||
|
||||
:::
|
||||
That's it! With a functioning and enabled rotary encoder, you're ready to begin configuring the Canned Message Module.
|
||||
|
||||
## Hardware
|
||||
|
||||
To navigate through messages and select one, you will require some hardware attached to your device. Currently, the module is tested with a generic rotary encoder, but this is not a limitation further input methods can be added in the future.
|
||||
|
||||
### Rotary encoder
|
||||
|
||||
Meshtastic supports hardwired rotary encoders as input devices. (Technically the Canned Message Module is independent of rotary encoders. It is described here, because no other module utilizes rotary encoders just yet.)
|
||||
|
||||
You will need a generic rotary encoder. The types listed below has five legs where two is dedicated to a "press" action, but any other types will likely do the job. You can also use a three-legged version, where the "press" action should be wired from an independent switch.
|
||||
|
||||
<!--- TODO move links to hardware section --->
|
||||
|
||||
- [Amazon link](https://www.amazon.com/Rotary-Encoder-Washers-Digital-Potentiometer/dp/B07Y619CZR/ref=sr_1_21?keywords=rotary+encoder&qid=1642317807&sprefix=rotary+enco%2Caps%2C186&sr=8-21)
|
||||
- [Amazon.DE link](https://www.amazon.de/-/en/sourcing-Degree-Rotary-Encoder-Digital/dp/B07RLZPX5K/ref=sr_1_12?keywords=rotary+encoder&qid=1642320025&sprefix=rotary%2Caps%2C105&sr=8-12)
|
||||
- [Aliexpress link1](https://www.aliexpress.com/item/32992227812.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-23&pdp_ext_f=%7B%22sku_id%22%3A%2266940265509%22%7D&pdp_pi=-1%3B1.66%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch)
|
||||
- [Aliexpress link2](https://www.aliexpress.com/item/32946444853.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&aem_p4p_detail=2022011523263276283624312400022072680&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-6&pdp_ext_f=%7B%22sku_id%22%3A%2266223434642%22%7D&pdp_pi=-1%3B1.91%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch)
|
||||
- [Aliexpress link3](https://www.aliexpress.com/item/10000056483250.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-9&pdp_ext_f=%7B%22sku_id%22%3A%2220000000116682147%22%7D&pdp_pi=-1%3B2.51%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch)
|
||||
|
||||
Connect your rotary encoder as follows. The rotary encoder has two rows of legs. One of the rows contains two legs, the other contains three legs. Bottom side view:
|
||||
|
||||
```
|
||||
B o --- o PRESS
|
||||
GND o | |
|
||||
A o --- o GND
|
||||
```
|
||||
|
||||
The two legs is to sense the press action (or push). Connect one of the two to GROUND and the other to a GPIO pin. (No matter which one goes where.) Let's call this connected ports 'PRESS'.
|
||||
|
||||
The three legs is to sense the rotation action. Connect the middle leg to GROUND and the ones on the side to GPIO pins. Let's call these ports 'A' and 'B', according to the scheme below.
|
||||
|
||||
```
|
||||
A --||
|
||||
GND --||]========
|
||||
B --||
|
||||
```
|
||||
|
||||
Recommended GPIO pins for connecting a rotary encoder.
|
||||
|
||||
- TTGO LoRa V1:
|
||||
- A - GPIO-22
|
||||
- B - GPIO-23
|
||||
- PRESS - GPIO-21
|
||||
|
||||
There is a reference case 3D-design utilizing the rotary encoder for TTGO LoRa V1:
|
||||
[Case for TTGO-ESP32-LORA-OLED-v1.0 with rotary encoder](https://www.thingiverse.com/thing:5178495)
|
||||
|
|
|
|||
|
|
@ -131,4 +131,36 @@ External Notification module config is not available for the Web UI.
|
|||
|
||||
:::tip
|
||||
Once module settings are changed, a **reset** is required for them to take effect.
|
||||
:::
|
||||
:::
|
||||
|
||||
## Examples
|
||||
|
||||
### Alert Types
|
||||
|
||||
We support being alerted on two events:
|
||||
|
||||
1. Incoming Text Message
|
||||
|
||||
2. Incoming Text Message that contains the ASCII bell character. At present, only the Python API can send an ASCII bell character, but more support may be added in the future.
|
||||
|
||||
:::info
|
||||
The bell character is ASCII 0x07. Include 0x07 anywhere in the text message and with ext_notification_module_alert_bell enabled, we will issue an external notification.
|
||||
:::
|
||||
|
||||
## External Hardware
|
||||
|
||||
Be mindful of the max current sink and source of the ESP32 GPIO. The easiest devices to interface with would be either an LED or Active Buzzer.
|
||||
|
||||
Ideas for external hardware:
|
||||
|
||||
- LED
|
||||
- Active Buzzer
|
||||
- Flame thrower
|
||||
- Strobe Light
|
||||
- Siren
|
||||
|
||||
## Known Problems
|
||||
|
||||
- This won't directly support a passive (normal) speaker as it does not generate any audio wave forms.
|
||||
- This currently only supports the ESP32. Other targets may be possible, I just don't have to test with.
|
||||
- This module only monitors text messages. We won't trigger on any other packet types.
|
||||
|
|
|
|||
|
|
@ -7,11 +7,10 @@ sidebar_label: Range Test
|
|||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
This module allows you to test the range of your Meshtastic nodes. It requires at least two nodes, a sender and a receiver. The receiving node then saves the messages along with the GPS coordinates at which they were received into a .csv file. This .csv file can then be integrated into [Google Earth](https://earth.google.com), [Google Maps - My Maps](https://mymaps.google.com), or any other program capable of processing .csv files. This can enable you to visualize your mesh.
|
||||
|
||||
The range test module config options are: Enabled, Save, and Sender. Range Test Module config uses an admin message sending a `ConfigModule.RangeTest` protobuf.
|
||||
|
||||
This module allows you to test the range of your Meshtastic nodes. It requires at least two nodes, a sender and a receiver. The receiving node then saves the messages along with the GPS coordinates at which they were received into a .csv file. This .csv file can then be integrated into [Google Earth](https://earth.google.com), [Google Maps - My Maps](https://mymaps.google.com), or any other program capable of processing .csv files. This can enable you to visualize your mesh.
|
||||
|
||||
## Range Test Module Config Values
|
||||
|
||||
### Enabled
|
||||
|
|
@ -99,7 +98,7 @@ All range test module config options are available in the Web UI.
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Details
|
||||
## Examples
|
||||
|
||||
While a minimum of two radios is required, more can be used. You can have any number of receivers and senders that your mesh is able to handle. You can test having a single sender with multiple receivers or a single receiver with multiple senders. Let us know on the [forum thread](https://meshtastic.discourse.group/t/new-plugin-rangetestplugin/2591) the results of your configuration.
|
||||
|
||||
|
|
@ -127,4 +126,67 @@ http://198.168.0.15
|
|||
| Long Slow | 60 |
|
||||
| Long Alt | 30 |
|
||||
| Medium | 15 |
|
||||
| Short Fast | 15 |
|
||||
| Short Fast | 15 |
|
||||
|
||||
|
||||
|
||||
## Application Examples
|
||||
|
||||
### Google Earth Integration
|
||||
|
||||
Steps:
|
||||
|
||||
1. [Download](https://www.google.com/earth/versions/#download-pro) and open Google Earth
|
||||
1. Select File > Import
|
||||
2. Select CSV
|
||||
3. Select Delimited, Comma
|
||||
4. Make sure the button that states “This dataset does not contain latitude/longitude information, but street addresses” is unchecked
|
||||
5. Select “rx lat” & “rx long” for the appropriate lat/lng fields
|
||||
6. Click finish
|
||||
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.
|
||||
|
||||
Your data will load onto the map, make sure to click the checkbox next to your dataset in the sidebar to view it.
|
||||
|
||||
### My Maps
|
||||
|
||||
You can use [My Maps](http://mymaps.google.com). It takes CSVs and the whole interface is much easier to work with.
|
||||
|
||||
Google has instructions on how to do that [here](https://support.google.com/mymaps/answer/3024836?co=GENIE.Platform%3DDesktop&hl=en#zippy=%2Cstep-prepare-your-info%2Cstep-import-info-into-the-map).
|
||||
|
||||
You can style the ranges differently based on the values, so you can have the pins be darker the if the SNR or RSSI (if that gets added) is higher.
|
||||
|
||||
## FAQ
|
||||
|
||||
Q: Where is rangetest.csv saved?
|
||||
|
||||
- Turn on the WiFi on your device as either a WiFi client or a WiFi AP. Once you can connect to your device, navigate to `Extensions > File Browser` and you will see `rangetest.csv` once messages have been saved and the file has been created.
|
||||
|
||||
Q: Do I need to have WiFi turned on for the file to be saved?
|
||||
|
||||
- Nope, it'll just work.
|
||||
|
||||
Q: Do I need a phone for this module?
|
||||
|
||||
- There's no need for a phone.
|
||||
|
||||
Q: Can I use this as a message logger?
|
||||
|
||||
- While it's not the intended purpose, sure, why not. Do it!
|
||||
|
||||
Q: What will happen if I run out of space on my device?
|
||||
|
||||
- We have a protection in place to keep you from completely filling up your device. This will make sure that other device critical functions will continue to work. We will reserve at least 50k of free space.
|
||||
|
||||
Q: What do I do with the rangetest.csv file when I'm done?
|
||||
|
||||
- Go to /static and delete the file.
|
||||
|
||||
Q: Can I use this as a sender while on battery power?
|
||||
|
||||
- Yes, but your battery will run down quicker than normal. While sending, we tell the device not to go into low-power mode since it needs to keep to a fairly strict timer.
|
||||
|
||||
Q: Why is this operating on incoming messages instead of the existing location discovery protocol?
|
||||
|
||||
- This module is still young and currently supports monitoring just one port at a time. I decided to use the existing message port because that is easy to test with. A future version will listen to multiple ports to be more promiscuous.
|
||||
|
|
|
|||
|
|
@ -143,4 +143,19 @@ All serial test module config options are available in the Web UI.
|
|||
:::
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
</Tabs>
|
||||
|
||||
## Examples
|
||||
|
||||
Default is to use RX GPIO 16 and TX GPIO 17.
|
||||
### Basic Usage:
|
||||
|
||||
1. Enable the module by setting `serial_module_enabled` to `1`.
|
||||
2. Set the pins (`serial_module_rxd` / `serial_module_rxd`) for your preferred RX and TX GPIO pins. On tbeam boards it is recommended to use:
|
||||
- RXD 35
|
||||
- TXD 15
|
||||
3. Set `serial_module_timeout` to the amount of time to wait before we consider your packet as "done".
|
||||
4. (Optional) In serial_module.h set the port to `PortNum_TEXT_MESSAGE_APP`if you want to send messages to/from the general text message channel.
|
||||
5. Connect to your device over the serial interface at `38400 8N1`.
|
||||
6. Send a packet up to 240 bytes in length. This will get relayed over the mesh network.
|
||||
7. (Optional) Set `serial_module_echo` to `1` and any message you send out will be echoed back to your device.
|
||||
|
|
@ -504,3 +504,40 @@ The sensors can be wired differently, here's [one example](https://randomnerdtut
|
|||
### Known Problems
|
||||
|
||||
- No default configuration values are currently set, so this must be done when enabling the module.
|
||||
|
||||
|
||||
|
||||
## Examples
|
||||
|
||||
### RAK 4631 with Environment Sensor
|
||||
|
||||
Setup of a RAK 4631 with Environment Sensor
|
||||
|
||||
[<img src="RAK4631_with_EnvSensor" src="/img/hardware/rak/RAK4631_with_EnvSensor.jpg" style={{zoom:'25%'}} />](/img/hardware/rak/RAK4631_with_EnvSensor.jpg)
|
||||
|
||||
Requirements:
|
||||
|
||||
- RAK4631
|
||||
- Environment Sensor
|
||||
|
||||
Steps:
|
||||
|
||||
- configure the device:
|
||||
|
||||
```shell
|
||||
meshtastic --set telemetry_module_measurement_enabled true --set telemetry_module_screen_enabled true --set telemetry_module_update_interval 15 --set telemetry_module_display_farenheit true --set telemetry_module_sensor_type 6
|
||||
```
|
||||
|
||||
:::tip
|
||||
You can change the values above to suit your needs. The commands can be run one at a time or in a group as show above.
|
||||
:::
|
||||
|
||||
- reboot/reset the device (press the button or unplug/plug in the device)
|
||||
- when the device boots it should say "Telemetry" and it may show the sensor data
|
||||
- if still "no data", run:
|
||||
|
||||
```shell
|
||||
meshtastic --info
|
||||
```
|
||||
|
||||
and verify the the `telemetry_module_sensor_type`
|
||||
|
|
@ -4,4 +4,5 @@ label: Software
|
|||
collapsible: true # make the category collapsible
|
||||
link:
|
||||
type: generated-index
|
||||
title: Software
|
||||
title: Software
|
||||
slug: /software
|
||||
|
|
@ -1,66 +0,0 @@
|
|||
---
|
||||
id: device-channels
|
||||
title: Multiple channel support
|
||||
sidebar_label: Multiple channels
|
||||
---
|
||||
|
||||
:::warning
|
||||
Multiple channel support is currently an experimental feature that is ONLY supported by the Python CLI and WebUI right now.
|
||||
:::
|
||||
|
||||
Version 1.2 of the software adds support for multiple (simultaneous) channels. The idea behind this feature is that a mesh can allow multiple users/groups to be share common mesh infrastructure. Even including routing messages for others when no one except that subgroup of users has the encryption keys for their private channel.
|
||||
|
||||
### What is the Primary channel
|
||||
|
||||
The way this works is that each node keeps a list of channels it knows about. One of those channels (normally the first one) is labeled as the "PRIMARY" channel. The primary channel is the **only** channel that is used to set radio parameters. This channel controls things like spread factor, coding rate, bandwidth etc... Indirectly this channel also is used to select the specific frequency that all members of this mesh are talking over.
|
||||
|
||||
This channel may or may not have a PSK (encryption). If you are providing mesh to 'the public' we recommend that you always leave this channel with its default PSK. The default PSK is technically encrypted (and random users sniffing the ether would have to use Meshtastic to decode it), but the key is included in the GitHub source code and you should assume any 'attacker' would have it. But for a 'public' mesh you want this, because it allows anyone using Meshtastic in your area to send packets through 'your' mesh.
|
||||
|
||||
```shell title="Setting default channel"
|
||||
$ meshtastic --seturl https://www.meshtastic.org/d/#CgUYAyIBAQ
|
||||
Connected to radio
|
||||
```
|
||||
|
||||
The device will now have its primary channel set to the default:
|
||||
|
||||
```shell title="Expected output"
|
||||
$ meshtastic --info
|
||||
Connected to radio
|
||||
...
|
||||
Channels:
|
||||
PRIMARY psk=default { "modemConfig": "Bw125Cr48Sf4096", "psk": "AQ==" }
|
||||
Primary channel URL: https://www.meshtastic.org/d/#CgUYAyIBAQ
|
||||
```
|
||||
|
||||
### How to use Secondary channels
|
||||
|
||||
Any channel you add after that Primary channel is Secondary. Secondary channels are used only for encryption and (in the case of some special applications) security. If you would like to have a private channel over a more public mesh, you probably want to create a secondary channel. When sharing that URL with your private group you will share the "Complete URL". The complete URL includes your secondary channel (for encryption) and the primary channel (to provide radio/mesh access).
|
||||
|
||||
Secondary channels **must** have a PSK (encryption).
|
||||
|
||||
```shell title="Adding a channel called testing"
|
||||
$ meshtastic --ch-add testing
|
||||
Connected to radio
|
||||
Writing modified channels to device
|
||||
```
|
||||
|
||||
The device will now have a Secondary channel called "testing"
|
||||
|
||||
```shell title="Expected output"
|
||||
$ meshtastic --info
|
||||
Connected to radio
|
||||
...
|
||||
Channels:
|
||||
PRIMARY psk=default { "modemConfig": "Bw125Cr48Sf4096", "psk": "AQ==" }
|
||||
SECONDARY psk=secret { "psk": "HW7E3nMbiNbvr6MhsDonLCmj7eSAhttzjbIx/r5OQmg=", "name": "testing" }
|
||||
Primary channel URL: https://www.meshtastic.org/d/#CgUYAyIBAQ
|
||||
Complete URL (includes all channels): https://www.meshtastic.org/d/#CgUYAyIBAQopIiAdbsTecxuI1u-voyGwOicsKaPt5ICG23ONsjH-vk5CaCoFYWRtaW4
|
||||
```
|
||||
|
||||
Secondary channels can be deleted by specifying their index, otherwise ch-del will attempt to delete channel index 0
|
||||
|
||||
```shell title="Deleting a secondary channel"
|
||||
$ meshtastic --ch-index 1 --ch-del
|
||||
Connected to radio
|
||||
Deleting channel 1
|
||||
```
|
||||
|
|
@ -1,43 +0,0 @@
|
|||
---
|
||||
id: ham
|
||||
title: Licensed (HAM) Operation
|
||||
sidebar_label: Licensed (HAM) Operation
|
||||
slug: /software/device/ham
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Ham Operators
|
||||
|
||||
(This written US only, may be applicable elsewhere)
|
||||
|
||||
Meshtastic can be used by both unlicensed people and licensed operators.
|
||||
|
||||
Having a ham radio license grants you addition privilages and restrictions.
|
||||
|
||||
# Additional privilages
|
||||
|
||||
- Additional power
|
||||
- Higher gain antennas
|
||||
|
||||
# Restrictions
|
||||
|
||||
- Unencrypted
|
||||
- Identified with your ID
|
||||
|
||||
# Let's do it!
|
||||
|
||||
Remember, by doing this you are self certifying that you are licensed operate in the mode you have chosen. Failure to comply with your local regulations may result in fines.
|
||||
|
||||
## Use the Python CLI
|
||||
|
||||
Meshtastic is designed to be used without a radio operator license. If you do have a license you can set your operator ID and turn off encryption with the [Python CLI](/docs/software/python/python-uses#ham-radio-support):
|
||||
|
||||
```shell title="Expected Output"
|
||||
# You should see a result similar to this:
|
||||
mydir$ meshtastic --port /dev/ttyUSB1 --set-ham KI1345
|
||||
Connected to radio
|
||||
Setting Ham ID to KI1345 and turning off encryption
|
||||
Writing modified channels to device
|
||||
```
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
id: device-power
|
||||
title: Power Management State Machine
|
||||
sidebar_label: Power Management
|
||||
title: 1.2 Power Management State Machine
|
||||
sidebar_label: 1.2 Power Management
|
||||
---
|
||||
|
||||
Long battery life is one of the main goals of this project. Based on initial measurements, the current code should run for about three days between charging (assuming using a t-beam with a 3500mAh 18650 battery). This will hopefully be increased to around eight days in the future.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
id: device-remote-admin
|
||||
title: Remote node administration
|
||||
sidebar_label: Remote node administration
|
||||
title: 1.2 Remote node administration
|
||||
sidebar_label: 1.2 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.
|
||||
|
|
@ -53,7 +53,7 @@ Notice that now we have a new secondary channel and the `--info` option prints o
|
|||
|
||||
## Sharing the admin channel with other nodes
|
||||
|
||||
Creating an "admin" channel automatically generates a preshared key, just like with [Multiple channel support](./device-channels). In order to administer to other nodes remotely, we need to copy the preshared key to the new nodes.
|
||||
Creating an "admin" channel automatically generates a preshared key. In order to administer to other nodes remotely, we need to copy the preshared key to the new nodes.
|
||||
|
||||
For this step you need physical access to both the nodes.
|
||||
|
||||
|
|
|
|||
|
|
@ -168,4 +168,4 @@ Received RemoteHardware typ=GPIOS_CHANGED, gpio_value=16
|
|||
Received RemoteHardware typ=GPIOS_CHANGED, gpio_value=0
|
||||
Received RemoteHardware typ=GPIOS_CHANGED, gpio_value=16
|
||||
< press ctrl-c to exit >
|
||||
```
|
||||
```
|
||||
|
|
@ -4,4 +4,5 @@ label: 'Javascript'
|
|||
collapsible: true # make the category collapsible
|
||||
link:
|
||||
type: generated-index
|
||||
title: Javascript
|
||||
title: Javascript
|
||||
slug: /software/js
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
|
||||
position: 5 # float position is supported
|
||||
label: Firmware Modules
|
||||
collapsible: true # make the category collapsible
|
||||
link:
|
||||
type: generated-index
|
||||
title: Firmware Modules
|
||||
|
|
@ -1,65 +0,0 @@
|
|||
---
|
||||
id: canned-message-module
|
||||
title: Canned messages
|
||||
sidebar_label: Canned messages
|
||||
sidebar_position: 3
|
||||
---
|
||||
## About
|
||||
|
||||
The Canned Message Module will allow you to send messages to the mesh network from the device without using the phone app. You can predefine text messages to choose from.
|
||||
|
||||
## Hardware
|
||||
|
||||
To navigate through messages and select one, you will require some hardware attached to your device. Currently, the module is tested with a generic rotary encoder, but this is not a limitation further input methods can be added in the future.
|
||||
|
||||
### Rotary encoder
|
||||
|
||||
Meshtastic supports hardwired rotary encoders as input devices. (Technically the Canned Message Module is independent of rotary encoders. It is described here, because no other module utilizes rotary encoders just yet.)
|
||||
|
||||
You will need a generic rotary encoder. The types listed below has five legs where two is dedicated to a "press" action, but any other types will likely do the job. You can also use a three-legged version, where the "press" action should be wired from an independent switch.
|
||||
|
||||
<!--- TODO move links to hardware section --->
|
||||
|
||||
- [Amazon link](https://www.amazon.com/Rotary-Encoder-Washers-Digital-Potentiometer/dp/B07Y619CZR/ref=sr_1_21?keywords=rotary+encoder&qid=1642317807&sprefix=rotary+enco%2Caps%2C186&sr=8-21)
|
||||
- [Amazon.DE link](https://www.amazon.de/-/en/sourcing-Degree-Rotary-Encoder-Digital/dp/B07RLZPX5K/ref=sr_1_12?keywords=rotary+encoder&qid=1642320025&sprefix=rotary%2Caps%2C105&sr=8-12)
|
||||
- [Aliexpress link1](https://www.aliexpress.com/item/32992227812.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-23&pdp_ext_f=%7B%22sku_id%22%3A%2266940265509%22%7D&pdp_pi=-1%3B1.66%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch)
|
||||
- [Aliexpress link2](https://www.aliexpress.com/item/32946444853.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&aem_p4p_detail=2022011523263276283624312400022072680&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-6&pdp_ext_f=%7B%22sku_id%22%3A%2266223434642%22%7D&pdp_pi=-1%3B1.91%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch)
|
||||
- [Aliexpress link3](https://www.aliexpress.com/item/10000056483250.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-9&pdp_ext_f=%7B%22sku_id%22%3A%2220000000116682147%22%7D&pdp_pi=-1%3B2.51%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch)
|
||||
|
||||
Connect your rotary encoder as follows. The rotary encoder has two rows of legs. One of the rows contains two legs, the other contains three legs. Bottom side view:
|
||||
|
||||
```
|
||||
B o --- o PRESS
|
||||
GND o | |
|
||||
A o --- o GND
|
||||
```
|
||||
|
||||
The two legs is to sense the press action (or push). Connect one of the two to GROUND and the other to a GPIO pin. (No matter which one goes where.) Let's call this connected ports 'PRESS'.
|
||||
|
||||
The three legs is to sense the rotation action. Connect the middle leg to GROUND and the ones on the side to GPIO pins. Let's call these ports 'A' and 'B', according to the scheme below.
|
||||
|
||||
```
|
||||
A --||
|
||||
GND --||]========
|
||||
B --||
|
||||
```
|
||||
|
||||
Recommended GPIO pins for connecting a rotary encoder.
|
||||
|
||||
- TTGO LoRa V1:
|
||||
- A - GPIO-22
|
||||
- B - GPIO-23
|
||||
- PRESS - GPIO-21
|
||||
|
||||
There is a reference case 3D-design utilizing the rotary encoder for TTGO LoRa V1:
|
||||
[Case for TTGO-ESP32-LORA-OLED-v1.0 with rotary encoder](https://www.thingiverse.com/thing:5178495)
|
||||
|
||||
## Configuration
|
||||
|
||||
Configuration details are available on the [Device Settings](/docs/settings) pages. Configuring the Canned Message Module requires configuring both of the following modules:
|
||||
- [Input Broker Module](/docs/settings/modules/input-broker-module)
|
||||
- [Canned Message Module](/docs/settings/modules/canned-message-module).
|
||||
|
||||
## Known Problems
|
||||
|
||||
- Rotary encoder input uses a technology called "interrupts". Using the rotary encoder might cause unexpected software problems. This needs to be tested.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
---
|
||||
id: ext-notif-module
|
||||
title: External notifications
|
||||
sidebar_label: External notifications
|
||||
sidebar_position: 2
|
||||
---
|
||||
## About
|
||||
|
||||
The ExternalNotification Module will allow you to connect a speaker, LED or other device to notify you when a message has been received from the mesh network.
|
||||
|
||||
### Alert Types
|
||||
|
||||
We support being alerted on two events:
|
||||
|
||||
1. Incoming Text Message
|
||||
|
||||
2. Incoming Text Message that contains the ASCII bell character. At present, only the Python API can send an ASCII bell character, but more support may be added in the future.
|
||||
|
||||
:::info
|
||||
The bell character is ASCII 0x07. Include 0x07 anywhere in the text message and with ext_notification_module_alert_bell enabled, we will issue an external notification.
|
||||
:::
|
||||
|
||||
## External Hardware
|
||||
|
||||
Be mindful of the max current sink and source of the ESP32 GPIO. The easiest devices to interface with would be either an LED or Active Buzzer.
|
||||
|
||||
Ideas for external hardware:
|
||||
|
||||
- LED
|
||||
- Active Buzzer
|
||||
- Flame thrower
|
||||
- Strobe Light
|
||||
- Siren
|
||||
|
||||
## Configuration
|
||||
|
||||
Configuration details are available on the [Device Settings](/docs/settings) pages. Configuring the External Notification Module requires configuring the following modules:
|
||||
- [External Notification Module](/docs/settings/modules/external-notification-module)
|
||||
|
||||
## Known Problems
|
||||
|
||||
- This won't directly support a passive (normal) speaker as it does not generate any audio wave forms.
|
||||
- This currently only supports the ESP32. Other targets may be possible, I just don't have to test with.
|
||||
- This module only monitors text messages. We won't trigger on any other packet types.
|
||||
|
|
@ -1,12 +0,0 @@
|
|||
---
|
||||
id: modules
|
||||
title: Firmware Modules Overview
|
||||
sidebar_label: Firmware Modules
|
||||
---
|
||||
import ModuleOverviewText from '@site/docs/_blocks/_module_overview_text.mdx';
|
||||
|
||||
<ModuleOverviewText/>
|
||||
|
||||
## Configuration
|
||||
|
||||
Configuration details are available on the [Device Settings](/docs/settings/modules) pages.
|
||||
|
|
@ -1,95 +0,0 @@
|
|||
---
|
||||
id: range-test-module
|
||||
title: Range Test Module
|
||||
sidebar_label: Range Test
|
||||
sidebar_position: 1
|
||||
---
|
||||
## About
|
||||
|
||||
This module allows you to test the range of your Meshtastic nodes. It uses two nodes, one to send a message every minute, and another to receive the messages. The receiving node then saves the messages along with the GPS coordinates at which they were received into a .csv file. This .csv file can then be integrated into, for example, Google Earth, allowing you to see where you have coverage.
|
||||
|
||||
:::info Hardware Compatibility
|
||||
|
||||
The Range Test module is currently only compatible with ESP32 devices. nRF52 devices are not yet supported.
|
||||
|
||||
:::
|
||||
|
||||
### Other things to keep in mind
|
||||
|
||||
Be sure to turn off either the module configured as a sender or the device where the module setup as sender when not in use. This will use a lot of time on air and will spam your channel.
|
||||
|
||||
Also, be mindful of your space usage on the file system. It has protections from filling up the space but it's best to delete old range test results.
|
||||
|
||||
## Application Examples
|
||||
|
||||
### Google Earth Integration
|
||||
|
||||
Steps:
|
||||
|
||||
1. [Download](https://www.google.com/earth/versions/#download-pro) and open Google Earth
|
||||
1. Select File > Import
|
||||
2. Select CSV
|
||||
3. Select Delimited, Comma
|
||||
4. Make sure the button that states “This dataset does not contain latitude/longitude information, but street addresses” is unchecked
|
||||
5. Select “rx lat” & “rx long” for the appropriate lat/lng fields
|
||||
6. Click finish
|
||||
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.
|
||||
|
||||
Your data will load onto the map, make sure to click the checkbox next to your dataset in the sidebar to view it.
|
||||
|
||||
### My Maps
|
||||
|
||||
You can use [My Maps](http://mymaps.google.com). It takes CSVs and the whole interface is much easier to work with.
|
||||
|
||||
Google has instructions on how to do that [here](https://support.google.com/mymaps/answer/3024836?co=GENIE.Platform%3DDesktop&hl=en#zippy=%2Cstep-prepare-your-info%2Cstep-import-info-into-the-map).
|
||||
|
||||
You can style the ranges differently based on the values, so you can have the pins be darker the if the SNR or RSSI (if that gets added) is higher.
|
||||
|
||||
## Configuration
|
||||
|
||||
Configuration details are available on the [Device Settings](/docs/settings) pages. Configuring the Range Test Module requires configuring the following modules:
|
||||
- [Range Test Module](/docs/settings/modules/range-test-module)
|
||||
|
||||
## Known Problems
|
||||
|
||||
If turned on, using mesh network will become unwieldy because messages are sent over the same channel as the other messages. See TODO below.
|
||||
|
||||
## TODO
|
||||
|
||||
Right now range test messages go over the `TEXT_MESSAGE_APP` port. We need a toggle to switch to optionally send over `RANGE_TEST_APP`.
|
||||
|
||||
## FAQ
|
||||
|
||||
Q: Where is rangetest.csv saved?
|
||||
|
||||
- Turn on the WiFi on your device as either a WiFi client or a WiFi AP. Once you can connect to your device, navigate to `Extensions > File Browser` and you will see `rangetest.csv` once messages have been saved and the file has been created.
|
||||
|
||||
Q: Do I need to have WiFi turned on for the file to be saved?
|
||||
|
||||
- Nope, it'll just work.
|
||||
|
||||
Q: Do I need a phone for this module?
|
||||
|
||||
- There's no need for a phone.
|
||||
|
||||
Q: Can I use this as a message logger?
|
||||
|
||||
- While it's not the intended purpose, sure, why not. Do it!
|
||||
|
||||
Q: What will happen if I run out of space on my device?
|
||||
|
||||
- We have a protection in place to keep you from completely filling up your device. This will make sure that other device critical functions will continue to work. We will reserve at least 50k of free space.
|
||||
|
||||
Q: What do I do with the rangetest.csv file when I'm done?
|
||||
|
||||
- Go to /static and delete the file.
|
||||
|
||||
Q: Can I use this as a sender while on battery power?
|
||||
|
||||
- Yes, but your battery will run down quicker than normal. While sending, we tell the device not to go into low-power mode since it needs to keep to a fairly strict timer.
|
||||
|
||||
Q: Why is this operating on incoming messages instead of the existing location discovery protocol?
|
||||
|
||||
- This module is still young and currently supports monitoring just one port at a time. I decided to use the existing message port because that is easy to test with. A future version will listen to multiple ports to be more promiscuous.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
---
|
||||
id: serial-module
|
||||
title: Serial communication module
|
||||
sidebar_label: Serial communication
|
||||
sidebar_position: 4
|
||||
---
|
||||
## About
|
||||
|
||||
This is a simple interface to send messages over the mesh network by sending strings over a serial port.
|
||||
|
||||
Default is to use RX GPIO 16 and TX GPIO 17.
|
||||
## Basic Usage:
|
||||
|
||||
1. Enable the module by setting `serial_module_enabled` to `1`.
|
||||
2. Set the pins (`serial_module_rxd` / `serial_module_rxd`) for your preferred RX and TX GPIO pins. On tbeam boards it is recommended to use:
|
||||
- RXD 35
|
||||
- TXD 15
|
||||
3. Set `serial_module_timeout` to the amount of time to wait before we consider your packet as "done".
|
||||
4. (Optional) In serial_module.h set the port to `PortNum_TEXT_MESSAGE_APP`if you want to send messages to/from the general text message channel.
|
||||
5. Connect to your device over the serial interface at `38400 8N1`.
|
||||
6. Send a packet up to 240 bytes in length. This will get relayed over the mesh network.
|
||||
7. (Optional) Set `serial_module_echo` to `1` and any message you send out will be echoed back to your device.
|
||||
|
||||
:::note
|
||||
The device must be restarted after the settings have been changed for the module to take effect.
|
||||
:::
|
||||
|
||||
## TODO (in this order):
|
||||
|
||||
- Define a verbose RX mode to report on mesh and packet information.
|
||||
|
||||
:::note
|
||||
This won't happen any time soon.
|
||||
:::
|
||||
|
||||
## Configuration
|
||||
|
||||
Configuration details are available on the [Device Settings](/docs/settings) pages. Configuring the Serial Module requires configuring the following modules:
|
||||
- [Serial Module](/docs/settings/modules/serial-module)
|
||||
|
||||
## Known Problems
|
||||
|
||||
- Until the module is initialized by the startup sequence, the TX pin is in a floating state. Device connected to that pin may see this as "noise".
|
||||
- Will not work on NRF and the Linux device targets.
|
||||
|
|
@ -1,218 +0,0 @@
|
|||
---
|
||||
id: store-forward-module
|
||||
title: Store and Forward Module
|
||||
sidebar_label: Store and Forward
|
||||
sidebar_position: 5
|
||||
---
|
||||
## About
|
||||
|
||||
:::caution
|
||||
This is a work in progress and is partially available. Stability is not guaranteed.
|
||||
:::
|
||||
|
||||
The Store Forward Module is an implementation of a Store and Forward system to enable resilient messaging in the event that a client device is disconnected from the main network.
|
||||
|
||||
Because of the increased network traffic for this overhead, it's not advised to use this if you are duty cycle limited for your airtime usage nor is it advised to use this for SF12 (Long Range / Slow).
|
||||
|
||||
### About - How it works
|
||||
|
||||
|
||||
|
||||
## Requirements
|
||||
|
||||
Initial Requirements:
|
||||
|
||||
- Must be installed on a router node.
|
||||
- This is an artificial limitation, but is in place to enforce best practices.
|
||||
- Router nodes are intended to be always online. If this module misses any messages, the reliability of the stored messages will be reduced.
|
||||
- Esp32 Processor based device with external PSRAM. (tbeam v1.0 and tbeamv1.1, and maybe others)
|
||||
|
||||
## Usage Overview
|
||||
|
||||
To use / test this you will want at least 3 devices
|
||||
|
||||
- One device will (currently) need be a tbeam v1.0 and tbeamv1.1 configured as a Meshtastic router. Other devices with built in PSRAM will be supported at some point.
|
||||
- Two others will be regular clients. Nothing special required.
|
||||
|
||||
### Meshtastic channel configuration
|
||||
|
||||
Don't use this on the "Long Range / Slow" or "Long Range / Fast" channel settings. You're welcome to try and report back, but those channels have a [very low bitrate](/docs/developers/firmware/radio-settings#pre-defined).
|
||||
|
||||
Either use a custom channel configuration with at an at least 1kbit data rate or use "Medium Range / Fast".
|
||||
|
||||
Recommended channel setting is for 1.343kbps:
|
||||
|
||||
```shell
|
||||
meshtastic --setchan spread_factor 11 --setchan coding_rate 4 --setchan bandwidth 500
|
||||
```
|
||||
|
||||
With an aftermarket coaxial antenna or moxon antenna, that will give you roughly the same range as "Long Range / Slow" and 5x the bitrate.
|
||||
|
||||
### Router setup
|
||||
|
||||
- Configure your device as a [Meshtastic router](/docs/settings/router).
|
||||
- Configure the Store and Forward Module
|
||||
- Required configuration
|
||||
- `store_forward_module_enabled` - Set this to true to enable the module. False to disable the module.
|
||||
- Optional configuration
|
||||
- `store_forward_module_records` - Set this to the maximum number of records to save. Best to leave this at the default (0) where the module will use 2/3 of your device's available PSRAM. This is about 11,000 records.
|
||||
- Name your router node something that makes it easily identifiable, aka "Router".
|
||||
|
||||
Don't enable the Store and Forward module on multiple routers!
|
||||
|
||||
### Client Usage
|
||||
|
||||
Currently, no special configuration is required. To request your history sent to you, send the command into the message field "SF". That's it. This will eventually change to make it easier. At the moment, that message will be sent to everyone on the mesh but we'll (eventually) make it easier to use where there'll be a button (or maybe it'll be transparent) and the command isn't sent as a text message to the mesh.
|
||||
|
||||
Available Commands:
|
||||
|
||||
| Command | Definition |
|
||||
| :-----: | :------------------------------------------: |
|
||||
| SF | Send the last few messages I may have missed |
|
||||
| SFm | Send a 240 byte payload (Used for testing) |
|
||||
|
||||
The Store and Forward module will only service one client at a time. If a second client requests messages while the S&F is busy, the S&F will send a private message to the second client that they will need to wait.
|
||||
|
||||
## Settings
|
||||
|
||||
| Setting | Acceptable Values | Default |
|
||||
| :-------------------------------------------: | :---------------: | :-----: |
|
||||
| store_forward_module_enabled | `true`, `false` | `false` |
|
||||
| store_forward_module_records | integer | `0` |
|
||||
| store_forward_module_replay_max_records (tbd) | integer | `0` |
|
||||
| store_forward_module_replay_max_time (tbd) | integer | `0` |
|
||||
|
||||
## Example Request/Response
|
||||
|
||||
### Request History (Use Router Defaults)
|
||||
|
||||
Story: Carol has been away from the mesh with device turned off. She would like to get a replay of what she has missed. The router will return the messages.
|
||||
|
||||
- Carol
|
||||
- Packet (Port: STORE_FORWARD_APP)
|
||||
- To: Broadcast (Optionally, direct to router)
|
||||
- StoreAndForward.rr.CLIENT_HISTORY
|
||||
- Router
|
||||
- Packet (Port: STORE_FORWARD_APP)
|
||||
- To: Carol
|
||||
- StoreAndForward.rr.ROUTER_HISTORY
|
||||
- StoreAndForward.history.HistoryMessages = 42 // Router has 42 messages that will be sent to Carol.
|
||||
- StoreAndForward.history.Window = 120 // Router searched for messages over the last two hours.
|
||||
- StoreAndForward.history.LastRequest = 0 // Carol has never asked for the history.
|
||||
- Packet (Port: TEXT_MESSAGE_APP)
|
||||
- ... a series of 42 text messages
|
||||
|
||||
### Request History (No history available)
|
||||
|
||||
Story: Carol has been away from the mesh with device turned off. She would like to get a replay of what she has missed but the router indicates there are no messages available.
|
||||
|
||||
- Carol
|
||||
- Packet (Port: STORE_FORWARD_APP)
|
||||
- To: Broadcast (Optionally, direct to router)
|
||||
- StoreAndForward.rr.CLIENT_HISTORY
|
||||
- Router
|
||||
- Packet (Port: STORE_FORWARD_APP)
|
||||
- To: Carol
|
||||
- StoreAndForward.rr.ROUTER_HISTORY
|
||||
- StoreAndForward.history.HistoryMessages = 0 // Router has no messages to be sent to Carol.
|
||||
- StoreAndForward.history.Window = 120 // Router searched for messages over the last two hours.
|
||||
- StoreAndForward.history.LastRequest = (timestamp) // Last time carol requested the history.
|
||||
|
||||
### Store & Forward Router Heartbeat
|
||||
|
||||
Story: The Store & Forward Router sends a periodic message onto the network. This allows connected devices to know that a router is in range and listening to received messages. Client will not respond to network but (optionally) indicate to the user that a S&F router is available or not available.
|
||||
|
||||
- Router
|
||||
- Packet (Port: STORE_FORWARD_APP)
|
||||
- To: Broadcast
|
||||
- StoreAndForward.rr.ROUTER_HEARTBEAT
|
||||
- StoreAndForward.heartbeat.Period = 120 // Expect a heartbeat every 2 minutes.
|
||||
- StoreAndForward.heartbeat.Secondary = false // If true, this is a secondary "backup" S&F node. Will be (eventually) used for router election in the event there are multiple S&F Routers.
|
||||
|
||||
## Meshpacket
|
||||
|
||||
To support functionality of Store and Forward, a new enum has been added to the MeshPacket.
|
||||
|
||||
```
|
||||
typedef enum _MeshPacket_Delayed {
|
||||
MeshPacket_Delayed_NO_DELAY = 0,
|
||||
MeshPacket_Delayed_DELAYED_BROADCAST = 1,
|
||||
MeshPacket_Delayed_DELAYED_DIRECT = 2
|
||||
} MeshPacket_Delayed;
|
||||
```
|
||||
|
||||
- NO_DELAY - The packet was sent in real time. Store and Forward had no hand in this message. This is the default case.
|
||||
- DELAYED_BROADCAST - This is a delayed message. The 'to' of the packet has been directed at a named user but was previously a broadcast packet.
|
||||
- DELAYED_DIRECT - This is a delayed message. The 'to' of the packet has been directed at a named user but was previously a direct packet.
|
||||
|
||||
As a reminder, broadcast messages are messages where the "to" of a payload is directed at NODENUM_BROADCAST or (0xFFFFFFFF).
|
||||
|
||||
Example Cases:
|
||||
|
||||
- Real time :: BROADCAST
|
||||
- Delayed = MeshPacket_Delayed_NO_DELAY
|
||||
- From: Ann
|
||||
- To: BROADCAST
|
||||
- Real time :: Direct
|
||||
- Delayed = MeshPacket_Delayed_NO_DELAY
|
||||
- From: Ann
|
||||
- To: Bob
|
||||
- Delayed :: BROADCAST
|
||||
- Delayed = MeshPacket_Delayed_DELAYED_BROADCAST
|
||||
- From: Ann
|
||||
- To: Bob
|
||||
- Delayed :: Direct
|
||||
- Delayed = MeshPacket_Delayed_DELAYED_DIRECT
|
||||
- From: Ann
|
||||
- To: Bob
|
||||
|
||||
When a message is 'real time', time a message is sent is the same as the time the message was received. In the case the message is delayed, there is no timestamp available for the message.
|
||||
|
||||
Where the message is a delayed broadcast, the "To" is _not_ a broadcast address but rather the address of the device that requested the messages to be replayed. This is to allow the message to be routed over the mesh network and not displayed in the message screen of other devices.
|
||||
|
||||
## Configuration
|
||||
|
||||
Configuration details are available on the [Device Settings](/docs/settings) pages. Configuring the Store and Forward requires configuring the following modules:
|
||||
- [Store and Forward](/docs/settings/modules/store-and-forward-module)
|
||||
|
||||
## Developer TODO
|
||||
|
||||
Not necessarily in this order:
|
||||
|
||||
- Client Interface (Web, Android, Python or iOS when that happens) to request packets be resent.
|
||||
|
||||
- Router sends a heartbeat so the client knows there is a router in range.
|
||||
|
||||
- Support for a mesh to have multiple routers that have the store & forward functionality (for redundancy).
|
||||
|
||||
- Add a default channel at about 1.5kbit / sec.
|
||||
|
||||
- Eventually we could add a "want_store_and_forward" bit to MeshPacket and that could be nicer than whitelists in this module. Initially we'd only set that bit in text messages (and any other module messages that can cope with this). This change would be backward wire compatible so can add easily later.
|
||||
|
||||
- Have a "cool down" period to disallow a client to request the history too often.
|
||||
|
||||
- Message with SF status on requests.
|
||||
|
||||
- Be able to identify if you're within range of a router.
|
||||
|
||||
- Be able to specify the HOP MAX to reduce airtime. Is this necessary?
|
||||
|
||||
- Restrict operation of S&F on the slow channel configurations.
|
||||
|
||||
- Create a TX queue to prevent the history from being modified in flight.
|
||||
|
||||
- Only allow n-number of requests to the router at any one time.
|
||||
|
||||
- Set number of max messages from the history.
|
||||
|
||||
- Calculate a new channel with 250kHz bandwidth and ~1.5kbit.
|
||||
|
||||
\*\*\* Done
|
||||
|
||||
- Disable ACK. If the router is within range, so is the requester.
|
||||
|
||||
- Currently the way we allocate messages in the device code is super inefficient. It always allocates the worst case message size. Really we should dynamically allocate just the # of bytes we need. This would allow many more MeshPackets to be kept in RAM.
|
||||
|
||||
- Allow max history to be defined by radioConfig.preferences.store_forward_module_records.
|
||||
|
||||
- Add a starting to send / finished sending message.
|
||||
|
|
@ -1,173 +0,0 @@
|
|||
---
|
||||
id: telemetry-module
|
||||
title: Telemetry
|
||||
sidebar_label: Telemetry
|
||||
sidebar_position: 6
|
||||
---
|
||||
## About
|
||||
|
||||
The Telemetry Module will allow nodes to send a specific message with information from connected sensors. Currently supported sensors are `BME280`, `BME680`, `DHT11`, `DHT12`, `DHT21`, `DHT22`, Dallas 1-wire `DS18B20`, and `MCP9808`.
|
||||
|
||||
The preferred setup is using I2C, so the `telemetry_module_sensor_pin` may not be needed.
|
||||
|
||||
## Usage Notes
|
||||
|
||||
For basic usage, start with:
|
||||
|
||||
```shell
|
||||
telemetry_module_enabled = 1
|
||||
|
||||
telemetry_module_screen_enabled = 1
|
||||
```
|
||||
|
||||
Depending on which pin your sensor is connected to, set it accordingly:
|
||||
|
||||
```shell
|
||||
telemetry_module_sensor_pin = 13
|
||||
```
|
||||
|
||||
:::note
|
||||
The device must be restarted after the settings have been changed for the module to take effect.
|
||||
:::
|
||||
|
||||
## Hardware
|
||||
|
||||
The sensors can be wired differently, here's one example for sensor DS18B20 https://randomnerdtutorials.com/esp32-ds18b20-temperature-arduino-ide
|
||||
|
||||
## Example of T-LoraV1 with DHT22 temperature sensor
|
||||
|
||||
Setup of a T-LoraV1 with DHT22 temperature sensor.
|
||||
|
||||
[<img src="T-LoraV1 with DHT22" src="/img/hardware/lora_v1_with_DHT22.jpg" style={{zoom:'25%'}} />](/img/hardware/lora_v1_with_DHT22.jpg)
|
||||
|
||||
Requirements:
|
||||
|
||||
- T-LoraV1 (but any esp32 should work, just be sure to double check which GPIO to use)
|
||||
- DHT22 sensor
|
||||
- 10 Kohm resistor (optional, but recommended)
|
||||
- breadboard (optional)
|
||||
- two red wires (could be a different color, but 5V is typically red)
|
||||
- two yellow wires for GPIO (could be a different color)
|
||||
- one black wire (could be a different color, but GROUND is typically black)
|
||||
|
||||
Steps:
|
||||
|
||||
- disconnect power/battery
|
||||
- connect black wire from GROUND to "-" on the DHT22
|
||||
- connect yellow wire from middle PIN to a row on bread board
|
||||
- connect red wire from 5V to a row on breadboard
|
||||
- connect resistor between red and yellow rows
|
||||
- connect red wire from row with red to "+" on DHT22
|
||||
- connect yellow wire from yellow row to GPIO on device (ex: GPIO21)
|
||||
- double check the cabling (if you get it wrong, you can damage the device and/or the DHT22 sensor)
|
||||
- plug in device
|
||||
- configure the device:
|
||||
|
||||
```shell
|
||||
meshtastic --set telemetry_module_measurement_enabled true --set telemetry_module_screen_enabled true --set telemetry_module_update_interval 15 --set telemetry_module_display_farenheit true --set telemetry_module_sensor_type DHT22 --set telemetry_module_sensor_pin 21
|
||||
```
|
||||
|
||||
:::tip
|
||||
You can change the values above to suit your needs. The commands can be run one at a time or in a group as show above.
|
||||
:::
|
||||
|
||||
- reboot/reset the device (press the RST button or unplug/plug in the device)
|
||||
- when the device boots it should say "Telemetry" and it may show the sensor data
|
||||
- if "no data", then triple check the wiring
|
||||
- if still "no data", run:
|
||||
|
||||
```shell
|
||||
meshtastic --info
|
||||
```
|
||||
|
||||
and verify the the `telemetry_module_sensor_type and` `telemetry_module_sensor_pin`
|
||||
|
||||
## Example of T-LoraV1 with Dallas DS18B20 temperature sensor
|
||||
|
||||
Setup of a T-LoraV1 with DS18B20 temperature sensor.
|
||||
|
||||
[<img src="T-LoraV1 with DS18B20" src="/img/hardware/lora_v1_with_DS18B20.jpg" style={{zoom:'25%'}} />](/img/hardware/lora_v1_with_DS18B20.jpg)
|
||||
|
||||
Requirements:
|
||||
|
||||
- T-LoraV1 (but any esp32 should work, just be sure to double check which GPIO to use)
|
||||
- DS18B20 sensor
|
||||
- 10 Kohm resistor (optional, but recommended)
|
||||
- breadboard (optional)
|
||||
- two red wires (could be a different color, but 5V is typically red)
|
||||
- two yellow wires for GPIO (could be a different color)
|
||||
- one black wire (could be a different color, but GROUND is typically black)
|
||||
|
||||
Steps:
|
||||
|
||||
- disconnect power/battery
|
||||
- connect black wire from GROUND to "-" on the DS18B20
|
||||
- connect yellow wire from DAT pin to a row on bread board
|
||||
- connect red wire from 5V to a row on breadboard
|
||||
- connect resistor between red and yellow rows
|
||||
- connect red wire from row with red to "VCC" on DS18B20
|
||||
- connect yellow wire from yellow row to GPIO on device (ex: GPIO21)
|
||||
- double check the cabling (if you get it wrong, you can damage the device and/or the sensor)
|
||||
- plug in device
|
||||
- configure the device:
|
||||
|
||||
```shell
|
||||
meshtastic --set telemetry_module_measurement_enabled true --set telemetry_module_screen_enabled true --set telemetry_module_update_interval 15 --set telemetry_module_display_farenheit true --set telemetry_module_sensor_type DS18B20 --set telemetry_module_sensor_pin 21
|
||||
```
|
||||
|
||||
:::tip
|
||||
You can change the values above to suit your needs. The commands can be run one at a time or in a group as show above.
|
||||
:::
|
||||
|
||||
- reboot/reset the device (press the RST button or unplug/plug in the device)
|
||||
- when the device boots it should say "Telemetry" and it may show the sensor data
|
||||
- if "no data", then triple check the wiring
|
||||
- if still "no data", run:
|
||||
|
||||
```shell
|
||||
meshtastic --info
|
||||
```
|
||||
|
||||
and verify the the `telemetry_module_sensor_type` and `telemetry_module_sensor_pin`
|
||||
|
||||
## Example of RAK 4631 with Environment Sensor
|
||||
|
||||
Setup of a RAK 4631 with Environment Sensor
|
||||
|
||||
[<img src="RAK4631_with_EnvSensor" src="/img/hardware/rak/RAK4631_with_EnvSensor.jpg" style={{zoom:'25%'}} />](/img/hardware/rak/RAK4631_with_EnvSensor.jpg)
|
||||
|
||||
Requirements:
|
||||
|
||||
- RAK4631
|
||||
- Environment Sensor
|
||||
|
||||
Steps:
|
||||
|
||||
- configure the device:
|
||||
|
||||
```shell
|
||||
meshtastic --set telemetry_module_measurement_enabled true --set telemetry_module_screen_enabled true --set telemetry_module_update_interval 15 --set telemetry_module_display_farenheit true --set telemetry_module_sensor_type 6
|
||||
```
|
||||
|
||||
:::tip
|
||||
You can change the values above to suit your needs. The commands can be run one at a time or in a group as show above.
|
||||
:::
|
||||
|
||||
- reboot/reset the device (press the button or unplug/plug in the device)
|
||||
- when the device boots it should say "Telemetry" and it may show the sensor data
|
||||
- if still "no data", run:
|
||||
|
||||
```shell
|
||||
meshtastic --info
|
||||
```
|
||||
|
||||
and verify the the `telemetry_module_sensor_type`
|
||||
|
||||
## Configuration
|
||||
|
||||
Configuration details are available on the [Device Settings](/docs/settings) pages. Configuring the Telemetry Module requires configuring the following modules:
|
||||
- [Telemetry Module](/docs/settings/modules/telemetry-module)
|
||||
|
||||
## Known Problems
|
||||
|
||||
- No default configuration values are currently set, so this must be done when enabling the module.
|
||||
|
|
@ -4,17 +4,15 @@ title: 1.3 Enthusiast
|
|||
sidebar_label: 1.3 Enthusiast
|
||||
---
|
||||
|
||||
Meshtastic 1.3 is currently highly experimental. While we believe that it's stable-ish,
|
||||
it's not yet complete.
|
||||
|
||||
*** WARNING ***
|
||||
|
||||
Meshtastic 1.3 Experimental!
|
||||
|
||||
*** WARNING ***
|
||||
|
||||
READ ME
|
||||
|
||||
Meshtastic 1.3 is currently highly experimental. While we believe that it's stable-ish,
|
||||
it's not yet complete.
|
||||
|
||||
If you're reading this and want to experiment with Meshtastic 1.3, you must be an
|
||||
enthusiast and are OK with being fustrated and things not working.
|
||||
|
||||
|
|
@ -40,7 +38,7 @@ https://github.com/meshtastic/Meshtastic-device/issues
|
|||
|
||||
## Meshtastic 1.3 - python
|
||||
|
||||
TBD - Not yet available
|
||||
In progress, a few basic commands work (--info, --nodes) help wanted!
|
||||
|
||||
Where to file bugs:
|
||||
|
||||
|
|
@ -85,4 +83,10 @@ Where to file bugs:
|
|||
|
||||
TBD
|
||||
|
||||
## Meshtastic 1.3 - Flasher
|
||||
|
||||
Not yet available, dependant on the CLI being completed
|
||||
|
||||
Where to file bugs:
|
||||
|
||||
TBD
|
||||
|
|
|
|||
|
|
@ -4,4 +4,5 @@ label: Other
|
|||
collapsible: true # make the category collapsible
|
||||
link:
|
||||
type: generated-index
|
||||
title: Other
|
||||
title: Other
|
||||
slug: /software/other
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
---
|
||||
id: remote-hardware-service
|
||||
title: Remote Hardware Service
|
||||
sidebar_label: 1.2 Remote Hardware
|
||||
---
|
||||
|
||||
FIXME - the following are a collection of notes moved from elsewhere. We need to refactor these notes into actual documentation on the remote-hardware/GPIO service.
|
||||
|
||||
### 1.7.2. New 'no-code-IOT' mini-app
|
||||
|
||||
Add a new 'remote GPIO/serial port/SPI/I2C access' mini-app. This new standard app would use the MQTT messaging layer to let users (developers that don't need to write device code) do basic (potentially dangerous) operations remotely.
|
||||
|
||||
#### 1.7.2.1. Supported operations in the initial release
|
||||
|
||||
Initially supported features for no-code-IOT.
|
||||
|
||||
- Set any GPIO
|
||||
- Read any GPIO
|
||||
|
||||
#### 1.7.2.2. Supported operations eventually
|
||||
|
||||
General ideas for no-code IOT.
|
||||
|
||||
- Subscribe for notification of GPIO input status change (i.e. when pin goes low, send my app a message)
|
||||
- Write/read N bytes over I2C/SPI bus Y (as one atomic I2C/SPI transaction)
|
||||
- Send N bytes out serial port Z
|
||||
- Subscribe for notification for when regex X matches the bytes that were received on serial port Z
|
||||
|
|
@ -4,4 +4,5 @@ label: Python CLI
|
|||
collapsible: true # make the category collapsible
|
||||
link:
|
||||
type: generated-index
|
||||
title: Python
|
||||
title: Python
|
||||
slug: /software/python-cli
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
id: python-cli
|
||||
title: meshtastic command line interface guide
|
||||
sidebar_label: meshtastic cli
|
||||
title: Meshtastic Command Line Interface
|
||||
sidebar_label: Meshtastic CLI
|
||||
---
|
||||
|
||||
# Meshtastic CLI Guide
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
id: python-development
|
||||
title: Meshtastic-python Development
|
||||
sidebar_label: Meshtastic-python development
|
||||
title: Meshtastic Python Development
|
||||
sidebar_label: Python Development
|
||||
---
|
||||
|
||||
## A note to developers of this lib
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
id: python-uses
|
||||
title: Uses of the meshtastic command line interface tool
|
||||
sidebar_label: Uses
|
||||
sidebar_label: Use Cases
|
||||
---
|
||||
|
||||
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.
|
||||
|
|
@ -58,7 +58,7 @@ For a full list of preferences which can be set (and their documentation) can be
|
|||
The channel settings can also be changed, either by using a standard (shareable) meshtastic URL or you can set particular channel parameter (for advanced users).
|
||||
|
||||
:::warning
|
||||
Meshtastic encodes the radio channel and PSK in the channel's URL. All nodes must connect to the channel again by using the URL provided after a change in this section by performing the `--info` switch. Please refer to [Multiple Channel Support](/docs/software/device/device-channels).
|
||||
Meshtastic encodes the radio channel and PSK in the channel's URL. All nodes must connect to the channel again by using the URL provided after a change in this section by performing the `--info` switch.
|
||||
:::
|
||||
|
||||
```shell
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
id: python-using-library
|
||||
title: using the Meshtastic-python library
|
||||
sidebar_label: Using the meshtastic Python library
|
||||
sidebar_label: Using the Python Library
|
||||
---
|
||||
|
||||
An example using Python 3 code to send a message to the mesh, get and set a radio configuration preference:
|
||||
|
|
|
|||
|
|
@ -88,11 +88,11 @@ const config = {
|
|||
},
|
||||
{
|
||||
label: 'Software',
|
||||
to: 'docs/category/software',
|
||||
to: 'docs/software',
|
||||
},
|
||||
{
|
||||
label: 'Developers',
|
||||
to: 'docs/category/developers',
|
||||
to: 'docs/developers',
|
||||
},
|
||||
],
|
||||
},
|
||||
|
|
|
|||
Loading…
Reference in a new issue