search

PricelessToolkit / MailBoxGuard

Lora Long Range Mailbox Sensor for Smart Homes or for Standalone use
BSD 3-Clause "New" or "Revised" License
182 stars 28 forks source link

readme

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

ko-fi

Long Range "LoRa" Universal MailBox Sensor

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

Use Cases

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

Sensor Specifications

📣 Updates, Bugfixes, and Breaking Changes

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

⚠️ Battery 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".

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

#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

Name V1.0 V1.2(T-Fox) V1.3 V1.6 V2.1
OLED RST 16 N/A N/A N/A N/A
OLED SDA 4 21 4 21 21
OLED SCL 15 22 15 22 22
SDCard CS N/A N/A N/A 13 13
SDCard MOSI N/A N/A N/A 15 15
SDCard MISO N/A N/A N/A 2 2
SDCard SCLK N/A N/A N/A 14 14
DS3231 SDA N/A 21 N/A N/A N/A
DS3231 SCL N/A 22 N/A N/A N/A
LORA MOSI 27 27 27 27 27
LORA MISO 19 19 19 19 19
LORA SCLK 5 5 5 5 5
LORA CS 18 18 18 18 18
LORA RST 14 23 23 23 23
LORA DIO0 26 26 26 26 26

Setting up WIFI and LoRa in the Gateway

/////////////////////////// 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 0xF3         // 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

UNIProg MailBox Guard
GND GND
3v3 3v3
UPD UPD
  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 the trigger criteria are met. #### Action 1. **Service:** `mqtt.publish` - **Data:** - **QoS:** `0` - Quality of Service level. - **Retain:** `true` - Retains the message on the MQTT broker. - **Topic:** `homeassistant/sensor/YourSensorName/state` - The MQTT topic to publish to. - **Payload:** `empty` - The message content, indicating the mailbox state is now empty. 2. **Service:** `notify.mobile_app_doogee_v20pro` - **Data:** - **Message:** `clear_notification` - Clears the notification. - **Data:** - **Tag:** `mailbox` - Identifies which notification to clear. 3. **Service:** `notify.mobile_app_oneplus8t` - **Data:** - **Message:** `clear_notification` - Clears the notification. - **Data:** - **Tag:** `mailbox` - Identifies which notification to clear. #### Mode - **Mode:** `single` - Ensures that only one instance of this automation can run at a time. 

alias: 📬 LoRa MailBox Dismiss Notification
description: ""
trigger:
  - platform: event
    event_data:
      action: received
    event_type: mobile_app_notification_action
condition: []
action:
  - service: mqtt.publish
    data:
      qos: 0
      retain: true
      topic: homeassistant/sensor/YourSensorName/state
      payload: empty
  - service: notify.mobile_app_doogee_v20pro
    data:
      message: clear_notification
      data:
        tag: mailbox
  - service: notify.mobile_app_oneplus8t
    data:
      message: clear_notification
      data:
        tag: mailbox
mode: single

"Script" MailBox Status Reset for using from Dashboard

alias: MailBox Status Reset and Dismiss Notification
sequence:
  - service: mqtt.publish
    data:
      qos: "0"
      retain: true
      topic: homeassistant/sensor/YourSensorName/state
      payload: empty
  - service: notify.mobile_app_doogee_v20pro
    data:
      data:
        tag: mailbox
      message: clear_notification
  - service: notify.mobile_app_oneplus8t
    data:
      message: clear_notification
      data:
        tag: mailbox
mode: single