⚠️ MailBox Guard Production is Discontinued. The New version "PirBOX-LITE or PirBOX-MAX"

🤗 Please consider subscribing to my YouTube channel Your subscription goes a long way in backing my work.

Long Range "LoRa" Universal MailBox Sensor

Can be integrated with Home Assistant, used via WhatsApp, or be operated offline.

Use Cases

• Mailbox Sensor - "Code examples are provided"
• Alarm / Motion Sensor

How it works - Mailbox Use Case

The Mailbox Guard is a device that detects when a new letter or package has been delivered to your mailbox using a PIR sensor and door reed switch. It can send a signal to your LoRa gateway, then the gateway sends a message via WiFi to Home Assistant "MQTT" or its "API" or to WhatsApp allowing you to receive notifications directly into your phone. Or you can use it offline, the gateway display will show the number of letters received, Battery status, and signal strength.

Links

• YouTube video https://youtu.be/gf1WWKyEnbg

• My Shop

• Mailbox Sensor https://www.pricelesstoolkit.com/

• UNIProg Programmer https://www.pricelesstoolkit.com/

• Official Multiprotocol Gateway CapiBridge https://www.pricelesstoolkit.com/

• Gateway on Aliexpress LILYGO® TTGO LoRa32 V2.1_1.6 Version 433/868/915Mhz

• Pogo Pin Clamp 6 Pin Minimum 2.54mm pitch
• Reed Switch "Normally open When the magnet is far away" "For soldering on PCB" https://s.click.aliexpress.com/e/_DkA1Sjp
• Reed Switch with cable "Normally open When the magnet is far away" https://s.click.aliexpress.com/e/_DFNJv1h
• Battery Li-Ion 14500 800mA
• USB Battery charger "just in case" https://s.click.aliexpress.com/e/_DkDAztD

Sensor Specifications

• Microcontroller "Attiny1616"
• LoRa Bands "433/868/915"
• PIR Sensor AM312 "With the option to turn it off"
• Onboard reed switch "optional"
• External reed switch "Input 2 Pin"
• Battery Holder for "Li-Ion 14500"
• Optional 2 Pin SMD LiPo Battery connector
• Build-in Battery Charger "Can be separated"
• Connector USB-C
• Charge status LED "Charging, Full"
• Extremely Low Power Consumption
• Motion Sensor PIR 11.30uAh
• Only reed switch 280nAh
• Every data submission uses 65uA
• TX LED "With the option to turn it off"
• Size
• With charger "XXmm to XXmm"
• Without charger "XXmm to XXmm"
• Programming Protocol
• UPDI / Serial2UPDI

📣 Updates, Bugfixes, and Breaking Changes

[!NOTE] If you're ready to contribute to the project, your support would be greatly appreciated.

• 22.05.2025 - Breaking Change (XOR obfuscation "Encryption" for LoRa).
• • CapiBridge and MailBox Guard firmware need to be updated.
• 08.05.2025
• MailBox Guard Production is Discontinued. The New version "PirBOX-LITE or PirBOX-MAX"
• 30.07.2024
• New multisensor Gateway firmware LoRa_Gateway_MQTT_JSON.ino
• Sensor firmware cleanup Mailbox_Guard_Sensor_MQTT_JSON.ino

⚠️ Battery Polarity ⚠️

• Before connecting the battery, make sure to check the connector polarity on your battery. This is especially important because many 1S LiPo batteries have inverted polarity.

Arduino IDE Setup

[!NOTE] For the Library "megaTinyCore" the official recommendation is. Only versions of the Arduino IDE downloaded from https://arduino.cc should be used, NEVER from a Linux package manager. The golden standard is "V1.8.13".

• Additional Boards Manager URLs

• ESP32 https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_dev_index.json

• megaTinyCore http://drazzy.com/package_drazzy.com_index.json

• Libraries Used

• LoRa
• PubSubClient
• ArduinoJson.h
• ESP8266 and ESP32 OLED driver for SSD1306 displays
• UrlEncode
• HARestAPI "Sketch > Include Library > Add .ZIP Library..."
  • https://github.com/debsahu/HARestAPI

Choosing a Gateway Hardware

1. CapiBridge LoRa/ESP-NOW Gateway: I developed this project, featuring multi-protocol support, including LoRa and ESP-NOW. It will be compatible with my future LoRa and ESP-NOW sensor projects. Purchasing this gateway will support my ongoing open-source developments.
2. LilyGo LoRa Board: This option is more affordable but only supports LoRa. It may not be compatible with all future projects.

Choosing Firmware for LoRa Gateway

1. LoRa_Gateway_MQTT_JSON.ino - 🆕 "Home Assistant MQTT Autodiscovery": Automatically discovers and integrates sensors with Home Assistant via MQTT.

2. LoRa_Gateway_OLED.ino - "For Offline Use": Displays new mail notifications, including letter count, signal strength, and battery status. Requires a reset after mail retrieval.

3. LoRa_Gateway_WhatsApp.ino - Sends a "You have new mail" message to WhatsApp.

4. LoRa_Gateway_MQTT.ino - Sends raw messages and RSSI to an MQTT server.

5. LoRa_Gateway_HARestAPI.ino - Sends new mail notifications to Home Assistant via REST API.

Gateway Configuration

[!NOTE] If you are using CapiBridge Gateway, configure it using the Capibridge page.

Select TTGO_LoRa Board Version

• In Arduino IDE select Tools > Board > ESP32 Arduino > ESP32 Dev Module
• Change the BOARD definition in board.h according to your Lilygo gateway HW Version " 1 = ENABLE / 0 = DISABLE ".

#define LORA_V1_0_OLED  0
#define LORA_V1_2_OLED  0
#define LORA_V1_3_OLED  0
#define LORA_V1_6_OLED  0
#define LORA_V2_0_OLED  1

TTGO Boards GPIOs

Setting up WIFI and LoRa in the Gateway

• Firmware LoRa_Gateway_MQTT_JSON.ino
• Configuration File config.h
• The LoRa settings in the gateway and in the sensor must match.

/////////////////////////// Gateway Key ///////////////////////////

#define GATEWAY_KEY "xy" // Keep it short

///////////////////////////////////////////////////////////////////////////////

////////////////////////////// WIFI / MQTT ////////////////////////////////////
#define WIFI_SSID "wifi-name"
#define WIFI_PASSWORD "wifi-password"
#define MQTT_USERNAME "mqtt-username"
#define MQTT_PASSWORD "mqtt-password"
#define MQTT_SERVER "IP-Address"
#define MQTT_PORT 1883


////////////////////////// LoRa Config ////////////////////////////////////////

#define SIGNAL_BANDWITH 125E3  // signal bandwidth in Hz, defaults to 125E3
#define SPREADING_FACTOR 8    // ranges from 6-12, default 7 see API docs
#define CODING_RATE 5          // Supported values are between 5 and 8, corresponding to coding rates of 4/5 and 4/8. The coding rate numerator is fixed at 4.
#define SYNC_WORD 0x12         // byte value to use as the sync word, defaults to 0x12
#define PREAMBLE_LENGTH 6      // Supported values are between 6 and 65535.
#define TX_POWER 20            // TX power in dB, defaults to 17, Supported values are 2 to 20
#define BAND 868E6             // 433E6 / 868E6 / 915E6

///////////////////////////////////////////////////////////////////////////////

The remaining is to upload the code into the LilyGo board after that the "LoRaGateway" RSSI entity will appear in the MQTT devices list.

Mailbox Sensor configuration and Programming

For programming MailBox Guard, you need any 3.3V "UPDI programmer" You can use my other open-source project "UNIProg Programmer" GitHub

UPDI Connection Diagram

1. In Arduino IDE select the programmer "SerialUPDI-230400 baud"
2. Select board configuration as shown below "screenshot"

1. Open Sensor firmware Mailbox_Guard_Sensor_MQTT_JSON.ino then change sensor name, gateway key, and LoRa settings according to your needs.

[!NOTE] The LoRa settings must match the gateway ones.

///////////////////////////////// CHANGE THIS /////////////////////////////////

#define SIGNAL_BANDWITH 125E3
#define SPREADING_FACTOR 8
#define CODING_RATE 5
#define SYNC_WORD 0xF3
#define PREAMBLE_LENGTH 6
#define TX_POWER 20
#define BAND 868E6  // 433E6 / 868E6 / 915E6
#define NODE_NAME "mbox" // The name of your sensor must be unique.
#define GATEWAY_KEY "xy" // must match the Gateway key.

///////////////////////////////////////////////////////////////////////////////

1. Click "Upload Using Programmer" or "Ctrl + Shift + U"

Done! Once the sensor is triggered for the first time, it will appear in the MQTT devices list on Home Assistant.

Home Assistant Configuration

"Automation" Sensor Notification

Explanation Click here

This automation is set up to notify a mobile device when new mail is detected in the mailbox. This setup ensures that whenever new mail is detected by the mailbox sensor, a high-priority notification with relevant details and an image is sent to the specified mobile device. The details of the automation are as follows:

Trigger

• Platform: State
• Entity: sensor.mbox_state
• To State: mail
• For Duration: 1 second
• From State: Not specified (null)

This means that the automation will trigger when the state of sensor.mbox_state changes to mail and remains in that state for at least 1 second. The "From State" being null indicates that the trigger does not depend on the previous state of the sensor.

Condition

There are no conditions specified, so this automation will run whenever the trigger criteria are met.

Action

• Service: notify.mobile_app_doogee_v20pro
• Data:
• Message: "Mailbox is Full!"
• Title: "New Mail!"
• Additional Data:
  • URL: /lovelace/home - A link to the Home Assistant dashboard.
  • Persistent: true - Ensures the notification stays on the device until manually dismissed.
  • Importance: high - Sets the priority of the notification.
  • Channel: MailBox - Specifies the notification channel, useful for Android devices.
  • Tag: mailbox - A tag to help categorize the notification.
  • Image: /media/local/notify/mailbox.jpg - An image included in the notification.
  • Actions:
  • Action: received - A custom action identifier.
  • Title: "I took the parcel" - A label for the action button in the notification.

Mode

• Mode: single - Ensures that only one instance of this automation can run at a time.

alias: 📬 LoRa MailBox Sensor Notification
description: ""
trigger:
  - platform: state
    entity_id:
      - sensor.mbox_state
    to: mail
    for:
      hours: 0
      minutes: 0
      seconds: 1
    from: null
condition: []
action:
  - service: notify.mobile_app_doogee_v20pro
    data:
      message: Mailbox is Full !
      title: New Mail!
      data:
        url: /lovelace/home
        persistent: true
        importance: high
        channel: MailBox
        tag: mailbox
        image: /media/local/notify/mailbox.jpg
        actions:
          - action: received
            title: I took the parcel
mode: single

"Automation" MailBox Dismiss Notification from Notification

Explanation Click here

This automation is designed to handle the dismissal of a notification when a specific action is triggered on a mobile device. Works by sending an MQTT message to update the state of the mailbox sensor and then clearing the corresponding notifications on specified mobile devices. The details of the automation are as follows:

Trigger

• Platform: Event
• Event Type: mobile_app_notification_action
• Event Data:
• Action: received

This means the automation is triggered when the mobile app receives a notification action event with the action identifier received.

Condition

There are no conditions specified, so this automation will run whenever