meshtastic/docs/settings/moduleconfig/canned-message.mdx

---
id: canned-message
title: Canned Message Module Configuration
sidebar_label: Canned Message
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::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 module requires attaching a peripheral accessory to your device. It will not work without one. It also requires use of the [Rotary Encoder Module](input-broker) to configure the input source.
:::

## Overview

The CannedMessage 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.

:::tip
Once module settings are changed, a **reset** is required for them to take effect.
:::

## Settings

|                 Setting                  | Acceptable Values | Default |
| :--------------------------------------: | :---------------: | :-----: |
| canned_message_module_allow_input_source | `rotEnc1`, `_any` | `_any`  |
|      canned_message_module_enabled       |  `true`, `false`  | `false` |
|      canned_message_module_messages      |     `string`      |  `""`   |
|     canned_message_module_send_bell      |  `true`, `false`  | `false` |
|               (Messages)\*               |     `string`      |  `""`   |

- Messages can be set with a dedicated option:

`--set-canned-message "<messages>"`

### Enabled

### Allow Input Source

Input event source accepted by the canned message module.

|   Value   |                                                                                                              Description                                                                                                              |
| :-------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|  `_any`   |                                                                                 Default. Allows any peripheral input device connected to the device.                                                                                  |
| `rotEnc1` | Hardcoded value naming the input device that this module listens to. This could allow multiple input devices to be named with future software development. At present, this doesn't do anything differently than the default setting. |

#### Set input source

<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">

```shell title="Set Allowed Input Source"
meshtastic --set canned_message_module_allow_input_source "_any"
```

```shell title="Specify Allowed Input Source"
meshtastic --set canned_message_module_allow_input_source "rotEnc1"
```

  </TabItem>
  <TabItem value="android">

:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::

  </TabItem>
  <TabItem value="iOS">

:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::

  </TabItem>
  <TabItem value="web">

:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::

  </TabItem>
</Tabs>

### canned_message_module_enabled

Enables the module.

:::tip
Using the canned message module requires you set up the [Rotary Encoder Module](input-broker). See [prerequisites](#prerequisites) below.
:::

#### Enable/Disable the module

<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">

```shell title="Enable Canned Message Module"
meshtastic --set canned_message_module_enabled true
```

```shell title="Disable Canned Message Module"
meshtastic --set canned_message_module_enabled false
```

  </TabItem>
  <TabItem value="android">

:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::

  </TabItem>
  <TabItem value="iOS">

:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::

  </TabItem>
  <TabItem value="web">

:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::

  </TabItem>
</Tabs>

### canned_message_module_send_bell

CannedMessageModule also sends a "bell character" with the messages.
The [External Notification Module](external-notification) can benefit from this feature as it utilizes the bell character.

_We have an "External Notification Module", that can be set up to beep, when new message arrives.
This module can also be configured to beep only when message contains the "bell character".
See module documentation (link above) for details._

#### Enable/Disable bell character

<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">

```shell title="Enable Bell Character"
meshtastic --set canned_message_module_send_bell true
```

```shell title="Disable Bell Character"
meshtastic --set canned_message_module_send_bell false
```

  </TabItem>
  <TabItem value="android">

:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::

  </TabItem>
  <TabItem value="iOS">

:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::

  </TabItem>
  <TabItem value="web">

:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::

  </TabItem>
</Tabs>

### Messages

CLI has a dedicated option for canned message module to set predefines messages: `--set-canned-message <message>`
Predefined messages separated by `|` characters.

You can define up to 50 messages with a total length 800 bytes.

Existing configuration can be queried with CLI option: `--get-canned-message`

#### Set canned messages

<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">

```shell title="Set Canned Messages"
meshtastic --set canned_message_module_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"
```

  </TabItem>
  <TabItem value="android">

:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::

  </TabItem>
  <TabItem value="iOS">

:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::

  </TabItem>
  <TabItem value="web">

:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::

  </TabItem>
</Tabs>

## Details

### Prerequisites

<!--- TODO add link to hardware pages to first bullet point --->

- Attach a compatible peripheral device. Take note of the GPIO numbers you use, as they will be used in the following step.
- Once attached, configure peripheral device with [Rotary Encoder Module](input-broker) Settings.

:::note
Replace each `GPIO` (x3) below with the GPIO numbers from hardware setup.

```shell title="Canned Message Module - Required Rotary Encoder Module Settings"
meshtastic --set rotary1_pin_a GPIO
meshtastic --set rotary1_pin_b GPIO
meshtastic --set rotary1_pin_press GPIO
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
```

:::
That's it! With a functioning and enabled rotary encoder, you're ready to begin configuring the Canned Message Module.

## Hardware

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, 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 the Canned Message Module 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.

<!--- 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:

```
  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)