The External Notification Module allows you to connect a buzzer, speaker, LED, or other devices to notify you when a message is received from the mesh network. You can enable up to 3 pins independently.
The configuration options for the External Notification Module include: 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 configuration uses an admin message to send a ConfigModule.ExternalNotificationConfig protobuf.
External Notification Module Configuration 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 set to true, the pin will be pulled active high; if set to false, it means active low.
-
Alert when receiving a bell (general / LED, Vibra and Buzzer): Specifies if an alert should be triggered upon receiving an incoming bell.
-
Alert when receiving a message (general / LED, Vibra and Buzzer): Specifies if an alert should be triggered upon receiving an incoming message.
-
GPIO Pins (general / LED, Vibra and Buzzer): Specifies the GPIO that your external circuit is connected to on the device. On devices with 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 device.buzzer_gpio will be used instead. If you enable PWM mode, the device will use RTTTL ring tones for notifications. You can find examples of RTTTL ring tones here and upload them to the device via a client application. NOTE: 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 and cannot be used as outputs, so you CANNOT use these pins as outputs.
-
How long monitored GPIO is triggered: Specifies how long in milliseconds you want your GPIOs to be active; in the case of the repeat option, this is the duration of each tone and pause, with a default value of 0 set to 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 the specified 'value' number of seconds has passed.
External Notification Module Configuration Client
Android
External Notification Config options are available for Android.
-
Open the Meshtastic App.
-
Navigate to: Vertical Ellipsis (3 dots top right) > Radio Configuration > External Notification.
Apple
All external notification module config options are available on iOS, iPadOS, and macOS at Settings > Module Configuration > External Notification.
CLI
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 |
-
Enable/Disable External Notification Module
| meshtastic --set external_notification.enabled true meshtastic --set external_notification.enabled false |
-
Enable/Disable alert on incoming bell
| meshtastic --set external_notification.alert_bell true meshtastic --set external_notification.alert_bell false |
-
Set GPIO active high / low (default of false is low)
| meshtastic --set external_notification.active false meshtastic --set external_notification.active true |
-
Enable/Disable alert on incoming message
| meshtastic --set external_notification.alert_message true meshtastic --set external_notification.alert_message false |
-
Set GPIO to monitor to 21
| meshtastic --set external_notification.output 21 |
-
Set monitored GPIO output duration (default of 0 is 1000ms)
| meshtastic --set external_notification.output_ms 0 meshtastic --set external_notification.output_ms 1500 |
NOTE: Since the device will reboot after each command is sent via CLI, it is recommended to chain commands together as one when setting multiple values in a config section. For example:
| meshtastic --set external_notification.enabled true --set external_notification.alert_bell true |
Web
All External Notification module config options are available for the Web UI.
Examples
Alert Type
The bell character is ASCII 0x07. To enable external notifications, include 0x07 anywhere in the text message and ensure that ext_notification.alert_bell is enabled.
We support being alerted on two events:
-
Incoming Text Message.
-
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.
External Hardware
Be aware of the maximum current sink and source capabilities of the ESP32 GPIO. The simplest devices to connect would be an LED or an Active Buzzer.
Here are some ideas for external hardware:
-
LED
-
Active Buzzer
-
Flame thrower
-
Strobe Light
-
Siren
Known Limitations
This module only monitors text messages. We won't trigger any other packet types.
