Board Reference Matrix

This document is the ground truth for all CeresFlows firmware documentation. Every code example and warning in other chapters references the information here.

Before you write a single line of firmware, identify your board in the table below and understand its constraints. Ignoring these constraints is the most common cause of firmware failures.

Supported Boards

CeresFlows supports controllers in two tiers:

[!NOTE] A “Satellite” controller is not a limitation of CeresFlows — it is a valid architectural choice. A cheap ESP8266 dedicated to a single humidity sensor is often the right engineering decision.

Board Overview

[!CAUTION] The Arduino Nano has only 2 KB of RAM and 32 KB of Flash. A full-featured firmware with WiFi, ArduinoJson, and all bus commands will not fit. You must compile a stripped-down version. See the memory budget section below.

Transport Layer

How the board receives commands from the CeresFlows backend.

[!IMPORTANT] Arduino Nano has no WiFi hardware. It can only receive commands via the USB Serial port. This means it cannot be used as a standalone networked controller — it must be connected directly to the computer running CeresFlows.

WiFi Library (Critical — Wrong Library = Compile Error)

[!WARNING] <WiFi.h> on the Arduino IDE resolves to different libraries depending on which board is selected in the Board Manager. Do not copy-paste WiFi code between board types without checking the include.

Hardware Capabilities

Analog Input

[!CAUTION] ESP8266 has a single analog input (A0) with a maximum input voltage of 1.0V. Connecting a standard 0–5V sensor directly to A0 will damage the ESP8266. A voltage divider is required. Additionally, there is only one analog pin — you cannot read two analog sensors simultaneously on an ESP8266.

[!WARNING] ESP32 ADC returns 0–4095, not 0–1023. If your backend template or calibration is configured for a 10-bit range, readings will appear 4× higher than expected. Always configure your device template with the correct ADC resolution for your board.

Digital I/O

[!WARNING] ESP32 does not support the standard analogWrite() function in older Arduino core versions (< 3.x). If you are using an older ESP32 board package, you must use ledcWrite() instead. Always check your installed ESP32 Arduino core version before using PWM commands.

I2C Bus

[!NOTE] The Wire.h library is consistent across all boards. However, the physical pin numbers differ. I2C_TRANSFER commands always specify the I2C device address — the SDA/SCL pins are fixed by the board and cannot be changed at runtime without modifying the firmware.

UART / Serial Bus

[!WARNING] On all boards except ESP32, running UART_TRANSFER and MODBUS_RTU at the same time on different sensors requires two SoftwareSerial instances — which is unreliable above 9600 baud and can cause data corruption. The ESP32 is the only recommended board for simultaneous UART + Modbus use due to its multiple hardware UART ports.

SPI Bus

System Functions

Critical functions that differ between chips. Getting these wrong causes silent failures or compiler errors.

[!CAUTION] ESP32 does not have a traditional EEPROM. The EEPROM.h library on ESP32 emulates EEPROM in flash. You must call EEPROM.begin(size) before any read/write operations, and EEPROM.commit() after writes — otherwise data is lost on reboot. Forgetting EEPROM.commit() is a very common bug.

[!CAUTION] ESP8266 also requires EEPROM.begin(N) where N is the number of bytes you intend to use. Without this call, all reads return 0xFF and writes are silently ignored.

Interrupt-Capable Pins (for PULSE_COUNT)

The PULSE_COUNT command uses hardware interrupts. Not all pins support interrupts.

[!WARNING] On Arduino Nano, only pins D2 and D3 support hardware interrupts. If you connect a flow meter or pulse sensor to any other pin and use PULSE_COUNT, no pulses will be counted and the command will always return 0.

Memory Budget (Arduino Nano)

The Nano’s 2 KB RAM and 32 KB Flash impose hard limits. Here is what fits:

[!CAUTION] On Arduino Nano, never use DynamicJsonDocument. Its heap allocation will collide with the stack. Use only StaticJsonDocument<N> with N ≤ 128. For complex commands like I2C_TRANSFER or MODBUS_RTU that require parsing multi-field JSON, the Nano may not have sufficient RAM — test carefully.

Command Compatibility Summary

This document is the reference baseline for all CeresFlows firmware documentation. All board-specific warnings in other chapters derive from the constraints listed here.