IoTflow: Build Scalable IoT Automation with IoTextra Modules

Modern IoT prototyping is easy, building production-ready systems is hard. Most teams hit a wall when transitioning from Arduino or Raspberry Pi prototypes to stable, maintainable industrial products, often requiring complete hardware redesigns.

IoTflow eliminates this gap by providing a lightweight orchestration layer that unifies automation across IoTextra I/O modules and microcontroller nodes. Whether you're building a quick proof-of-concept or scaling to multi-device industrial automation, IoTflow gives you a consistent, MQTT-based workflow that grows with your project.

In this tutorial, we'll demonstrate IoTflow using IoTextra modules (Digital, Analog, and Combo I/O), starting with the IoTsmart quick-start path for rapid prototyping, then bridging to the IoTbase architecture for scalable, production-ready deployments.

What You'll Learn

• How to set up IoTflow with IoTextra I/O modules
• Quick-start automation using IoTsmart MCU nodes
• Building event-driven workflows with MQTT and Node-RED
• Scaling from prototype to production with IoTbase
• Implementing real-world automation examples

Hardware Requirements

Core Components

IoTextra Modules (choose one or more):

• IoTextra Input (Digital I/O)
• IoTextra Relay (Digital I/O)
• IoTextra Analog (Analog inputs)
• IoTextra Combo (Digital + Analog combined)

MCU Node (IoTsmart Quick Start):

• IoTsmart ESP32-S3
• IoTsmart RP2040/RP2350A
• IoTsmart XIAO
• Tiny Adaptor Board with Cable (for flashing)

For Scaling (IoTbase Architecture):

• IoTbase PICO (Raspberry Pi Pico, Pico W, Pico 2W)
• IoTbase NANO (Waveshare ESP32-S3-Nano)

Additional Hardware

• Gateway device (Raspberry Pi 3/4/5, Linux and etc as a host)
• MQTT Broker (can run on gateway)
• USB cables for programming and debugging (Depending on the board your using)
• Power supply (5V)
• Sensors/actuators (LEDs, buttons, relays, etc.)

Software Requirements

• MicroPython (for MCU nodes)
• Thonny IDE or similar MicroPython editor
• Node-RED (for automation flows)
• MQTT Broker (Mosquitto, EMQX, Aedes and etc)
• IoTflow Repository from GitHub

Architecture Overview

IoTflow uses a three-layer architecture:

┌─────────────────────────────────────┐
│     Node-RED Automation Layer       │
│  (Logic, Rules, Dashboards)         │
└─────────────────┬───────────────────┘
                  │ MQTT
┌─────────────────▼───────────────────┐
│      MQTT Broker (Mosquitto)        │
│  (Message Routing & Persistence)    │
└─────────────────┬───────────────────┘
                  │ MQTT Topics
┌─────────────────▼───────────────────┐
│    IoTflow Kernel (MicroPython)     │
│  Running on IoTsmart/IoTbase MCU    │
│  + IoTextra I/O Modules             │
└─────────────────────────────────────┘

Key Concepts:

• IoTextra Modules: Handle physical I/O (digital inputs, relays, analog sensors)
• IoTsmart/IoTbase: MCU nodes running IoTflow Kernel and interfaces with IoTextra Modules
• MQTT: Messaging protocol for device communication
• Node-RED: Visual programming for automation logic

IoTsmart Quick Start Path

Step 1: Flash MicroPython Firmware

First, ensure your microcontroller has MicroPython installed:

For Raspberry Pi Pico W (example):

• Download the firmware.uf2 file from MicroPython official website
• Hold down BOOTSEL on the Pico W and connect it via USB
• Release BOOTSEL – Pico appears as RPI-RP2 drive
• Copy the firmware.uf2 file to this drive
• Pico will reboot with MicroPython installed

For other microcontrollers: Visit micropython.org for specific guides.

Step 2: Install IoTflow Kernel

• Clone the IoTflow repository:

bash

git clone https://github.com/makethingshappy/iotflow.git
cd iotflow

Connect your IoTsmart module:

• For normal operation: Insert SOM into HOST connector slot on IoTextra Module
• For firmware flashing: Use the IoTsmart flexi adapter cable
• Connect USB for power and programming

Open Thonny IDE (or VS Code with MicroPython support)

Upload IoTflow Kernel files:

• Select MicroPython interpreter for your device
• Transfer main.py to the root directory of your MCU
• Transfer all other .py files into a lib folder on the MCU
• Open config.py and update any hardware details (I2C, GPIO and etc), Wi-Fi credentials and MQTT settings
• Save and reboot your device

Step 3: Configure IoTflow Forge

IoTflow Forge is a Python-based configuration tool that generates settings and configurations for your specific hardware setup and allows you to tell any IoTsmart module and IoTbase module to talk to IoTextra Modules you have in the way you want.

• Connect your microcontroller to your computer via USB
• Run IoTflow Forge:

bash

cd "IoTflow Forge"
python "IoTflow Forge.py"

Configure your setup:

• Create new configuration or load existing
• Select IoTsmart MCU type (ESP32-S3, RP2040, etc.)
• Add IoTextra modules you're using (Digital, Analog, Combo)
• Configure I/O channels (input/output, I2C/GPIO interface)
• Set MQTT broker details (IP address, port, credentials)
• Define device ID and base topic

Send configuration to MCU:

• Click "Send to Device" in IoTflow Forge
• Wait for system response confirmation
• Configuration is saved as config.py on the MCU and stores details in on-board EEPROM (IoTsmart or IoTbase)

Verify and disconnect once configuration matches your setup

Important: All 8 channels (AP0-AP7) can be individually configured as input or output, using either I2C or GPIO (HOST connector) interface.

Step 4: Set Up MQTT Broker

On your Raspberry Pi or Linux gateway:

bash

# Install Mosquitto
sudo apt update
sudo apt install mosquitto mosquitto-clients

# Start broker
sudo systemctl start mosquitto
sudo systemctl enable mosquitto

# Test broker
mosquitto_sub -h localhost -t '#' -v

Step 5: Install Node-RED

On Raspberry Pi or Linux gateway:

bash

# Install Node-RED
bash <(curl -sL https://raw.githubusercontent.com/node-red/linux-installers/master/deb/update-nodejs-and-nodered)

# Start Node-RED
node-red-start

# Access at http://[gateway-ip]:1880

Install Node-RED Dashboard:

• Open Node-RED in browser
• Click menu (top right) → Manage palette → Install
• Search for node-red-dashboard and install

Install custom IoTextra nodes:

These custom nodes provide pre-built interfaces for IoTextra modules:

bash

# Navigate to Node-RED user directory
cd ~/.node-red

# Install IoTextra nodes from repository
npm install /path/to/iotflow/node-red-contrib-iotextra

# Restart Node-RED
node-red-restart

Verify installation:

• Open Node-RED palette

Look for three new nodes in the "network" category:

• iotextra - input (for digital inputs)
• iotextra - output (for digital outputs)
• iotextra - analog (for analog channels)

Step 6: Import Example Flows

IoTflow provides ready-to-use Node-RED flows for each IoTextra module type.

• Open Node-RED in your browser (http://[gateway-ip]:1880)

Import example flow:

• Click menu (top right) → Import
• Navigate to /Node-RED Examples/ in the repository

Select the flow matching your hardware:

• iotextra_input_flow.json - IoTextra Input module
• iotextra_relay_flow.json - IoTextra Relay module
• iotextra_analog_flow.json - IoTextra Analog module
• iotextra_combo_flow.json - IoTextra Combo module
• iotextra_octal_flow.json - IoTextra Octal module

Configure MQTT broker:

• Double-click any iotextra node in the imported flow
• Update MQTT broker address if it differs from default (localhost)
• Ensure the base topic matches your config.py setting

Deploy the flow:

• Click Deploy button (top right)
• Dashboard becomes available at: http://[gateway-ip]:1880/ui

Verify operation:

• Open the dashboard
• Test inputs and outputs
• Monitor MQTT messages in debug panel

MQTT Topic Structure

IoTflow uses hierarchical MQTT topics based on <MQTT_BASE_TOPIC> defined in your configuration:

Category

MQTT Topic

Description

Values

Device Status

<MQTT_BASE_TOPIC>/status

Device online/offline state

online / offline

Digital Input

<MQTT_BASE_TOPIC>/input/<channel>

Input channel state

1 (ON) / 0 (OFF)

Digital Output Command

<MQTT_BASE_TOPIC>/output/<channel>/set

Set output state

1 (ON) / 0 (OFF)

Digital Output State

<MQTT_BASE_TOPIC>/output/<channel>/state

Confirms output state

1 (ON) / 0 (OFF)

Analog Channel

<MQTT_BASE_TOPIC>/analog/<channel>

Analog reading

String (e.g., "3.142") in V or mA

Examples:

Device status:

Topic: home/iotextra/status
Payload: online

Digital input (button pressed):

Topic: home/iotextra/input/1
Payload: 1

Digital output control (turn on relay):

Topic: home/iotextra/output/2/set
Payload: 1

Digital output confirmation:

Topic: home/iotextra/output/2/state
Payload: 1

Analog reading (temperature sensor):

Topic: home/iotextra/analog/1
Payload: "23.1"

Channel Naming:

• Digital I/O channels: AP0-AP7 (8 channels)
• Analog channels: A0-A1, A2-A3 (differential pairs up to 4 channels)
• Multiple ADCs: Processed in I²C address order (ADC 1, ADC 2, etc.)

Understanding IoTextra Custom Node-RED Nodes

IoTflow provides three specialized Node-RED nodes for seamless IoTextra integration:

1. IoTextra Output Node (Digital Control)

Purpose: Control digital outputs on IoTextra modules (relays, LEDs, actuators)

How it works:

• Input: Accepts msg.payload as true/false or 1/0
• Action: Sends MQTT command to <MQTT_BASE_TOPIC>/output/<channel>/set
• Confirmation: Device responds on <MQTT_BASE_TOPIC>/output/<channel>/state
• Output: Node outputs confirmed state as '1' or '0'

Example:

javascript

// Incoming message to turn on relay on channel 2
msg.payload = 1;
return msg;

2. IoTextra Input Node (Digital Monitoring)

Purpose: Monitor digital inputs on IoTextra modules (buttons, switches, sensors)

How it works:

• Detection: Firmware detects state changes on channels AP0-AP7
• Publishing: Device publishes to <MQTT_BASE_TOPIC>/input/<channel>
• Output: Node outputs msg.payload as '1' (ON) or '0' (OFF)

Features:

• Only publishes on state change (not continuous polling)
• Ideal for event-driven automation

3. IoTextra Analog Node (Analog Monitoring)

Purpose: Read analog values from IoTextra Analog or Combo modules

How it works:

• Continuous reading: Firmware continuously reads differential ADC channels (A0-A1, A2-A3)
• Publishing: Device publishes converted voltage/current to <MQTT_BASE_TOPIC>/analog/<channel>
• Output: Node outputs msg.payload as string (e.g., "3.124") in V or mA

Optional deadband filtering:

• Firmware can be configured to publish only on significant changes
• Reduces MQTT traffic and improves efficiency

Multiple ADC handling:

• For modules with multiple ADCs (IoTextra Analog 2, Analog 3)
• Firmware processes ADCs in I²C address order
• First address = ADC 1 (channels A0-A1, A2-A3)
• Second address = ADC 2 (channels A0-A1, A2-A3), etc.

Node-RED Flow Examples

Import this flow structure:

• IoTextra nodes subscribe or publish to your device channel and device topics
• Function nodes implement logic rules
• Switch nodes route based on conditions
• Dashboard nodes display real-time data
• Blynk IoT nodes(Optional) monitor data in real-time using nice UI dashboards

Testing Your Automation

• Monitor MQTT traffic:

bash

mosquitto_sub -h localhost -t 'iotflow/#' -v

• Trigger sensors and observe automation responses
• View Node-RED dashboard for real-time monitoring
• Check debug panel for message flow

Bridging to IoTbase for Scaling

Once your prototype is working with IoTsmart, scaling to production is seamless.

Why Scale to IoTbase?

IoTsmart (Quick Start):

• ✅ Compact wireless nodes
• ✅ Rapid prototyping
• ✅ Battery-efficiency
• ⚠️ Limited I/O expansion

IoTbase (Production):

• ✅ Full-featured serial-ready solutions
• ✅ More I/O expansion capacity
• ✅ Better stability for 24/7 operation
• ✅ Easier debugging and monitoring
• ✅ Same IoTflow Kernel and workflows

Migration Path

Step 1: Choose IoTbase Hardware

Replace IoTsmart with:

• IoTbase PICO (Raspberry Pi Pico W/2W and etc)
• IoTbase NANO (ESP32-S3-Nano and etc)

Step 2: Hardware Adaptation

IoTbase boards have standard headers compatible with IoTextra modules, no wiring changes needed.

Step 3: Software Migration

• Same IoTflow Kernel runs on IoTbase
• Same configuration files from IoTflow Forge
• Same MQTT topics and message structure
• Same Node-RED flows work without modification

Step 4: Enhanced Features

With IoTbase, you gain:

• Robust hardware interfaces for debugging
• More modular hardware expansion
• Better thermal management
• Professional enclosure compatibility

Multi-Device Scaling Example

Deploy multiple nodes with the same workflow:

Gateway (Raspberry Pi)
├─ MQTT Broker
├─ Node-RED
└─ Blynk Dashboard

Device Network:
├─ device01: IoTbase PICO + IoTextra Combo (Room 1)
├─ device02: IoTbase PICO + IoTextra Relay (Room 2)
├─ device03: IoTbase NANO + IoTextra Analog (Room 3)
└─ device04: IoTsmart ESP32-S3 + IoTextra Input (Remote sensor)

All devices share:

• Same IoTflow Kernel
• Same MQTT topic structure
• Same Node-RED automation logic
• Centralized management

Advanced Automation Patterns

1. State-Change Event Pipelines

Detect and act on state changes only.

2. Multi-Module Orchestration

Chain actions across multiple IoTextra modules.

Motion Detected (Device 1)
  → Turn ON Lights (Device 2)
  → Start Camera (Device 3)
  → Log Event (Database)

3. Timed Automation Sequences

Create delayed action chains:

Door Opened
  → Wait 5 seconds
  → Check if still open
  → Send alert if yes
  → Trigger alarm after 30 seconds

Troubleshooting

MQTT Connection Issues

bash

# Check broker is running
sudo systemctl status mosquitto

# Test connectivity
mosquitto_pub -h localhost -t 'test' -m 'hello'
mosquitto_sub -h localhost -t 'test'

MCU Not Publishing:

• Verify Wi-Fi credentials in config.py or IoTflow Forge configuration (If corrupted you may need to erase all EEPROM data.)
• Check MQTT broker IP address and port settings
• Ensure <MQTT_BASE_TOPIC> matches across device and Node-RED
• Ensure IoTflow Kernel is running (check main.py execution)
• Monitor serial console for error messages in Thonny or any compatible IDE

Node-RED Flow Not Triggering:

• Verify MQTT topics match exactly between device and nodes
• Check that iotextra nodes are configured with correct broker address
• Enable debug nodes to monitor incoming messages via serial
• Confirm messages are being received using MQTT subscriber:

bash

mosquitto_sub -h localhost -t '<MQTT_BASE_TOPIC>/#' -v

IoTflow Forge Configuration Issues:

• Ensure microcontroller is properly connected via USB
• Check that MicroPython is installed on the device
• Verify config.py was successfully written to device and correctly configured
• Reboot device after configuration changes so it boots from EEPROM

Hardware Connection Problems:

• For IoTsmart modules: Ensure SoM Module is properly seated in HOST connector slot
• For flashing: Use IoTsmart adapter cable (not direct connection)
• For IoTextra modules: Verify module is fully inserted into HOST connector
• Check power supply to IoTbase (USB or external 5V)
• Verify I²C connections if using I²C interface mode

Performance and Best Practices

Topic Naming Conventions

• Use hierarchical structure: project/location/device/sensor
• Keep topics short and descriptive
• Use consistent naming across all devices to avoid confusion in your workflow

Custom Message Optimization

• Publish only on state changes (not continuous polling)
• Use retained messages for device status
• Implement QoS 1 for critical commands
• Batch multiple readings in single message when appropriate

Scaling Considerations

• One MQTT broker can handle 100+ IoTflow devices
• Use Node-RED subflows for reusable logic
• Implement device health monitoring
• Set up automated backups of configurations

Next Steps and Resources

Expand Your System

• Add more IoTextra modules for additional I/O
• Integrate with stable cloud platforms (AWS IoT, Azure IoT)
• Build custom dashboards with Node-RED UI
• Implement data logging and analytics

Additional Resources

• GitHub Repository: IoTflow Documentation
• Video Demos: Hardware and workflow demonstrations
• Open Hardware Files: All IoTextra modules are Open Hardware and information can be found in makethingshappy.io official website

Learn More About Make Things Happy

The Make Things Happy platform provides:

IoTextra: Modular I/O hardware (Digital, Analog, Combo)

• Digital: https://makethingshappy.io/collections/digital-iotextra
• Analog: https://makethingshappy.io/collections/analog-iotextra
• Combo: https://makethingshappy.io/collections/combo-iotextra

IoTsmart: Compact wireless MCU nodes

IoTbase: Full-featured serial-ready solutions

IoTflow: Orchestration layer (this tutorial)

All hardware is Open Hardware, well-documented, and designed for the prototype-to-production journey.

Conclusion

IoTflow bridges the gap between rapid prototyping and production-ready IoT automation. By starting with IoTsmart for quick validation and scaling to IoTbase for deployment, you maintain the same codebase, workflows, and automation logic throughout your project lifecycle.

The combination of IoTextra modules, standardised MQTT communication, and Node-RED visual programming creates a powerful, flexible platform for building real-world industrial IoT solutions.

Key Takeaways:

• ✅ No-code automation with Node-RED
• ✅ Consistent workflows from prototype to production
• ✅ MQTT-based, standards-compliant architecture
• ✅ Open Hardware, fully documented
• ✅ Scalable to hundreds of devices, with potential for more depending on your own architecture and design philosophy.

Start building your IoT automation today with IoTflow!