From f4e9c19c314a82e47d774f6adfad8786256c366d Mon Sep 17 00:00:00 2001 From: pdxlocations Date: Wed, 20 Sep 2023 16:51:53 -0700 Subject: [PATCH 1/6] add remote-hardware page --- .../module-config/remote-hardware.mdx | 238 ++++++++++++++++++ 1 file changed, 238 insertions(+) create mode 100644 docs/configuration/module-config/remote-hardware.mdx diff --git a/docs/configuration/module-config/remote-hardware.mdx b/docs/configuration/module-config/remote-hardware.mdx new file mode 100644 index 00000000..2f75ae29 --- /dev/null +++ b/docs/configuration/module-config/remote-hardware.mdx @@ -0,0 +1,238 @@ +--- +id: remote-hardware +title: Remote Hardware Module Usage +slug: /settings/moduleconfig/remote-hardware +sidebar_label: Remote Hardware +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +The Remote Hardware Module allows control of a GPIO pin on a remote node. Config options are: Enabled, Allow Undefined Pin Access, Available Pins + +:::info + +While configuring this module may be available in clients, setting and reading GPIO's is currently only possible using the [Meshtastic Python CLI](/docs/software/python/cli) + +::: + +## Remote Hardware Config Values + +### Enabled + +Whether the module is enabled + +### Allow Undefined Pin Access + +Whether the module allows consumers to read/write to pins not that are not defined in available_pins + +### Available Pins + +Exposes the available pins to the mesh for reading and writing + + +## Remote Hardware Module Client Availability + + + + + +:::info +All Remote Hardware Module config options are available for Android in app. + +1. Open the Meshtastic App +2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > Remote Hardware** +::: + + + + +:::info +All Remote Hardware Module config options are available on iOS, iPadOS and macOS app.and higher at Settings > Modules > Remote Hardware +::: + + + + +:::info + +All Remote Hardware Module config options are available in the python CLI. + +::: + + + + +Not implemented. + + + + + + + +## Remote Hardware Module Usage + +:::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. +::: + +### Supported Operations + +- Set any GPIO +- Read any GPIO +- Receive notification of changes in any GPIO + +### Setup + +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/cli/installation) for more details. + +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 + ``` +3. If doing local testing, you may also want to change the speed of the channel: + ```shell + meshtastic --ch-mediumfast + ``` +4. Check the channel has been created and copy the long "Complete URL" that contains all the channels on that device: + ```shell + meshtastic --info + ``` +5. Connect the remote device via USB (or use the [remote admin](/docs/configuration/remote-admin) feature to reach it through the mesh) +6. 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 to the other to verify. Also run `--nodes` to verify the second node shows up. + +### Masks + +To determine the appropriate mask for the pin(s) that you want to know. The python program (and output) below might help: + +```python +>>> 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 +``` + +## Testing 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/cli/installation) documentation for more details. + +You can add a simple LED and resistor to validate that the GPIO operations work as expected. Use [this tutorial](https://www.instructables.com/Slide-Switch-With-Arduino-Uno-R3/) as a guide. + +### Requirements + +- (x2) 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) +- (x2) wires (black and yellow; they can be any color but typically black is used for ground) +- (x1) LED +- (x1) 220Ω resistor (somewhat optional, but recommended) +- (x1) Breadboard (optional) + +### Preparation + +1. Disconnect the remote device from power (battery/usb) +2. Connect the resistor to the longer (positive) lead of the LED and the yellow wire to the other end of the resistor +3. Connect the other end of the yellow wire to a GPIO pin that will not cause any issues (ex: for TLoraV1, we can use GPIO21) +4. Connect 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 shorter (negative) lead of the LED +5. 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) + +## Using GPIOs from the Python CLI + +### Writing a GPIO + +```shell title="Example: turning 'on' GPIO4" +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 + +```shell title="Example: read GPIO4" +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 + +```shell title="Example: watching GPIO4 for changes" +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 5642df9648c147c78f4dd11c0c1944a4da3a000e Mon Sep 17 00:00:00 2001 From: pdxlocations Date: Wed, 20 Sep 2023 16:52:38 -0700 Subject: [PATCH 2/6] update index --- docs/configuration/module-config/index.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/configuration/module-config/index.mdx b/docs/configuration/module-config/index.mdx index 1f44bde9..d7086b3a 100644 --- a/docs/configuration/module-config/index.mdx +++ b/docs/configuration/module-config/index.mdx @@ -18,6 +18,7 @@ Modules are included in the firmware and allow users to extend the functionality | [MQTT](/docs/settings/moduleconfig/mqtt) | Forward packets along to an MQTT server. This allows users on the local mesh to communicate with users on another mesh over the internet. | | [Neighbor Info](/docs/settings/moduleconfig/neighbor-info) | Send info on 0-hop neighbors to the mesh. | | [Range Test](/docs/settings/moduleconfig/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. | +| [Remote Hardware](/docs/settings/moduleconfig/remote-hardware) | Set and read a GPIO status remotely over the mesh. | | [Serial Module](/docs/settings/moduleconfig/serial) | Send messages across the mesh by sending strings over a serial port. | | [Store & Forward](/docs/settings/moduleconfig/store-and-forward-module) | Stores messages on a device for delivery after disconnected clients rejoin the mesh. | | [Telemetry](/docs/settings/moduleconfig/telemetry) | Attach sensors to the device and transmit readings on a regular interval to the mesh. | From f9a35c46c565ba000a1d919cc5a6de1e85d85d57 Mon Sep 17 00:00:00 2001 From: pdxlocations Date: Wed, 20 Sep 2023 16:55:04 -0700 Subject: [PATCH 3/6] update link --- docs/development/device/module-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/device/module-api.mdx b/docs/development/device/module-api.mdx index 01832c4c..fa61fa22 100644 --- a/docs/development/device/module-api.mdx +++ b/docs/development/device/module-api.mdx @@ -57,7 +57,7 @@ A number of [key services](http://github.com/meshtastic/firmware/tree/master/src - [NodeInfoModule](http://github.com/meshtastic/firmware/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/firmware/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/hardware/peripheral/#remote-hardware) for details. +- [RemoteHardwareModule](http://github.com/meshtastic/firmware/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/settings/moduleconfig/remote-hardware) for details. - [ReplyModule](http://github.com/meshtastic/firmware/tree/master/src/modules/ReplyModule.h) - A simple module that just replies to any packet it receives (provides a 'ping' service). From 0013d2e18ec640a8c8495aabe86002aaf85658bb Mon Sep 17 00:00:00 2001 From: pdxlocations Date: Wed, 20 Sep 2023 16:55:36 -0700 Subject: [PATCH 4/6] remove gpio-peripherals --- docs/configuration/gpio-peripherals.mdx | 165 ------------------------ 1 file changed, 165 deletions(-) delete mode 100644 docs/configuration/gpio-peripherals.mdx diff --git a/docs/configuration/gpio-peripherals.mdx b/docs/configuration/gpio-peripherals.mdx deleted file mode 100644 index ea8c5730..00000000 --- a/docs/configuration/gpio-peripherals.mdx +++ /dev/null @@ -1,165 +0,0 @@ ---- -id: gpio-peripherals -title: Configuring GPIO Peripherals -sidebar_label: Setup GPIO Peripherals -slug: /hardware/peripheral/ -sidebar_position: 4 ---- - -## 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. -::: - -### Supported Operations - -- Set any GPIO -- Read any GPIO -- Receive notification of changes in any GPIO - -### Setup - -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/cli/installation) for more details. - -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 - ``` -3. If doing local testing, you may also want to change the speed of the channel: - ```shell - meshtastic --ch-mediumfast - ``` -4. Check the channel has been created and copy the long "Complete URL" that contains all the channels on that device: - ```shell - meshtastic --info - ``` -5. Connect the remote device via USB (or use the [remote admin](/docs/configuration/remote-admin) feature to reach it through the mesh) -6. 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 to the other to verify. Also run `--nodes` to verify the second node shows up. - -### Masks - -To determine the appropriate mask for the pin(s) that you want to know. The python program (and output) below might help: - -```python ->>> 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 -``` - -## Testing 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/cli/installation) documentation for more details. - -You can add a simple LED and resistor to validate that the GPIO operations work as expected. Use [this tutorial](https://www.instructables.com/Slide-Switch-With-Arduino-Uno-R3/) as a guide. - -### Requirements - -- (x2) 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) -- (x2) wires (black and yellow; they can be any color but typically black is used for ground) -- (x1) LED -- (x1) 220Ω resistor (somewhat optional, but recommended) -- (x1) Breadboard (optional) - -### Preparation - -1. Disconnect the remote device from power (battery/usb) -2. Connect the resistor to the longer (positive) lead of the LED and the yellow wire to the other end of the resistor -3. Connect the other end of the yellow wire to a GPIO pin that will not cause any issues (ex: for TLoraV1, we can use GPIO21) -4. Connect 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 shorter (negative) lead of the LED -5. 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) - -## Using GPIOs from the Python CLI - -### Writing a GPIO - -```shell title="Example: turning 'on' GPIO4" -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 - -```shell title="Example: read GPIO4" -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 - -```shell title="Example: watching GPIO4 for changes" -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 d00a35ae72b201b45a977ba8b9e7e4a0470b2cd2 Mon Sep 17 00:00:00 2001 From: pdxlocations Date: Mon, 25 Sep 2023 18:50:51 -0700 Subject: [PATCH 5/6] info box with link to info --- docs/configuration/device-config/lora.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/configuration/device-config/lora.mdx b/docs/configuration/device-config/lora.mdx index 821e7a7c..e6dd9073 100644 --- a/docs/configuration/device-config/lora.mdx +++ b/docs/configuration/device-config/lora.mdx @@ -103,6 +103,10 @@ Defaults to true This is controlling the actual hardware frequency the radio is transmitting on. A channel number between 1 and NUM_CHANNELS (whatever the max is in the current region). If this is ZERO/UNSET then the rule is "use the old channel name hash based algorithm to derive the channel number". +:::info +LoRa Channel Configuration should not to be confused with messaging [Channel Configuration](/docs/settings/config/channels). See [Chat Channels VS Lora Modem Channels](/docs/configuration/tips#chat-channels-vs-lora-modem-channels) for further clarification. +::: + ### Ignore Incoming Array For testing it is useful sometimes to force a node to never listen to particular other nodes (simulating radio out of range). All nodenums listed in the ignore_incoming array will have packets they send dropped on receive (by router.cpp) From 6217a428056c60af121106443cad65a2da6d54ca Mon Sep 17 00:00:00 2001 From: GUVWAF Date: Tue, 26 Sep 2023 20:22:01 +0200 Subject: [PATCH 6/6] Update SerialModule with reference to Arduino client library --- docs/configuration/module-config/serial.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/configuration/module-config/serial.mdx b/docs/configuration/module-config/serial.mdx index fb01189c..7426e3e4 100644 --- a/docs/configuration/module-config/serial.mdx +++ b/docs/configuration/module-config/serial.mdx @@ -34,8 +34,8 @@ Available Values: - `DEFAULT` - `SIMPLE` operate as an dumb UART tunnel. What goes in will come out, Requires a channel named 'serial'. -- `PROTO` Exposes the Protobuf Client API on this serial port. You can use this to connect from another device. [API Reference](/docs/development/device/client-api) -- `TEXTMSG` Will send the string received over the serial port as a Text Message for Display on the other devices. +- `PROTO` Exposes the Protobuf Client API on this serial port. You can use this to connect from another device, see the [Arduino client library](https://github.com/meshtastic/Meshtastic-arduino) and the [API Reference](/docs/development/device/client-api). +- `TEXTMSG` Will broadcast the string received over the serial port as a Text Message to the default channel. - `NMEA` Will output a NMEA 0183 Data stream containing the internal GPS or fixed position and other node locations as Waypoints (WPL). - `CALTOPO` Will output NMEA 0183 Waypoints (WPL) every 10 seconds for all valid node locations, to be consumed by [CalTopo / SARTopo](/docs/software/integrations/caltopo.mdx). @@ -112,7 +112,7 @@ All serial module config options are available in the python CLI. Example comman | serial.mode | `DEFAULT` `SIMPLE` `PROTO` `TEXTMSG`, `NMEA`, `CALTOPO` | `DEFAULT` | | serial.rxd | GPIO Pin Number 1-39 | Default of `0` is Unset | | serial.txd | GPIO Pin Number 1-33 | Default of `0` is Unset | -| serial.baud | `BAUD_DEFAULT` `BAUD_110` `BAUD_300` `BAUD_600` `BAUD_1200` `BAUD_2400` `BAUD_4800` `BAUD_9600` `BAUD_19200` `BAUD_38400` `BAUD_57600` `BAUD_115200` `BAUD_230400` `BAUD_460800` `BAUD_576000` `BAUD_921600` | `BAUD_DEFAULT` | +| serial.baud | `BAUD_DEFAULT` `BAUD_110` `BAUD_300` `BAUD_600` `BAUD_1200` `BAUD_2400` `BAUD_4800` `BAUD_9600` `BAUD_19200` `BAUD_38400` `BAUD_57600` `BAUD_115200` `BAUD_230400` `BAUD_460800` `BAUD_576000` `BAUD_921600` | `BAUD_DEFAULT` (38400) | | serial.timeout | `integer` (milli seconds) | Default of `0` corresponds to 250 ms | | serial.override_console_serial_port | `true`, `false` | `false` | @@ -186,12 +186,12 @@ Default is to use RX GPIO 16 and TX GPIO 17. - RXD 13 - TXD 14 3. Set `serial.timeout` to the amount of time to wait before we consider your packet as "done". -4. (Optional) set serial.mode to TEXTMSG if you want to send messages to/from the general text message channel +4. (Optional) set serial.mode to `TEXTMSG` if you want to send messages to/from the general text message channel. For more specific control, use the `PROTO` mode, e.g. in combination with the [Arduino client library](https://github.com/meshtastic/Meshtastic-arduino/blob/master/examples/SendReceiveClient/SendReceiveClient.ino). 5. Connect to your device over the serial interface at `38400 8N1`. With [tio](https://github.com/tio/tio) – `tio -e -b 38400 -f none /dev/myserialport` -6. Send a packet up to 237 bytes in length. This will get relayed over the mesh network. +6. Send a packet up to 237 bytes in length. This will get broadcasted over the default channel. 7. (Optional) Set `serial.echo` to `1` and any message you send out will be echoed back to your device. ### Interfacing PIR Sensor With External Microcontroller @@ -200,7 +200,7 @@ The following are examples of using either a Raspberry Pi Pico or Arduino Mini P #### Meshtastic Software Configuration -- Serial module enabled, mode: TXTMSG +- Serial module enabled, mode: TEXTMSG - GPIO Pins (For T-Beam) RX 13, TX 14 - 38400 Baud