This is a project intended to provide a ESP32 demo.
The code is developed and tested so far with the ESP32 devkit. The board can be powered via the USB connection which can be used for the UART and therefore the console.
Functionality implemented so far:
- If the device has not been connected before
- Scan the network for available access points
- Bring up a HTML server which allows to select a network and provide a password, if necessary
- If the device was connected before retrieve the previous connection data from NVS
- Connect to the selected network
- If not successful, start again in 1.i
- Store the connection information in NVS
- Look for mDNS service
_mqtt._tcpand try to connect to server at the specified port - Periodically send an update to the topic /BOARDNAME/heartbeat which is a JSON string
- Listen to the topic /BOARDNAME/command. The expected data is a JSON string with a command key-value pair
- Establish external SD card filesystem
- Optional: Establish internal flash filesystem (Note: this is code memory intensive so usually left out)
- Optional: Establish ultrasonic sensor with associated MQTT commands
- Optional: Establish OLED RGB display of ssid/pw when in initial AP mode and heartbeat info when connected to MQTT
- Optional: Establish environmental sensor with associated MQTT commands
- Optional: Connect a coprocessor with a UART which can be programmed to send a JSON report
BOARDNAME has the form ESP32-XXXXXXXXXXXX where XXXXXXXXXXXX is the hexadecimal representation of the MAC
address of the board.
So far the original Espressif toolchain is used and tested.
A WiFi network is needed. Only WPA2 networks have been tested so far.
On the network a mDNS service _mqtt._tcp has to be announced. On Fedora systems use
avahi-publish -s HOSTNAME _mqtt._tcp 1883
where HOSTNAME is the name of the machine with the MQTT server. Adjust the port number,
if necessary. This could be done permanently (see below).
On the specified host, run a MQTT broker. On Fedora systems install the mosquitto package and then just
/usr/sbin/mosquitto
Make sure the firewall allows outside connections to the MQTT (1883) port.
To monitor the topic run on the same or a different machine mosquitto_sub:
mosquitto_sub -h HOSTNAME -t '/environment'
Replace HOSTNAME with the name of the machine running the MQTT broker.
When using Firefox to connect to the device to select a WiFi network it is necessary (as of version 83) to enable an option. In the browser, open a tab and use the URL
about:config
Then in the search box type dialog. This will show a number of entry, among them one
named
dom.dialog_element.enabled
This variable needs to be set to true. If this is not already the case double-click
on the false in this row to change the value.
Instead of starting mosquitto directly and separately announcing the service one can install the
mosquitto.service file as /etc/avahi/services/mosquitto.service. With this avahi takes care of
announcing the service.
The mosquitto broker can also be started as a service:
# systemctl start mosquitto
To enable the availability across the next reboot the service can be enabled:
# systemctl enable mosquitto
The toolchain and basic runtime (RTOS and some drivers) come from the ESP-IDF which can be installed from its github repository:
$ cd "$DEVELHOME"
$ git clone --recursive https://github.com/espressif/esp-idf.git
$ cd esp-idf
$ ./install.sh <TARGET>
The DEVELHOME environment variable is used here just for visualization.
If support for more than the base version if ESP32 is wanted replace the last line with
$ ./install.sh esp32,esp32s2,esp32s3,esp32c3
or a reduced version.
Before every development session (and the subsequent steps) the environment of the shell session needs to be initialized for the IDF.
$ . "$DEVELHOME/esp-idf/export.sh"
In addition to the toolchain, the ESP driver library has to be available. It is expected to be available in the same directory as the ESP IDF source tree.
$ cd "$DEVELHOME"
$ git clone [email protected]:UncleRus/esp-idf-lib.git
The SDK needs configuration as well. The board settings need to match the available hardware.
The board is connected through USB. The device for the communication needs to be specified. It is
usually something like /dev/ttyUSB1 or so.
To support secure HTTPS connections when accessing the device as an access
point a CA certification and key needs to be created. This is not done
automatically to allow choosing the files. With the gen-ca.sh script the
ca directory can be filled with the appropriate files.
When building the project for the first time or after cleaning up everything the configuration needs to be created.
$ idf.py menuconfig
The appropriate configurations can be selected. There is also a toplevel menu ESP32 Connect which allows
to specify the system-specific options. So far this project allows to specify the number of MAX7219 chips
which are daisy-chained.
Running this command also creates the build subdirectory which is where the project should be built.
$ idf.py build
$ idf.py flash monitor
This will build the binary, flash it to the device, and then start the serial console.
To access services on the local network or the wider Internet the decice needs to get access to the local WiFi network. To safely enable the connection the SSID and password of the WiFi network are not stored in the source code or somehow else added to the binary.
Instead, if the program on the ESP32 cannot connect to a WiFi network (either because it has never done that or because a previously used network is not available anymore) it will create a WiFi access point (AP).
The SSID of the AP is ESP32-XXXXXXXXXXXX where XXXXXXXXXXXX is the MAC address
of the boards. The password is randomly generated. The details are shown on
a display (and in debug mode, on the serial console).
Connect to the IP address 192.168.4.1, which is the ESP32 board access point, with
HTTPS. Please keep in mind the note about the use of Firefox above.
The page that is displayed allows to select the WiFi network to use during
operation. Selecting it will bring up a dialog to enter the password.
After successfully filling in the information the access point will stop and the ESP32 device will try to connect to the selected WiFi network. if successful it will connect to the advertizes MQTT service.
If the WiFi connection fails the AP will be brought up again and the information can be entered anew.
- Digilent PMOD OLEDRGB
- Bosch Sensortech BME280
- Ultrasonic Sensor (e.g. HCSR04)
- SD card over SPI
Running idf.py menuconfig from within the project's base directory brings up an interface for project configuration options. In the ESP Demo options menu there are submenus for the peripherals listed above. GPIOs need to be assigned based on how your ESP32C3 board is wired up to your peripherals.
Once a connection to the MQTT broker is established, commands can be sent over the topic /BOARDNAME/command.
Responses are currently limited to the idf.py monitor output, however, these will be moved to MQTT once
the IoT application is fleshed out.
The following commands are accepted, depending on project configuration options:
- {"command":"GetVersion"}
- {"command":"GetFileFromURL","url":""}
- {"command":"ListSDCardFiles"}
- {"command":"ListInternalFiles"}
- {"command":"RemoveFile","filename":""}
- {"command":"DisplayClear"}
- {"command":"DisplayString","value":"","x":,"y":}
- {"command":"GetUltrasonicDistance"}
- {"command":"GetBME280Data"}
- {"command":"ReqReport"}