mirror of
https://github.com/meshtastic/meshtastic.git
synced 2024-12-28 23:19:47 -08:00
249 lines
7.6 KiB
Plaintext
249 lines
7.6 KiB
Plaintext
---
|
|
id: remote-hardware
|
|
title: Remote Hardware Module Usage
|
|
sidebar_label: Remote Hardware
|
|
description: The Remote Hardware Module allows to read, write and watch GPIO pins on a remote node.
|
|
---
|
|
|
|
import Tabs from "@theme/Tabs";
|
|
import TabItem from "@theme/TabItem";
|
|
|
|
The Remote Hardware Module allows to read, write and watch GPIO pins on a remote node. Config options are: Enabled.
|
|
|
|
:::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.
|
|
|
|
## Remote Hardware Module Client Availability
|
|
|
|
<Tabs
|
|
groupId="settings"
|
|
defaultValue="cli"
|
|
values={[
|
|
{label: 'Android', value: 'android'},
|
|
{label: 'Apple', value: 'apple'},
|
|
{label: 'CLI', value: 'cli'},
|
|
{label: 'Web', value: 'web'},
|
|
]}>
|
|
<TabItem value="android">
|
|
|
|
#### Android
|
|
|
|
:::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**
|
|
:::
|
|
|
|
</TabItem>
|
|
<TabItem value="apple">
|
|
|
|
#### Apple
|
|
|
|
:::info
|
|
All Remote Hardware Module config options are available on iOS, iPadOS and macOS app.and higher at Settings > Module Configuration > Remote Hardware
|
|
:::
|
|
|
|
</TabItem>
|
|
<TabItem value="cli">
|
|
|
|
#### CLI
|
|
|
|
:::info
|
|
|
|
All Remote Hardware Module config options are available in the python CLI.
|
|
|
|
:::
|
|
|
|
</TabItem>
|
|
<TabItem value="web">
|
|
|
|
#### Web
|
|
|
|
Not implemented.
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
|
|
|
|
|
|
## 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 a notification over the mesh if any GPIO changes state.
|
|
Note that it cannot detect fast changes like button presses. For this, look at the [Detection Sensor module](/docs/configuration/module/detection-sensor) instead.
|
|
|
|
The result of reading a GPIO or notifications of GPIO changes will also be sent over MQTT (if enabled) in JSON format (if enabled).
|
|
|
|
### 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. Furthermore, you need to enable the module on both units.
|
|
|
|
The procedure using the python command line tool is:
|
|
|
|
1. Connect local device via USB
|
|
2. Enable the Remote Hardware module:
|
|
```shell
|
|
meshtastic --set remote_hardware.enabled true
|
|
```
|
|
3. Create a GPIO channel:
|
|
```shell
|
|
meshtastic --ch-add gpio
|
|
```
|
|
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. Enable the Remote Hardware module:
|
|
```shell
|
|
meshtastic --set remote_hardware.enabled true
|
|
```
|
|
7. 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
|
|
|
|
A mask is used to set the GPIOs to control. For GPIO 1, bit 1 of the mask is set (0x2 in hexadecimal), for GPIO 2, bit 2 of the mask is set (0x4 in hexadecimal), and so on.
|
|
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
|
|
```
|
|
|
|
## Using GPIOs from the Python CLI
|
|
|
|
:::info
|
|
You can also control or watch GPIOs of your USB-connected node by setting `--dest` to the local node's ID. No `gpio` channel is needed in this case.
|
|
:::
|
|
|
|
### 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 >
|
|
```
|
|
|
|
## 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`.
|
|
|
|
|