From c4f49a0d2d362e35be9080968c59535faab5e3fe Mon Sep 17 00:00:00 2001 From: Balazs Kelemen <10376327+prampec@users.noreply.github.com> Date: Tue, 18 Jan 2022 23:27:59 +0100 Subject: [PATCH] CannedMessagePlugin --- docs/software/overview.md | 1 + docs/software/plugins/canned-message.md | 149 ++++++++++++++++++ docs/software/plugins/plugins.md | 1 + .../settings/canned-message-plugin.md | 53 +++++++ docs/software/settings/rotary-encoder.md | 58 +++++++ sidebars.js | 3 + 6 files changed, 265 insertions(+) create mode 100644 docs/software/plugins/canned-message.md create mode 100644 docs/software/settings/canned-message-plugin.md create mode 100644 docs/software/settings/rotary-encoder.md diff --git a/docs/software/overview.md b/docs/software/overview.md index c8da9c90..8df4f221 100644 --- a/docs/software/overview.md +++ b/docs/software/overview.md @@ -16,6 +16,7 @@ The following applications are available to support your Meshtastic network: - Pre-installed device plugins for: - [Range testing](/docs/software/plugins/range-test-plugin) - [External notifications](/docs/software/plugins/ext-notif-plugin) + - [Canned messages](/docs/software/plugins/canned-message-plugin) - [Serial communication](/docs/software/plugins/serial-plugin) - [Store and forwarding messages](/docs/software/plugins/store-forward-plugin) (in development) - [Environment measurement](/docs/software/plugins/environment-plugin) (in development) diff --git a/docs/software/plugins/canned-message.md b/docs/software/plugins/canned-message.md new file mode 100644 index 00000000..6b046cf3 --- /dev/null +++ b/docs/software/plugins/canned-message.md @@ -0,0 +1,149 @@ +--- +id: canned-message-plugin +title: Canned messages +sidebar_label: Canned messages +--- +## About + +The CannedMessage Plugin will allow you to send messages to the mesh network +from the device without using the phone app. +You can predefine text messages to choose from. + +## Hardware + +To navigate through messages and select one, you will require some +hardware attached to your device. +Currently, the plugin is tested with a generic rotary encoder, but this is +not a limitation further input methods can be added in the future. + +### Rotary encoder + +Meshtastic supports hardwired rotary encoders as input devices. +(Technically CannedMessage plugin is independent of rotary +encoders. It is described here, because no other module utilizes rotary encoders just yet.) + +You will need a generic rotary encoder. The types listed below has five legs +where two is dedicated to a "press" action, +but any other types will likely do the job. You can also use a +three-legged version, where the "press" action should be wired from +an independent switch. + +* [Amazon link](https://www.amazon.com/Rotary-Encoder-Washers-Digital-Potentiometer/dp/B07Y619CZR/ref=sr_1_21?keywords=rotary+encoder&qid=1642317807&sprefix=rotary+enco%2Caps%2C186&sr=8-21) +* [Amazon.DE link](https://www.amazon.de/-/en/sourcing-Degree-Rotary-Encoder-Digital/dp/B07RLZPX5K/ref=sr_1_12?keywords=rotary+encoder&qid=1642320025&sprefix=rotary%2Caps%2C105&sr=8-12) +* [Aliexpress link1](https://www.aliexpress.com/item/32992227812.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-23&pdp_ext_f=%7B%22sku_id%22%3A%2266940265509%22%7D&pdp_pi=-1%3B1.66%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch) +* [Aliexpress link2](https://www.aliexpress.com/item/32946444853.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&aem_p4p_detail=2022011523263276283624312400022072680&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-6&pdp_ext_f=%7B%22sku_id%22%3A%2266223434642%22%7D&pdp_pi=-1%3B1.91%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch) +* [Aliexpress link3](https://www.aliexpress.com/item/10000056483250.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-9&pdp_ext_f=%7B%22sku_id%22%3A%2220000000116682147%22%7D&pdp_pi=-1%3B2.51%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch) + +Connect your rotary encoder as follows. The rotary encoder has two +rows of legs. One of the rows contains two legs, the other contains three +legs. Bottom side view: + + B o --- o PRESS + GND o | | + A o --- o GND + +The two legs is to sense the press action (or push). Connect +one of the two to GROUND and the other to a GPIO pin. (No matter which one +goes where.) Let's call this connected ports 'PRESS'. + +The three legs is to sense the rotation action. +Connect the middle leg to GROUND and the ones on the side +to GPIO pins. Let's call these ports 'A' and 'B', according to +the scheme below. + + A --|| + GND --||]======== + B --|| + +Recommended GPIO pins for connecting a rotary encoder. + +* TTGO LoRa V1: + * A - GPIO-22 + * B - GPIO-23 + * PRESS - GPIO-21 + +There is a reference case 3D-design utilizing the rotary encoder for TTGO LoRa V1: +[Case for TTGO-ESP32-LORA-OLED-v1.0 with rotary encoder](https://www.thingiverse.com/thing:5178495) + +### Configuration of the rotary encoder #1 + + rotary1_enabled + Enable the rotary encoder #1 + + rotary1_pin_a + GPIO pin for rotary encoder A port. + + rotary1_pin_b + GPIO pin for rotary encoder B port. + + rotary1_pin_press + GPIO pin for rotary encoder Press port. + + rotary1_event_cw + Generate input event on CW of this kind. + For using with CannedMessagePlugin you must choose value "UP" here! + + rotary1_event_ccw + Generate input event on CCW of this kind. + For using with CannedMessagePlugin you must choose value "DOWN" here! + + rotary1_event_press + Generate input event on Press of this kind. + For using with CannedMessagePlugin you must choose value "SELECT" here! + +The rotary encoder #1 will send input events under name "rotEnc1". + +## Configuration of the plugin + +Following configuration can be set for the plugin. + + canned_message_plugin_enabled + Enable/disable CannedMessagePlugin. + + canned_message_plugin_allow_input_source + Input event origin accepted by the canned message plugin. + Can be e.g. "rotEnc1" or keyword "_any" + + canned_message_plugin_messages + Predefined messages for CannedMessagePlugin separated by '|' characters. + + canned_message_plugin_send_bell + CannedMessagePlugin also sends a bell character with the messages. + ExternalNotificationPlugin can benefit from this feature. + +## Usage Notes + +For setting up the rotary encoder #1 using the Python CLI you will +need to execute a sequence like this: + + meshtastic --set rotary1_pin_a 22 + meshtastic --set rotary1_pin_b 23 + meshtastic --set rotary1_pin_press 21 + meshtastic --set rotary1_event_cw KEY_UP + meshtastic --set rotary1_event_ccw KEY_DOWN + meshtastic --set rotary1_event_press KEY_SELECT + meshtastic --set rotary1_enabled True + +For setting up the plugin you will +need to execute a sequence like this: + + meshtastic --set canned_message_plugin_allow_input_source "_any" + meshtastic --set canned_message_plugin_messages "I'm fine|I'm out|I'm back|Need helping hand|Help me with saw|I need an alpinist|I need ambulance|Keep Calm|On my way|I will be late|I'm already waiting|We have company|Beer is cold|Roger" + meshtastic --set canned_message_plugin_send_bell False + meshtastic --set canned_message_plugin_enabled True + +:::note +You can define up to 50 messages with a total length 200 bytes. +(We are working on a solution to extend total length.) +Use short texts as end of line will be truncated on the screen. +::: + +:::note +The device must be restarted after the settings have been changed for the plugin to take effect. +::: + +## Known Problems + +* Rotary encoder input uses a technology called "interrupts". Using the +rotary encoder might cause unexpected software problems. This needs to be +tested. \ No newline at end of file diff --git a/docs/software/plugins/plugins.md b/docs/software/plugins/plugins.md index ece12078..da3f717b 100644 --- a/docs/software/plugins/plugins.md +++ b/docs/software/plugins/plugins.md @@ -9,6 +9,7 @@ There are a number of plugins that have been integrated into the device firmware 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 +* Canned messages - Device can be used without the phone to send a message by choosing a predefined text * Serial - Allows messages to be sent across the mesh by sending strings across a serial port These plugins are currently in development: diff --git a/docs/software/settings/canned-message-plugin.md b/docs/software/settings/canned-message-plugin.md new file mode 100644 index 00000000..d2b74b99 --- /dev/null +++ b/docs/software/settings/canned-message-plugin.md @@ -0,0 +1,53 @@ +--- +id: canned-message-plugin-settings +title: Canned Message Plugin Settings +sidebar_label: Canned Message Plugin Settings +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + +## Overview + +The CannedMessage Plugin will allow you to send messages to the mesh network +from the device without using the phone app. +You can predefine text messages to choose from. + +Please also follow settings of Rotary Encoder to configure input source! + +## Settings + +| Setting | Acceptable Values | Default | +| :-----: | :---------------: | :-----: | +| canned_message_plugin_enabled | `true`, `false` | `false` | +| canned_message_plugin_allow_input_source | `string` | `_all` | +| canned_message_plugin_messages | `string` | (not defined) | +| canned_message_plugin_send_bell | `true`, `false` | `false` | + +### canned_message_plugin_enabled + +Enables the plugin. + +### canned_message_plugin_allow_input_source + +Input event origin accepted by the canned message plugin. +Can be e.g. "rotEnc1" or keyword "_any" + +### canned_message_plugin_messages + +Predefined messages for CannedMessagePlugin separated by '|' characters. + +You can define up to 50 messages with a total length 1024 bytes. + +### canned_message_plugin_send_bell + +CannedMessagePlugin also sends a bell character with the messages. +ExternalNotificationPlugin can benefit from this feature. + +## Details + +See "Software / Plugins / Canned messages" for details! + +## Examples + +See "Software / Plugins / Canned messages" for examples! diff --git a/docs/software/settings/rotary-encoder.md b/docs/software/settings/rotary-encoder.md new file mode 100644 index 00000000..191dc3fa --- /dev/null +++ b/docs/software/settings/rotary-encoder.md @@ -0,0 +1,58 @@ +--- +id: rotary-encoder-settings +title: Rotary Encoder +sidebar_label: Rotary Encoder +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + +## Overview + +Meshtastic supports hardwired rotary encoders as input devices. +Currently, one rotary encoder (`rotary1`) is defined, but later more rotary encoders +can be added (if needed) the same way. + +## Settings + +| Setting | Acceptable Values | Default | +| :-----: | :---------------: | :-----: | +| rotary1_enabled | `true`, `false` | `false` | +| rotary1_pin_a | `integer` | (not defined) | +| rotary1_pin_b | `integer` | (not defined) | +| rotary1_pin_press | `integer` | (not defined) | +| rotary1_event_cw | `InputEventChar` | (not defined) | +| rotary1_event_ccw | `InputEventChar` | (not defined) | +| rotary1_event_press | `InputEventChar` | (not defined) | + +### rotary1_enabled +Enable the rotary encoder #1 + +### rotary1_pin_a +GPIO pin for rotary encoder A port. + +### rotary1_pin_b +GPIO pin for rotary encoder B port. + +### rotary1_pin_press +GPIO pin for rotary encoder Press port. + +### rotary1_event_cw +Generate input event on CW of this kind. +(For using with CannedMessagePlugin you must choose value "UP" here.) + +### rotary1_event_ccw +Generate input event on CCW of this kind. +(For using with CannedMessagePlugin you must choose value "DOWN" here.) + +### rotary1_event_press +Generate input event on Press of this kind. +(For using with CannedMessagePlugin you must choose value "SELECT" here.) + +## Details + +See "Software / Plugins / Canned messages" for details! + +## Examples + +See "Software / Plugins / Canned messages" for examples! diff --git a/sidebars.js b/sidebars.js index e4c5afa6..695d61ea 100644 --- a/sidebars.js +++ b/sidebars.js @@ -66,6 +66,7 @@ module.exports = { "software/plugins/plugins", "software/plugins/range-test-plugin", "software/plugins/ext-notif-plugin", + "software/plugins/canned-message-plugin", "software/plugins/serial-plugin", "software/plugins/store-forward-plugin", "software/plugins/environment-plugin", @@ -116,9 +117,11 @@ module.exports = { Plugins: [ "software/settings/environmental-measurement-plugin", "software/settings/external-notification-plugin", + "software/settings/canned-message-plugin-settings", "software/settings/range-test-plugin", "software/settings/serial-plugin", "software/settings/store-and-forward-plugin", + "software/settings/rotary-encoder-settings", ], Advanced: [ "software/settings/channel-advanced",