2022-06-25 00:39:41 -07:00
---
id: canned-message
title: Canned Message Module Configuration
2022-11-02 11:46:54 -07:00
slug: /settings/moduleconfig/canned-message
2022-06-25 00:39:41 -07:00
sidebar_label: Canned Message
---
2023-01-19 05:01:57 -08:00
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
The Canned Message Module 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.
2022-06-25 00:39:41 -07:00
2023-01-19 05:01:57 -08:00
The canned message module config options are: Enabled, Save, and Sender. Range Test Module config uses an admin message sending a `ConfigModule.CannedMessage` protobuf.
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
## Canned Message Module Config Values
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
### Enabled
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
Enables the canned message module.
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
### Send Bell
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
Sends a bell character with each message.
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
The [External Notification Module](external-notification) can be set up to beep when a new message arrives.
2023-01-19 05:01:57 -08:00
This module can also be configured to beep only when message contains the bell character.
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
### Messages
2022-06-25 00:39:41 -07:00
2023-05-26 11:43:16 -07:00
The list of pre-set messages as configured by the user. Messages should be separated by pipes `|`. The total byte count for the message list can be up to 200 bytes
2022-06-29 12:08:30 -07:00
2022-07-14 22:10:48 -07:00
### Input Source
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
Input event sources accepted by the canned message module.
2022-06-25 00:39:41 -07:00
2023-01-19 05:01:57 -08:00
| Value | Description |
| :----------: | :------------------------------------------------------------------: |
| `_any` | Default. Allows any peripheral input device connected to the device. |
| `rotEnc1` | Basic Rotary Encoder |
| `upDownEnc1` | Up Down Encoder (use this also for RAK14006 Rotary Encoder) |
| `cardkb` | M5 Stack CardKB (this covers RAK14004 Keymatrix) |
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
### Rotary Encoder Enabled
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
Enable the default rotary encoder.
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
### Up Down Encoder Enabled
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
Enable the up / down encoder.
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
### Input Broker Pin A
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
GPIO Pin Value (1-39) For encoder port A
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
### Input Broker Pin B
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
GPIO Pin Value (1-39) For encoder port B
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
### Input Broker Pin Press
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
GPIO Pin Value (1-39) For encoder Press port
2022-06-25 00:39:41 -07:00
2022-08-08 16:40:57 -07:00
### Input Broker Event Clockwise
2022-06-25 00:39:41 -07:00
2022-11-02 11:46:54 -07:00
Generate the rotary clockwise event.
2022-06-25 00:39:41 -07:00
2022-08-08 16:40:57 -07:00
### Input Broker Event Counter Clockwise
2022-06-25 00:39:41 -07:00
2022-11-02 11:46:54 -07:00
Generate the rotary counter clockwise event.
2022-07-14 22:10:48 -07:00
### Input Broker Event Press
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
Generate input event on Press of this kind.
## Canned Message Module Config Client Availability
2022-06-25 00:39:41 -07:00
<Tabs
groupId="settings"
2022-07-14 22:10:48 -07:00
defaultValue="apple"
2022-06-25 00:39:41 -07:00
values={[
{label: 'Android', value: 'android'},
2022-07-14 22:10:48 -07:00
{label: 'Apple', value: 'apple'},
{label: 'CLI', value: 'cli'},
2022-06-25 00:39:41 -07:00
{label: 'Web', value: 'web'},
]}>
2022-07-14 22:10:48 -07:00
<TabItem value="android">
2022-06-25 00:39:41 -07:00
:::info
2022-12-04 13:26:06 -08:00
Canned Message Config options are available for Android.
1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Module Settings > Canned Message Config**
2022-06-25 00:39:41 -07:00
:::
2022-07-14 22:10:48 -07:00
</TabItem>
<TabItem value="apple">
2022-06-25 00:39:41 -07:00
:::info
2022-07-14 22:10:48 -07:00
All canned message module config options are available on iOS, iPadOS and macOS at Settings > Modules > Canned Messages.
2022-06-25 00:39:41 -07:00
:::
2022-07-14 22:10:48 -07:00
</TabItem>
<TabItem value="cli">
2022-06-25 00:39:41 -07:00
:::info
2023-01-06 16:02:38 -08:00
2023-01-19 05:01:57 -08:00
All canned message module config options are available in the python CLI.
2023-01-06 16:02:38 -08:00
2022-06-25 00:39:41 -07:00
:::
2022-07-14 22:10:48 -07:00
Example commands are below:
2022-06-25 00:39:41 -07:00
2023-01-19 05:01:57 -08:00
| Setting | Acceptable Values | Default |
| :------------------------------------: | :---------------------------------------: | :-----------: |
| canned_message.enabled | `true`, `false` | `false` |
| canned_message.send_bell | `true`, `false` | `false` |
| canned_message.allow_input_source | `rotEnc1`, `_any`, `upDownEnc1`, `cardkb` | `_any` |
2023-05-26 11:43:16 -07:00
| canned_message.messages | `string` | `""` (separate using pipes) |
2023-01-19 05:01:57 -08:00
| canned_message.inputbroker_event_cw | `InputEventChar` | (not defined) |
| canned_message.inputbroker_event_ccw | `InputEventChar` | (not defined) |
| canned_message.inputbroker_event_press | `InputEventChar` | (not defined) |
| canned_message.inputbroker_pin_a | `integer` | (not defined) |
| canned_message.inputbroker_pin_b | `integer` | (not defined) |
| canned_message.inputbroker_pin_press | `integer` | (not defined) |
2022-07-14 22:10:48 -07:00
2023-01-06 16:02:38 -08:00
:::tip
Because the device will reboot after each command is sent via CLI, it is recommended when setting multiple values in a config section that commands be chained together as one.
```shell title="Example:"
meshtastic --set canned_message.enabled true --set canned_message.send_bell true
```
:::
2022-07-14 22:10:48 -07:00
```shell title="Enable/Disable the Canned Message Module"
2022-08-03 08:16:18 -07:00
meshtastic --set canned_message.enabled true
meshtastic --set canned_message.enabled false
2022-06-25 00:39:41 -07:00
```
2022-07-14 22:10:48 -07:00
```shell title="Enable/Disable send bell character"
2022-08-03 08:16:18 -07:00
meshtastic --set canned_message.send_bell true
meshtastic --set canned_message.send_bell false
2022-06-25 00:39:41 -07:00
```
2022-07-14 22:10:48 -07:00
```shell title="Set Messages"
2023-05-26 11:43:16 -07:00
meshtastic --set canned_message.messages "I need an alpinist!|Call Me|Roger Roger|Keep Calm|On my way"
2022-07-14 22:10:48 -07:00
```
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
```shell title="Set Input Source"
2022-08-03 08:16:18 -07:00
meshtastic --set canned_message.allow_input_source "_any"
meshtastic --set canned_message.allow_input_source "rotEnc1"
2022-07-14 22:10:48 -07:00
```
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
```shell title="Enable/Disable rotary1"
2022-11-09 03:17:06 -08:00
meshtastic --set canned_message.rotary1_enabled 1
2022-07-14 22:10:48 -07:00
```
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
```shell title="Set/Unset Encoder Pin A"
2022-08-03 08:16:18 -07:00
meshtastic --set canned_message.inputbroker_pin_a 17
meshtastic --set canned_message.inputbroker_pin_a 0
2022-07-14 22:10:48 -07:00
```
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
```shell title="Set/Unset Encoder Pin B"
2022-08-03 08:16:18 -07:00
meshtastic --set canned_message.inputbroker_pin_b 39
meshtastic --set canned_message.inputbroker_pin_b 0
2022-07-14 22:10:48 -07:00
```
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
```shell title="Set/Unset Encoder Pin Press"
2022-08-03 08:16:18 -07:00
meshtastic --set canned_message.inputbroker_pin_press 21
meshtastic --set canned_message.inputbroker_pin_press 0
2022-06-25 00:39:41 -07:00
```
2022-07-14 22:10:48 -07:00
```shell title="Set/Unset Input Broker CW Event"
2022-08-03 08:16:18 -07:00
meshtastic --set canned_message.inputbroker_event_cw KEY_UP
meshtastic --set canned_message.inputbroker_event_cw ""
2022-07-14 22:10:48 -07:00
```
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
```shell title="Set/Unset Input Broker CCW Event"
2022-08-03 08:16:18 -07:00
meshtastic --set canned_message.inputbroker_event_ccw KEY_DOWN
meshtastic --set canned_message.inputbroker_event_ccw ""
2022-07-14 22:10:48 -07:00
```
2022-06-25 00:39:41 -07:00
2022-07-14 22:10:48 -07:00
```shell title="Set/Unset Input Broker Press Event"
2022-08-03 08:16:18 -07:00
meshtastic --set canned_message.inputbroker_event_press KEY_SELECT
meshtastic --set canned_message.inputbroker_event_press ""
2022-07-14 22:10:48 -07:00
```
2023-01-19 05:01:57 -08:00
2022-07-14 22:10:48 -07:00
</TabItem>
2023-01-06 16:02:38 -08:00
<TabItem value="web">
2022-06-25 00:39:41 -07:00
:::info
2022-08-03 08:16:18 -07:00
All canned message module config options are available in the Web UI.
2022-06-25 00:39:41 -07:00
:::
2023-01-19 05:01:57 -08:00
2022-06-25 00:39:41 -07:00
</TabItem>
</Tabs>
2022-07-14 22:29:59 -07:00
:::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.
This module requires attaching a peripheral accessory to your device. It will not work without one.
:::
2022-07-03 11:20:04 -07:00
## Hardware
2022-11-09 03:17:06 -08:00
To navigate through messages and select one, you will require some hardware attached to your device. Currently, the module is tested with a generic rotary encoder, an up/down/select 3 button logic and several I2C Keyboards. Further input methods will be added in the future.
### I2C Keymatrix
This is tested with the RAK14004 Keyboard. A keypress will immediately send the message attached to the button number. Buttons are numbered from upper left to lower right on the keypanels. So pressing the upper left button will send the first message. The second button will send the second message and so on.
**Caveat:** the RAK 3x4 keymatrix is missing the 4th button row while scanning, so you have to skip every 4th message slot. Button 1 sends message 1 and button 4 will send message 5
Example: 1|2|3||5|6|7||9|10|11||13|14|15 - the slots 4,8 and 12 can not be used.
### CardKB
The CardKB is fully supported in freetext mode and select mode. Use UP/DOWN/ENTER to select a predefined message and send it. For a freetext message, just type it in and press ENTER to send it.
If you don't want to broadcast your freetext message, you can use the CardKB to send it to a specific node. Just press TAB and select the target node with the LEFT/RIGHT keys. The message will be sent to the node with the matching name and node number. The target node will be remebered for your nexxt message.
### 3 Buttun up/down and RAK rotary encoder
Just use UP/DOWN/ENTER to select a predefined message and send it.
2022-07-03 11:20:04 -07:00
### Rotary encoder
2023-01-19 05:01:57 -08:00
Meshtastic supports hardwired rotary encoders as input devices.
2022-07-03 11:20:04 -07:00
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.
<!--- TODO move links to hardware section --->
- [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:
2023-01-19 05:01:57 -08:00
```text
2022-07-03 11:20:04 -07:00
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.
2023-01-19 05:01:57 -08:00
```text
2022-07-03 11:20:04 -07:00
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)
2022-07-14 22:10:48 -07:00
## Examples
- Attach a compatible peripheral device. Take note of the GPIO numbers you use, as they will be used in the following step.
:::note
Replace each `GPIO` (x3) below with the GPIO numbers from your hardware setup.
:::
```shell title="Canned Message Module - Required Rotary Encoder Module Settings"
2022-08-08 16:40:57 -07:00
meshtastic --set canned_message.inputbroker_pin_a GPIO
meshtastic --set canned_message.inputbroker_pin_b GPIO
meshtastic --set canned_message.inputbroker_pin_press GPIO
meshtastic --set canned_message.inputbroker_event_cw KEY_UP
meshtastic --set canned_message.inputbroker_event_ccw KEY_DOWN
meshtastic --set canned_message.inputbroker_event_press KEY_SELECT
2022-08-03 08:16:18 -07:00
meshtastic --set canned_message.rotary1_enabled True
2022-07-14 22:10:48 -07:00
```
That's it! With a functioning and enabled rotary encoder, you're ready to begin configuring the Canned Message Module.