From 9ea1192f51c5267e12b4381c8eacb09b11a7f9e8 Mon Sep 17 00:00:00 2001 From: Garth Vander Houwen Date: Sun, 3 Jul 2022 11:00:32 -0700 Subject: [PATCH 01/15] Start of cleanup of broken firmware modules pages under software --- docs/software/other/1.3-enthusiast.mdx | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/software/other/1.3-enthusiast.mdx b/docs/software/other/1.3-enthusiast.mdx index 7cd19188..fdfbcea4 100644 --- a/docs/software/other/1.3-enthusiast.mdx +++ b/docs/software/other/1.3-enthusiast.mdx @@ -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 From c015a74fcb1c5fe5b492c01af73456875a7dcad4 Mon Sep 17 00:00:00 2001 From: Garth Vander Houwen Date: Sun, 3 Jul 2022 11:00:50 -0700 Subject: [PATCH 02/15] Comit --- docs/_blocks/_module_overview_text.mdx | 17 +- docs/_blocks/_plugin_overview_text.mdx | 17 ++ docs/settings/moduleconfig/telemetry.mdx | 37 ++++ docs/software/device/power.mdx | 4 +- docs/software/device/remote-admin.mdx | 4 +- .../device/remote-hardware-service.mdx | 4 +- docs/software/js/_category_.yml | 3 +- docs/software/modules/modules.mdx | 12 -- docs/software/modules/telemetry.mdx | 173 ------------------ docs/software/other/_category_.yml | 3 +- .../other/remote-hardware-service.mdx | 27 --- .../{modules => plugins}/_category_.yml | 5 +- .../{modules => plugins}/canned-message.mdx | 2 +- .../external-notifications.mdx | 4 +- .../{modules => plugins}/range-test.mdx | 4 +- docs/software/{modules => plugins}/serial.mdx | 6 +- .../{modules => plugins}/store-forward.mdx | 4 +- 17 files changed, 85 insertions(+), 241 deletions(-) create mode 100644 docs/_blocks/_plugin_overview_text.mdx delete mode 100644 docs/software/modules/modules.mdx delete mode 100644 docs/software/modules/telemetry.mdx delete mode 100644 docs/software/other/remote-hardware-service.mdx rename docs/software/{modules => plugins}/_category_.yml (60%) rename docs/software/{modules => plugins}/canned-message.mdx (99%) rename docs/software/{modules => plugins}/external-notifications.mdx (95%) rename docs/software/{modules => plugins}/range-test.mdx (98%) rename docs/software/{modules => plugins}/serial.mdx (94%) rename docs/software/{modules => plugins}/store-forward.mdx (99%) diff --git a/docs/_blocks/_module_overview_text.mdx b/docs/_blocks/_module_overview_text.mdx index 9ea84bdf..d03af435 100644 --- a/docs/_blocks/_module_overview_text.mdx +++ b/docs/_blocks/_module_overview_text.mdx @@ -1,16 +1,15 @@ -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: +Modules are included in the firmware and allow users to extend the functionality of their mesh or device. | 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. | +| [Canned Message](/settings/moduleconfig/canned-message) | Set a number of predefined messages to send out directly from the device with the use of an input device like a rotary encoder. | +| [External Notification](external-notification) | Incoming messages are able to alert you using circuits you attach to the device (LEDs, Buzzers, etc) | +| [Input Broker](input-broker) | Attach and define input devices such as external keyboards and rotary encoders. | +| [Range Test](range-test) | Send messages with GPS location at an interval to test the distance your devices can communicate. Requires (at least) one device set up as a sender and one as a receiver. The receiver(s) will log all incoming messages to a CSV. | +| [Serial Module](serial) | Send messages across the mesh by sending strings over a serial port. | +| [Store and Forward](store-and-forward) | Set a designated node to store messages and resend them to nodes with intermittent connection to a mesh. | +| [Telemetry](telemetry) | 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. diff --git a/docs/_blocks/_plugin_overview_text.mdx b/docs/_blocks/_plugin_overview_text.mdx new file mode 100644 index 00000000..9ea84bdf --- /dev/null +++ b/docs/_blocks/_plugin_overview_text.mdx @@ -0,0 +1,17 @@ +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. +::: diff --git a/docs/settings/moduleconfig/telemetry.mdx b/docs/settings/moduleconfig/telemetry.mdx index d5814296..54568fa6 100644 --- a/docs/settings/moduleconfig/telemetry.mdx +++ b/docs/settings/moduleconfig/telemetry.mdx @@ -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/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` \ No newline at end of file diff --git a/docs/software/device/power.mdx b/docs/software/device/power.mdx index 72c8fef7..398a8d04 100644 --- a/docs/software/device/power.mdx +++ b/docs/software/device/power.mdx @@ -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. diff --git a/docs/software/device/remote-admin.mdx b/docs/software/device/remote-admin.mdx index f5742ffe..66f2da6f 100644 --- a/docs/software/device/remote-admin.mdx +++ b/docs/software/device/remote-admin.mdx @@ -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. diff --git a/docs/software/device/remote-hardware-service.mdx b/docs/software/device/remote-hardware-service.mdx index e80e7f73..676f807c 100644 --- a/docs/software/device/remote-hardware-service.mdx +++ b/docs/software/device/remote-hardware-service.mdx @@ -1,7 +1,7 @@ --- id: remote-hardware-service -title: Remote Hardware Service -sidebar_label: Remote Hardware +title: 1.2 Remote Hardware Service +sidebar_label: 1.2 Remote Hardware --- :::warning diff --git a/docs/software/js/_category_.yml b/docs/software/js/_category_.yml index 0b8b0393..2dfef08e 100644 --- a/docs/software/js/_category_.yml +++ b/docs/software/js/_category_.yml @@ -4,4 +4,5 @@ label: 'Javascript' collapsible: true # make the category collapsible link: type: generated-index - title: Javascript \ No newline at end of file + title: Javascript + slug: /software/js \ No newline at end of file diff --git a/docs/software/modules/modules.mdx b/docs/software/modules/modules.mdx deleted file mode 100644 index 49f4cef7..00000000 --- a/docs/software/modules/modules.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -id: modules -title: Firmware Modules Overview -sidebar_label: Firmware Modules ---- -import ModuleOverviewText from '@site/docs/_blocks/_module_overview_text.mdx'; - - - -## Configuration - -Configuration details are available on the [Device Settings](/docs/settings/modules) pages. diff --git a/docs/software/modules/telemetry.mdx b/docs/software/modules/telemetry.mdx deleted file mode 100644 index e18fe9d5..00000000 --- a/docs/software/modules/telemetry.mdx +++ /dev/null @@ -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/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/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/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. diff --git a/docs/software/other/_category_.yml b/docs/software/other/_category_.yml index edc92098..ac11fb4e 100644 --- a/docs/software/other/_category_.yml +++ b/docs/software/other/_category_.yml @@ -4,4 +4,5 @@ label: Other collapsible: true # make the category collapsible link: type: generated-index - title: Other \ No newline at end of file + title: Other + slug: /software/other \ No newline at end of file diff --git a/docs/software/other/remote-hardware-service.mdx b/docs/software/other/remote-hardware-service.mdx deleted file mode 100644 index 8e3e5f1e..00000000 --- a/docs/software/other/remote-hardware-service.mdx +++ /dev/null @@ -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 diff --git a/docs/software/modules/_category_.yml b/docs/software/plugins/_category_.yml similarity index 60% rename from docs/software/modules/_category_.yml rename to docs/software/plugins/_category_.yml index ddf5aed1..4dd2a8bd 100644 --- a/docs/software/modules/_category_.yml +++ b/docs/software/plugins/_category_.yml @@ -1,7 +1,8 @@ position: 5 # float position is supported -label: Firmware Modules +label: 1.2 Firmware Plugins collapsible: true # make the category collapsible link: type: generated-index - title: Firmware Modules \ No newline at end of file + title: Firmware Modules + slug: /software/plugins \ No newline at end of file diff --git a/docs/software/modules/canned-message.mdx b/docs/software/plugins/canned-message.mdx similarity index 99% rename from docs/software/modules/canned-message.mdx rename to docs/software/plugins/canned-message.mdx index 551cbb4f..15f59bbd 100644 --- a/docs/software/modules/canned-message.mdx +++ b/docs/software/plugins/canned-message.mdx @@ -1,7 +1,7 @@ --- id: canned-message-module title: Canned messages -sidebar_label: Canned messages +sidebar_label: 1.2 Canned messages sidebar_position: 3 --- ## About diff --git a/docs/software/modules/external-notifications.mdx b/docs/software/plugins/external-notifications.mdx similarity index 95% rename from docs/software/modules/external-notifications.mdx rename to docs/software/plugins/external-notifications.mdx index 620c2ea8..e6b4de2a 100644 --- a/docs/software/modules/external-notifications.mdx +++ b/docs/software/plugins/external-notifications.mdx @@ -1,7 +1,7 @@ --- id: ext-notif-module -title: External notifications -sidebar_label: External notifications +title: 1.2 External notifications +sidebar_label: 1.2 External notifications sidebar_position: 2 --- ## About diff --git a/docs/software/modules/range-test.mdx b/docs/software/plugins/range-test.mdx similarity index 98% rename from docs/software/modules/range-test.mdx rename to docs/software/plugins/range-test.mdx index 6a269ddc..6c005dd9 100644 --- a/docs/software/modules/range-test.mdx +++ b/docs/software/plugins/range-test.mdx @@ -1,7 +1,7 @@ --- id: range-test-module -title: Range Test Module -sidebar_label: Range Test +title: 1.2 Range Test Plugin +sidebar_label: 1.2 Range Test sidebar_position: 1 --- ## About diff --git a/docs/software/modules/serial.mdx b/docs/software/plugins/serial.mdx similarity index 94% rename from docs/software/modules/serial.mdx rename to docs/software/plugins/serial.mdx index e8fbdbca..fe7e2c87 100644 --- a/docs/software/modules/serial.mdx +++ b/docs/software/plugins/serial.mdx @@ -1,7 +1,7 @@ --- -id: serial-module -title: Serial communication module -sidebar_label: Serial communication +id: serial-plugin +title: Serial communication plugin +sidebar_label: 1.2 Serial communication sidebar_position: 4 --- ## About diff --git a/docs/software/modules/store-forward.mdx b/docs/software/plugins/store-forward.mdx similarity index 99% rename from docs/software/modules/store-forward.mdx rename to docs/software/plugins/store-forward.mdx index dcf0a283..72e90142 100644 --- a/docs/software/modules/store-forward.mdx +++ b/docs/software/plugins/store-forward.mdx @@ -1,7 +1,7 @@ --- id: store-forward-module -title: Store and Forward Module -sidebar_label: Store and Forward +title: 1.2 Store and Forward Plugin +sidebar_label: 1.2 Store and Forward sidebar_position: 5 --- ## About From 2b2a29358ce0885314471dd4b27b08a9f3bd2c5c Mon Sep 17 00:00:00 2001 From: Garth Vander Houwen Date: Sun, 3 Jul 2022 11:20:04 -0700 Subject: [PATCH 03/15] Remove additonaly duplicate pages --- docs/settings/moduleconfig/canned-message.mdx | 46 +++++++++ .../moduleconfig/external-notification.mdx | 34 ++++++- docs/settings/moduleconfig/range-test.mdx | 67 ++++++++++++- docs/settings/moduleconfig/serial.mdx | 17 +++- docs/software/plugins/canned-message.mdx | 65 ------------- .../plugins/external-notifications.mdx | 44 --------- docs/software/plugins/range-test.mdx | 95 ------------------- docs/software/plugins/serial.mdx | 44 --------- 8 files changed, 160 insertions(+), 252 deletions(-) delete mode 100644 docs/software/plugins/canned-message.mdx delete mode 100644 docs/software/plugins/external-notifications.mdx delete mode 100644 docs/software/plugins/range-test.mdx delete mode 100644 docs/software/plugins/serial.mdx diff --git a/docs/settings/moduleconfig/canned-message.mdx b/docs/settings/moduleconfig/canned-message.mdx index 527fef5f..d17cf5a7 100644 --- a/docs/settings/moduleconfig/canned-message.mdx +++ b/docs/settings/moduleconfig/canned-message.mdx @@ -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. + + + +- [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) diff --git a/docs/settings/moduleconfig/external-notification.mdx b/docs/settings/moduleconfig/external-notification.mdx index 576166b1..8f1e5d0b 100644 --- a/docs/settings/moduleconfig/external-notification.mdx +++ b/docs/settings/moduleconfig/external-notification.mdx @@ -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. -::: \ No newline at end of file +::: + +## 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. diff --git a/docs/settings/moduleconfig/range-test.mdx b/docs/settings/moduleconfig/range-test.mdx index 0f60b6b6..dc978efd 100644 --- a/docs/settings/moduleconfig/range-test.mdx +++ b/docs/settings/moduleconfig/range-test.mdx @@ -99,7 +99,7 @@ All range test module config options are available in the Web UI. -## 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 +127,67 @@ http://198.168.0.15 | Long Slow | 60 | | Long Alt | 30 | | Medium | 15 | -| Short Fast | 15 | \ No newline at end of file +| 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. diff --git a/docs/settings/moduleconfig/serial.mdx b/docs/settings/moduleconfig/serial.mdx index c81bb791..4fce0224 100644 --- a/docs/settings/moduleconfig/serial.mdx +++ b/docs/settings/moduleconfig/serial.mdx @@ -143,4 +143,19 @@ All serial test module config options are available in the Web UI. ::: - \ No newline at end of file + + +## 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. \ No newline at end of file diff --git a/docs/software/plugins/canned-message.mdx b/docs/software/plugins/canned-message.mdx deleted file mode 100644 index 15f59bbd..00000000 --- a/docs/software/plugins/canned-message.mdx +++ /dev/null @@ -1,65 +0,0 @@ ---- -id: canned-message-module -title: Canned messages -sidebar_label: 1.2 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. - - - -- [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. diff --git a/docs/software/plugins/external-notifications.mdx b/docs/software/plugins/external-notifications.mdx deleted file mode 100644 index e6b4de2a..00000000 --- a/docs/software/plugins/external-notifications.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -id: ext-notif-module -title: 1.2 External notifications -sidebar_label: 1.2 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. diff --git a/docs/software/plugins/range-test.mdx b/docs/software/plugins/range-test.mdx deleted file mode 100644 index 6c005dd9..00000000 --- a/docs/software/plugins/range-test.mdx +++ /dev/null @@ -1,95 +0,0 @@ ---- -id: range-test-module -title: 1.2 Range Test Plugin -sidebar_label: 1.2 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. diff --git a/docs/software/plugins/serial.mdx b/docs/software/plugins/serial.mdx deleted file mode 100644 index fe7e2c87..00000000 --- a/docs/software/plugins/serial.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -id: serial-plugin -title: Serial communication plugin -sidebar_label: 1.2 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. From c935a9c4571fe114e13b1e44290c1a81032ef704 Mon Sep 17 00:00:00 2001 From: Garth Vander Houwen Date: Sun, 3 Jul 2022 11:21:24 -0700 Subject: [PATCH 04/15] Delete duplicate store and forward doc page --- docs/software/plugins/_category_.yml | 8 - docs/software/plugins/store-forward.mdx | 218 ------------------------ 2 files changed, 226 deletions(-) delete mode 100644 docs/software/plugins/_category_.yml delete mode 100644 docs/software/plugins/store-forward.mdx diff --git a/docs/software/plugins/_category_.yml b/docs/software/plugins/_category_.yml deleted file mode 100644 index 4dd2a8bd..00000000 --- a/docs/software/plugins/_category_.yml +++ /dev/null @@ -1,8 +0,0 @@ - -position: 5 # float position is supported -label: 1.2 Firmware Plugins -collapsible: true # make the category collapsible -link: - type: generated-index - title: Firmware Modules - slug: /software/plugins \ No newline at end of file diff --git a/docs/software/plugins/store-forward.mdx b/docs/software/plugins/store-forward.mdx deleted file mode 100644 index 72e90142..00000000 --- a/docs/software/plugins/store-forward.mdx +++ /dev/null @@ -1,218 +0,0 @@ ---- -id: store-forward-module -title: 1.2 Store and Forward Plugin -sidebar_label: 1.2 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 - -![Store & Forward - Overview](/img/modules/store_and_forward/store_and_forward-overview.png) - -## Requirements - -Initial Requirements: - -- Must be installed on a router node. - - This is an artificial limitation, but is in place to enforce best practices. - - Router nodes are intended to be always online. If this module misses any messages, the reliability of the stored messages will be reduced. -- Esp32 Processor based device with external PSRAM. (tbeam v1.0 and tbeamv1.1, and maybe others) - -## Usage Overview - -To use / test this you will want at least 3 devices - -- One device will (currently) need be a tbeam v1.0 and tbeamv1.1 configured as a Meshtastic router. Other devices with built in PSRAM will be supported at some point. -- Two others will be regular clients. Nothing special required. - -### Meshtastic channel configuration - -Don't use this on the "Long Range / Slow" or "Long Range / Fast" channel settings. You're welcome to try and report back, but those channels have a [very low bitrate](/docs/developers/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. From f88f23ccd1d25e2a99b4875ad4f0255f30521898 Mon Sep 17 00:00:00 2001 From: Garth Vander Houwen Date: Sun, 3 Jul 2022 11:35:25 -0700 Subject: [PATCH 05/15] Delete modue landing blocks --- docs/_blocks/_module_overview_text.mdx | 16 ---------------- docs/_blocks/_plugin_overview_text.mdx | 17 ----------------- 2 files changed, 33 deletions(-) delete mode 100644 docs/_blocks/_module_overview_text.mdx delete mode 100644 docs/_blocks/_plugin_overview_text.mdx diff --git a/docs/_blocks/_module_overview_text.mdx b/docs/_blocks/_module_overview_text.mdx deleted file mode 100644 index d03af435..00000000 --- a/docs/_blocks/_module_overview_text.mdx +++ /dev/null @@ -1,16 +0,0 @@ - -Modules are included in the firmware and allow users to extend the functionality of their mesh or device. - -| Name | Description | -|:----:|:-----------:| -| [Canned Message](/settings/moduleconfig/canned-message) | Set a number of predefined messages to send out directly from the device with the use of an input device like a rotary encoder. | -| [External Notification](external-notification) | Incoming messages are able to alert you using circuits you attach to the device (LEDs, Buzzers, etc) | -| [Input Broker](input-broker) | Attach and define input devices such as external keyboards and rotary encoders. | -| [Range Test](range-test) | Send messages with GPS location at an interval to test the distance your devices can communicate. Requires (at least) one device set up as a sender and one as a receiver. The receiver(s) will log all incoming messages to a CSV. | -| [Serial Module](serial) | Send messages across the mesh by sending strings over a serial port. | -| [Store and Forward](store-and-forward) | Set a designated node to store messages and resend them to nodes with intermittent connection to a mesh. | -| [Telemetry](telemetry) | 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. -::: diff --git a/docs/_blocks/_plugin_overview_text.mdx b/docs/_blocks/_plugin_overview_text.mdx deleted file mode 100644 index 9ea84bdf..00000000 --- a/docs/_blocks/_plugin_overview_text.mdx +++ /dev/null @@ -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. -::: From 92ea05e5d3e6cb364e3ef297b13567cedcb70fa9 Mon Sep 17 00:00:00 2001 From: Garth Vander Houwen Date: Sun, 3 Jul 2022 11:46:00 -0700 Subject: [PATCH 06/15] Fix broken links --- docs/developers/Firmware/module-api.mdx | 2 +- docs/developers/contributing.mdx | 2 +- docs/faq/modules.mdx | 2 +- docs/hardware/antenna/testing.mdx | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/developers/Firmware/module-api.mdx b/docs/developers/Firmware/module-api.mdx index c1eca8dc..83e09153 100644 --- a/docs/developers/Firmware/module-api.mdx +++ b/docs/developers/Firmware/module-api.mdx @@ -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. diff --git a/docs/developers/contributing.mdx b/docs/developers/contributing.mdx index 5b23e5d8..c96d37e3 100644 --- a/docs/developers/contributing.mdx +++ b/docs/developers/contributing.mdx @@ -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 diff --git a/docs/faq/modules.mdx b/docs/faq/modules.mdx index d543c204..895df351 100644 --- a/docs/faq/modules.mdx +++ b/docs/faq/modules.mdx @@ -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? diff --git a/docs/hardware/antenna/testing.mdx b/docs/hardware/antenna/testing.mdx index decfbadc..251a052d 100644 --- a/docs/hardware/antenna/testing.mdx +++ b/docs/hardware/antenna/testing.mdx @@ -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. From def6f557db30cfe587e3fafcc848868d14474aa7 Mon Sep 17 00:00:00 2001 From: Garth Vander Houwen Date: Sun, 3 Jul 2022 11:50:37 -0700 Subject: [PATCH 07/15] remove broken link --- docs/developers/Firmware/module-api.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developers/Firmware/module-api.mdx b/docs/developers/Firmware/module-api.mdx index 83e09153..d20771ad 100644 --- a/docs/developers/Firmware/module-api.mdx +++ b/docs/developers/Firmware/module-api.mdx @@ -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. - [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 From c610dee9123ba1a0c82a76eec1bc95c543e4ba99 Mon Sep 17 00:00:00 2001 From: Garth Vander Houwen Date: Sun, 3 Jul 2022 11:58:04 -0700 Subject: [PATCH 08/15] Remove extra pages --- docs/settings/ham.mdx | 34 ++++ docs/software/device/channels.mdx | 66 ------- docs/software/device/ham.mdx | 43 ----- .../device/remote-hardware-service.mdx | 171 ------------------ 4 files changed, 34 insertions(+), 280 deletions(-) delete mode 100644 docs/software/device/channels.mdx delete mode 100644 docs/software/device/ham.mdx delete mode 100644 docs/software/device/remote-hardware-service.mdx diff --git a/docs/settings/ham.mdx b/docs/settings/ham.mdx index 861eb87b..0ada6ab4 100644 --- a/docs/settings/ham.mdx +++ b/docs/settings/ham.mdx @@ -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 +``` diff --git a/docs/software/device/channels.mdx b/docs/software/device/channels.mdx deleted file mode 100644 index 61ecf295..00000000 --- a/docs/software/device/channels.mdx +++ /dev/null @@ -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 -``` diff --git a/docs/software/device/ham.mdx b/docs/software/device/ham.mdx deleted file mode 100644 index d43c570a..00000000 --- a/docs/software/device/ham.mdx +++ /dev/null @@ -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 -``` diff --git a/docs/software/device/remote-hardware-service.mdx b/docs/software/device/remote-hardware-service.mdx deleted file mode 100644 index 676f807c..00000000 --- a/docs/software/device/remote-hardware-service.mdx +++ /dev/null @@ -1,171 +0,0 @@ ---- -id: remote-hardware-service -title: 1.2 Remote Hardware Service -sidebar_label: 1.2 Remote Hardware ---- - -:::warning -GPIO access is fundamentally dangerous because invalid options can physically damage or destroy your hardware. Ensure that you fully understand the schematic for your particular device before trying this as we do not offer a warranty. Use at your own risk. -::: - -:::note -This feature uses a preinstalled module in the device code and associated command line flags/classes in the python code. You'll need to be running at least version 1.2.23 (or later) of the python and device code to use this feature. -::: - -You can get the latest python tool/library with `pip3 install --upgrade meshtastic` on Windows/Linux/OS-X. See the [python section](/docs/software/python/python-installation) for more details. - -## Supported operations in the initial release - -- Set any GPIO -- Read 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. - -The procedure using the python command line tool is: - -1. Connect local device via USB - -2. Create a gpio channel - ```shell - meshtastic --ch-add gpio - ``` - -:::tip -If doing local testing, may want to change the speed of the channel at this time, too. (ex: "meshtastic --ch-mediumfast") -::: - -3. Check the channel has been created and copy the long "Complete URL" that contains all the channels on that device - - ```shell - meshtastic --info - ``` - -4. Connect the remote device via USB (or use the [remote admin](device-remote-admin) feature to reach it through the mesh) - -5. Set it to join the gpio channel you created - ```shell - meshtastic --seturl theurlyoucopiedinstep3 - ``` - -Now both devices should be able to talk over the `gpio` channel. Send a text message from one the other other verify. Also run "--nodes" to verify the second node shows up. - -## A little bit of information about masks - -To determine the appropriate mask for the pin(s) that you want to know. The python program (and output) below might help: - -``` ->>> for i in range(1,45): -... print(f'GPIO:{i} mask:{hex(2**i)}') -... -GPIO:1 mask:0x2 -GPIO:2 mask:0x4 -GPIO:3 mask:0x8 -GPIO:4 mask:0x10 -GPIO:5 mask:0x20 -GPIO:6 mask:0x40 -GPIO:7 mask:0x80 -GPIO:8 mask:0x100 -GPIO:9 mask:0x200 -GPIO:10 mask:0x400 -GPIO:11 mask:0x800 -GPIO:12 mask:0x1000 -GPIO:13 mask:0x2000 -GPIO:14 mask:0x4000 -GPIO:15 mask:0x8000 -GPIO:16 mask:0x10000 -GPIO:17 mask:0x20000 -GPIO:18 mask:0x40000 -GPIO:19 mask:0x80000 -GPIO:20 mask:0x100000 -GPIO:21 mask:0x200000 -GPIO:22 mask:0x400000 -GPIO:23 mask:0x800000 -GPIO:24 mask:0x1000000 -GPIO:25 mask:0x2000000 -GPIO:26 mask:0x4000000 -GPIO:27 mask:0x8000000 -GPIO:28 mask:0x10000000 -GPIO:29 mask:0x20000000 -GPIO:30 mask:0x40000000 -GPIO:31 mask:0x80000000 -GPIO:32 mask:0x100000000 -GPIO:33 mask:0x200000000 -GPIO:34 mask:0x400000000 -GPIO:35 mask:0x800000000 -GPIO:36 mask:0x1000000000 -GPIO:37 mask:0x2000000000 -GPIO:38 mask:0x4000000000 -GPIO:39 mask:0x8000000000 -GPIO:40 mask:0x10000000000 -GPIO:41 mask:0x20000000000 -GPIO:42 mask:0x40000000000 -GPIO:43 mask:0x80000000000 -GPIO:44 mask:0x100000000000 -``` - -## How to easily test GPIO operations? - -You can add a simple LED and resistor to validate that the GPIO operations work as expected. Used the tutorial at https://www.instructables.com/Slide-Switch-With-Arduino-Uno-R3/ as a guide. - -Need: - -- 2 Meshtastic devices (one device could be on a local computer, and the other one just has to be powered and is the one with the LED to be connected to it) -- 2 wires (black and yellow; they can be any color but typically black is used for ground) -- breadboard (optional) -- 1 LED -- 1 220Ω resistor (somewhat optional, but recommended) - -Prep: - -- disconnect the remote device from power (battery/usb) -- add a resistor from yellow wire to the one end of the LED (either end of the resistor is ok, either end of the LED is ok) -- add the yellow wire from a GPIO pin that will not cause any issues (ex: for TLoraV1, we can use GPIO21) -- add the black "ground" wire from the ground pin on the device (ex: for TLoraV1 it is the end pin next to the RST button) to the other end of the LED -- power on the device - -Validation: -By default, the pin may be "off" or "on". (It will most likely "off".) See the steps below for running commands. In the example of GPIO21, the mask would be 0x200000. - -[T-Lora v1 with LED on GPIO 21](/img/LED_on_TLoraV1.jpg) - -## Doing GPIO operations - -You can programmatically do operations from your own python code by using the Meshtastic `RemoteHardwareClient` class. See the [python API](/docs/software/python/python-installation) documentation for more details. - -## Using GPIOs from the python CLI - -Writing a GPIO (ex: turn "on" GPIO4): - -```shell 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 (ex: read GPIO4): - -```shell title="Expected output" -$ meshtastic --port /dev/ttyUSB0 --gpio-rd 0x10 --dest \!28979058 -Connected to radio -Reading GPIO mask 0x10 from !28979058 -GPIO read response gpio_value=16 -``` - -:::note -If the mask and the gpio_value match, then the value is "on". If the gpio_value is 0, then the value is "off". -::: - -Watching for GPIO changes (ex: watching GPIO4 for changes): - -```shell title="Expected output" -$ meshtastic --port /dev/ttyUSB0 --gpio-watch 0x10 --dest \!28979058 -Connected to radio -Watching GPIO mask 0x10 from !28979058 -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 > -``` From 71bd8d2383237b22fe99d4b46c45f50f438dff66 Mon Sep 17 00:00:00 2001 From: Garth Vander Houwen Date: Sun, 3 Jul 2022 12:02:54 -0700 Subject: [PATCH 09/15] Fix links --- docs/faq/channel.mdx | 2 +- docs/software/device/remote-admin.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/faq/channel.mdx b/docs/faq/channel.mdx index 9e286c1b..d6a1e99d 100644 --- a/docs/faq/channel.mdx +++ b/docs/faq/channel.mdx @@ -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. diff --git a/docs/software/device/remote-admin.mdx b/docs/software/device/remote-admin.mdx index 66f2da6f..a8d1254e 100644 --- a/docs/software/device/remote-admin.mdx +++ b/docs/software/device/remote-admin.mdx @@ -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. From f5b1f96e31d8b54c3d5387cea733b9f000a1e972 Mon Sep 17 00:00:00 2001 From: Garth Vander Houwen Date: Sun, 3 Jul 2022 12:06:06 -0700 Subject: [PATCH 10/15] Bad link --- docs/settings/moduleconfig/range-test.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/settings/moduleconfig/range-test.mdx b/docs/settings/moduleconfig/range-test.mdx index dc978efd..216dddc7 100644 --- a/docs/settings/moduleconfig/range-test.mdx +++ b/docs/settings/moduleconfig/range-test.mdx @@ -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 From 90b2f6f5c9cf9fa974b7cd652f8b88f96d26d6c2 Mon Sep 17 00:00:00 2001 From: Garth Vander Houwen Date: Sun, 3 Jul 2022 12:12:36 -0700 Subject: [PATCH 11/15] Fix some slugs and titles --- docs/software/_category_.yml | 3 ++- docs/software/python/_category_.yml | 3 ++- docs/software/python/cli.mdx | 4 ++-- docs/software/python/development.mdx | 4 ++-- docs/software/python/uses.mdx | 2 +- docs/software/python/using_library.mdx | 2 +- 6 files changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/software/_category_.yml b/docs/software/_category_.yml index 35567f4a..507913f7 100644 --- a/docs/software/_category_.yml +++ b/docs/software/_category_.yml @@ -4,4 +4,5 @@ label: Software collapsible: true # make the category collapsible link: type: generated-index - title: Software \ No newline at end of file + title: Software + slug: /software \ No newline at end of file diff --git a/docs/software/python/_category_.yml b/docs/software/python/_category_.yml index 92798c9c..b1debdd7 100644 --- a/docs/software/python/_category_.yml +++ b/docs/software/python/_category_.yml @@ -4,4 +4,5 @@ label: Python CLI collapsible: true # make the category collapsible link: type: generated-index - title: Python \ No newline at end of file + title: Python + slug: /software/python-cli \ No newline at end of file diff --git a/docs/software/python/cli.mdx b/docs/software/python/cli.mdx index 718fd344..c0ec6a11 100644 --- a/docs/software/python/cli.mdx +++ b/docs/software/python/cli.mdx @@ -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 diff --git a/docs/software/python/development.mdx b/docs/software/python/development.mdx index 1f466720..bb1fcfb0 100644 --- a/docs/software/python/development.mdx +++ b/docs/software/python/development.mdx @@ -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 diff --git a/docs/software/python/uses.mdx b/docs/software/python/uses.mdx index 89b69560..5201206d 100644 --- a/docs/software/python/uses.mdx +++ b/docs/software/python/uses.mdx @@ -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. diff --git a/docs/software/python/using_library.mdx b/docs/software/python/using_library.mdx index 81ded923..5d5711cd 100644 --- a/docs/software/python/using_library.mdx +++ b/docs/software/python/using_library.mdx @@ -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: From 4287b3f3e7e2d52335b52c53aef5cb2037fb8053 Mon Sep 17 00:00:00 2001 From: Garth Vander Houwen Date: Sun, 3 Jul 2022 12:22:24 -0700 Subject: [PATCH 12/15] fix the slugs --- docusaurus.config.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index a2e71d22..cf6d3b89 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -88,11 +88,11 @@ const config = { }, { label: 'Software', - to: 'docs/category/software', + to: 'docs/software', }, { label: 'Developers', - to: 'docs/category/developers', + to: 'docs/developers', }, ], }, From e51478a3a4e8cc86297ee02169e8ffe27d433156 Mon Sep 17 00:00:00 2001 From: Garth Vander Houwen Date: Sun, 3 Jul 2022 12:26:34 -0700 Subject: [PATCH 13/15] fix developers slug --- docs/developers/_category_.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/developers/_category_.yml b/docs/developers/_category_.yml index d259f462..d4feb728 100644 --- a/docs/developers/_category_.yml +++ b/docs/developers/_category_.yml @@ -4,4 +4,5 @@ label: 'Developers' collapsible: true # make the category collapsible link: type: generated-index - title: Developers \ No newline at end of file + title: Developers + slug: /developers \ No newline at end of file From 8a0131e6b8dc651012b94983d2565e6e47252197 Mon Sep 17 00:00:00 2001 From: Garth Vander Houwen Date: Sun, 3 Jul 2022 12:31:23 -0700 Subject: [PATCH 14/15] Fix links --- docs/faq/index.mdx | 2 +- docs/software/python/uses.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/faq/index.mdx b/docs/faq/index.mdx index b38806f9..f36a76c2 100644 --- a/docs/faq/index.mdx +++ b/docs/faq/index.mdx @@ -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. diff --git a/docs/software/python/uses.mdx b/docs/software/python/uses.mdx index 5201206d..2bc7f08a 100644 --- a/docs/software/python/uses.mdx +++ b/docs/software/python/uses.mdx @@ -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 From d639e4e1f560bf790acf23465039ddd9de7fc441 Mon Sep 17 00:00:00 2001 From: Garth Vander Houwen Date: Sun, 3 Jul 2022 12:46:46 -0700 Subject: [PATCH 15/15] Add back remote hardware page --- docs/developers/Firmware/module-api.mdx | 2 +- .../device/remote-hardware-service.mdx | 171 ++++++++++++++++++ 2 files changed, 172 insertions(+), 1 deletion(-) create mode 100644 docs/software/device/remote-hardware-service.mdx diff --git a/docs/developers/Firmware/module-api.mdx b/docs/developers/Firmware/module-api.mdx index d20771ad..ddd2c5a5 100644 --- a/docs/developers/Firmware/module-api.mdx +++ b/docs/developers/Firmware/module-api.mdx @@ -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. +- [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 diff --git a/docs/software/device/remote-hardware-service.mdx b/docs/software/device/remote-hardware-service.mdx new file mode 100644 index 00000000..bb6f796a --- /dev/null +++ b/docs/software/device/remote-hardware-service.mdx @@ -0,0 +1,171 @@ +--- +id: remote-hardware-service +title: Remote Hardware Service +sidebar_label: Remote Hardware +--- + +:::warning +GPIO access is fundamentally dangerous because invalid options can physically damage or destroy your hardware. Ensure that you fully understand the schematic for your particular device before trying this as we do not offer a warranty. Use at your own risk. +::: + +:::note +This feature uses a preinstalled module in the device code and associated command line flags/classes in the python code. You'll need to be running at least version 1.2.23 (or later) of the python and device code to use this feature. +::: + +You can get the latest python tool/library with `pip3 install --upgrade meshtastic` on Windows/Linux/OS-X. See the [python section](/docs/software/python/python-installation) for more details. + +## Supported operations in the initial release + +- Set any GPIO +- Read 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. + +The procedure using the python command line tool is: + +1. Connect local device via USB + +2. Create a gpio channel + ```shell + meshtastic --ch-add gpio + ``` + +:::tip +If doing local testing, may want to change the speed of the channel at this time, too. (ex: "meshtastic --ch-mediumfast") +::: + +3. Check the channel has been created and copy the long "Complete URL" that contains all the channels on that device + + ```shell + meshtastic --info + ``` + +4. Connect the remote device via USB (or use the [remote admin](device-remote-admin) feature to reach it through the mesh) + +5. Set it to join the gpio channel you created + ```shell + meshtastic --seturl theurlyoucopiedinstep3 + ``` + +Now both devices should be able to talk over the `gpio` channel. Send a text message from one the other other verify. Also run "--nodes" to verify the second node shows up. + +## A little bit of information about masks + +To determine the appropriate mask for the pin(s) that you want to know. The python program (and output) below might help: + +``` +>>> for i in range(1,45): +... print(f'GPIO:{i} mask:{hex(2**i)}') +... +GPIO:1 mask:0x2 +GPIO:2 mask:0x4 +GPIO:3 mask:0x8 +GPIO:4 mask:0x10 +GPIO:5 mask:0x20 +GPIO:6 mask:0x40 +GPIO:7 mask:0x80 +GPIO:8 mask:0x100 +GPIO:9 mask:0x200 +GPIO:10 mask:0x400 +GPIO:11 mask:0x800 +GPIO:12 mask:0x1000 +GPIO:13 mask:0x2000 +GPIO:14 mask:0x4000 +GPIO:15 mask:0x8000 +GPIO:16 mask:0x10000 +GPIO:17 mask:0x20000 +GPIO:18 mask:0x40000 +GPIO:19 mask:0x80000 +GPIO:20 mask:0x100000 +GPIO:21 mask:0x200000 +GPIO:22 mask:0x400000 +GPIO:23 mask:0x800000 +GPIO:24 mask:0x1000000 +GPIO:25 mask:0x2000000 +GPIO:26 mask:0x4000000 +GPIO:27 mask:0x8000000 +GPIO:28 mask:0x10000000 +GPIO:29 mask:0x20000000 +GPIO:30 mask:0x40000000 +GPIO:31 mask:0x80000000 +GPIO:32 mask:0x100000000 +GPIO:33 mask:0x200000000 +GPIO:34 mask:0x400000000 +GPIO:35 mask:0x800000000 +GPIO:36 mask:0x1000000000 +GPIO:37 mask:0x2000000000 +GPIO:38 mask:0x4000000000 +GPIO:39 mask:0x8000000000 +GPIO:40 mask:0x10000000000 +GPIO:41 mask:0x20000000000 +GPIO:42 mask:0x40000000000 +GPIO:43 mask:0x80000000000 +GPIO:44 mask:0x100000000000 +``` + +## How to easily test GPIO operations? + +You can add a simple LED and resistor to validate that the GPIO operations work as expected. Used the tutorial at https://www.instructables.com/Slide-Switch-With-Arduino-Uno-R3/ as a guide. + +Need: + +- 2 Meshtastic devices (one device could be on a local computer, and the other one just has to be powered and is the one with the LED to be connected to it) +- 2 wires (black and yellow; they can be any color but typically black is used for ground) +- breadboard (optional) +- 1 LED +- 1 220Ω resistor (somewhat optional, but recommended) + +Prep: + +- disconnect the remote device from power (battery/usb) +- add a resistor from yellow wire to the one end of the LED (either end of the resistor is ok, either end of the LED is ok) +- add the yellow wire from a GPIO pin that will not cause any issues (ex: for TLoraV1, we can use GPIO21) +- add the black "ground" wire from the ground pin on the device (ex: for TLoraV1 it is the end pin next to the RST button) to the other end of the LED +- power on the device + +Validation: +By default, the pin may be "off" or "on". (It will most likely "off".) See the steps below for running commands. In the example of GPIO21, the mask would be 0x200000. + +[T-Lora v1 with LED on GPIO 21](/img/LED_on_TLoraV1.jpg) + +## Doing GPIO operations + +You can programmatically do operations from your own python code by using the Meshtastic `RemoteHardwareClient` class. See the [python API](/docs/software/python/python-installation) documentation for more details. + +## Using GPIOs from the python CLI + +Writing a GPIO (ex: turn "on" GPIO4): + +```shell 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 (ex: read GPIO4): + +```shell title="Expected output" +$ meshtastic --port /dev/ttyUSB0 --gpio-rd 0x10 --dest \!28979058 +Connected to radio +Reading GPIO mask 0x10 from !28979058 +GPIO read response gpio_value=16 +``` + +:::note +If the mask and the gpio_value match, then the value is "on". If the gpio_value is 0, then the value is "off". +::: + +Watching for GPIO changes (ex: watching GPIO4 for changes): + +```shell title="Expected output" +$ meshtastic --port /dev/ttyUSB0 --gpio-watch 0x10 --dest \!28979058 +Connected to radio +Watching GPIO mask 0x10 from !28979058 +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 > +``` \ No newline at end of file