This is a universal firmware for all PixelWeather nodes. It was created using the esp-idf template.
PixelWeather is a weather station network that collects environment data using "nodes" (a collection of microcontrollers and sensors). This repository contains the firware for said nodes (PWOS).
- Espressif ESP32-S3 microcontroller
- Classic ESP32 and ESP32-C3 series are no longer supported!
- 4MB Flash minimum, 8MB recommended, 16MB best
- Future versions may drop support for 4MB models. It's advised to use 8MB models for future-proofing.
- Read section Build variants for details
- 512KB SRAM (models with less may be sufficient)
- PSRAM not required, it's not used (yet)
- 2x resistors for measuring battery voltage. Exact values are defined in
battery.rs-DIVIDER_R1andDIVIDER_R2. - Battery - any generic 18650 will do
- Additional protection circuit recommended
- An environment sensor
- Temperature reading support (required)
- Humidity reading support (required)
- Optional:
- Air pressure reading support
- I2C interface
As of now, this firmware has been tested with:
As of now, this firmware has been tested with:
It's recommended to use hardware from reputable brands such as Adafruit, SparkFun, DFRobot, etc. These are generally more expensive but also higher quality.
src/firmware.rs- This is the entry point for the firmware. If you want to explore this project, you should start from here.src/main.rs- The main entry point, it's responsible for initializing core components.src/sysc/- Contains components of PWOSsrc/config/- Contains configuration definitions for the firmware.
All drivers for external hardware are in src/sysc/drivers.
The firmware includes one universal driver that should be compatible with any HTU21-like sensor. It works with:
You could also implement your own driver, however the sensor must support temperature and humidity measuring at minimum. Your driver then must implement the EnvironmentSensor trait.
Using multiple environment sensors is not supported. The firmware will use the first sensor it finds (which is typically the one with the lowest I2C address). This also means that every I2C hardware must use a different address.
The project currently only supports the ESP32. There are no plans to support any other MCU.
Consumption measurements:
| Board | Sensor | Test voltage | Running | Sleeping | Peak | Notes |
|---|---|---|---|---|---|---|
| N/A | N/A | N/A | N/A | N/A | N/A | N/A |
Battery life measurements:
| Board | Sensor | Battery model | Capacity | Environment | Sleep time | Time |
|---|---|---|---|---|---|---|
| N/A | N/A | N/A | N/A | N/A | N/A | N/A |
Note that the battery voltage measurement is currently unreliable.
- Make sure that
sdkconfig.debugandsdkconfig.releaseare correct for your specific board. - Check if the firmware uses the correct GPIO pins for I2C and on-board LED.
- Follow the toolchain setup in Espressifs Rust Book
- Create a custom
sys.rsconfig using the example. - Use
cargo buildto compile the firmware. - Use the commands below to build an image or flash the firmware.
If you just want to build the image, use the following command (for example):
cargo espflash save-image -T partitions.csv --frozen --locked --release --chip esp32s3 --merge image.bin To directly flash the firmware, use the command below. Remember to change the serial port for your machine.
cargo espflash flash -T partitions.csv --frozen --locked --release -c esp32s3 --noverify --erase-data-parts otadata -B 921600 -p /dev/ttyXXXXIf you notice weird/buggy bevaiour, you can erase the entire flash like so:
cargo espflash erase-flash -c esp32s3 -p /dev/ttyACM0 -B 921600⚠️ Note for Arduino Nano ESP32
After erasing the flash you may not be able to flash the board with Arduino IDE. You'll need to re-burn the bootloader.
Depending on which ESP32S3 development board you're using, you may need to add additional arguments to the two example commands above (especially flash).
-c esp32s3-s 16mb/-s 8mb- For 16MB and 8MB of flash respectively.
To build a debug image (or flash it) remove the --release flag from the above commands.
LILYGO T7 S3 v1.2
The provided sdkconfig.debug and sdkconfig.release configurations are designed for this board by default.
No changes are needed.
The default pin configuration of PWOS is designed for this board. No changes are needed.
- On-board LED:
GPIO_17 - I2C SDA:
GPIO_5 - I2C SCL:
GPIO_8 - Battery measurement:
GPIO_2
- For saving as image:
cargo espflash save-image --frozen --locked --release -T partitions.csv -s 16mb --chip esp32s3 image.bin
- For flashing:
cargo espflash flash --frozen --locked --release -T partitions.csv -s 16mb -c esp32s3 -B 921600 -p /dev/ttyXXXX -M --no-verify --erase-data-parts ota
Arduino Nano ESP32
In both sdkconfig.debug and sdkconfig.release uncomment/add the following entries:
CONFIG_RTC_CLK_SRC_EXT_CRYS=y
The on-board LED is on a different pin. You'll need to set LED_BUILTIN in your sysconfig (src/config/sys.rs).
- On-board LED:
GPIO_48 - I2C SDA:
GPIO_5 - I2C SCL:
GPIO_8 - Battery measurement:
GPIO_2
- For saving as image:
cargo espflash save-image --frozen --locked --release -T partitions.csv -s 16mb --chip esp32s3 image.bin
- For flashing:
cargo espflash flash --frozen --locked --release -T partitions.csv -s 16mb -c esp32s3 -B 921600 -p /dev/ttyXXXX -M --no-verify --erase-data-parts ota
Seeed Studio XIAO ESP32S3
The provided sdkconfig.debug and sdkconfig.release configurations are designed for this board by default.
No changes are needed.
The on-board LED is on a different pin. You'll need to set LED_BUILTIN in your sysconfig (src/config/sys.rs). Additionally, you'll also need to set LED_BUILTIN_INVERT to true, because the LED's negative terminal is connected to the GPIO pin.
- On-board LED:
GPIO_21 - I2C SDA:
GPIO_5 - I2C SCL:
GPIO_8 - Battery measurement:
GPIO_2
- For saving as image:
cargo espflash save-image --frozen --locked --release -T partitions.csv -s 8mb --chip esp32s3 image.bin
- For flashing:
cargo espflash flash --frozen --locked --release -T partitions.csv -s 8mb -c esp32s3 -B 921600 -p /dev/ttyXXXX -M --no-verify --erase-data-parts ota
Firmware size (as of commit a273a72):
- Release build:
855,952/2,031,616 bytes, 42.13% - Debug build:
1,198,240/2,031,616 bytes, 58.98%
Debug builds may be slower and contain a lot of debug messages. As such they are slightly larger.
Some parts of the flash memory are reserved for other data then PWOS itself. 12KB are reserved for NVS storage. Read more here.
Latest verified stable version: N/A
A version is deemed "stable" if it runs without interruptions/buggy behaviour for at least 1 month.
- If you're planning to flash the firmware and use it "in production", you should always use release builds. Just pass
--releasetocargo buildandcargo espflash. - For troubleshooting, you should use debug builds, as they have more verbose logging.
- Make sure to use the given partition layout (
partitions.csv) by passing-T partitions.csvtocargo espflash. The default partition layout has a way too smallapppartition. - Some lower-quality USB cables may require a lower baud rate. Use
115200if921600does not work for you. - The firmware does not support unencrypted WiFi networks (at least not without modifying
src/firmware.rsandsrc/sysc/net/wifi.rs). - By default, the firmware sets the WiFi power saving mode to maximum. This may change in future versions, as the goal is to make it work with maximum power savings.
- Hidden WiFi networks are not supported.
- It's recommended to ensure that the RSSI (signal strength) is no less than -70dBm. Some boards can handle worse scenarios, but others may experience connectivity issues.
- WiFi credentials are stored in code, instead of NVS because:
- If they were stored on the NVS, PWOS would need special functionality to update them using OTA updates and rollbacks. This would have a major impact on PWOS's complexity.
- Since they are stored in code, every build of PWOS contains has its own credentials, meaning you can easily update them with OTA updates, and rollbacks will also restore the old values as a side effect.
- The NVS has a very simple data structure, which limits how these credentials can be stored, since we need to store SSIDs, password and per-network IP configuration (WIP).
- It would be almost impossible to implement this without storing all this data in a specific format and deserializing them with some
serde_*crate. However, this would also introduce a performance penalty and unnecessary extra complexity.
- It would be almost impossible to implement this without storing all this data in a specific format and deserializing them with some
- node - A station that consists of PWOS-compatible hardware and runs PWOS. It collects weather information and sends it over PWMP to a remote server.
- sysconfig/system configuration - Board-specific configuration with pin definitions. Should be in
src/config.sys.rs. For an example configuration, checksrc/config/sys.rs.example - appconfig/application configuration - Defines how PWOS behaves, e.g. whether it should check battery voltages, how long should the node sleep, etc. This configuration is defined in the PWMP database.
- sBOP/software-based battery overdischarge protection - Permanently shuts down the node if the battery voltage drops below a critical value.
- OTA/Over-the-Air (updates) - Firmware updates that are delivered wirelessly to the nodes.
- OTA Updates
- USB connection detection
- Serial port detection can't be implemented yet due to API limitations of ESP IDF v5.2.2
You can download prebuilt binaries of Espressif's QEMU fork from here. However as of now, PWOS cannot be emulated. You will get a panic on boot. This is likely due to the emulator not being able to emulate the WiFi hardware.