Home Assistant Integration

A project log for Mailbox Sensor

I'm tired of walking the whole way to my mailbox to see if there is mail in it, so technology comes to the rescue

Kevin KesslerKevin Kessler 09/23/2020 at 01:530 Comments

Home Assistant is an open source, cloud free,  home automation hub ( ). It is often hosted on a Raspberry Pi, as in my case, and integrates with many commercial IOT products. This mailbox  system uses the MQTT integration to get data into Home Assistant.

The sensor in the mailbox sends raw data from the proximity sensor, the battery voltage, and the uController temperature, to the Mailbox Base Station. Since the base station is OTA flash-able, and so easy to modify, all of decisions about the data are made there. If the 16 bit value returned by the VCNL4200 is greater than 128, the base station assumes there is mail in the box, and lifts the flag. 

The base station connects to the Home Assistant MQTT Server, and transmits the collected in Home Assistant's discover format. On power up, the base station sends a series of JSON messages which describes the data that will be sent.  Home Assistant looks to receive this configuration information on the homeassistant/sensor/variable_name/config topic. On initialization, the base station sends the following messages to initialize the mail_temperature, mail_proximity, mail_status, mail_battery, and mail_lifecycle variables:

Topic: homeassistant/sensor/mail_temperature/config
Message: {"device_class":"temperature","name": "Mail_Temperature","state_topic": "homeassistant/sensor/mail/state", "unit_of_measurement": "°C", "value_template": "{{ value_json.temperature}}" }

Topic: homeassistant/sensor/mail_proximity/config 
Message: {"name": "Mail_Proximity","state_topic": "homeassistant/sensor/mail/state", "unit_of_measurement": "Count", "value_template": "{{ value_json.mailproximity}}" }

Topic: homeassistant/sensor/mail_status/config
Message: {"name": "Mail_Status","state_topic": "homeassistant/sensor/mail/state", "value_template": "{{ value_json.status}}" }

Topic: homeassistant/sensor/mail_battery/config
Message: {"name": "Mail_Battery","state_topic": "homeassistant/sensor/mail/state", "unit_of_measurement": "V", "value_template": "{{ value_json.battery}}" }

Message: {"name": "Mail_Lifecycle","state_topic": "homeassistant/sensor/mail/state", "unit_of_measurement": "", "value_template": "{{ value_json.lifecycle}}" } 

The mail_proximity variable is the raw return value from the VCNL4200,  the mail_battery is the current battery voltage, mail_temperature is the internal temperature of the uC (just because it was available), mail_status is a string stating whether mail is present, absent, or the mailbox door is open, and mail_lifecycle is a string representing why the base station sent the message (either heartbeat or and update from the mailbox sensors). The base station sends a heartbeat message on MQTT every 5 minutes to verify it is still alive. 

The data messages look like:

Topic: homeassistant/sensor/mail/state 
Message: {"lifecycle":"UPDATE", "mailproximity":28, "status":"NONE","battery":4.05,"temperature":9.5}

 Home Assistant collects this data which can be displayed on its various graphing widgets. I have also configured it to send 3 alerts. It sends an SMS to my phone when status is set to "MAIL" which means mail is in the box, when the battery level is below 3.0 V, and when the mailbox is opened for more than 2 minutes (status "OPEN"). The last alert is somewhat important for battery life, because the current draw is about 1mA when the door is open compared to about 20uA when closed.