Skip to content

There are two computers on this board, and they do not get along by default

The Arduino UNO Q runs Debian Linux on a quad-core 64-bit processor and Zephyr on a 32-bit microcontroller, on one circuit board, wired together. This is a course in making them cooperate — written for someone who can program, and has never done embedded development.

Start the course Set up a board Browse the reference

The thing you will build

Linux measures how busy its four CPU cores are. It sends those four numbers down a serial line to the microcontroller. The microcontroller draws them as four bars of light on an 8×13 LED grid, refreshing the panel about a thousand times a second so your eye sees a steady picture instead of a flicker.

It is deliberately unglamorous, and every part of it is load-bearing. Linux cannot draw that panel — you will measure exactly why. The microcontroller cannot read /proc/stat — it has no filesystem, no processes and 786 KB of memory. Neither chip can do the job alone, which is the entire argument for a board that has both.

The big one — MPU

Qualcomm QRB2210. Four 64-bit cores, gigabytes of memory, Debian 13, a network stack, a package manager and a filesystem.

Good at networking, storage, AI models, anything large or open-ended.

Bad at doing something at an exact microsecond. The kernel will preempt you whenever it likes, and it is right to.

The small one — MCU

STMicroelectronics STM32U585. One 32-bit Cortex-M33 core, 786 KB of RAM, Zephyr RTOS, and nothing between your code and the pins.

Good at timing you can rely on, and hardware you talk to directly.

Bad at everything the big one is good at. There is no filesystem to read and no network to reach.

The course

Sixteen short chapters, meant in order. Each one introduces an idea, then puts you in front of the real board to watch it happen.

  • What is actually here

    Two processors, two kinds of software, and the vocabulary to argue about which job belongs where. Then a tour of each side on its own terms.

    Start here

  • Making them cooperate

    A serial line, a framing protocol, a cross-compiler, and a panel of LEDs that only exists because of persistence of vision.

    How they talk

  • Living with real hardware

    Firmware updates that undo themselves when they go wrong, one USB cable pretending to be three devices, and debugging a program that cannot print.

    Updating safely

  • Making it yours

    What to build next, where the unfinished work is, and how to change this project without breaking the board.

    Make it yours

Why this exists

Most embedded tutorials stop at blinking an LED, and most Linux tutorials never mention that a computer can miss a deadline. The interesting engineering is in between: two processors with genuinely different strengths, a wire between them, and a set of decisions about who does what.

This project is a factory-fresh UNO Q turned into a working development board one script at a time, with everything that went wrong written down. The course teaches the stack. The reference records the detail, including the parts that took days to work out. The findings log is the unedited list of things that were wrong the first time.

  • Reference

    The exact detail, for someone who already knows the material: pin assignments, protocol framing, systemd units, recovery procedures.

    Hardware · MPU · MCU · USB

  • When it breaks

    It will. Symptom-first: what you saw, what it usually means, and what to run next.

    Troubleshooting

  • Further reading

    The free material this course is built on — Zephyr, the kernel docs, Bootlin, Beej, Nand2Tetris — annotated with what each one is actually good for.

    Further reading

  • The source

    Every script, sketch and test, MIT licensed. The provisioning is the project: you should be able to reproduce this board from a factory reset.

    On GitHub

Three ways to read this

You are looking at one of them. All three are built from the same markdown, by the same command, so they cannot disagree about what the board does.

Where How you get there Needs
GitHub The docs/ folder in the repository A browser
The board http://<board>:8080/ — served by unoq-learn The board running
The USB drive The UNO-Q drive that appears when you plug the board in Nothing at all

The drive is the point of the third one. Open it on a laptop with no network, no account and no installed tools, and the whole course is there — search included.