-
Notifications
You must be signed in to change notification settings - Fork 1
Getting Started
Follow this sequence:
- Assemble transmitter and receiver modules
- Prepare setup to program ESP-01 and HC-12
- Install dependencies
- Program two HC-12 modules with "rfconf" sketch
- Program ESP-01S (remote module) with "nowifi" sketch
- Program ESP-01S (remote module) with "mailbox" sketch
- Upload icon file to ESP-01 (local module)
- Program ESP-01 (local module) with "mailbox" sketch
- Setup Telegram bot (optional)
- Setup Google Assistant relay (optional)
- Power up and register the mailbox
Programs expect the corresponding hardware to run; so be sure to assemble local and remote module circuits, either on a breadboard, or on PCB. See Schematics for details.
ESP-01 and HC-12 need dedicated circuits for programming, different from the circuits where the program will execute. Again, see Schematics for sample connections using Arduino Uno.
The mailbox sketch is a pretty complex program, so several dependencies are needed:
| Library | Last Version Tested | Remark |
|---|---|---|
| Arduino IDE | 1.8.13 | |
| ESP8266 Core for Arduino | 3.0.2 | Install via Arduino Boards Manager |
| ESP8266 LittleFS plugin | 2.6.0 | Only if you need a web site icon |
| ESP-DS-System | 1.1.3 | Included with the sketch; no need to install separately |
| WiFiManager | 0.16.0 | Install via Arduino Library Manager |
| JLED | 4.7.0 | Install via Arduino Library Manager |
| AceButton | 1.9.1 | Install via Arduino Library Manager |
| Uptime-Library | 1.0.0 | Install via Arduino Library Manager |
| ArduinoJson | 6.18.3 | Only if you need Telegram interface. Install via Arduino Library Manager |
| UniversalTelegramBot | 1.3.0 | Only if you need Telegram interface. Install via Arduino Library Manager |
| Assistant Relay | 3.2.0 | Only if you need Google Home interface. This is not Arduino software but a NodeJS package to be installed on Linux or Windows host next to the Google Home |
The rfconf sketch is made for Arduino Uno, so you need to select this board in Arduino IDE. If you are not using Arduino Uno, it could be equally run from some ESP8266 development board, like NodeMCU, but you will need to adapt wiring and PIN_HC12_TX, PIN_HC12_RX settings in the sketch.
Note that serial console speed for diagnostic output of this sketch is 9600 bod, not 115200. Somehow, when I set it to 115200, it does not seem to work.
The sketch sends several commands to HC-12, but only two of them are important:
| Command | Meaning |
|---|---|
AT+FU4 |
Set ultra long distance communication mode |
AT+C007 |
Set communication channel #7 (435.8 MHz) |
If you want to change these defaults for whatever reason, I recommend you going through the HC-12 user manual for the options available (look for the latest 2.4 version). Changing communication mode from FU4 to something else will likely require changing various delays hardcoded into mailbox's Transmitter.cpp file, as well as adaptations in RF_* macros in Transceiver.h. Changing communication channel from #7 to something else will need adaptations in antennas (see Antennas for more details). The configuration must be identical for both HC-12 modules, otherwise they will not be able to communicate.
Program output should resemble to this:
+ Started. ++ Entering configuration mode... ++ Pinging... AT OK ++ Requesting module ID... AT+V www.hc01.com HC-12_V2.4 ++ Resetting to factory settings... AT+DEFAULT OK+DEFAULT ++ Factory settings: AT+RX OK+B9600 OK+RC001 OK+RP:+20dBm OK+FU3 ++ Setting transmission mode... AT+FU4 OK+FU4,B1200 ++ Setting communication channel... AT+C007 OK+C007 ++ Finished. Configured settings: AT+RX OK+B1200 OK+RC007 OK+RP:+20dBm OK+FU4
If you do not see the commands sent, check your serial console settings. If you see the commands sent but not the OK+... replies, check your wiring and power on sequence, as specified in Schematics.
The nowifi sketch is optional. This one-line program will turn the Wi-Fi circuit on remote module off, because it is of no use there. Turning it off helps reducing battery power consumption of the remote module during cold start. Cold start is a rare event, happening in situations like when replacing a battery. On warm start (normal mode) the remote module wakes up with the RF module already turned off, so the Wi-Fi settings do not matter. The setting is persistent, so this sketch needs to be loaded only once before uploading the actual remote module program. If, for whatever reason, you overwrite the entire flash of ESP-01S, you will need to reload this sketch again.
The reason this one-liner is made as a separate sketch is to avoid linking into remote module program the entire Wi-Fi support stack for the sole reason of turning it off on start.
To activate compilation of remote module code, go to MySystem.h and uncomment the DS_MAILBOX_REMOTE macro. Normally, no other changes are needed. If you want to change the mailbox ID from the default #1, go to remote.ino.h and update the MAILBOX_ID macro. If you want the remote module to report to the receiver other than default #1, go to Transceiver.h and update the RECEIVER_ID macro.
Once this is done, set the following settings in Arduino IDE, then compile and flash the program:
| Setting | Value |
|---|---|
| Board | Generic ESP8266 Module |
| Flash Size | 1MB (FS:none) |
| Flash Mode | QIO (fast) (if your board supports it; otherwise stick to DOUT) |
This is only needed if you plan to use web interface and would like to have a "favicon" for the web site. Favicons make navigation nicer when switching tabs, making bookmarks, etc. Not loading any icon will not affect any other functionality of the program.
"mailbox" sketch contains a data folder with a default favicon in it. You can change the icon, but it must be called favicon.png and contain a PNG image of 192x192 px (multi-resolution icons are OK).
To upload the icon to ESP, see the instructions on LittleFS Uploader page. Note that this operation actually assembles the file system image from scratch, so any data stored on the existing file system will be lost.
To activate compilation of local module code, go to MySystem.h and comment out the DS_MAILBOX_REMOTE macro. If you would like to run emulator of remote module instead of real communication, uncomment DS_DEVBOARD macro. Telegram and Google Assistant interfaces are turned off by default; to enable them, set macros DS_SUPPORT_TELEGRAM and DS_SUPPORT_GOOGLE_ASSISTANT. You might also want to update the time zone from default UTC to your time zone by setting DS_TIMEZONE macro. Refer to the list of available zones in the file TZ.h in ESP8266 Arduino Core.
If you want the local module to identify itself as the receiver other than default #1, go to Transceiver.h and change the RECEIVER_ID macro.
Local module will present itself in the network via mDNS as Mailbox.local. If you would like a different host name, set it in local.ino.h.
If you activated Telegram support, go to Telegram.cpp and provide bot token and chat ID. When working with emulator, it is recommended to open private chat with the bot in order to spare the main chat from test traffic. If you plan to use emulator, you can provide this private chat ID too.
If you activated Google Assistant support, go to GoogleAssistant.cpp and provide URL of where Assistant Relay is deployed. If you use default settings of the Relay, only the IP address needs to be changed.
Once this is done, set the following settings in Arduino IDE, then compile and flash the program:
| Setting | Value (Production) | Value (Emulator) |
|---|---|---|
| Board | Generic ESP8266 Module | Generic ESP8266 Module |
| Flash Size | 1MB (FS:256kB) | 1MB (FS:256kB) |
| Flash Mode | DOUT (compatible) | DOUT (compatible) |
| Builtin LED | 1 | 2 |
| Upload Speed | 115200 | 460800 |
See dedicated section.
See dedicated section.
The first thing to do is to power up the freshly baked local module and connect it to your Wi-Fi network. The module is equipped with Wi-Fi manager, which can be activated with a button long press (at least 5 seconds). This will bring online a new Wi-Fi network with SSID Mailbox and password 42Mailbo (if you changed the host name in the previous step, the SSID and password will change too). Connect to this network, go to the captive portal (or any site if the portal does not pop up automatically). Follow the portal instructions to connect to your network. Once this is done, reconnect yourself to your network and go to the local module web interface http://mailbox.local.
Note: mDNS does not work on Android, so if you are connecting from Android, you need to use the IP address of the module instead of its symbolic name. The easiest way to learn the IP address is to follow-up the module boot via its diagnostic serial line. You can also check for new devices popped in your Wi-Fi access point interface, if you have access to it.
Mailbox registration happens automatically as soon as the remote module (transmitter) sends any message. Power up the remote module. It should send a message about its boot; you should be able to see the new mailbox after refreshing the web page. If, for some reason, this did not happen, try to open and close mailbox door; this will send more messages.
Mailbox label is not hardcoded in the program; you can set it via web interface by clicking on mailbox ID in the list.