Installing HydraFerret on ESP32 IOT Module

Enfield Cat's Blog: Arduino and other projects.

Introduction

By downloading from this site you accept the conditions of use.

There are two ways of installing HydraFerret on ESP32 modules: flashing a precompiled binary and using the Arduino IDE to compile and flash the image.

Note: the flashed ESP32 module should use serial bus 0 (normally the USB connection) at 115200 baud, 8 bits, no parity and 1 stop bit to connect to a serial terminal such as that of the Arduino IDE, Putty or Teraterm Pro. Disconnect your serial console when flashing the ESP32 module.

Version numbers should be in the format 2-digit-year followed by 2-digit-month. Example: "HydraFerret_2104" indicates a release date 2021 and 4th month (April). "rc" suffix in name indicates release candidate. This can assist in assessing how aged any installation is when maintaing software versions.

Precompiled binaries

Using a precompiled binary is probably this simplest way of installing a HydraFerret unit. It is a two step process of obtaining the binary from a link below and then using the tool described below to burn the code to an esp32 module. Once done the unit can be configured to communicate with attached sensors. Precompiled versions do not include BlueTooth support as this adds considerably to the size of the binary.

Available downloads:

date	binary	comment
Apr-2021	HydraFerret_2104.zip	April 2021 release
May-2021	HydraFerret_2110rc1.zip	21/10 release candidate 1 Timing bug fix: Only run timers which are required. Add support for switch sensor Address wifimode ondemand memory leak Use highest alert level for page if there are multiple devices of same type but different warning levels Adjust help command to support a summary parameter
Oct-2021	HydraFerret_2110rc1.zip	21/10 release candidate 2 Added "rescan" command for I2C devices Added onboard esp32 based WiFi Access point support Added mDNS support, devices should accessable as "<device-name>.local" Added pfc8583 support as either high speed counter (up to 1MHz) or for ultra-sonic distance measurement Added "transform" function/variable to most devices for arbitrary rpn calculation
Oct-2021	HydraFerret_2110rc1.zip	21/10 release

Flashing a precompiled binary

This is supplied in a zip file containing multiple files. There are 4 segments which need to be installed, and the file naming convention indicates where each segment should be loaded. However, multiple bootloader images are provided. These bootloader images support different memory access models and memory speeds. Unfortunately this means either you'll need to know a little about the hardware your ESP32 system is configured with or beprepared to experiment a little. A good option to start with if you are unsure is 0x1000_bootloader_dio_40m.bin. There are either 2 speeds of memory I/O supported 40 or 80 MHz. There are 4 types of memory access supported, as follows:

The "d" boot loaders use a "double" I/O to access 2 bits of memory per memory cycle.
The "q" boot loaders use a "quad" I/O to access 4 bits of memory per memory cycle.
The "io" boot loaders use the selected "d" or "q" I/O access both in addressing and accessing of data.
The "out" boot loaders use the selected "d" or "q" I/O access data but not to address it, consequently this results is slightly slower access.

Flashing the wrong boot image to the ESP module won't damage the ESP module, but it might not boot up properly. When correctly booted the unit will return text to the console device, a series of illegible characters and beeps indicates the wrong boot image has been applied.

The contents of the zip file should look similar to this:

$ unzip -t *.zip
Archive:  HydraFerret_Bin_000rc1.zip
    testing: 0x1000_bootloader_dio_40m.bin   OK
    testing: 0x1000_bootloader_dio_80m.bin   OK
    testing: 0x1000_bootloader_dout_40m.bin   OK
    testing: 0x1000_bootloader_dout_80m.bin   OK
    testing: 0x1000_bootloader_qio_40m.bin   OK
    testing: 0x1000_bootloader_qio_80m.bin   OK
    testing: 0x1000_bootloader_qout_40m.bin   OK
    testing: 0x1000_bootloader_qout_80m.bin   OK
    testing: 0x10000_program.bin      OK
    testing: 0x8000_partition.bin     OK
    testing: 0xe000_ota_data.bin      OK
No errors detected in compressed data of HydraFerret_Bin_000rc1.zip.

To flash the unit a number of tools can be used, but the recommended option is Expressif's Flash Download Tool, which can be downloaded from: www.espressif.com.

Once installed, run this and you will be presented with a choice of "developer" or "factory" mode. Factory mode is used if you wish to flash multiple modules in parallel. For this discussion use developer mode, which will flash just a single ESP32 module.

Next select esp32 as the target architecture.

Then select the binaries you wish to install from the directory / folder where you unzipped the installation. You will also have to specify to location where to flash the file. If the check box on the left is not selected the file won't be flashed to the unit. The order in which the files are specified is not relevant provided they get flashe to the right place. If you have flashed all four file and just need to change the bootloader, then only the one module you want to change needs to be flashed to the module. Once you are ready, press start and the program will detect some data about your unit such as network MAC addresses, before flashing the image to memory. A progress bar will appear at the bottom of the window.

Select the SPI speed and mode to match your bootloader. Note the flash size is in bits not bytes. So 32Mbit is 4M bytes, and so on. The com device should match your USB connections detected device number. Checking the "SpiAutoSet" box will usually do a good job of auto detecting the devices capabilities for you.

After flashing, the unit can be rebooted and a serial console connected at 115200, 8 bits, no parity, 1 stop bit and no handshake.

Compile from Source

Regardless of the tool used to compile the project there are some Arduino modules which will have to be installed. Here are the ones used by the precompiled binary:

Option selections for Arduino IDE compilation

$ arduino-cli lib list
Name                      Installed Available Location Description
Adafruit_BME280_Library   2.1.2    -        user     -
Adafruit_BusIO            1.7.2    -        user     -
Adafruit_GFX_Library      1.10.4   -        user     -
Adafruit_SSD1306          2.4.3    -        user     -
Adafruit_Unified_Sensor   1.1.4    -        user     -
Adafruit_VEML6075_Library 2.1.0    -        user     -
OneWire                   2.3.5    -        user     -

Download the source code

The source code can be downloaded from https://github.com/enfieldcat/HydraFerret

Compile from Arduino IDE

Ensure your system is configured to compile for the ESP32, check these instructions.

Load the project from the folder where you downloaded it to.
Use the tools drop down to select your board type.
Select the port where the board is connected.
Set the partition scheme to "Minimal SPIFFS (Large APPS with OTA)"
Review the tab "envGeneral.h" and make any changes you want, eg to support BlueTooth
Compile and flash to the ESP32 module
Connect to the module using the serial terminal at 115200 baud to configure wireless and module name.

If you want to export the compiled binary from the IDE, select "Sketch" → "Export compiled Binary".

Compile using command line tool

Ensure your system is configured to compile for the ESP32, check these instructions.

mkdir HydraFerret_bin
arduino-cli compile --output-dir ./HydraFerret_bin --fqbn esp32:esp32:lolin32:CPUFreq=80,PartitionScheme=min_spiffs HydraFerret/
arduino-cli board list
arduino-cli upload -p /dev/ttyACM0 --fqbn esp32:esp32:lolin32 HydraFerret_bin

The compiled file will be in the HydraFerret_bin directory. Adjust serial device and directory names to suit your system.

Copy the binary file to web server

This is a completely optional step, but allows a fleet of HydraFerret devices to update over the air. The OTA code is already integrated into the HydraFerret, so no code changes are required. But the individual HydraFerret modules should all reference your web server for updates. The default OTA source is otherwise the latest development build of the HydraFerret project.

An OTA update allows a HydraFerret module to update its firmware "in the field". This becomes important if the unit is installed in some hard to reach place, or remotely. There are a number of options which can be used to apply Over The Air (OTA) updates to HydraFerret modules.

Configure an OTA update check on reboot. If an update is available it is downloaded. Only a reset or power-cycle is required to initiate the update.
Configure one of the outputs as an OTA check eg: uptime > 1440 mins and day is 15th of month. The update is only applied if one is available.
Wait for manual intervention, someone connects to the unit using either the console or telnet, and runs "ota update". The update is only applied if one is available.

For instructions on how to set up the OTA server see these instructions.

Thank you for visiting camelthorn.cloud

Home