SmartFuseBox – `Local.h` Configuration Reference

Local.h is the single file a developer edits to configure SmartFuseBox for their specific hardware. It controls board selection, feature flags, pin assignments, and relay count. No other file should need to change for a standard hardware setup.

Do not commit secrets or hardware-specific pin changes back to the main repository. Treat Local.h as a local override file.

Naming Convention

Throughout Local.h, the trailing underscore convention marks a define as inactive:

#define ARDUINO_UNO_R4        // ✅ ACTIVE   — remove underscore to enable
#define ARDUINO_R4_MINIMA_    // ❌ INACTIVE — underscore means disabled

This lets all options stay visible in the file without needing to delete or comment anything out.

1. Board Selection

Exactly one board must be active. The compile-time #error guards will catch multiple active selections or no selection.

Define	Board	WiFi	BLE	Notes
`ARDUINO_UNO_R4`	Arduino Uno R4 WiFi	✅	✅	WiFi and BLE are mutually exclusive — see Connectivity Constraints
`ARDUINO_R4_MINIMA`	Arduino Uno R4 Minima	❌	❌	Serial and sensor support only; `WIFI_SUPPORT` and `BLUETOOTH_SUPPORT` must not be defined
`ESP32_NODE_32`	ESP32 NodeMCU-32 or compatible	✅	✅	Full feature support; activating this also defines `ESP32` if the ESP32 toolchain hasn't already done so

To switch boards, remove the trailing underscore from the target and add one to all others:

// Switch from Uno R4 to ESP32
#define ARDUINO_UNO_R4_     // now inactive
#define ARDUINO_R4_MINIMA_  // still inactive
#define ESP32_NODE_32       // now active

2. Feature Flags

`FUSE_BOX_CONTROLLER`

#define FUSE_BOX_CONTROLLER

Includes all SmartFuseBox controller functionality — relay management, sensor pipeline, config system, serial command handlers, and connectivity subsystems. Remove this only if using the underlying components (e.g. WifiController, MQTTClient) in a completely different project.

`WIFI_SUPPORT`

#define WIFI_SUPPORT

Enables the WifiController, WifiServer, HTTP REST API, and all network command handlers. Only define this on boards with a WiFi radio (ARDUINO_UNO_R4 or ESP32_NODE_32).

`MQTT_SUPPORT`

#if defined(WIFI_SUPPORT)
#define MQTT_SUPPORT
#endif

Enables the MQTT client, MQTTController, and all MQTT handlers including Home Assistant auto-discovery. Guarded inside #if defined(WIFI_SUPPORT) — MQTT requires an active WiFi connection and will not compile without it.

To disable MQTT while keeping WiFi active, comment out or remove the #define MQTT_SUPPORT line.

`BLUETOOTH_SUPPORT`

#define BLUETOOTH_SUPPORT_   // inactive by default

Enables the BLE stack (BluetoothController, BluetoothManager) and all three BLE services. Remove the trailing underscore to activate. See Connectivity Constraints for the WiFi conflict on Arduino Uno R4.

`SD_CARD_SUPPORT`

#define SD_CARD_SUPPORT

Enables SD card support via the MicroSdDriver singleton. When defined, the system can log data to the SD card and optionally load configuration from config.txt. This feature requires the SD card SPI pins to be configured correctly (see section 6).

`CARD_CONFIG_LOADER`

#define CARD_CONFIG_LOADER_   // inactive by default — experimental

When active, the system reads config.txt from the SD card at boot and on card-insert, allowing configuration changes without reflashing. Requires the SD card SPI pins to be wired correctly. This feature is experimental and disabled by default.

3. Connectivity Constraints

On Arduino Uno R4 WiFi, the ANNA-B112 (BLE) and ESP32-S3 (WiFi) modules share the same RF path and cannot run simultaneously. A compile-time guard enforces this:

#if defined(ARDUINO_UNO_R4) && defined(WIFI_SUPPORT) && defined(BLUETOOTH_SUPPORT)
#error "WIFI_SUPPORT and BLUETOOTH_SUPPORT cannot both be enabled on Arduino Uno R4."
#endif

Board	WiFi + MQTT	BLE only	Both
Arduino Uno R4 WiFi	✅	✅	❌ compile error
Arduino R4 Minima	❌	❌	❌
ESP32 NodeMCU-32	✅	✅	✅

4. Serial Initialisation Timeout

constexpr uint64_t serialInitTimeoutMs = 300;

If waitForConnection is true when initialising serial, the firmware waits up to this many milliseconds for the USB serial connection before continuing with setup. Useful when debugging startup log messages that would otherwise be missed because the serial monitor opens after the board has already booted.

5. Sensor Pins

For full per-board pin tables, ESP32 safety rules, and porting caveats see Docs/Pins.md.

Default pin assignments for the example sensors. Change these to match your wiring.

Constant	Default	Connected to
`WaterSensorPin`	`A0`	Water level sensor analog output
`LightSensorAnalogPin`	`A1`	LDR analog output — read every poll and averaged over a rolling queue of 10 samples
`LightSensorPin`	`D3`	LDR digital pin — initialised as `INPUT`; analog reading is now the primary detection source
`WaterSensorActivePin`	`D8`	Water sensor power pin — pulsed `HIGH` before each reading to reduce corrosion
`Dht11SensorPin`	`D9`	DHT11 data line

When adding new sensors, define additional pin constants here and use them when constructing the sensor handler in SmartFuseBox.ino.

6. SD Card SPI Pins

Used by MicroSdDriver for SD card access (logging and optional config loading). Requires SD_CARD_SUPPORT to be defined.

Note: The CONFIGURE_SPI flag in Local.h gates platform-specific SPI pin configuration:

Defined (ESP32): Calls SPI.begin(sck, miso, mosi) with the configured pins.

Undefined (Arduino UNO R4, AVR): Calls the portable SPI.begin() with core-default pins.

Pin values passed to beginInitialize() are always stored regardless of the flag, so they remain available for board-specific helpers like SPI.setSCK() / setMISO() / setMOSI() if the target core provides them.

Constant	Default	SPI Signal
`SdCardCsPin`	`D10`	Chip Select
`SdCardMosiPin`	`D11`	MOSI (Master Out, Slave In)
`SdCardMisoPin`	`D12`	MISO (Master In, Slave Out)
`SdCardSckPin`	`D13`	Clock

Configuration via Serial Commands

SD card pins can be configured at runtime:

Command	ID	Format	Description
SPI Pins	`C4`	`s=<sck>;o=<mosi>;i=<miso>`	Set SPI pins (SCK, MOSI, MISO). Note the parameter order: `s` = SCK, `o` = MOSI, `i` = MISO
CS Pin	`C32`	`v=<pin>`	Set chip select pin
SD Speed	`C31`	`v=<4\|8\|12\|16\|20\|24>`	Set SPI speed in MHz

Example:

C4:s=13;o=11;i=12    ← Configure SPI pins
C32:v=10              ← Set CS pin to D10
C31:v=8               ← Set SPI speed to 8 MHz

All four pins (MISO, MOSI, SCK, CS) must be set to valid pin numbers (not 0xFF / PinDisabled) before MicroSdDriver::beginInitialize() will proceed. If any pin is invalid, the SpiPinConfigError warning is raised.

7. Relay Configuration

`ConfigRelayCount`

constexpr uint8_t ConfigRelayCount = 8;

The number of physical relays. Must match the number of entries in the Relays[] array. The system will not function with fewer than 1 relay. Set this to less than the number of defined pin constants if not all relays are populated.

Relay Pins

constexpr uint8_t Relay1 = D7;   // digital header
constexpr uint8_t Relay2 = D6;
constexpr uint8_t Relay3 = D5;
constexpr uint8_t Relay4 = D4;
constexpr uint8_t Relay5 = 19;   // analog header used in digital mode (A5)
constexpr uint8_t Relay6 = 18;   // A4
constexpr uint8_t Relay7 = 17;   // A3
constexpr uint8_t Relay8 = 16;   // A2

On Arduino Uno R4 / R4 Minima, analog header pins A2–A5 are exposed as integer indices 16–19 when used in digital mode.

`Relays[]` Array

constexpr uint8_t Relays[ConfigRelayCount] = {
    Relay1, Relay2, Relay3, Relay4, Relay5, Relay6, Relay7, Relay8
};

The command layer addresses relays by 0-based index into this array — index 0 is relay 1, index 1 is relay 2, and so on. Always keep Relay1 at index 0 and ensure the array contains exactly ConfigRelayCount entries.

8. Compile-Time Guards

Local.h enforces valid configurations with #error directives that fail the build immediately with a clear message:

Guard	Condition	Error message
WiFi + BLE on R4	`ARDUINO_UNO_R4 && WIFI_SUPPORT && BLUETOOTH_SUPPORT`	"WIFI_SUPPORT and BLUETOOTH_SUPPORT cannot both be enabled on Arduino Uno R4."
Multiple boards	e.g. `ARDUINO_UNO_R4 && ESP32`	"Multiple board types defined."
No board	None of the three boards active	"No board type defined."

9. Common Configuration Recipes

Arduino Uno R4 WiFi with MQTT (default)

#define ARDUINO_UNO_R4
#define ARDUINO_R4_MINIMA_
#define ESP32_NODE_32_
#define FUSE_BOX_CONTROLLER
#define WIFI_SUPPORT
// MQTT_SUPPORT is auto-enabled inside the WIFI_SUPPORT guard
#define BLUETOOTH_SUPPORT_    // inactive — mutually exclusive with WiFi on R4
#define CARD_CONFIG_LOADER_   // inactive

Arduino Uno R4 WiFi with BLE (no MQTT)

#define ARDUINO_UNO_R4
#define ARDUINO_R4_MINIMA_
#define ESP32_NODE_32_
#define FUSE_BOX_CONTROLLER
// #define WIFI_SUPPORT     ← comment out entirely
#define BLUETOOTH_SUPPORT   // active — WiFi is off so no conflict
#define CARD_CONFIG_LOADER_

Arduino Uno R4 Minima (sensors + serial only)

#define ARDUINO_UNO_R4_        // inactive
#define ARDUINO_R4_MINIMA      // active
#define ESP32_NODE_32_         // inactive
#define FUSE_BOX_CONTROLLER
// WIFI_SUPPORT, MQTT_SUPPORT, BLUETOOTH_SUPPORT must all be absent or inactive
#define CARD_CONFIG_LOADER_

ESP32 (WiFi + BLE + MQTT)

#define ARDUINO_UNO_R4_
#define ARDUINO_R4_MINIMA_
#define ESP32_NODE_32         // active
#define FUSE_BOX_CONTROLLER
#define WIFI_SUPPORT
// MQTT_SUPPORT auto-enabled
#define BLUETOOTH_SUPPORT     // also active — ESP32 supports both simultaneously
#define CARD_CONFIG_LOADER_

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

SmartFuseBox – `Local.h` Configuration Reference

Naming Convention

1. Board Selection

2. Feature Flags

`FUSE_BOX_CONTROLLER`

`WIFI_SUPPORT`

`MQTT_SUPPORT`

`BLUETOOTH_SUPPORT`

`SD_CARD_SUPPORT`

`CARD_CONFIG_LOADER`

3. Connectivity Constraints

4. Serial Initialisation Timeout

5. Sensor Pins

6. SD Card SPI Pins

Configuration via Serial Commands

7. Relay Configuration

`ConfigRelayCount`

Relay Pins

`Relays[]` Array

8. Compile-Time Guards

9. Common Configuration Recipes

Arduino Uno R4 WiFi with MQTT (default)

Arduino Uno R4 WiFi with BLE (no MQTT)

Arduino Uno R4 Minima (sensors + serial only)

ESP32 (WiFi + BLE + MQTT)

FilesExpand file tree

Local.md

Latest commit

History

Local.md

File metadata and controls

SmartFuseBox – Local.h Configuration Reference

Naming Convention

1. Board Selection

2. Feature Flags

FUSE_BOX_CONTROLLER

WIFI_SUPPORT

MQTT_SUPPORT

BLUETOOTH_SUPPORT

SD_CARD_SUPPORT

CARD_CONFIG_LOADER

3. Connectivity Constraints

4. Serial Initialisation Timeout

5. Sensor Pins

6. SD Card SPI Pins

Configuration via Serial Commands

7. Relay Configuration

ConfigRelayCount

Relay Pins

Relays[] Array

8. Compile-Time Guards

9. Common Configuration Recipes

Arduino Uno R4 WiFi with MQTT (default)

Arduino Uno R4 WiFi with BLE (no MQTT)

Arduino Uno R4 Minima (sensors + serial only)

ESP32 (WiFi + BLE + MQTT)

SmartFuseBox – `Local.h` Configuration Reference

`FUSE_BOX_CONTROLLER`

`WIFI_SUPPORT`

`MQTT_SUPPORT`

`BLUETOOTH_SUPPORT`

`SD_CARD_SUPPORT`

`CARD_CONFIG_LOADER`

`ConfigRelayCount`

`Relays[]` Array