Merge pull request #3 from meshtastic/master

Update following plugins merge

website/docs/software/plugins/environment.md

@@ -0,0 +1,9 @@
+---
+id: environment-plugin
+title: Environment measurement
+sidebar_label: Environment measurement
+---
+
+:::caution
+This is a work in progress and is not yet available.
+:::

website/docs/software/plugins/external-notifications.md

@@ -0,0 +1,93 @@
+---
+id: ext-notif-plugin
+title: External notifications
+sidebar_label: External notifications
+---
+## About
+
+The ExternalNotification Plugin will allow you to connect a speaker, LED or other device to notify you when a message has been received from the mesh network.
+
+## Configuration
+
+These are the settings that can be configured.
+
+    ext_notification_plugin_enabled
+        Is the plugin enabled?
+        
+        0 = Disabled (Default)
+        1 = Enabled
+
+    ext_notification_plugin_active
+        Is your external circuit triggered when our GPIO is low or high?
+
+        0 = Active Low (Default)
+        1 = Active High
+
+    ext_notification_plugin_alert_message
+        Do you want to be notified on an incoming message?
+
+        0 = Disabled (Default)
+        1 = Alert when a text message comes
+
+    ext_notification_plugin_alert_bell
+        Do you want to be notified on an incoming bell?
+
+        0 = Disabled (Default)
+        1 = Alert when the bell character is received
+
+    ext_notification_plugin_output
+        What GPIO is your external circuit attached?
+
+        GPIO of the output. (Default = 13)
+
+    ext_notification_plugin_output_ms
+        How long do you want us to trigger your external circuit?
+    
+        Amount of time in ms for the alert. Default is 1000.
+
+
+## Usage Notes
+
+For basic usage, start with:
+
+	ext_notification_plugin_enabled = 1
+
+	ext_notification_plugin_alert_message = 1
+    
+Depending on how your external cirtcuit configured is configured, you may need to set the active state to true.
+
+	ext_notification_plugin_active = 1
+
+:::note
+The device must be restarted after the settings have been changed for the plugin to take effect.
+:::
+	
+### 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.
+
+#### Bell Character
+
+The bell character is ASCII 0x07. Include 0x07 anywhere in the text message and with ext_notification_plugin_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 an 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 plugin only monitors text messages. We won't trigger on any other packet types.

website/docs/software/plugins/plugins.md

@@ -0,0 +1,16 @@
+---
+id: plugins
+title: Plugins overview
+sidebar_label: Overview
+---
+
+There are a number of plugins that have been integrated into the device firmware. These can be turned on using the Meshtastic python command line program. Please note that these plugins require the device to be rebooted once they have been enabled for them to start running.
+
+These plugins are currently integrated into the firmware:
+* Range test - Allows automated testing of communication range of nodes
+* External notifications - Allows a speaker, LED or other device to indicate when a message has been received
+* Serial - Allows messages to be sent across the mesh by sending strings across a serial port
+
+These plugins are currently in development:
+* Store and forward - Allows a node to store messages and resend them to nodes that have intermittant connection to the mesh
+* Environment measurement - Allows a node to measure it's local environment and report across the mesh

website/docs/software/plugins/range-test.md

@@ -0,0 +1,135 @@
+---
+id: range-test-plugin
+title: Range test plugin
+sidebar_label: Range test
+---
+
+This plugin allows you to test he 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.
+
+## Configuration
+
+These are the settings that can be configured.
+
+    range_test_plugin_enabled
+        Is the plugin enabled?
+        
+        0 = Disabled (Default)
+        1 = Enabled
+
+    range_test_plugin_save
+        If enabled, we will save a log of all received messages to /static/rangetest.csv which you can access from the webserver. We will abort
+        writing if there is less than 50k of space on the filesystem to prevent filling up the storage.
+
+        0 = Disabled (Default)
+        1 = Enabled
+
+    range_test_plugin_sender
+        Number of seconds to wait between sending packets. Using the long_slow channel configuration, it's best not to go more frequent than once every 60 seconds. You can be more agressive with faster settings. 0 is default which disables sending messages.
+
+:::note
+The device must be restarted after the settings have been changed for the plugin to take effect.
+:::
+
+### Usage Notes
+
+For basic usage, you will need two devices both with a GPS. A device with a paired phone with GPS may work, I have not tried it.
+
+The first thing to do is to turn on the plugin. The device will need to be restarted after appling the settings. With the plugin turned on, the other settings will be available:
+
+    range_test_plugin_enabled = 1
+
+If you want to send a message every 60 seconds:
+
+    range_test_plugin_sender = 60
+
+To save a log of the messages:
+
+    range_test_plugin_save = 1
+
+Recommended settings for a sender at different radio settings:
+
+    Long Slow  ... range_test_plugin_sender = 60
+    Long Alt   ... range_test_plugin_sender = 30
+    Medium     ... range_test_plugin_sender = 15
+    Short Fast ... range_test_plugin_sender = 15
+
+### Python API Examples
+
+Sender
+
+`meshtastic --set range_test_plugin_enabled 1`
+
+`meshtastic --set range_test_plugin_sender 60`
+
+Receiver
+
+`meshtastic --set range_test_plugin_enabled 1`
+
+`meshtastic --set range_test_plugin_save 1`
+
+### Other things to keep in mind
+
+Be sure to turn off either the plugin configured as a sender or the device where the plugin 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 relavant 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.
+
+## Known Problems
+
+If turned on, using mesh network will become unwieldly 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, go to /static and you will see rangetest.csv.
+
+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 plugin? 
+* 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 completly 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 plugin 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.

website/docs/software/plugins/serial.md

@@ -0,0 +1,40 @@
+---
+id: serial-plugin
+title: Serial communication plugin
+sidebar_label: Serial communication
+---
+
+## 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 plugin by setting `serialplugin_enabled` to `1`.
+2. Set the pins (`serialplugin_rxd` / `serialplugin_rxd`) for your preferred RX and TX GPIO pins. On tbeam boards it is recommend to use:
+    * RXD 35
+    * TXD 15
+3. Set `serialplugin_timeout` to the amount of time to wait before we consider your packet as "done".
+4. (Optional) In SerialPlugin.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 `serialplugin_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 plugin to take effect.
+:::
+
+## TODO (in this order):
+
+* Define a verbose RX mode to report on mesh and packet infomration.
+
+:::note
+This won't happen any time soon.
+:::
+
+## Known Problems
+
+* Until the plugin is initilized 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.

website/docs/software/plugins/store-forward.md

@@ -0,0 +1,112 @@
+---
+id: store-forward-plugin
+title: Store and forward plugin
+sidebar_label: Store and forward
+---
+
+## About
+:::caution
+This is a work in progress and is not yet available.
+:::
+
+The Store Forward Plugin 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 adviced to use this if you are duty cycle limited for your airtime usage nor is it adviced to use this for SF12 (Long range but Slow).
+
+## 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 plugin 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, maybe others)
+
+## Implementation timeline
+
+Not necessarily in this order:
+
+UC 1) MVP - automagically forward packets to a client that may have missed packets.
+
+UC 2) Client Interface (Web, Android, Python or iOS when that happens) to optionally request packets be resent. This is to support the case where Router has not detected that the client was away. This is because the router will only know you're away if you've been gone for a period of time but will have no way of knowing if you were offline for a short number of minutes. This will cover the case where you have ducked into a cave or you're swapping out your battery.
+
+UC 3) router sends a periodic “heartbeat” to let the clients know they’re part of the main mesh
+
+UC 4) support for a mesh to have multiple routers that have the store & forward functionality (for redundancy)
+
+UC 5) Support for "long term" delayed messages and "short term" delayed messages. Handle the cases slightly different to improve user expierence. A short term delayed message would be a message that was resent becaue a node was not heard from for <5 minutes. A long term delayed message is a message that has not been delivered in >5 minutes.
+
+UC 6) Eventually we could add a "want_store_and_forward" bit to MeshPacket and that could be nicer than whitelists in this plugin. Initially we'd only set that bit in text messages (and any other plugin messages that can cope with this). This change would be backward wire compatible so can add easily later.
+
+UC 7) 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.
+
+UC 8) We'll want a "delayed" bit in MeshPacket. This will indicate that the message was not received in real time.
+
+## Things to consider
+
+Not all these cases will be initially implemented. It's just a running stream of thoughts to be considered.
+
+### Main Mesh Network with Router
+
+The store and forward plugin is intended to be enabled on a router that designates your "main" mesh network.
+
+### Store and Forward on Multiple Routers
+
+If multiple routers with the plugin are enabled, they should be able to share their stored database amongst each other. This enable resilliancy from one router going offline.
+
+### Fragmented networks - No router
+
+In this case, the mesh network has been fragmented by two client devices leaving the main network.
+
+If two Meshtastic devices walk away from the main mesh, they will be able to message each other but not message the main network. When they return to the main network, they will receive the messages they have missed from the main mesh network.
+
+### Fragmented network - With routers
+
+In this case, we have two routers separate by a great distance, each serving multiple devices. One of the routers have gone offline. This has now created two physically seaprated mesh networks using the same channel configuration.
+
+Q: How do we rejoin both fragmented networks? Do we care about messages that were unrouted between fagments?
+
+### Identifing Delayed Messages
+
+When a message is replayed for a node, identify the packet as "Delayed". This will indicate that the message was not received in real time.
+
+## Router Data Structures
+
+Structure of received messages:
+
+    receivedMessages
+      Port_No
+      packetID
+      to
+      from
+      rxTimeMsec
+      data
+
+Structure of nodes and last time we heard from them. This is a record of any packet type.
+
+    receivedRecord
+      From
+      rxTimeMillis
+
+## General Operation for UC1 - automagically forward packets to a client that may have missed packets
+
+On every handled packet
+* Record the sender from and the time we heard from that sender into senderRecord.
+
+On every handled packet
+
+* If the packet is a message, save the messsage into receivedMessages
+
+On every handled packet, if we have not heard from that sender in a period of time greater than timeAway, let's assume that they have been away from the network.
+
+* In this case, we will resend them all the messages they have missed since they were gone
+
+### Expected problems this implementation
+
+* If the client has been away for less than 5 minutes and has received the previously sent message, the client will gracefully ignore it. This is thanks to PacketHistory::wasSeenRecently in PacketHistory.cpp.
+* * If the client has been away for more than 5 minutes and we resend packets that they have already received, it's possible they will see duplicate messages. This should be unlikely but is still possible. 
+
+
+## Designed limitations
+
+The Store and Forward plugin will subscribe to specific packet types and channels and only save those. This will both reduce the amount of data we will need to store and reduce the overhead on the network. Eg: There's no need to replay ACK packets nor is there's no need to replay old location packets.

website/sidebars.js

@@ -35,6 +35,16 @@ module.exports = {
           },
         ],
       },
+      {
+        "Plugins": [
+          "software/plugins/plugins",
+          "software/plugins/range-test-plugin",
+          "software/plugins/ext-notif-plugin",
+          "software/plugins/serial-plugin",
+          "software/plugins/store-forward-plugin",
+          "software/plugins/environment-plugin",
+        ],
+      },
       {
         Other: [
           "software/other/sw-design",