meshtastic/docs/configuration/module/external-notification.mdx

---
id: external-notification
title: External Notification Module Configuration
sidebar_label: External Notification
description: This module will allow you to connect a buzzer, speaker, LED, or other similar accessory to your Meshtastic device.
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import ReactPlayer from "react-player";

The External Notification Module will allow you to connect a buzzer, speaker, LED, or other device to notify you when a message has been received from the mesh network. You can enable up to 3 pins independently from each other.

The External Notification Module config options are: Enabled, Active, Alert Bell (General),Alert Bell Vibra, Alert Bell Buzzer, Alert Message (General), Alert Message Vibra, Alert Message Buzzer, Output (General), Output Vibra, Output Buzzer, Output Milliseconds, Use PWM, and Nag Timeout. External Notification config uses an admin message sending a `ConfigModule.ExternalNotificationConfig` protobuf.

<div style={{ maxWidth: "800px", margin: "auto" }}>
  <ReactPlayer
    url="https://youtu.be/MWt3RHMpifo"
    controls
    width="100%"
    height="400px"
  />
</div>

## External Notification Module Config Values

### Enabled

Enables the external notification module.

### Active (general / LED only)

Specifies whether the external circuit is active when the device's GPIO is low or high. If this is set true, the pin will be pulled active high, false means active low.

### Alert when receiving a bell (general / LED, Vibra and Buzzer)

Specifies if an alert should be triggered when receiving an incoming bell.

### Alert when receiving a message (general / LED, Vibra and Buzzer)

Specifies if an alert should be triggered when receiving an incoming message.

### GPIO Pins (general / LED, Vibra and Buzzer)

Specifies the GPIO that your external circuit is attached to on the device. On devices that have a PWM buzzer, you can use the buzzer for notifications by setting the use_pwm property to TRUE. The Buzzer Pin will be ignored and the device.buzzer_gpio is used instead. If you enable PWM mode, the device will use
so-called RTTTL ring tones for notification. You can find examples of RTTTL ring tones [here](https://www.laub-home.de/wiki/RTTTL_Songs) and upload them to the device via a client application.

:::info
On ESP32 based boards, GPIOs 34 to 39 are GPIs – input only pins. These pins do not have internal pull-up or pull-down resistors. They can not be used as outputs, so you can NOT use these pins as outputs.
:::

### How long monitored GPIO is triggered

Specifies how long in milliseconds you would like your GPIOs to be active. In case of the repeat option, this is the duration of every tone and pause.

Default of 0 is 1000ms

### Repeat (Nag Timeout) (general / LED, Vibra and Buzzer)

Specifies if the alert should be repeated. If set to a value greater than zero, the alert will be repeated until the user button is pressed or 'value' number of seconds have past.

## External Notification Module Config Client Availability

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

#### Android

:::info

External Notification Config options are available for Android.

1. Open the Meshtastic App
2. Navigate to: **Vertical Ellipsis (3 dots top right) > Radio Configuration > External Notification**

:::

</TabItem>
<TabItem value="apple">

#### Apple

:::info
All external notification module config options are available on iOS, iPadOS and macOS at Settings > Module Configuration > External Notification.
:::

</TabItem>
<TabItem value="cli">

#### CLI

:::info

All external notification module config options are available in the python CLI. Example commands are below:

:::

|                  Setting                   |    Acceptable Values     | Default |
| :----------------------------------------: | :----------------------: | :-----: |
|       external_notification.enabled        |     `true`, `false`      | `false` |
|        external_notification.active        |     `true`, `false`      | `false` |
|      external_notification.alert_bell      |     `true`, `false`      | `false` |
|   external_notification.alert_bell_vibra   |     `true`, `false`      | `false` |
|  external_notification.alert_bell_buzzer   |     `true`, `false`      | `false` |
|    external_notification.alert_message     |     `true`, `false`      | `false` |
| external_notification.alert_message_vibra  |     `true`, `false`      | `false` |
| external_notification.alert_message_buzzer |     `true`, `false`      | `false` |
|        external_notification.output        |        `integer`         |   `0`   |
|     external_notification.output_vibra     |        `integer`         |   `0`   |
|    external_notification.output_buzzer     |        `integer`         |   `0`   |
|      external_notification.output_ms       | `integer` (milliseconds) |   `0`   |
|       external_notification.use_pwm        |     `true`, `false`      | `false` |
|     external_notification.nag_timeout      |   `integer` (seconds)    |   `0`   |

:::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 external_notification.enabled true --set external_notification.alert_bell true
```

:::

```shell title="Enable/Disable External Notification Module"
meshtastic --set external_notification.enabled true
meshtastic --set external_notification.enabled false
```

```shell title="Enable/Disable alert on incoming bell"
meshtastic --set external_notification.alert_bell true
meshtastic --set external_notification.alert_bell false
```

```shell title="Set GPIO active high / low (default of false is low)"
meshtastic --set external_notification.active false
meshtastic --set external_notification.active true
```

```shell title="Enable/Disable alert on incoming message"
meshtastic --set external_notification.alert_message true
meshtastic --set external_notification.alert_message false
```

```shell title="Set GPIO to monitor to 21"
meshtastic --set external_notification.output 21
```

```shell title="Set monitored GPIO output duration (default of 0 is 1000ms)"
meshtastic --set external_notification.output_ms 0
meshtastic --set external_notification.output_ms 1500
```

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

#### Web

:::info
All External Notification module config is available for the Web UI.
:::

</TabItem>
</Tabs>

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

## Examples

### 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.

:::info
The bell character is ASCII 0x07. Include 0x07 anywhere in the text message and with ext_notification.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 Limitations

- This module only monitors text messages. We won't trigger on any other packet types.