Run Home Assistant on Arduino Uno Q with Docker and MQTT

Why Run Home Assistant on the Arduino Uno Q?

Running Home Assistant on the Arduino Uno Q means using its Linux processor to host Docker containers while the STM32 microcontroller drives physical GPIO, with MQTT and a bridge script passing messages between them so a single board can act as both home automation server and hardware controller.

Think of the Uno Q as a tiny two-part computer: one side is a Qualcomm-based Debian Linux system that runs Docker, Python, networking tools, and your Home Assistant Docker container; the other side is an STM32U585 microcontroller that behaves like a classic Arduino sketch runner and talks to the real pins. The two do not share memory or a network stack, so an explicit communication path is required. This is where the MQTT microcontroller bridge and Router Bridge come in, forming a chain from the Home Assistant dashboard to the physical LED on the board.

If you have ever set up development boards like the ESP32-CAM, where you first learn the hardware, identify GPIO pins, wire a programming adapter, configure an IDE, upload a first sketch, and fix wiring or power issues, this project will feel familiar. The difference is that here your embedded Linux IoT side looks like a miniature server. The payoff is that flipping a virtual switch in Home Assistant can toggle the Uno Q’s onboard LED automatically, no manual dashboard editing needed.

What You Need and How the Architecture Works

Before touching commands, be clear on the architecture: Home Assistant runs in Docker on the Uno Q’s Linux processor, an MQTT broker in another container handles messages, a Python script on Linux bridges MQTT to the Router Bridge, and an STM32 sketch exposes functions that drive the onboard LED. This chain is the mental model you will use whenever something misbehaves.

Hardware-wise, you need an Arduino Uno Q, a USB-C cable, and a computer on the same network to SSH in and open the Home Assistant dashboard. You also need Arduino App Lab on that computer to handle the first boot and Wi‑Fi setup for the board. If you are used to working with boards like the ESP32-CAM, where an FTDI USB-to-TTL adapter, jumper wires, and a USB cable are standard equipment, this requirement set will look modest by comparison: no extra components are required for the base LED example.

On the software side, the Uno Q’s Linux environment usually ships with Docker tooling because App Lab already relies on containers. The STM32 microcontroller runs sketches much like any other STM32 home automation project, driving GPIO pins once it receives commands over the Router Bridge. The key advantage is that this dual Linux and microcontroller architecture enables containerized applications alongside low-level I/O on a single board, a neat embedded Linux IoT platform when you do not want a full PC or separate microcontroller board.

Step-by-Step: From SSH Login to LED Control

Here is the full Arduino Uno Q setup to get Home Assistant Docker, MQTT, and the STM32 LED example working. Follow the order; most headaches come from doing steps out of sequence or forgetting which processor you are working on.

1. Connect and SSH into Linux: Power the Uno Q over USB-C, connect it to your network using App Lab for the initial Wi‑Fi setup, then SSH into the Linux side with ssh arduino@<uno-q-ip-address>. Run whoami and hostname -I to confirm your user and IP, and write that IP down for later Home Assistant access. Do not assume this IP is permanent; DHCP or router reboots can change it, and a stale IP is a common cause of failed connections.
2. Check or install Docker: On the Linux side, run docker --version to see if Docker is preinstalled as part of the existing container stack. If it is missing, install it with the official script and then add your user to the docker group so you are not prefixing every command with sudo. Log out and back in so group changes take effect. If the script warns that Docker is already present, cancel instead of forcing a reinstall, as that can break the current setup.
3. Run Home Assistant in Docker: Start Home Assistant as a Docker container on the Uno Q’s Linux side with a command that runs it detached, sets a timezone, persists configuration under ~/homeassistant, and uses host networking. After a minute, confirm it is running with docker ps, then open http://<uno-q-ip-address>:8123 from your computer to complete the onboarding wizard. For a quick health check, add the Demo integration in Settings → Devices & Services so you can see fake lights and switches before you layer on MQTT and real hardware.
4. Add the MQTT broker container: Since this Home Assistant Docker setup does not include an add-on store, run an Eclipse Mosquitto container yourself, mapping port 1883 and binding Docker volumes for configuration and data under ~/mosquitto. If the config directory was created by Docker, change its ownership to your user so you can write files there without permission errors. Then create a mosquitto.conf with a listener 1883 and allow_anonymous true so Home Assistant and your bridge script can connect; Mosquitto 2.x defaults will otherwise block non-local, anonymous connections.
5. Bridge MQTT to the STM32 and test LED control: On the Linux side, use a Python script that connects to the MQTT broker, subscribes to a topic for LED control, and forwards messages over the Router Bridge to the STM32. On the MCU side, load a sketch that exposes a function such as set_led_state via Bridge.provide, so the Linux script can call it by name. Once this chain is in place, create or use an automatically discovered switch entity in Home Assistant that publishes control messages; toggling that switch should turn the Uno Q’s onboard LED on and off in real time, showing that Home Assistant, MQTT, Linux, and the microcontroller are all in sync.

The most common mistakes look a lot like those you hit when setting up microcontroller boards: mismatched connections and missing configuration. For ESP32-CAM projects, issues such as GPIO0 not being pulled to ground, TX/RX lines swapped, unstable 5 V power, the wrong COM port, a loose camera ribbon, or the wrong board selected in the IDE cause most upload failures. Here, the equivalents are pointing your browser at an old IP, skipping the Mosquitto listener or allow_anonymous settings, or forgetting which side of the Uno Q a given script is running on. According to one guide, “this is the single most common failure point in this whole setup” when describing Mosquitto’s default configuration blocking connections.

What You Get Once It Works (and How to Grow It)

When all the pieces click, you end up with three things: Home Assistant running in Docker on the Uno Q’s Linux side, an MQTT broker container bridging Linux and the STM32 microcontroller, and a working example where toggling a switch in the Home Assistant dashboard turns the Uno Q’s onboard LED on or off. That LED entity appears automatically, so you do not have to hand-edit the dashboard to see it. It is a clean, end-to-end demonstration of embedded Linux IoT where containers and microcontroller code share a single board.

From there, the pattern is the same as with an ESP32-CAM camera web server project: once the base configuration is stable, you can build many projects on top, from extra LEDs and relays to sensors and monitoring systems. On the Uno Q, each new physical device becomes a GPIO on the STM32 sketch, a Bridge-exposed function, an MQTT topic, and a Home Assistant entity. You stay within the same STM32 home automation loop while gaining the full Home Assistant ecosystem for dashboards, automations, and integrations.

The trade-offs are mostly about complexity. You must think in terms of two processors, a message broker, and containers instead of a single sketch. The reward is flexible control: your Uno Q behaves like a mini server and a microcontroller board at once. As you expand, keep an eye on IP address changes, MQTT configuration, and which side of the board a given bug lives on, and you will avoid most of the gotchas that trip people up.