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

164 lines
5.1 KiB
Plaintext
Raw Normal View History

2022-06-25 00:39:41 -07:00
---
id: external-notification
2022-06-29 08:55:33 -07:00
title: External Notification Module Configuration
2022-11-02 11:46:54 -07:00
slug: /settings/moduleconfig/external-notification
2022-06-25 00:39:41 -07:00
sidebar_label: External Notification
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
2022-06-29 12:08:30 -07:00
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.
2022-06-25 00:39:41 -07:00
2022-06-29 12:08:30 -07:00
## External Notification Module Config Values
2022-06-25 00:39:41 -07:00
2022-06-29 12:08:30 -07:00
### Enabled
2022-06-25 00:39:41 -07:00
2022-06-29 12:08:30 -07:00
Enables the external notification module.
2022-06-25 00:39:41 -07:00
2022-06-29 12:08:30 -07:00
### Alert when receiving a bell
2022-06-25 00:39:41 -07:00
2022-06-29 12:08:30 -07:00
Specifies if an alert should be triggered when receiving an incoming bell.
2022-06-25 00:39:41 -07:00
2022-06-29 12:08:30 -07:00
### Alert when receiving a message
2022-06-25 00:39:41 -07:00
2022-06-29 12:08:30 -07:00
Specifies if an alert should be triggered when receiving an incoming message.
2022-06-25 00:39:41 -07:00
2022-06-29 12:08:30 -07:00
### Active
2022-06-25 00:39:41 -07:00
2022-06-29 12:08:30 -07:00
Specifies whether the external circuit is triggered when the device's GPIO is low or high.
2022-06-25 00:39:41 -07:00
2022-06-29 12:08:30 -07:00
### GPIO to monitor
2022-06-25 00:39:41 -07:00
2022-11-09 03:17:06 -08:00
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 this to the same pin the buzzer uses.
2022-06-25 00:39:41 -07:00
2022-10-22 03:50:49 -07:00
:::info
2022-11-02 11:46:54 -07:00
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.
2022-10-22 03:50:49 -07:00
:::
2022-06-29 12:08:30 -07:00
### How long monitored GPIO is triggered
2022-06-25 00:39:41 -07:00
2022-06-29 12:08:30 -07:00
Specifies how long in milliseconds you would like your external circuit to be triggered.
2022-06-25 00:39:41 -07:00
2022-06-29 12:08:30 -07:00
Default of 0 is 1000ms
2022-06-25 00:39:41 -07:00
2022-06-29 12:08:30 -07:00
## External Notification Module Config Client Availability
2022-06-25 00:39:41 -07:00
<Tabs
groupId="settings"
defaultValue="apple"
2022-06-25 00:39:41 -07:00
values={[
{label: 'Android', value: 'android'},
2022-06-29 12:08:30 -07:00
{label: 'Apple', value: 'apple'},
2022-06-25 00:39:41 -07:00
{label: 'CLI', value: 'cli'},
2022-06-29 12:08:30 -07:00
{label: 'Flasher', value: 'flasher'},
2022-06-25 00:39:41 -07:00
{label: 'Web', value: 'web'},
]}>
2022-06-29 12:08:30 -07:00
<TabItem value="android">
2022-06-25 00:39:41 -07:00
:::info
2022-06-29 12:08:30 -07:00
External notification module config is not available for Android.
2022-06-25 00:39:41 -07:00
:::
2022-06-29 12:08:30 -07:00
</TabItem>
<TabItem value="apple">
2022-06-25 00:39:41 -07:00
:::info
2022-06-29 12:08:30 -07:00
All external notification module config options are available on iOS, iPadOS and macOS at Settings > Modules > External Notification.
2022-06-25 00:39:41 -07:00
:::
2022-06-29 12:08:30 -07:00
</TabItem>
<TabItem value="cli">
2022-06-25 00:39:41 -07:00
2022-11-02 11:46:54 -07:00
All external notification module config options are available in the python CLI. Example commands are below:
2022-06-25 00:39:41 -07:00
2022-08-03 08:16:18 -07:00
| 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_message | `true`, `false` | `false` |
| external_notification.output | `integer` | `0` |
| external_notification.output_ms | `integer` (milliseconds) | `0` |
2022-06-25 00:39:41 -07:00
2022-06-29 12:08:30 -07:00
```shell title="Enable/Disable External Notification Module"
meshtastic --set external_notification.enabled true
meshtastic --set external_notification.enabled false
2022-06-25 00:39:41 -07:00
```
2022-06-29 12:08:30 -07:00
```shell title="Enable/Disable alert on incoming bell"
meshtastic --set external_notification.alert_bell true
meshtastic --set external_notification.alert_bell false
2022-06-25 00:39:41 -07:00
```
2022-11-02 11:46:54 -07:00
```shell title="Set GPIO active high / low (default of false is low)"
meshtastic --set external_notification.active false
meshtastic --set external_notification.active true
2022-06-29 12:08:30 -07:00
```
2022-06-25 00:39:41 -07:00
2022-06-29 12:08:30 -07:00
```shell title="Enable/Disable alert on incoming message"
meshtastic --set external_notification.alert_message true
meshtastic --set external_notification.alert_message false
2022-06-29 12:08:30 -07:00
```
2022-06-25 00:39:41 -07:00
2022-06-29 12:08:30 -07:00
```shell title="Set GPIO to monitor to 21"
meshtastic --set external_notification.output 21
2022-06-25 00:39:41 -07:00
```
2022-06-29 12:08:30 -07:00
```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
2022-06-25 00:39:41 -07:00
```
2022-06-29 12:08:30 -07:00
</TabItem>
<TabItem value="flasher">
2022-06-25 00:39:41 -07:00
:::info
2022-06-29 12:08:30 -07:00
External Notification module config is not available in the Flasher.
2022-06-25 00:39:41 -07:00
:::
</TabItem>
<TabItem value="web">
:::info
2022-08-03 08:16:18 -07:00
All External Notification module config is available for the Web UI.
2022-06-25 00:39:41 -07:00
:::
2022-06-29 12:08:30 -07:00
2022-06-25 00:39:41 -07:00
</TabItem>
</Tabs>
2022-06-29 12:08:30 -07:00
2022-07-14 22:17:44 -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
## 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
2022-08-03 08:16:18 -07:00
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.
2022-07-03 11:20:04 -07:00
:::
## 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 Problems
2022-10-22 03:50:49 -07:00
- This module only monitors text messages. We won't trigger on any other packet types.