From cbfd80f893ecff3946f9b987182fc7ce0059262e Mon Sep 17 00:00:00 2001 From: Kevin Hester Date: Tue, 6 Apr 2021 10:56:23 +0800 Subject: [PATCH] fix #779. Add basic GPIO documentation --- docs/software/remote-hardware-service.md | 61 +++++++++++++++++++----- 1 file changed, 49 insertions(+), 12 deletions(-) diff --git a/docs/software/remote-hardware-service.md b/docs/software/remote-hardware-service.md index 1ff448cb3..50b08c1f7 100644 --- a/docs/software/remote-hardware-service.md +++ b/docs/software/remote-hardware-service.md @@ -1,23 +1,60 @@ # Remote Hardware Service -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. +These are 'programmer focused' notes on using the "remote hardware" feature. -### 1.7.2. New 'no-code-IOT' mini-app +Note: This feature uses a preinstalled plugin in the device code and associated commandline 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. -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. +You can get the latest python tool/library with "pip3 install --upgrade meshtastic" on Windows/Linux/OS-X. -#### 1.7.2.1. Supported operations in the initial release - -Initially supported features for no-code-IOT. +## Supported operations in the initial release - Set any GPIO - Read any GPIO +- Receive notification of changes in any GPIO. -#### 1.7.2.2. Supported operations eventually +## Setup -General ideas for no-code IOT. +GPIO access is fundamentally 'dangerous' because invalid options can physically burn-up hardware. 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. -- 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 \ No newline at end of file +The procedure using the python command line tool is: + +1. Connect local device via USB +2. "meshtastic --ch-add admin; meshtastic --info" thn copy the (long) "Complete URL" that info printed +3. Connect remote device via USB (or use the remote admin feature to reach it through the mesh, but that's beyond the scope of this tutorial) +4. "meshtastic --seturl theurlyoucopiedinstep2" + +Now both devices can talk over the "gpio" channel. + +## Doing GPIO operations + +Here's some examples using the command line tool. + +## Using GPIOs from python + +You can programmatically do operations from your own python code by using the meshtastic "RemoteHardwareClient" class - see the python documentation for more details. + +Writing a GPIO +``` +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 +``` +meshtastic --port /dev/ttyUSB0 --gpio-rd 0x10 --dest \!28979058 +Connected to radio +Reading GPIO mask 0x10 from !28979058 +GPIO read response gpio_value=16 +``` + +Watching for GPIO 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 > +``` \ No newline at end of file