Device pages

website/docs/software/device/channels.md

@@ -0,0 +1,58 @@
+---
+id: device-channels
+title: Multiple channel support
+sidebar_label: Multiple channels
+---
+
+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.
+
+:::note
+Older meshtastic applications that don't yet understand multi-channel support will only show the user the primary 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 labelled 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.
+
+```bash 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:
+
+```bash 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 encyryption 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).
+
+```bash title="Adding a channel called testing-channel"
+$ meshtastic --ch-add testing-channel
+Connected to radio
+Writing modified channels to device
+```
+
+The device will now have a Secondary channel called "testing-channel"
+
+```bash title="Expected output"
+$ meshtastic --info
+Connected to radio
+...
+Channels:
+  PRIMARY psk=default { "modemConfig": "Bw125Cr48Sf4096", "psk": "AQ==" }
+  SECONDARY psk=secret { "psk": "HW7E3nMbiNbvr6MhsDonLCmj7eSAhttzjbIx/r5OQmg=", "name": "testing-channel" }
+Primary channel URL: https://www.meshtastic.org/d/#CgUYAyIBAQ
+Complete URL (includes all channels): https://www.meshtastic.org/d/#CgUYAyIBAQopIiAdbsTecxuI1u-voyGwOicsKaPt5ICG23ONsjH-vk5CaCoFYWRtaW4
+```

website/docs/software/device/device.md

@@ -0,0 +1,48 @@
+---
+id: device-software
+title: Device firmware
+sidebar_label: Device firmware
+---
+
+The device firmware runs on the nodes to build the mesh for communication. Each different make and model of device requires a different build of the Meshtastic firmware in order to run properly. Thankfully, due to the design of Meshtastic, it is possible to port the firmware to new devices as they become available. The firmware currently runs on a range of ESP32 based devices, but there is also increasing support for the nRF52 microprocessor with some more recent devices coming to market.
+
+The current firmware has support for a screen to display received messages, along with information about nodes on the mesh, and more detailed information about the device on which it is running.
+
+### Buttons
+
+A number of devices support buttons that can be used to interact with the firmware. These buttons have a number of different functions:
+* Reset button - This is present on most devices
+* Power button - This is present on some devices. A long press powers the device off or turns it back on again.
+* Program button - This is present of some devices and has a number of functions:
+    * Single press - This changes the page of information displayed on the screen.
+    * Double press - This sets the bluetooth pairing code to `123456` (useful if you do not have a screen on the device).
+    * Long press - This adjusts the contrast of the screen.
+    * Long press during reboot - This turns on the software wifi access point on devices that support wifi.
+
+### Screens
+
+A number of devices have screens capable of displaying the messages received and information about the mesh and other details. On powering the device it will display the Meshtastic splashscreen for a couple of seconds:
+
+![Splash screen](/img/screen/mesh-splash.jpg)
+
+The screen is split up into pages, through which you can navigate using the program button as described above. The first page to be displayed will be the message screen where received messages are displayed along with the name of the node it came from. The devices will automatically switch to this page when a new message is received.
+
+![Message page](/img/screen/mesh-message.jpg)
+
+The next pages display information about the nodes that are currently on the mesh. This includes the distance and direction to that node, along with signal strenth and time last seen.
+
+![Node page](/img/screen/mesh-node1.jpg) ![Node page](/img/screen/mesh-node2.jpg)
+
+The next page shows information about the device, battery power, number of nodes and how many are connected current, number of GPS satalites being received, channel name, last digits of the MAC address, and names of the last nodes to join the mesh.
+
+![Channel page](/img/screen/mesh-channel.jpg)
+
+The final page shows current battery voltage and capacity, as well as noting how long the device has been online and the current GPS time and GPS location.
+
+![GPS page](/img/screen/mesh-gps.jpg)
+
+If the device wifi has been enabled (only possible on ESP32 devices), another page appears displaying information about the WiFi settings, IP address and number of devices connected to the WiFi.
+
+![Wifi page](/img/screen/mesh-wifi.jpg)
+
+With a further press of the program button, the screen will cycle round to the message page.

website/docs/software/device/power.md

@@ -0,0 +1,36 @@
+---
+id: device-power
+title: Power Management State Machine
+sidebar_label: Power Management
+---
+
+Long battery life is one of the main goals of this project. Based on intial 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.
+
+## States
+
+From lower to higher power consumption.
+
+- Super-deep-sleep (SDS) - everything is off, CPU, radio, bluetooth, GPS. Only wakes due to timer or button press. We enter this mode only after no radio comms for a few hours, used to put the device into what is effectively "off" mode.
+  * onEntry: setBluetoothOn(false), call doDeepSleep
+  * onExit: (standard bootup code, starts in DARK)
+- deep-sleep (DS) - CPU is off, radio is on, bluetooth and GPS is off. Note: This mode is never used currently, because it only saves 1.5mA vs light-sleep - (Not currently used).
+- light-sleep (LS) - CPU is suspended (RAM stays alive), radio is on, bluetooth is off, GPS is off. Note: currently GPS is not turned off during light sleep, but there is a TODO item to fix this.
+  * NOTE: On NRF52 platforms (because CPU current draw is so low), light-sleep state is never used.  
+  * onEntry: setBluetoothOn(false), setGPSPower(false), doLightSleep()
+  * onIdle: (if we wake because our led blink timer has expired) blink the led then go back to sleep until we sleep for ls_secs
+  * onExit: setGPSPower(true), start trying to get gps lock: gps.startLock(), once lock arrives service.sendPosition(BROADCAST)
+- No bluetooth (NB) - CPU is running, radio is on, GPS is on but bluetooth is off, screen is off.
+  * onEntry: setBluetoothOn(false)
+  * onExit:
+- running dark (DARK) - Everything is on except screen.
+  * onEntry: setBluetoothOn(true)
+  * onExit:
+- serial API usage (SERIAL) - Screen is on, device doesn't sleep, bluetooth off.
+  * onEntry: setBluetooth off, screen on
+  * onExit:
+- full on (ON) - Everything is on, can eventually timeout and lower to a lower power state.
+  * onEntry: setBluetoothOn(true), screen.setOn(true)
+  * onExit: screen->setOn(false)
+- has power (POWER) - Screen is on, device doesn't sleep, bluetooth on, will stay in this state as long as we have power.
+  * onEntry: setBluetooth off, screen on
+  * onExit:

website/docs/software/device/remote-admin.md

@@ -0,0 +1,128 @@
+---
+id: device-remote-admin
+title: Remote node administration
+sidebar_label: Remote node admininstration
+---
+
+This feature will allow you to use the multiple channels feature to enable remote adminstration 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.
+
+## Creating the admin channel
+
+By default, nodes will **only** respond to adminstrative commands via the local USB/bluetooth/TCP interface.  This provides basic security to prevent unauthorized access.  This is how normal administration and settings changes work.  The only difference for the remote case is that we are sending those commands over the mesh.
+
+Before a node will allow remote admin access, it must have a primary channel:
+```bash 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
+```
+
+So from this output you see that this node knows about only one channel and that its PSK is set to the default value.
+
+Now add an admin channel: 
+
+```bash title="Command"
+meshtastic --ch-add admin
+```
+
+:::note
+The name of the channel is important, it must be `admin`.
+:::
+
+Your channels will now look like this:
+```bash title="Expected output"
+$ meshtastic --ch-add admin
+Connected to radio
+Writing modified channels to device
+$ meshtastic --info
+Connected to radio
+...
+Channels:
+  PRIMARY psk=default { "modemConfig": "Bw125Cr48Sf4096", "psk": "AQ==" }
+  SECONDARY psk=secret { "psk": "HW7E3nMbiNbvr6MhsDonLCmj7eSAhttzjbIx/r5OQmg=", "name": "admin" }
+Primary channel URL: https://www.meshtastic.org/d/#CgUYAyIBAQ
+Complete URL (includes all channels): https://www.meshtastic.org/d/#CgUYAyIBAQopIiAdbsTecxuI1u-voyGwOicsKaPt5ICG23ONsjH-vk5CaCoFYWRtaW4
+```
+
+Notice that now we have a new secondary channel.  Also, the `--info` option prints out TWO URLs.  The `Complete URL` includes all of the channels this node understands.  You should consider this URL something you should be very cautious about sharing.  In the case of remote adminstration, you only need the node you want to adminster and the node you are locally connected to know this new "admin" channel.
+
+## Sharing the admin channel with other nodes
+
+I'm going to assume you've already created the admin channel on your "local node" i.e. the meshtastic node sitting on your desk at your home.  But now you want to enable access on the "remote node" you want to eventually have far away from you.
+
+For this step you need physical access to both the nodes.
+
+1. Create the "admin" channel on the "local node" using the instructions above.
+2. Copy the "Complete URL" someplace for permanent reference/access.
+3. Connect to the "remote node" over the USB port.
+4. For the "remote node" type
+  ```bash
+  meshtastic --seturl the-url-from-step-2
+  ```
+5. Run `meshtastic --info` and confirm that the "Complete URL" is the same for both of the nodes.
+
+At this point you can take your remote node and install it far away and still be able to change any of its settings.
+
+## Remotely administering your node
+
+Now that both your local node and the remote node contain your secret admin channel key, you can do things like this:
+
+Get the node list from the local node:
+
+```bash title="Expected output"
+$ meshtastic --nodes
+Connected to radio
+/-------------------------------------------------------------------------------------------------------------\
+|N|    User    |AKA|   ID    |Latitude|Longitude|Altitude|Battery|   SNR   |     LastHeard     |    Since     |
+|-+------------+---+---------+--------+---------+--------+-------+---------+-------------------+--------------|
+|1|Unknown 9058|?58|!28979058|25.0382°|121.5731°|  N/A   |  N/A  |-13.50 dB|2021-03-22 09:25:42|19 seconds ago|
+\-------------------------------------------------------------------------------------------------------------/
+```
+
+Using the node ID from that list, send a message through the mesh telling that node to change its owner name.
+
+```bash title="Expected output"
+$ meshtastic --dest \!28979058 --set-owner "Im Remote"
+Connected to radio
+Setting device owner to Im Remote
+INFO:root:Requesting configuration from remote node (this could take a while)
+```
+
+:::note
+You will need to escape the `!` using `\!` otherwise the command will fail.
+:::
+
+And you can now confirm via the local node that the remote node has changed:
+
+```bash title="Expected output"
+$ meshtastic --nodes 
+Connected to radio
+/----------------------------------------------------------------------------------------------------\
+|N|  User   |AKA|   ID    |        Position        |Battery|  SNR  |     LastHeard     |    Since    |
+|-+---------+---+---------+------------------------+-------+-------+-------------------+-------------|
+|1|Im Remote|IR |!28979058|25.0382°, 121.5731°, N/A|  N/A  |8.75 dB|2021-03-22 09:35:42|3 minutes ago|
+\----------------------------------------------------------------------------------------------------/
+```
+
+Note: you can change **any** parameter, add channels or get info from the remote node.  Here's an example of setting ls_secs and printing the complete device info from the remote node:
+
+```bash title="Expected output"
+$ meshtastic --dest \!28979058 --set ls_secs 301 --info
+Connected to radio
+INFO:root:Requesting configuration from remote node (this could take a while)
+Set ls_secs to 301
+Writing modified preferences to device
+Preferences: { "lsSecs": 301, "region": "TW" }
+Channels:
+  PRIMARY psk=default { "modemConfig": "Bw125Cr48Sf4096", "psk": "AQ==" }
+  SECONDARY psk=secret { "psk": "HW7E3nMbiNbvr6MhsDonLCmj7eSAhttzjbIx/r5OQmg=", "name": "admin" }
+Primary channel URL: https://www.meshtastic.org/d/#CgUYAyIBAQ
+Complete URL (includes all channels): https://www.meshtastic.org/d/#CgUYAyIBAQopIiAdbsTecxuI1u-voyGwOicsKaPt5ICG23ONsjH-vk5CaCoFYWRtaW4
+```
+
+## Areas for future development
+
+In the future we will add a "deadman timer" to this feature so that the remote node will revert any changes if you fail to send a special "commit changes" command.  This will protect against sending bad settings to nodes that you can't physically access.  Instead if the node does not receive a commit message within 10 minutes it will revert all changes and (hopefully) rejoin the mesh.

website/docs/software/device/remote-hardware-service.md

@@ -0,0 +1,78 @@
+---
+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 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.
+:::
+
+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
+    ```bash
+    meshtastic --ch-add gpio
+    ```
+3. Check the channel has been created and copy the long "Complete URL" that contains all the channels on that device.
+    ```bash
+    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
+    ```bash
+    meshtastic --seturl theurlyoucopiedinstep3
+    ```
+
+Now both devices can talk over the `gpio` channel.
+
+## Doing GPIO operations
+
+You can programmatically do operations from your own python code by using the meshtastic `RemoteHardwareClient` class. See the [python API](https://meshtastic.github.io/Meshtastic-python) documentation for more details.
+
+## Using GPIOs from the python CLI
+
+Writing a GPIO
+```bash 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
+```bash 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
+```
+
+Watching for GPIO changes:
+```bash 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 >
+```

website/docs/software/device/wifi.md

@@ -0,0 +1,113 @@
+---
+id: device-wifi
+title: WiFi on ESP32 devices
+sidebar_label: WiFi
+---
+
+The ESP32 based devices have the ability to connect to WiFi and also are able to create a software based access point. The WiFi can be set up through the python API. The WiFi can also be set to AP mode by rebooting the device with the program switch depressed.
+
+## Setting up WiFi in host mode
+
+To enable WiFi access to an existing access point, you need to set two preferences:
+
+* `wifi_ssid`
+* `wifi_password`
+
+This can be done using the python CLI
+
+```bash title="Expected output"
+$ meshtastic --set wifi_ssid dogsRuleCatsDrool --set wifi_password butDogsFearCats
+Connected to radio
+Set wifi_ssid to dogsRuleCatsDrool
+Set wifi_password to butDogsFearCats
+Writing modified preferences to device
+```
+
+Once connected, if you have a screen attached to your device, the final page will display something similar to the following:
+
+```
+WiFi: Connected  RSSI-63
+IP: 192.168.1.89
+SSID: dogsRuleCatsDrool
+http://meshtastic.local
+      * * * * *
+```
+
+You should then be able to connect to the node using either the displayed IP address or the http link.
+
+To disable the WiFi, set the preferences to empty strings.
+
+```bash title="Expected output"
+$ meshtastic --set wifi_ssid "" --set wifi_password ""
+Connected to radio
+Set wifi_ssid to 
+Set wifi_password to 
+Writing modified preferences to device
+```
+
+## Setting up WiFi in AP mode
+
+The device can also be set up in access point mode and is capable of hosting upto four connected devices. The access point is enalbed by setting the following preferences:
+
+* `wifi_ap_mode`
+* `wifi_ssid`
+* `wifi_password`
+
+### Setting up the AP using the python CLI
+
+Use the following command to set the preferences:
+
+```bash title="Expected output"
+$ meshtastic --set wifi_ssid dogsRuleCatsDrool --set wifi_password butDogsFearCats --set wifi_ap_mode true
+Connected to radio
+Set wifi_ssid to dogsRuleCatsDrool
+Set wifi_password to butDogsFearCats
+Set wifi_ap_mode to true
+Writing modified preferences to device
+```
+
+Once set, if you have a screen attached to your device, the final page will display something similar to the following:
+
+```
+WiFi: Software AP
+IP: 192.168.42.1    (0/4)
+SSID: dogsRuleCatsDrool      - alternating with - PWD: butDogsFearCats
+http://meshtastic.local
+      * * * * *
+```
+
+:::note
+The first time your device restarts after enabling the WiFi access point, it will take an additional 20-30 seconds to boot. This is to generate self-signed SSL keys. The keys will be saved for future reuse.
+:::
+
+To disable the WiFi access point, set the preferences to empty strings and the `wifi_ap_mode` to `false`
+
+```bash title="Expected output"
+$ meshtastic --set wifi_ssid "" --set wifi_password "" --set wifi_ap_mode false
+Connected to radio
+Set wifi_ssid to 
+Set wifi_password to 
+Set wifi_ap_mode to false
+Writing modified preferences to device
+```
+
+### Setting up the AP using the admin mode
+
+This allows you to set up the access point mode without needing to use a computer to set the preferences. This is the easiest way to turn on the device WiFi. Do the following after the device has been powered on:
+
+* Hold down the user button
+* Press and release the reset button
+* Count to 2
+* Let go of the user button 
+
+On reboot, if you have a screen attached to your device, the final page will display something similar to the following:
+
+```
+WiFi: Software AP (Admin)
+IP: 192.168.42.1    (0/4)
+SSID: meshtasticAdmin       - alternating with - PWD: 12345678
+http://meshtastic.local
+      * * * * *
+```
+
+To disable to WiFi access point, simply reboot your device.

website/sidebars.js

@@ -18,7 +18,13 @@ module.exports = {
     Software: [
       "software/overview",
       {
-        "Meshtastic Device": [
+        "Meshtastic device": [
+          "software/device/device-software",
+          "software/device/device-channels",
+          "software/device/device-remote-admin",
+          "software/device/remote-hardware-service",
+          "software/device/device-wifi",
+          "software/device/device-power",
           "software/device/critical-error-codes",
         ],
       },