Introduction
This blog covers a mail notification project for Home Assistant that I use. It lets me know when the mailbox has been opened (and presumably) has mail inside. Using Home Assistant's automations, I can post a notification to my Home Assistant web page, and have Amazon Alexa tell me that I have mail.
The project consists of several components that will be covered in more details in sections to come:
Mailbox Sensor - This is a battery operated, low power sensor that resides with the mailbox. It uses a radio technology called LoRa which is short for Long Range. It is long range in that it can cover distances much longer than Wi-Fi, ZWave or Zigbee. Wi-Fi, ZWave, and Zigbee are common radio technologies used within the home for smart home applications. LoRa is a technology that is suited for use well outside the home.
Gateway - This is the device that resides within the home and receives the LoRa signal from the Mailbox Sensor. The Gateway is used to talk to Home Assistant and acts as a relay between Home Assistant and the Mailbox Sensor.
Home Assistant itself.
This project was made possible by some of the work done by "Priceless Tool Kit" whose links and credits you can find at the end of this blog. If you plan on building a project like this, I encourage you to watch his YouTube videos.
LoRa Sensor
The LoRa Mailbox Sensor is composed of a couple of main components, and we'll break them down as we go.
They are made up of:
Housing containing the LoRa PCB Assembly, along with the battery.
A motion sensor that has its own housing assembly.
My mailbox looks like the following (shows the main sensor housing in the yellow circle):
LoRa Sensor Housing
The Housing as shown below is made up of the PricelessToolkit PCB assembly along with a P18650 Lithium-ion rechargeable battery and battery holder. The three wires at the bottom (Red, Yellow, Black) go off to the Motion Detector (not shown).
The PCB Assembly is made up of:
PCB (with an assortment of SMB parts)
LoRa Module
Power Regulator with Battery Monitor
Arduino Pro Mini
PCB and SMB Parts
The PCB itself is provided by PricelessToolkit, and you can get the Gerber files at his website (see the references at the end of this blog). You'll need a PCB fabrication house to make these boards for you. I used PCBWay as I have used them for some of my other projects.
The assortment of SMB parts make up the Power Regulator and Battery Monitor discussed below. The PricelessToolkit website provides the parts list needed for the regulator and battery monitor. When picking out these parts, one needs to pay attention to the package types as SMB components come in various shapes and sizes. Capacitors can also differ in polarized/non-polarized versions. The silkscreen on the PCB is fairly well marked to indicate polarization orientation of the parts.
The PricelessToolkit's YouTube provides a demonstration of using a "hot plate" and solder paste for soldering the parts together. I acquired one of these hot plates, a UYUE 946C version 2, and put it to work. These hot plates appear to be designed for removing touch screens from cell phones, but they can also used for soldering SMB parts. For the solder paste, I used a low temperature solder paste "Sn42/Bi57/Ag1 T4". Using the solder profile provided with the solder paste datasheet, I set the temperature to the peak value of the profile.
The hot plate is not so good at rapid rise and cool down in a way that allows it to follow the profile. What I did was the following: with the assembly on the hotplate, I let the hot plate warm up at its own rate until it was near the profile's peak temperature, and then I set the temperature to 0 (instead of powering off the hotplate) and let the assembly cool down on the plate naturally in order to avoid any sort of thermal shock.
LoRa Module
The LoRa Module used is from Ai-Thinker. There are different models depending on country/region. A couple of devices that I have made notes about that are supported by Priceless Toolkit's PCB:
RA-01 433Mhz
RA-01H - This covers the range 803~930MHz. This range can be used for both the US, which uses 915MHz, and the EU, which uses 868MHz. The frequency will be set in software by the Arduino Pro Mini using a SPI interface with the module. Since I live in the U.S., this is the version I went with.
These modules use the SemTech SX1276 which is a popular chip set for LoRa applications.
An antenna may have to be ordered separately, which was the case for me. A helical ("spring") wire antenna is usually used, and the parameters of length, diameter, and number of turns dictates its resonance frequency, so be sure to pick the appropriate one. I selected one designed for 915MHz.
Antenna orientation is also of interest. Texas Instruments provides some insight into this. They have an antenna design kit that can be used by companies to evaluate several types of antennas, including a "spring" antenna. But more importantly they provide an analysis of an antenna's radiation pattern. What the analysis shows is that these types of "spring" antennas tend to radiate away from the spring coil perpendicularly. In other words, if the coil is standing up vertically on a desktop, the radiation would tend to be more parallel to the desktop. I had originally planned on mounting the housing assembly vertically so I placed the spring parallel to the PCB. However I ended up mounting the housing assembly horizontally, and with it the antenna was also mounted horizontally. It would have been better if my antenna was pointed vertically (perpendicular to the PCB) instead of the way it is shown in the picture above.
Complimentary to this antenna is the Gateway's antenna, which we will talk about later, and it should also be oriented the same way. If the two antennas are oriented differently, say the mailbox sensor's antenna is horizontal and the Gateway's antenna is vertical, then one can get quite a bit of polarization loss particularly in a true line-of-sight scenario. But when the Gateway's antenna is located well within the home, multi-path fading should be occurring, so the polarization loss shouldn't be so bad. Plus, if one looks at the power budget with a LoRa transmitter of around +19 to +20dBm, and a receiver sensitivity which can be as low as -148dBm, then in my case there is plenty of power budget to overcome polarization losses. So for now, I have kept the antenna orientation of the sensor in the wrong direction, but I may change it in the future.
Power Regulator & Battery Monitor
This is a custom design from PricelessToolkit that provides power to both the Arduino Pro Mini, LoRa module and the Motion Detector. The circuit diagram is reproduced below.
Power Regulator and Logic
The custom circuit uses a regulator to power the Pro Mini and LoRa Module, but does so only when the regulator has be "enabled". The circuit provides OR-like conditioning from which to "enable" the regulator. The regulator can be enabled when either the Motion Detection sees motion activity, and "enables" the regulator from its side, or when the Pro Mini software activates a signal to "enable" the regulator from its side.
Operationally, the first thing that happens is that the Motion Detector detects activity and applies a "high" signal level on pin 2 of the HDR-M header for a few seconds. This in turn enables the regulator to provide power to the Pro Mini which starts the CPU running. The Pro Mini's software immediately enables its side of the power regulator by setting the "DPIN" to "high" and keeps it applied long enough to send a message (or two) to the Gateway. After completion, the Pro Mini releases its "enable" side. When no more motion is detected, the Motion Detector releases its "enable" line by setting pin 2 of the HDR-M to "low". Only when both the Pro Mini and the Motion Detector release their respective "enable" lines will the regulator power down the Pro Mini and LoRa module.
As a side note, there is a "TEST" switch that when pressed also puts a "high" on pin 2 of the HDR-M header. It is there primarily to keep the CPU powered and running so that it can be programmed.
Power is always supplied to the Motion Detector, but its power consumption while in detection mode is very small (more on this below).
If one wants to understand how the circuitry works, one can do some "back of the napkin" analysis to see what is going on.
The AP2112K-3.3 regulator provides 3.3V output when the EN (enable) is 1.5V (or higher) and will shutdown its output when EN is 0.5V (or lower). For the motion detector side, we'll assume its "high" signal is 3.3V, and that the 1N5819 drops around 0.6V when current is forward biased. We'll assume that when the Pro Mini is powered down, that I3 =0. If we take a first approximation that I2 >> I1 then we can determine that the "EN" pin of the regulator (AP2112K-3) is about:
3.3 -I2R4-0.6-I2R2=0 Using Kirchhoff's Voltage Law
3.3-I2(R4+R2) -0.6=0
(3.3-0.6)/(R4+R2) = I2
I2=24.5uA
EN = 3.3- I2xR4-0.6 = 2.7-0.245 which is ~ 2.4V
Which is enough to enable the regulator.
For the Pro Mini side, we'll assume that when it sets DPIN "high" that it is 3.3V. If we take an approximation that I3 >> I2 >>I1, then we can determine that the "EN" pin of the regulator is:
3.3 - 0.6 - I3(R3+R2) = 0
I3 = 2.7/(R3+R2) = 26.9uA
EN = 2.7 - 26.9 x 220
EN ~ 2.7V
Which is enough to enable the regulator.
Battery Monitor & Battery
A 18650 Lithium-ion battery is used in the project. Here are a few notes of interest on a battery of this type:
Voltage range between 2.5V and 4.2V,
4.2V is the charging voltage.
As the battery drains, its voltage with decrease (which is true for most batteries).
Nominal voltage is considered to be 3.7V.
General practice is to discharge down to 3.0V before recharging
My battery's specification says to NOT allow it to discharge below 2.75V
Capacity - For my battery, it is 3200mAh
The battery monitoring is done primarily by using the Pro Mini's 10bit A/D converter. When power is enabled to the Pro Mini, its ADC can measure the voltage at the A0 pin. R6 and R7 form a voltage divider so we can do a "back-of-the napkin" analysis to determine an equation for measuring the battery voltage. When the EN pin of the regulator is active (~2.4V), we'll assume that Q2 is turned on and saturates with Vce=0.2V, however we'll ignore Vce for now.
Vbatt - Ibatt(R6+R7) =0 Using Kirchhoff's Voltage Law
Ibatt = Vbat/(R6+R7)
A0 = Ibatt xR7 = Vbatt x R7/(R6+R7)
Vbatt = A0 x(R6+R7)/R7
A0 is the value being read by the Pro Mini's ADC, so its good to understand a little about its ADC. There are a few different reference voltage choices that the Pro Mini can use for its ADC. The one used here is the INTERNAL reference voltage of 1.1V. This means that the 10 bit ADC can measure values between 1.1V (ADC value = 1023) and 0V (ADC value =0V) or put another way,
voltage_reading = ADC_value x 1.1/1023.
Since the voltage_reading is for A0, the equation for Vbatt becomes:
Vbatt = (ADC_value x 1.1/1023) x (R6+R7)/R7
Since R6 and R7 have a tolerance, then for a given reading of A0 by the ADC, Vbatt will actually be slightly higher or lower. Ideally one would measure the actual values of R6 and R7, and take Vce into account. Instead, I wanted to measure the actual Vbatt against ADC readings, paricularly near its discharge threshold of 3.0 Volts, and apply some sort of correction to the readings and see if the correction provided reasonable accuracy over the range of battery voltages. I ended up with the following substitute equation which seemed to provide reasonable accuracy over the measured voltages:
Vbatt = (ADC_value x 1.1/1023) x (R6+R7)/R7 + CF
where CF is a correction factor. Using this equation, CF can be formulated as:
CF = Vbatt - (ADC_value x1.1/1023) x (R6+R7)/R7
For the measurements, I used an adjustable lab based DC supply (acting as a battery), and measured its voltage with a voltmeter. I took ADC readings over different supply voltages of 3.7, 3.0, 2.75, and 2.5 to calculate CF and found that CF seemed to have roughly the same value over this range, and I pick the CF value at 3.0 Volts. So this the equation I went with and you'll see it in the Pro Mini sketch code.
One other thing to mention, is that the reading of an ADC is not necessarily instantaneous. This article goes into a lot of depth with the ATMega ADC, and discusses how the ATMega's ADC uses a sample and hold capacitor to sample the analog pin and that it takes a little bit of time for the capacitor to charge up, particularly for higher source impedances (>10k Ohm) which is the case here. In my testing, I found that the ADC value being read was not accurate if read early on after startup but was quite accurate if the reading was read again after a delay. I used a delay of 20ms which was probably overkill.
Battery Consumption
I made a few measurements of the current coming out of the battery when only the PIR was being used (no motion detected) and when both the PIR and the CPU plus LoRa module were running:
PIR only: ~42 uA
PIR, CPU and RF Module on: ~5.7 mA
This article discusses a 3.3V Pro Mini pulling around 4 to 8mA, so my measurements are consistent with this. Over the course of a day, the CPU might only run for a few seconds, let's say 10 seconds (5 seconds each time you open the mailbox), and this will consume 5.7mA x 10sec/(3600sec/hr) = 0.016mAh. Over a day, the PIR will consume 0.042mA x 24 hours = 1mAh. This means, in theory at least, that the battery should last 3600mAh/1.016mAh/day = 3500 days. I wouldn't think it would actually last this long, but it does suggest that one should not have to recharge the battery anytime soon!
Motion Detector
The Motion Detector used is an AM312 PIR (Passive Infrared) module. It consists of a motion detector that is integrated inside a T0-like can package (this package is also called an AM312), along with a voltage regulator, and a few other ancillary parts. Below is a picture of one I used (along with a 3D printed part).
These modules are fairly commoditize, however a data sheet on the module itself was a little hard to come by, but from what I could gather (see here and here), this is what a spec sheet might look like :
Working temperature: -20 to +60 °C
Working voltage: 2.7 to 12VDC between pin VCC and pin GND
Motion activity is output on pin OUT as 3 Volts ("high").
When motion activity is detected, the output goes high after some delay period (2 to 4 seconds), and then the output will remain high until motion abates. When motion activity abates, after the same delay, the output goes low.
Here is what the final assembly inside the mailbox looks like:
It is mounted behind the mailbox doorstop. The doorstop here provides a fair bit of protection when the mail person places (or shoves) mail into the box.
Alternative - Reed Switch and Magnets
Consider this section a thought exercise. One might ask, why use a motion detector? The use case for using a motion detector is when a mailbox has a slot that a mail carrier uses to drop mail into, in which case a motion detector is a pretty good solution. If there is a door, or something similar that the mail carrier opens, then it opens up a few other possibilities, one of which is a Reed Switch with magnets. Here is a way it "could" be used instead of the motion detector:
The figure shows a Reed Switch in a "single pole double throw" configuration. Simply hook Vbatt to the common lead, and have pin 2 of the HDR-M connect to the Normally Closed (N/C) lead (shown as Vout). A magnet would be attached to the mailbox door and with the door closed it would be in close proximity to the Reed Switch. With the door closed, the magnet forces the connection from Vbatt to Normally Open (N/O). When the mailbox door is open, the magnet is no longer in close proximity, and the Reed Switch moves Vbatt to the N/C lead. This then connects Vbatt to the HDR-M pin 2, which like the motion detector, will enable the regulator, thus turning on power to the Pro Mini. Here, the only time power is being consumed is when the door is opened, so this would save even more power compared to the motion detector. If the door is left open for long periods of time however, it can add considerable drain to the battery, and this is why I added a software based low power shutdown capability for the Pro Mini and LoRa module.
The big "gotcha" here is that mechanical switches bounce around before they settle into their final position and thus it is not a good idea to use one without any de-bouncing circuitry. Nevertheless, in my curiosity, I tested this out on my work bench to see if it would even work without any de-bouncing, and surprisingly it did. I did not do any further analysis to see how bad the bouncing effect was on the regulator's output, and one would certainly want to use a de-bouncing circuit for this, so for now I leave this for further study, as I carried on with the motion detector.
Arduino Pro Mini
The Arduino Pro Mini contains an AVR Atmel ATmega328P (P for Pico) CPU. The Pro Mini comes in a few different types, one with 3.3V based operations at 8MHz and one at 5V operation at 16MHz. This project uses the 3.3V version. These also come with a "Solder Joint 1" (SJ1) on the PCB which will need to be de-soldered in order to electrically disconnect the on-board power regulator, as the custom regulator will be used in its place.
Notes about "Clones" - "Clones" of the Pro Mini typically do not have SJ1, and this requires a couple of components (U2 and LED1) be removed off the board in order to electrically disconnect the on-board regulator. Another important factor is the FTDI connector pin outs. Some versions allow the FTDI to be connected at the top of the board, others from the bottom. The reason this is important is that the Priceless Toolkit PCB relies on the FTDI pin outs of the Pro Mini to be oriented a certain way. The best way to tell is to make sure the VCC of the Pro Mini's FTDI aligns with the Priceless Toolkit's PCB "VCC" where the FTDI header would go.
The following figure shows the final board assembly and a DIY FTDI header I used to program the Pro Mini. I cut out the VCC pin in the FTDI header so as to not have it compete with the lab bench power supply I was using (which is connected to BAT and GND).
The software used is a modified version of an Arduino sketch written by Priceless Toolkit. You can find it at my GitHub repository. The software uses the following libraries:
LoRa Library - Specifically the Sandeep Mistry LoRa library is used to provide the control and data handling of the LoRa Module. It initializes the module, sets its frequency, and transmit power level, and it encapsulates and sends the data. The initialization makes use of several default settings such as bandwidth, and coding rate, and "Sync" word. "Sync" word deserves a little discussion. A LoRa packet starts with a preamble and the preamble ends with this "Sync" word. If a LoRa receiver doesn't find this Sync word, then it is suppose to ignore the rest of the packet. The Sync word is also to be used to distinguish between public and private LoRa networks, namely the value of 0x34 (for SX127x devices) is recommended for public LoRa networks and 0x12 for private. Other values can be used, but there appear to be rules that limit how many other values are available. In my experimentation, it didn't seem to matter what the Sync word was set to as the Gateway always accepted it. Nevertheless, I used the 0x12 value.
Arduino Unique ID Library - This library reads various internal "identifying information" registers of the Pro Mini with the intent of deriving a unique ID, much like a MAC address, for this device (the authors however make no guarantees about this). The low level layers of the LoRa protocol, which is used in this project to carry the JSON data, do not provide any addressing information. If multiple LoRa sensor devices are used to send information to the Gateway, then it becomes difficult to determine which sensor sent the information (I discuss this further in the Gateway section). The Unique ID library is used as a substitute for a LoRa address which I refer to as a "node-id".
Arduino JSON Library - The mailbox sensor sends a JSON message to the Gateway that contains the "node-id" ("unique-id") of the sensor, the state of the sensor (which will only indicate "active" or "on") and the battery voltage level that is measured prior to sending the message. This library is used to formulate the data into JSON structures.
Arduino Low Power Library - This library is used to put the Arduino into a low power state. It is not necessary, but I used it when testing out the magnetic reed switch instead of a motion sensor as discussed above. I decided to keep the library in the code in the event that the motion sensor stays active for a long period of time, in which case the continued motion would keep the CPU powered up, and after a while, the library would be called to put the CPU into a lower power mode.
The Sketch code performs the following:
Immediately sets DPIN high to keep the regulator "enabled", and thus keeps the power going on the Pro Mini and LoRa module.
Generates the "unique id"/"node id".
Initializes the LoRa Module and initializes various data structures.
Goes into a simple loop with a loop counter and each loop cycle is delayed by 500ms plus another 20ms. For each of the first two loops, it formulates a JSON message and sends it to the Gateway, thus sending the message twice for reliability reasons. The message contains:
The node-id
The state of the sensor (which is always set to "ON")
The battery voltage level.
The Message is JSON formatted data that looks like the following (where 12345678 is the node-id):
After the two loops, the Pro Mini sets the DPIN low, which will attempt to disable the power regulator and shutdown the Pro Mini. If the Motion Detector is still indicating activity, the Pro Mini will remain powered on and will go through more loops. After around 1000 loops, it will activate low power mode for the LoRa module, and low power mode for itself. There are several different subsystems inside the Pro Mini that can be shutdown to save a little more power, and in this case they include disabling the ADC, and a Brown-out detector. You can find out more from this article by Rocketscream.
LoRa Gateway
The LoRa Gateway used in the project is from the open source Open MQTT Gateway (OMG) project. The OMG project, at a high level, is used as a gateway between a variety of of sensor types and a controller. The controller in this case being Home Assistant. OMG uses MQTT as the messaging transport between itself and the controller. OMG supports LoRa, and officially supports a few LoRa specific boards that can be used as the Gateway. I chose the LILYGO TTGO v1 board which comes with a LoRa module and uses an ESP32 with Wi-Fi. It also comes with an OLED display. I created a printed 3D housing for it that can be wall-mounted:
To follow-up from our earlier discussion on antenna orientation, I mounted the Gateway with the antenna oriented vertically. Although the mailbox sensor antenna was mounted horizontally when it should have been mounted vertically, there is still plenty of signal strength at the gateway to process the messages correctly.
I won't go into details for setting up OMG, but I did development and code building using Visual Studio Code and the PlatformIO plugins for it as PlatformIO is the primary way of building OMG. A section near the end of this blog provides a summary of code changes I made.
LoRa Gateway with Home Assistant
The OMG provides specific support for Home Assistant by using HA's MQTT discovery. This allows HA to learn of the OMG as a device, along with some of its entities. These MQTT messages are "retained" by the MQTT broker, so when Home Assistant starts up, it will get these messages from the broker without having to wait for the OMG to resend them. One of these entities that OMG has Home Assistant learn about is the LoRa sensor entity, named "gatewayLORA". The following shows what the OMG "Device" page would look like in Home Assistant including the "gatewayLORA" entity:
The OMG's approach to LoRa, is that any LoRa message the Gateway receives from any LoRa sensor device, will be sent (after tacking on some additional information like SNR, etc.) to Home Assistant and the LoRa "message" will become the state of the Home Assistant "gatewayLORA" sensor entity. The MQTT topic and message respectively that are sent from the OMG to Home Assistant (via the MQTT Broker) may look something like:
In this example, the "gatewayLORA" Home Assistant sensor entity would take on the state "Hello". In another example from the figure above, Home Assistant had already received a message of "0xA383" and this became the "gatewayLORA" sensor's state.
If you have only one LoRa sensor that you use, and you only need state information, then this approach works fine. But what if you have more than one sensor, or perhaps there is more information being conveyed such as temperature, humidity, etc.? For example, I'm considering taking the design of the mailbox sensor and say use it as a general purpose low power motion detector. I would have a few of them around, all reporting the same information. I'm also planning on deploying a few of these Makerfab's LoRa soil moisture and temperature sensor too.
To help better scale this, I decided to have each of my LoRa sensor's send some type of node-id along with data that was purposed for that sensor type. The Gateway will relay this information on to Home Assistant, and Home Assistant can then identify the sensor by its node-id. The message will also carry state information and other attributes of the sensor. As discussed in the section of the Pro Mini, the mailbox sensor will send this data to the Gateway in JSON format, and the Gateway will in turn send it encapsulated in JSON in the "message" field to Home Assistant. So instead of getting a simple textual "Hello" in the "message" field of the JSON payload, Home Assistant will see JSON formatted data in the "message" field (JSON encapsulated in JSON). As we'll see later, Home Assistant can handle this using the "from_json" template filter.
These members of the Home Assistant Community are also using this approach for their LoRa based Makerfab LoRa soil moisture and temperature sensor. That is to say, they have coded the Makerfab sensors to send data using a node-id and JSON formatted data.
Using this approach, on the Home Assistant side one would configure all the various LoRa based sensor entities as MQTT sensors. These MQTT sensors would receive the same MQTT message from the OMG and then use templating capabilities to filter in which message applies to them based on the node-id. This approach works perfectly fine.
However, I ran into a minor annoyance. My Gateway receives data from some other unknown LoRa sensor. The town I live in uses LoRaWAN sensors throughout the town to monitor flooding during storm surges, so I suspect that there is one of these sensors nearby that I am getting data from. The Gateway doesn't know any difference so it forwards messages from these sensors on to Home Assistant for the "gatewayLORA" sensor entity to consume. These messages are binary, and if Home Assistant gets one and tries to decode its JSON content to get at the node-id, it can't decode these binary messages, so it throws a log error.
To solve this, I decided to take advantage of a capability in OMG called "ValueAsATopic".
"ValueAsATopic" is a configurable item in OMG that, when enabled, allows some "value" in the payload received from a sensor to be tacked onto the end of the MQTT topic as a subtopic. This "ValueAsATopic" however does not exist in OMG for LoRa based sensors, so I made modifications to OMG that would allow it to parse the node-id from the message and tack it onto the MQTT topic. For example, if the node-id is 12345678, the MQTT topic will now look something like:
The drawback is that the LoRa messaging carrying the node-id of course is non-standard so it makes the modified OMG code also non-standard. But this is what I went with.
Next, I removed the "gatewayLORA" sensor from Home Assistant because its MQTT topic was the one that the unknown sensor messages was being sent over. I could have removed this from the OMG code, and in the future I might make these changes, but one can remove entities that are auto-discovered using MQTT. To do this, one publishes an MQTT message that uses the same topic that was used in discovery but is sent with an empty payload. I made a simple automation to do this that runs at startup and this is shown later on.
While I was "under the hood" making changes to the OMG code, I also added code to make use of the LILYGO TTGO v1 OLED display. When the OMG first boots up, it will display a simple message saying the LORA GW is Ready, and later on will print out the LoRa message it received from a LoRa Sensor.
Home Assistant Configurations and Presentations
I'll first mention that there are many different implementation options in Home Assistant for achieving what is covered in this section, but here is the implementation that I went with:
Binary Sensor (MQTT) "Mailbox Sensor"
This represents THE mailbox sensor. The state of this sensor follows the mailbox sensor's state based on its LoRa message. Since the LoRa mailbox sensor only reports an "on" state and doesn't report an "off" state, this binary sensor will update when it sees the LoRa message set to "on" but it is configured to expire after 20 seconds which will put it back in the "off" state. This binary sensor will also have the battery level as an attribute, and automations are used to check whether the battery level has become too low and sends a notification if it has.
I didn't configure this sensor using YAML. Instead, this sensor is created by sending a "faux" MQTT auto-discovery MQTT message to Home Assistant. This particular discovery message also contains the same "device" data as the OMG. This allows this binary sensor to be associated with the OMG device in the Home Assistant device page. In my Home Assistant setup, I publish this MQTT message at startup. The MQTT publishing looks like the following:
Note: After an HA restart, this sensor will be in an "unknown" state until the LoRa mailbox sensor actually sends a message.
Note: the "device" data in the MQTT message comes from OMG's discovery messages, and you can go to the OMG device page in Home Assistant and click on "MQTT" to see this data.
Input Boolean "You have Mail"
This tracks whether there is mail in the mailbox (true) or whether it has been retrieved (false). When the binary "Mailbox Sensor" above is set to true (that is when the mailbox door is opened), an automation is fired which sets this Input Boolean to true. As we'll see below, it will only be set to false when a notification is "dismissed" indicating someone has retrieved the mail. When someone goes to retrieve the mail, the mailbox door will open and the binary "Mailbox Sensor" will fire again, but if the Input Boolean is already true, no further action will take place.
Binary Sensor (Template) "Mail in Mailbox"
A Template Sensor is used to follow the state of the Input Boolean. The main purpose of using this template sensor is that a template sensor also allows the icon to be changed based on state and this state can be presented using a "badge" in Home Assistant.
Here are the icons my badges present when this Binary Sensor is false and when it is true respectively:
Notifications: Persistent and Alexa
When the Binary "Mailbox Sensor" above is set to true (when the mailbox door is opened and detected by Home Assistant), an automation is fired which checks whether the "Mail in Mailbox" Input Boolean is false (which indicates there is no mail), and if false, the automation posts a Home Assistant Persistent Notification on its web page notifying the user that there is mail available. The notification also contains a "Notification ID" which we'll make use of later. It also sends a TTS to Alexa saying "You have mail".
Here is what the notification looks like:
After the mail has been retrieved, it is intended that the user dismisses this notification by tapping the "DISMISS" button. This will trigger another automation that is used to detect that this particular notification (with a matching "Notification ID") has been dismissed, and the action sets the Input Boolean sensor to false.
Automation "Mailbox Opened"
Automation "Mail Persistent Notification Dismissed"
Automation to Remove "gatewayLORA" sensor (runs at startup):
Note: the topic in this MQTT message comes from OMG's discovery messages, and you can go to the OMG device page in Home Assistant and click on "MQTT" to see this topic.
Summary of OMG Changes
The changes I made to the OpenMQTTGateway code are based off of version 1.0.0. The summary of changes are:
User_config.h Note: these changes are not actually on my Github, you'll need to change these yourself
default_envs = ttgo-lora32-v1-915 or -868 One should uncomment one of these lines.
Added SSD1306 library to ttgo-lora32-v1-915 and -868 build data
ZGateLORA.ino - Added OLED display code
main.ino - Added ValuesAsATopic code for LoRa
config_LORA.h - No changes were actually made. The settings should work as is.
I have mirrored the v1.0.0 OpenMQTT Gateway repository along with my changes to my Github which is located here. Note: I have not actually tested cloning this and trying to build from it, so if you have any problems, just take the changes from the modified files discussed above.
Credits
"Priceless Took Kit" developed the schematics and PCB used in this project, and provided the base Arduino code for the sensor that I used to get started.
References:
3D Printed Part for Lilygo TTGO
The 3D part originated from Neodyme, but I heavily modified it so that the top side could more easily fit into the casing, and I changed the antenna orientation too.
Trademarks
LoRa, and LoRaWAN are registered trademarks or service marks of Semtech Corporation or its affiliates.
Wi-Fi is a trademark of the Wi-Fi Alliance.
ZIGBEE is a trademark of CONNECTIVITY STANDARDS ALLIANCE
Z WAVE is a trademark of Z-WAVE ALLIANCE INC.