Generic firmware for Twomes measurement devices

This repository contains the generic firmware, with features common to various Twomes measurement devices, based on an ESP32 SoC.

See Twomes presence detection documentation for more specific information about the optional presence detection capabilities of this Twomes generic firmware.

Table of contents

• General info
• Deploying
• Developing
• Releasing
• Supported devices
• Features
• Status
• License
• Credits

General info

Different Twomes measurement devices may have various features in common, including device preperation, provisioning of home Wi-Fi network credentials via Bluetooth Low Energy (BLE) or via a temporary software access point (SoftAP), device-backend activation, network time synchronisation, persistent buffering and secure uploading of measurement data. The generic firmware currently uploads the following data:

Sensor	Property or timestamp	Unit	Printf format	Default measurement interval [h:mm:ss]	Description
ESP32	heartbeat		%d	0:10:00	Incrementing counter indicating the device is working
ESP32	batteryVoltage	V	%.2f	0:10:00	Measures the battery voltage
ESP32 Bluetooth	countPresence	[-]	%u	0:10:00	If enabled; number of smartphones responding to Bluetooth name request
ESP32 device clock	timestamp	Unix time	%d	0:10:00	Each measurement is timestamped
ESP32 device clock	upload_time	Unix time	%d	0:10:00	Uploads of the contents of the secure upload queue to a Twomes server are timestamped
ESP32 internet	booted_fw	version	%s	48:00:00	Version string of firmware on first boot after provisioning or OTA update
ESP32 internet	new_fw	version	%s	48:00:00	If Over-The-Air (OTA) firmware updates are enabled; data is only logged when new valid firmware was downloaded
ESP32 internet	(none yet)	[-]	%u	24:00:00	Device clock is synchronized regularly via the internet over NTP (time skew will be recorded in a future version of the firmware)

This software repository provides a shared libary for many of these common features. With this library, we also intend to make it easier to port software between Twomes devices based on an ESP32 SoC. This facilitates development of firmware for Twomes measurement devices.

Deploying

Go to the deploying section of the twomes-generic-esp-firmware library documentation to learn you can deploy binary releases of the firmware, i.e. without changing the source code, without a development environment and without needing to compile the source code.

Developing

Go to the developing section of the twomes-generic-esp-firmware library documentation to learn how you can change the source code using a development environment and compile the source code into a binary release of the firmware that can be deployed, either via the development environment, or via the method described in the section Deploying.

Supported devices

Ths firmware currently only supports ESP32 devices. In particular, we tested on:

• LilyGO TTGO T7 Mini32 V1.3 ESP32
• M5Stack CoreInk`

In future releases support could be added for devices based on an ESP8266 SoC, such as the Wemos LOLIN D1 mini.

Features

Currently ready:

• Unified Provisioning over Bluetooth Low Energy (BLE; ESP32 only) and SoftAP
• Time synchronisation using NTP
• Secure transport over TLS/SSL (ESP32 only), using the ISRG Root X1 certificate
• Heartbeats: regular measurement and upload of timestamped measurment data with property heartbeat
• Wi-Fi reset via long button press
• Example code
• Over-the-Air (OTA) firmware updates
• Display provisioning QR-code on e-ink screen (M5Stack CoreInk only)
• Presence Detection (device preparation-time definition of tracked Bluetooth addresses)

To-do:

• Persistent buffering of measurement data
• Log time skew after NTP sync
• Visual indication via the LEDs, buzzer and/or the e-ink screen that allows the end user to recognize various device states
  • ready for device activation
  • device activation
  • (last time) a heartbeat was sent
• Presence Detection (runtime definition of tracked Bluetooth addresses)
• Support for ESP8266

Status

Project is: in-progress

License

This software is available under the Apache 2.0 license, Copyright 2021 Research group Energy Transition, Windesheim University of Applied Sciences

Credits

This software is made by:

• Nick van Ravenzwaaij · @n-vr
• Kevin Jansen · @KevinJan18
• Tiemen Molenaar · @Tiemen-M

Thanks also go to:

• Sjors Smit · @Shorts1999
• Stijn Wingens · @stijnwingens
• Jorrin Kievit · @JorrinKievit

Product owner:

• Henri ter Hofte · @henriterhofte · Twitter @HeNRGi

We use and gratefully acknowlegde the efforts of the makers of the following source code and libraries:

• ESP-IDF, by Espressif Systems, licensed under Apache 2.0 license
• bm8563, by Mika Tuupola, licensed under MIT License
• LovyanGFX, by lovyan03, licensed under FreeBSD