Operation
Remote (mailbox) module stays in deep sleep mode most of the time; it wakes up when the door opens and goes back to sleep as soon as the door is closed. Each door opening is considered as an "event"; on each event two messages are sent — one on door opening and one on door closure. Sending two messages allows tracking of for how long the door has been opened, and also improves reliability in the case one of the messages gets lost.
To avoid draining battery if the door stays open for a long time, the module goes to sleep 30 seconds after the door has been opened. 30 seconds is largely enough to put in or take out a parcel, so in practice this limit is rarely reached. In this case the user will be notified on timeout, and the door closure will not be separately reported.
Local module maintains a state machine for each mailbox. A mailbox in any given moment can be in one of the following states:
Any state other than No Event is considered as an "alarm" and signaled to a user. In absence of specific off-normal events mailbox follows the path No Event → Door Open → Door Flipped → No Event. If the door has not been closed in reasonable time, mailbox will stay in Door Left Open state instead of Door Flipped.
As for the off-normal events, remote module reboot is marked with a dedicated Booted state. There is also a periodic (hourly) check of mailbox health condition, which can put it in Low Battery state in the case the battery level drops below 20%, or Absent state in the case the mailbox has not sent any message in the last three days. Three days interval is selected as a reasonable compromise for mailbox owner checking mailbox once a day, except weekends. Thresholds for these alarms can be changed by editing constants in the code. Note that periodic check does not involve communication with remote module, since the communication is unidirectional; instead, it just evaluates the latest mailbox information cached in the local module.
There is no automatic reset of an alarm; the user has to acknowledge the alarm in order to return to the No Event state ("rearm" the mailbox). Normally, the acknowledgement should coincide with some action taken (e.g., mailbox emptied). If the alarm was acknowledged with no action behind, it may be reinstated, e.g., by a periodic check. It is not required to acknowledge alarm every time — the program will happily notify you of the next event irrespective of whether the alarm has been acknowledged or not. Explicit acknowledgment is useful when there are several people notified and could check mailbox — in this case, other people will know who took care of checking the mailbox without extra communication overhead.
Each state is assigned an alarm priority level, with No Event being the lowest and Door Open being the highest. In a regular situation these priorities do not matter, as mailbox can be in a single alarm state at a time. However, they are taken into account when a second event arrives while the previous one has not been processed by the user. E.g., if a mailbox was in Low Battery state, opening it will move it to a higher priority state Door Open. On the contrary, if a mailbox is latched to Door Flipped alarm, it will not go into Low Battery state by itself. There is an exception to priorities though, concerning the Absent state. If a mailbox has not reported back for three days, its standing alarms are considered stale, and it will be force moved from any state into Absent state. These transitions are not shown on the diagram.
Alarm priority also plays a role when calculating a synthetic alarm state across multiple mailboxes. An alarm with the highest rank is picked up as a group alarm.
There are several levels of notifications about a mailbox event:
LED notification on the local module side is the most reliable one, as it does not require any network to function. A built-in ESP-01 blue LED is used for a purpose: it is very bright and well visible, but requires a transparent module case, and that the module itself is placed in sight. This is not always possible due to receiver antenna configuration.
Signalling is done according to alarm severity, as follows:
| No Event | Light off |
| Booted | Steady dim light (lowest brightness) |
| Low Battery | |
| Absent | |
| Door Flipped | Steady bright light |
| Door Left Open | "Breathing" light |
| Door Open | Blinking |
LED is also used for some service tasks. It is glowing when initial Wi-Fi connection is being established, and is steadily lit when Wi-Fi manager is active.
Smooth blinking and breathing require that the main controller loop runs uninterrupted. When Telegram polling happens (every 10 seconds), you can observe LED freezing for a moment. This is a minor issue difficult to avoid because ESP8266 has no threading support.
This is not a true notification per se, but a local web site http://mailbox.local is updated with mailbox status, so if you refresh the web page, you will see the event. There are ways to make true notifications out of this, either but adding more code on the web page, or by making browser-side polling, but this was not pursued. Web site access requires that Wi-Fi connection is functional in the house, and both the local mailbox module and user are connected to it.
See web interface section below for more details on web site updates.
For each event two Telegram messages are sent into designated chat, indicating opening and closure events. Off-normal events, like lost messages, or reboots, are equally signaled. Telegram notifications, naturally, require that Wi-Fi access in the house functions, and provides working Internet access.
See dedicated Telegram page for more information on Telegram notifications.
Each mailbox event is announced on Google Home. This is done via broadcasting, so if you have got several Google speakers in the house, all of them will speak — but not necessarily synchronously. The announcement will be in the form "Incoming broadcast: mailbox one opened". If you have defined a mailbox label, Google will try to pronounce it as well, so do not make too complex labels. Only one announcement per event is made; door opening or closure are not reported separately. Off-normal events, such as reboots, are equally not announced. Like in Telegram case, for these notifications to work, you'll need to have a functioning Wi-Fi in the house with working Internet access, even though broadcast is made from a local source to a local speaker.
See dedicated Google Home page page for more information on Google Home notifications.
Local module provides a web interface which allows quickly checking what's up, and to do some service tasks. It is available via address http://mailbox.local. The site is only available in the internal Wi-Fi network. If you want to make it visible from anywhere, this is outside of scope of this project; there are many tutorials in the Internet explaining how to do this.
The web site provides several pages, explained below.
The front page shows the summary alarm state with a large icon, and provides a button to acknowledge (reset) it. It also shows a table of all mailboxes connected and allows for individual acknowledgement of events. For each mailbox the following information is displayed:
| Name | Description | Persistent |
|---|---|---|
| ID | Mailbox ID (hardcoded on remote module side) | Yes |
| Label | Mailbox label (empty by default, configurable, see below) | Yes |
| Status | Mailbox current state, as explained in mailbox states | No |
| Battery | Remote module battery level | Yes |
| Radio Reliability | Radio link quality | No |
| Last Contact | Time the mailbox was last seen (i.e., sent a message) | Yes |
| Uptime | Time since last boot | Yes |
Remote module enumerates all messages, allowing local module to recognize holes in communication. The quality of a radio link is then calculated as:
Radio Reliability = 100% * <number of received messages> / <number of sent messages>
If your antenna setup is good, this number should be close to 100%.
Properties marked as persistent are saved on ESP-01 flash, so they survive restarts or power-offs of local module. Non-persistent settings are initialized as soon as remote module sends some info.
This page only becomes available once mailbox have sent at least one message, and is known to local module. To open it, click on mailbox ID in the front page table. There are not many things to configure online — you can just set a mailbox label.
This page also lets you "forget" (unregister) mailbox. This is useful if you know that a given remote module is gone for good. There is no much point in trying to unregister an active mailbox — it will register itself back on the next event.
This page will let you browsing an event log recording all events, messages received and acknowledgements issued. The number in brackets is the message number assigned by transmitter. In a regular situation this number grows monotonically, but it may have gaps if the radio link is weak, or even restart if transmitter experiences a cold boot.
The log is stored on ESP-01 flash, so it survives reboots. There is a log rotation mechanism in place which trims the log as needed.
This page is courtesy of an external library ESP-DS-System; mailbox application just sends records to the log. See the library documentation if you want to adjust log parameters.
This page will show you various system-level parameters. It is not mailbox application-specific.
Similarly, this page comes for free with the ESP-DS-System library.