Meshtastic Detection Sensor Module: A Complete Guide

Introduction

Meshtastic is a LoRa-based platform that makes it possible to build communication networks that operate independently of services such as Internet access or cellular networks. In recent years, it has become increasingly popular around the world, enabling the creation of community networks that provide basic communication services in remote locations or serve as alternatives to commercial networks during emergencies.

Although its main purpose is to exchange short text messages and GPS location data, Meshtastic also includes basic telemetry features that allow sensor data to be transmitted through the mesh.

To support these applications, the Meshtastic firmware includes two specialized software modules: Telemetry and Detection Sensor. In this tutorial, I take an in-depth look at the Detection Sensor module, explaining how it works, how to configure it, and how you can make the most of its capabilities in your own projects.

The Detection Sensor Module

This module, included in the official Meshtastic firmware, monitors the state of the node’s GPIO pins and sends a message through the mesh when specific configured conditions are met.

The module works exclusively with discrete signals on the GPIO pins. It interprets their state—HIGH/LOW or ON/OFF—and, when required, detects changes from one state to the other. It cannot read sensors that provide a value proportional to a physical variable, such as a BMP280. That is precisely the purpose of the other module: Telemetry.

Typical applications include reporting motion detected by a PIR sensor, notifying when a door opens or closes, reporting the activation of an alarm, indicating the presence or absence of mains power, or warning when the water level in a tank falls below a critical threshold. In every case, the module works with binary conditions that have only two possible states.

Pins and Connections

To use the Detection Sensor module, the sensor to be monitored must be connected to an available GPIO pin on the board being used as the node.

Keep in mind that the available pins vary depending on the board. In this tutorial, all examples are based on the Seeed Studio Meshtastic Kit for ESP32-S3.

This kit consists of a XIAO ESP32-S3 and an SX1262-based LoRa module mounted on top of the XIAO through its board-to-board connector.

The LoRa module uses many of the XIAO pins for its operation and control, leaving only three pins available for general-purpose use: D5, D6, and D7.

The following image shows the pinout of the SX1262 module and the function assigned to each pin. The pins highlighted in green are available and can be used with the Detection Sensor module.

The module reads the selected GPIO pin every 100 milliseconds, so it is not suitable for signals that change very quickly.

Module Configuration

Once you have selected the pin where the sensor will be connected, the module must be configured. Among other settings, you need to specify the corresponding GPIO number, the condition that will trigger an alert, and the transmission intervals.

The image below shows the configuration screen in the Android app for a node running firmware version 2.7.26, although the procedure is similar in earlier versions.

To access this screen, open the node settings and select Module Configuration → Detection Sensor.

Let’s review each of the available settings:

• Detection Sensor Enabled: Enables or disables the module.
• Minimum Broadcast (seconds): Defines the minimum time allowed between two detection alerts.
• State Broadcast (seconds): Defines the interval between periodic state reports. These reports are sent even when the configured pin has not been activated.
• Send Bell with Alert Message: Adds a bell character to the text alert. This can be used to trigger the External Notification feature on the receiving node and activate an additional warning device.
• Friendly Name: This is the text included in the alert message, followed by the word “detected.”
• GPIO pin to Monitor: Specifies the GPIO pin that triggers the alert. The actual GPIO number must be entered. On the XIAO ESP32-S3 board used in these examples, D5 corresponds to GPIO6, D6 to GPIO43, and D7 to GPIO44.
• Detection Trigger Type: Defines the pin state or state transition that will trigger the alert.
• Use INPUT_PULLUP mode: Enables or disables the internal pull-up resistor on the selected GPIO pin.

When enabled, the Detection Sensor module can send two different types of messages: a Detection Alert and a State Report.

The Detection Alert is sent when the monitored pin is considered ACTIVE. The exact meaning of ACTIVE depends on the selected detection trigger type, which will be explained in greater detail in the next section.

The State Report, on the other hand, is sent periodically even if the pin is not activated, providing an update of its current condition.

The module only needs to be enabled and configured on the node where the sensor is physically connected. No additional configuration is required on the nodes that will receive the messages.

Detection Alert

This message is sent when the selected pin becomes active, meaning that it meets the condition defined by the Detection Trigger Type setting. This parameter can be configured with one of the following values:

The last two options are special cases in which both types of messages are sent: a Detection Alert when the pin becomes active and a State Report when it becomes inactive.

Let’s examine each of these conditions in more detail.

Logic Low

When this option is selected, the pin is considered ACTIVE whenever a LOW logic level is detected.

The behavior can be easily understood by looking at the diagram below. At point 1, the pin becomes ACTIVE because it is in the LOW state. This causes an alert message to be sent and starts the Minimum Broadcast Interval, another parameter in the module configuration.

If the pin is still active when this interval expires, as shown at point 2, another alert is sent.

This illustrates the importance of the Minimum Broadcast Interval. Without it, alert messages would be transmitted continuously, potentially saturating the radio channel.

If the pin becomes active again, as shown at point 3, but the minimum interval has not yet elapsed, the condition is ignored.

Finally, if the interval expires but the pin is no longer active because it has returned to the HIGH state, no alert is sent, as shown at point 4.

One possible application of this mode is a mains power failure detector. An alert is triggered when the mains voltage disappears and is repeated periodically according to the configured Minimum Broadcast Interval. When power is restored, the alerts stop.

The minimum interval also acts, to some extent, as a debounce filter. A mechanical sensor may generate a series of short pulses due to contact bounce. This guard interval prevents an alert from being sent for every one of those pulses.

Logic High

This option works in a similar way to the previous one, but with inverted logic.

If the pin becomes active by changing to the HIGH state, as shown at point 1, an alert message is sent and the minimum interval begins.

If the pin is still active when the interval expires, as shown at point 2, another alert is sent. However, if the pin becomes active again before the interval has elapsed, as shown at point 3, no alert is sent. If the pin is no longer active when the interval expires, as shown at point 4, no alert is sent either.

One possible application of this mode is a high-temperature detector built with a temperature sensor and a comparator. The comparator output changes to HIGH when the measured temperature exceeds a predefined threshold and remains LOW otherwise.

With this setting, alert messages are sent when the temperature exceeds the limit and continue while the condition remains active. The alerts stop when the temperature falls below the threshold.

Falling Edge

With this option, the pin becomes active when it changes from HIGH to LOW, producing a falling edge.

This behavior is shown in the following diagram. At point 1, a falling edge is detected, which triggers an alert and starts the minimum interval. At point 2, another falling edge occurs, but it is ignored because the minimum interval has not yet elapsed.

At point 3, the minimum interval has expired and the pin remains LOW. However, the pin is not considered active because no new falling edge has occurred, so no alert is sent.

At point 4, another falling edge is detected and a new alert is transmitted.

If this option were used with the mains power failure detector described earlier, an alert would be sent when power is lost, but no further alerts would be sent unless another transition occurred. If only the alert message were used as an indicator, we would know when the power failed, but not when it was restored.

Rising Edge

This option is the counterpart of the previous one.

If the pin becomes active by changing from LOW to HIGH, as shown at point 1, an alert is sent and the minimum interval begins.

If another rising edge occurs before the interval has elapsed, as shown at point 2, no alert is sent. If the interval expires while the pin remains HIGH, as shown at point 3, no alert is sent because the pin is not considered active unless a new edge is detected.

When another rising edge occurs, as shown at point 4, the pin becomes active again and a new alert is sent.

If this option is used with the temperature comparator example, an alert is sent when the temperature rises above the upper limit. No additional message is sent when the temperature returns to its normal range.

Either Edge Active Low

This option is slightly more complex because it combines edge and state detection and can send both a Detection Alert and a State Report.

The diagram shows how it works. For simplicity, the minimum interval is not shown, although it still applies in the same way as in the previous examples.

In this mode, the active level is LOW. If a transition causes the pin to become active, as shown at point 1, a Detection Alert is sent. When the activation ends and the pin returns to its inactive HIGH state, a State Report is sent.

The main difference between this mode and the previous ones is that one message is sent when the pin becomes active and another when it becomes inactive.

Applied to a mains power detector, this setting reports both when the power fails and when it is restored, although the two events are transmitted using different types of messages.

Either Edge Active High

This final option is the opposite of the previous one.

A Detection Alert is sent when the pin becomes active by changing from LOW to HIGH, as shown at point 1. A State Report is then sent when the pin returns to its inactive LOW state, as shown at point 2.

Applied to the temperature detector example, this setting sends an alert when the temperature becomes excessive and then sends a State Report when the condition ends and the temperature falls below the critical threshold.

State Report

In addition to the Detection Alert, the Detection Sensor module can periodically send an update containing the state of the selected pin.

If the State Broadcast Interval setting is configured with a value greater than zero, the module sends a message containing one of the following values:

state: 0
state: 1

In this context:

state: 0 = pin inactive
state: 1 = pin active

These values do not represent the actual logic level of the pin. Instead, they indicate whether the pin is considered active or inactive according to the selected Detection Trigger Type.

For example, if the configured condition is LOGIC_LOW and the selected pin is LOW when the State Report is transmitted, the module sends: state: 1

This is because the LOW level is considered the ACTIVE condition in this configuration.

Channels

An important point to keep in mind is that both Detection Alerts and State Reports, just like other telemetry data sent automatically by the node, are transmitted only through the primary channel, or channel 0.

As a protective measure, the firmware does not transmit this information if the primary channel does not have a PSK configured. This helps prevent large numbers of automatic messages from being sent over a channel that is often used as a public channel.

This means that both the transmitting node—the one connected to the sensor—and all receiving nodes must have the same primary channel configured. You can choose a name such as Sensors or Telemetry and define a PSK that will be shared by all of them.

A public channel such as LongFast can still be used, but it must be configured as a secondary channel, for example as channel 1 if no other secondary channel has already been defined.

The following image shows an example with two configured channels: Sensors as the primary channel and LongFast as the secondary channel.

Examples

The following sections show several simple applications of the Detection Sensor module using both Detection Alerts and State Reports.

For all these examples, I used firmware version 2.7.26 on both the transmitting node—a Seeed Studio Meshtastic Kit for ESP32-S3—and the receiving node, a Wio Tracker L1 Pro.

In the circuit diagrams, only the SX1262 module mounted on top of the XIAO ESP32-S3 is visible. Although the connections may appear to be made directly to this module, they are actually connected to the pins of the XIAO board underneath it, as shown in the photographs.

Emergency Button

This is probably the simplest example: a push button that triggers a Detection Alert.

One possible application is an emergency button installed in a remote location, such as a park or nature reserve, where Meshtastic is the only available communication coverage. When the button is pressed, the node sends a request for assistance.

The image below shows the circuit and the module configuration.

The push button is connected between D5, which corresponds to GPIO6, and GND. When pressed, it connects the pin to ground, producing a LOW logic level.

In the configuration, the trigger type is set to LOGIC_LOW, the internal PULL_UP resistor is enabled, and the Minimum Broadcast Interval is set to 15 seconds.

When the channels are configured correctly on both the transmitting and receiving nodes, pressing the button sends the Detection Alert. If the button remains pressed, the alert is repeated every 15 seconds.

If you press the button immediately after powering on or restarting the node and do not receive an alert, wait approximately one minute and try again. After startup, the firmware apparently spends some time initializing the node, searching for nearby nodes, and performing other tasks before it begins monitoring the GPIO pins.

On the right side of the image above, you can see the alert received by the destination node. The message contains the configured Friendly Name, “Emergency, ” followed by the word “detected, ” which is automatically added by the firmware.

The image below shows the test circuit assembled on a breadboard.

Door-Opening Detector

Imagine that you want to monitor a door in a remote location, such as a warehouse or a construction site, using Meshtastic. You could also use it as an additional home-security feature, sending an alert whenever the door opens while you are away.

This can be achieved by modifying the previous example and replacing the push button with a magnetic door sensor.

The sensor consists of a reed switch in the wired section and a magnet in the other section. When both parts are close together, which corresponds to the door being closed, the contacts remain closed. When they move apart because the door opens, the contacts open as well.

With the PULL_UP resistor enabled on the node’s GPIO input, D5 remains connected to GND through the sensor while the door is closed, producing a LOW level. When the door opens, the contact opens and the pin changes to HIGH.

This transition from LOW to HIGH is called a rising edge. Therefore, the Detection Trigger Type used in this example is RISING_EDGE. The remaining settings are unchanged.

When the door opens, a single alert is sent. It is not repeated because the trigger is the change of state itself rather than the level that remains afterward.

The following image shows how the sensor is connected to the board.

Water Tank Level Sensor

Another possible application is sending an alert when a water tank or reservoir reaches a particular level, for example when it becomes full or when it drops below a critical minimum.

Water levels can be detected in several ways. One simple option is the XKC-Y25, a capacitive sensor capable of detecting different types of liquids—not only water—through the external wall of a plastic or glass container, without coming into direct contact with the liquid.

This sensor is available in several versions. The version used in these tests has a PNP transistor output.

The application circuit is shown below. The sensor is powered from 5 V and GND. When liquid is detected, the sensor activates and connects its output to 5 V through its internal PNP transistor.

To avoid damaging the ESP32 with this voltage, three 10 kΩ resistors are used as a voltage divider, reducing the signal to approximately 3.3 V.

The sensor therefore produces a HIGH output when it detects water and a LOW output when no water is detected.

To make the node send an alert when the water falls below a specific level, the alert must be triggered when the sensor output changes to LOW. The module could therefore be configured using LOGIC_LOW or FALLING_EDGE.

To demonstrate a different option, I selected EITHER_EDGE_ACTIVE_LOW. This setting sends a Detection Alert when the pin changes to LOW and then sends a State Report when it returns to HIGH.

This allows the system to report both when the water level becomes too low and when it returns to an acceptable level.

As shown above, the message “Low level detected” is received when the water falls below the minimum level. When the water rises again, the message “Low level state: 0” is received.

In this case, state: 0 does not mean that the GPIO input has a LOW logic level. It means that the monitored condition is INACTIVE, which in this configuration corresponds to a HIGH logic level.

The following image shows the assembled circuit.

The version of the sensor with an NPN transistor output does not require the resistor divider. When activated, it connects the input to GND. The GPIO input must have its internal PULL_UP enabled, and the activation produces a falling edge.

Float-Switch Level Sensor

To complete these examples, this last circuit performs the same basic function as the previous one but uses a float switch instead of a capacitive sensor.

Several types of float switches are available. The model used here contains an internal switch with two outputs: normally open, or NO, and normally closed, or NC.

A small steel ball inside the device moves as the water level changes, switching the electrical contacts.

For this circuit, I used the normally closed contact, connected through the blue and brown wires. Depending on how the float is positioned inside the tank, it can indicate whether the water is above or below a selected critical level.

With these connections, the float switch works as follows:

Tank above the critical level → Switch open
Tank below the critical level → Switch closed

The simplest way to connect it to the ESP32 is shown in the following image.

When the tank is above the critical level, D5 remains HIGH through the internal PULL_UP resistor. As the tank empties and the float switch closes, the pin is connected to GND, producing a LOW logic level.

To explore another feature of the Detection Sensor module, I did not configure a Detection Alert in this example. Instead, I used periodic State Reports with the minimum available interval of 15 minutes.

The Minimum Broadcast Interval for alerts was left unconfigured. Although it is not used for triggering alerts in this example, the Detection Trigger Type was set to LOGIC_LOW.

With this configuration, the state of D5 is reported every 15 minutes, regardless of how the pin changes between reports.

As explained earlier, the value included in a State Report is not the actual logic level of the pin. It indicates whether the configured condition is active or inactive.

Because the selected trigger type is LOGIC_LOW, a LOW pin level is considered ACTIVE. Therefore:

state: 1 = active condition, pin LOW
state: 0 = inactive condition, pin HIGH

With the float switch connected as described:

state: 0 = tank above the critical level
state: 1 = tank below the critical level

On the right side of the previous image, you can see the circuit behavior. The tank is initially above the critical level, producing state: 0. It then falls below the critical level, producing state: 1, and finally rises above it again, returning to state: 0.

Each report was transmitted at 15-minute intervals.

The previous examples are intended to demonstrate several practical applications and different configuration options for the Detection Sensor module. You will probably come up with many more possibilities using different types of sensors.

One important point is that receiving alert or state messages on a mobile device or through the phone app is not the most convenient way to monitor a sensor, especially when several sensors are involved.

Fortunately, extracting these messages from the mesh for further processing and displaying them in a more graphical format is not particularly difficult. For example, Node-RED or a Python script running on a Raspberry Pi or PC connected to a Meshtastic node can be used to collect data from multiple sensors and display it on a dashboard, providing a faster and more convenient way to monitor their status.

Conclusions

The Detection Sensor module greatly expands the possibilities of Meshtastic by turning a node into a simple remote monitoring system.

By properly configuring the module parameters, it is possible to develop a wide range of applications using ON/OFF sensors, including push buttons, door-opening sensors, and water-level detectors.

Although the module is limited to binary signals, its integration into the standard firmware makes it possible to create simple and affordable solutions while taking advantage of an existing Meshtastic network infrastructure.

I hope you found this article useful and that it serves as a reference for developing your own applications. As always, feel free to leave your comments and questions below.

See you next time! 🚀