f411_io_mod

STM32F411 + W5500 IO controller running MQTT, REST API, Modbus TCP, and a web dashboard on FreeRTOS via Mongoose — all in one open-source firmware.

COMPONENTS Hardware components

WIZnet - W5500

x 1

PROJECT DESCRIPTION

Industrial IO Controller with STM32 + W5500 + Mongoose — F411 IO Mod

Open-source firmware for an STM32F411-based digital IO controller, using a W5500 Ethernet chip to deliver MQTT, REST API, Modbus TCP, a web dashboard, and OTA updates — all running on FreeRTOS with the Mongoose networking library.

Background: How Much Can a Small MCU Do?

The STM32F411CEUX — better known as the "BlackPill" — is a low-cost Cortex-M4 microcontroller running at up to 100MHz with 128KB of flash and 32KB of RAM. Developer kshypachov used this chip to build something far beyond a basic GPIO controller.

F411 IO Mod is firmware for a compact IO controller with 3 digital inputs and 3 relay outputs. On top of the hardware control layer, it integrates Ethernet, MQTT, REST API, Modbus TCP, a web dashboard, OTA firmware updates, an OLED display, NTP time sync, and SSDP auto-discovery — all within a single firmware binary. The project is maintained by a Ukrainian developer with GitHub Actions CI for automated builds.

WIZnet's Role: W5500 + Mongoose

Ethernet connectivity is handled entirely by the WIZnet W5500, connected via the SPI2 bus (PB13 SCK, PB14 MISO, PB15 MOSI), with CS on PB12 and RST on PA8.

Why W5500

The STM32F411 has no built-in Ethernet MAC. Adding a software TCP/IP stack like LwIP would consume a significant portion of the 128KB flash and 32KB RAM, leaving insufficient room for FreeRTOS, LittleFS, OLED, MQTT, Modbus, SSDP, and the rest. W5500's hardwired TCP/IP stack offloads all protocol processing to hardware, making the combination viable on this constrained platform.

W5500 + Mongoose: An Unusual Pairing

Rather than using WIZnet's ioLibrary, this project drives W5500 through the Mongoose networking library. Setting MG_ENABLE_DRIVER_W5500 1 in mongoose_config.h lets Mongoose use W5500 as a native driver, then runs HTTP, MQTT, TCP sockets, SNTP, and SSDP all through a single event loop (mg_mgr_poll).

// mongoose_config.h
#define MG_ENABLE_TCPIP         1
#define MG_ENABLE_DRIVER_W5500  1

This means a single FreeRTOS task (ethTask) owns the entire network stack, while the remaining tasks — IO polling, display, settings, logging, watchdog — run independently without touching the network layer.

How It Works: Multitask Architecture on FreeRTOS

The firmware runs six FreeRTOS tasks communicating via message queues and mutexes:

[ethTask]       ← Mongoose event loop: HTTP + MQTT + Modbus TCP + SNTP + SSDP
[IOTask]        ← GPIO input/output polling (1ms interval)
[displayTask]   ← SSD1306 OLED update over I2C
[settingsTask]  ← LittleFS config management, button handling
[loggingTask]   ← Log file writes to LittleFS
[WatchDogTask]  ← IWDG hardware watchdog refresh (500ms, high priority)

Network features:

Feature	Implementation
HTTP web server	Mongoose, port 80, serves files from LittleFS
REST API	JSON-based: IO control, MQTT config, firmware upload, log access
MQTT client	Mongoose, Home Assistant Auto Discovery supported
Modbus TCP server	FreeModbus 1.6 port, port 502, IP ACL access control
SNTP	NTP time sync on boot → RTC update
SSDP	UPnP auto-discovery, device visible on local network
OTA update	Firmware and web UI files uploaded via web or REST API

Storage: LittleFS is mounted on an external SPI flash chip (SPI1), storing MQTT credentials, web interface files, logs, user authentication data, and the Modbus ACL. W5500 uses SPI2 and the flash uses SPI1 — no bus conflicts.

Authentication: The REST API and web dashboard use SHA-1 password hashing with 48-hour session tokens. Default credentials are admin/admin, resettable by holding the button for 8 seconds.

Why This Project Stands Out

Mongoose + W5500 integration: Using Mongoose's built-in W5500 driver instead of ioLibrary is uncommon. This project serves as a clean, complete reference for the STM32 + Mongoose + W5500 stack.
Feature density: HTTP server, MQTT, Modbus TCP, REST API, OTA, OLED, NTP, SSDP, LittleFS, FreeRTOS, and SHA-1 auth — all fitting inside 128KB of flash. W5500's hardwired stack is what makes this possible.

Home Assistant integration: MQTT Discovery is implemented directly, auto-registering 3 inputs, 3 outputs, battery voltage, and power supply voltage as HA entities.

CI/CD: GitHub Actions build automation is in place, indicating an actively maintained codebase.

Use Cases

Smart home IO controller: 3-channel input/output control integrated with Home Assistant via MQTT — lights, locks, sensors, and relays remotely managed.
Lightweight industrial gateway: Modbus TCP server for PLC/SCADA communication, REST API for cloud data forwarding — a compact edge gateway on a single board.
Embedded prototyping reference: A complete, working implementation of STM32 + W5500 + Mongoose + FreeRTOS + LittleFS. A solid starting point for similar IoT product development.

Related Content	Why It Is Similar	Difference and Extension Value
How to Implement Mongoose Networking Library on STM32F4 using W5500	Also uses STM32F4, W5500, and Mongoose.	F411 IO Mod expands this from Ethernet bring-up into full firmware with MQTT, REST API, Modbus TCP, web UI, OTA, NTP, storage, and authentication.
Ethernet on Any STM32 MCU	Shows how STM32 can use W5500 for wired Ethernet through Mongoose.	F411 IO Mod adds FreeRTOS multitasking, real I/O control, MQTT/Home Assistant, Modbus TCP, REST API, and web configuration.
How to Build a Reliable MQTT I/O Controller with W5500 and Arduino Nano for Home Assistant	Similar wired MQTT I/O controller use case for Home Assistant.	F411 IO Mod is more multi-protocol, combining MQTT, REST, Modbus TCP, OTA, web dashboard, storage, and authentication for smart-home or edge-gateway use.

Tech Stack Summary

Item	Details
MCU	STM32F411CEUX (Cortex-M4, 100MHz, 128KB Flash, 32KB RAM)
Ethernet Chip	WIZnet W5500 (Hardwired TCP/IP, SPI2 interface)
W5500 Pins	SPI2 (PB13/14/15), CS: PB12, RST: PA8
Networking Library	Mongoose (W5500 driver built-in)
RTOS	FreeRTOS 10.3.1 (6 tasks)
File System	LittleFS (external SPI flash, SPI1)
Protocols	HTTP/REST, MQTT, Modbus TCP, SNTP, SSDP/UPnP
Display	SSD1306 OLED (I2C1)
IO	3× digital input (PA0–PA2), 3× relay output (PA5–PA7)
Security	SHA-1 password hash, token auth (48h), Modbus IP ACL
OTA	Firmware and web UI upload via web or REST API
CI/CD	GitHub Actions (automated build)
License	MIT

FAQ

Q. Does it use LwIP? No. W5500's hardwired TCP/IP stack handles all protocol processing. Mongoose drives W5500 directly as a network driver, so no software TCP/IP stack is needed. This is what allows everything else to coexist within 128KB of flash.

Q. Why Mongoose instead of WIZnet ioLibrary? Mongoose handles HTTP, MQTT, TCP sockets, SNTP, and more through a unified event loop, with W5500 support built in. Compared to pairing ioLibrary with separate HTTP and MQTT libraries, Mongoose simplifies the codebase and reduces memory footprint — important on a 128KB flash target.

Q. Can Modbus TCP and the HTTP server run at the same time? Yes. Mongoose's single event loop handles both HTTP (port 80) and Modbus TCP (port 502) concurrently. The FreeRTOS ethTask runs this loop and serves both simultaneously.

Q. Can it be used without Home Assistant? Yes. The REST API and web dashboard provide full IO control and configuration independently. MQTT is optional and can be left disabled — all other features work normally.

Q. How does OTA update work? Upload firmware.bin via the REST API (/api/firmware/upload). The file is stored in LittleFS under /firmware. Calling /api/firmware/apply moves it to /firmware.bin and reboots the device. The bootloader detects the file on the next boot and flashes it. MD5 checksum verification is supported.

Project Links
GitHub: kshypachov/f411_io_mod
WIZnet W5500: https://docs.wiznet.io/Product/Chip/Ethernet/W5500
Mongoose networking library: https://mongoose.ws

Documents

Comments Write

Wiznet makers