Best Setup for Running Robot Software on a Raspberry Pi

For a Raspberry Pi robot, the best setup is Raspberry Pi OS, one Python program, and middleware such as ROS 2 or HORUS later. A Pi has room for a real robot as long as nothing on it does work twice, and most Pi trouble is power, storage or Wi-Fi, not the board. What flips that: a robot needing mapping or a vendor's driver should start on ROS 2. The rest of this post is for someone with a Pi, a motor board and a plan, deciding what to install before writing any robot code.

You flashed a card, plugged the board in, and got a desktop, and that felt like progress. Then it got strange. The install instructions for the framework everyone recommended did not have a line for your operating system, so you tried building from source and went to bed while it compiled, and in the morning it had stopped on an error you cannot read. You tried a different image and lost your camera. The board works on the bench with a power brick and reboots itself the moment the motors draw current on battery. Wi-Fi drops when the robot drives to the far side of the room, taking your terminal with it. Twice now the card has come back corrupted after you pulled the plug, and you have re-flashed everything from scratch. Meanwhile you have not written a line of code that makes the machine do anything, and you are starting to suspect the board is too small for what you want. That last suspicion is usually wrong, and the rest of the trouble has ordinary causes.

What is the best software setup for a robot on a Raspberry Pi?

Raspberry Pi OS, running one Python program you start yourself, with nothing else between your code and the hardware. That setup gets a robot moving in an evening, keeps camera support and hardware pins working the way every tutorial assumes, and leaves you with a machine simple enough to reason about when something misbehaves. Skip the desktop and use the version without a graphical environment if the robot will not have a screen, since a desktop consumes memory to draw a picture nobody looks at. Connect over SSH, keep your code in a folder, and start it by hand while you are still learning what the robot does. Everything else people recommend — containers, a framework, a service that starts your code at power-on, a message layer — is a solution to a problem you may never have, and each one costs you an evening and a category of failure. Add them one at a time, when a specific difficulty makes the reason obvious. The best setup for a first Pi robot is the one with the fewest moving parts you did not choose deliberately.

What does a robot software setup on a Pi actually consist of?

A robot setup is four decisions stacked on top of each other, and people usually argue about the wrong one. The bottom is the operating system image: Raspberry Pi OS, Ubuntu Server, or a vendor's own image that came with your kit. Above that is where your code lives and how it starts: a folder you run by hand, a service that launches at power-on, or a container that carries its own dependencies. Above that is how your programs talk to hardware: a Python library for the pins, a camera library, a serial link to a motor board. And at the top is how your programs talk to each other, which is the layer people call middleware and which only exists once you have more than one program. Most of the pain a beginner feels comes from the first two decisions, not the last. Choosing a framework before you have chosen an image and a way to start things is how people end up with a board that boots into something they cannot fix.

What are your actual options for the software layer on a Pi?

You have seven realistic setups, and they differ mostly in how much you install before your robot moves. You can run one Python program on Raspberry Pi OS, which is the fastest route to a working machine. You can keep that program and add a small microcontroller over USB to hold motor timing, which fixes twitchy motion without changing your software approach. You can install ROS 2 natively on Ubuntu Server, which is the smoothest ROS 2 path but means giving up some Raspberry Pi OS conveniences. You can run ROS 2 in Docker on top of Raspberry Pi OS, keeping the camera stack you know while containing the framework. You can use a lighter middleware built for programs sharing one board, such as HORUS, an open-source real-time robotics middleware for Rust, Python and C++ where the three languages share the same shared-memory ring buffers, so messages between processes on one machine are not serialised, which suits a Python program working beside a Rust or C++ loop. You can run an MQTT broker and separate programs. Or you can stay on the vendor's own image and use what came with the kit.

What should you install if this is your first robot?

Install Raspberry Pi OS without a desktop, enable SSH during flashing, and write one Python program. That is the whole list, and adding to it now costs you time in exchange for capability you cannot yet use. Set the hostname during flashing so you can reach the board by name instead of hunting for an address. Put your Wi-Fi details in at the same time. Then make one file that reads a sensor, prints the reading, and stops, and get that running before you attach a single motor — the first hour of a Pi robot should establish that you can reach the board, run code, and see output, because every later problem is easier when those three are known good. Once motors are attached, keep the robot on blocks with the wheels off the ground until you trust it. Resist installing a framework at this stage, not because frameworks are bad, but because you will not be able to tell whether a problem is your code, your wiring or your new layer.

What hardware around the Raspberry Pi actually matters?

Power matters more than everything else combined, and it is the cause of most inexplicable Pi robot behaviour. A board that reboots when the motors start is not a software problem: motors pull current in sudden bursts, and a supply shared with the Pi will sag below what the board needs. Give the motors their own supply with a common ground, and give the Pi a source that can hold steady when the robot moves. Storage is second. SD cards wear out and corrupt when power disappears mid-write, which is exactly what happens when a robot drives into a table and you yank the plug, so an SSD over USB is the upgrade that saves the most evenings. Cooling is third: a board that gets hot quietly slows itself down, and a robot that behaves for a while and then gets sluggish is often just warm. After that comes memory, which decides how comfortably a camera and a planner coexist. The processor is rarely your limit, and whether Python is fast enough for robot control is a better question than which board to buy.

What if you have a competition or demo in a fortnight?

Freeze your setup now and change nothing below your own code. Two weeks is enough time to make a robot do something specific and nowhere near enough to survive an operating system change, a framework installation or a move to containers, because each of those brings failures you have never seen and will meet under pressure. Take an image of your working card today so you can restore it after any disaster. Then spend the fortnight on three things: making the one behaviour work, making it start reliably, and making it recover from the obvious failure. If motion is jittery, do not restructure — reduce what runs alongside the motor loop, or move the timing to a microcontroller if you already have one wired. If the camera stalls the wheels, process fewer frames. If Wi-Fi drops, stop relying on Wi-Fi during the run and log to disk instead. Write down every patch as a patch. After the demo, with nothing at stake, is when you decide what the setup should actually be.

What if Python is the only language you know?

Python alone runs a genuinely useful Raspberry Pi robot, and the wall you eventually hit is about shape rather than language. Reading sensors, deciding what to do and driving motors are all comfortable in Python, and enormous amounts of real robot work happens exactly this way. What Python struggles with on a Pi is holding a steady rhythm while also doing something heavy, because the heavy work and the rhythm compete inside the same program. The first fix is to do the slow thing less often. The second is a thread, which helps until it produces a fault you cannot reproduce. The third is either a separate program for the heavy part or a microcontroller for the timed part, and both are good answers. Many small robots settle exactly there: thinking in Python where changes are pleasant, timing handled by something that cannot be interrupted, and data moving between them. When you reach that point, publish and subscribe explained without jargon covers the vocabulary you are about to meet.

What does a struggling Raspberry Pi robot actually look like?

A struggling Pi robot behaves differently on battery than on the bench, and that difference is the most useful clue you will get. The specific symptoms come in a small set. The board reboots itself when the wheels turn, which is power. The robot behaves for a few minutes then goes sluggish, which is heat. Everything is fine until the camera is enabled and then the wheels hesitate on a rhythm, which is one loop doing two jobs. The card fails to boot after an unplanned shutdown, which is storage. Your terminal disconnects at the far side of the room and the robot keeps going, which is Wi-Fi and not the robot. Notice that only one of those is a software design problem. The mistake beginners make is treating all five as evidence that the Pi is too small, then buying a bigger board that reboots for exactly the same reason. Diagnose in this order: power, heat, storage, network, and only then the shape of your program.

What do people try first on a Pi, and why does it stop working?

Most people start by installing the framework their favourite tutorial used, and it stops working because the tutorial assumed a different image. The sequence is predictable. You flash Raspberry Pi OS because that is what the board's own documentation says, then follow ROS 2 instructions written for Ubuntu, then discover the packaged install does not match your system. You try building from source overnight, which sometimes works and leaves you with a system you cannot rebuild after the card dies. You switch to Ubuntu and lose the camera tooling that made Raspberry Pi OS pleasant. Somewhere in here you have spent a week and the robot has not moved. The second common start is the vendor image that came with the kit, which works beautifully until you attach a sensor the vendor never sold, at which point you are inside somebody else's system with no documentation. Neither start is stupid. Both skip the step where you get your own code running on a plain image first.

What do you give up by running everything on one Raspberry Pi?

You give up headroom, and headroom is what lets you be careless. On one board, every new thing you add competes with everything already there for memory, for processor attention and for the same operating system that can pause any program at any moment. That means heavy vision work, a planner and a control loop on one Pi will eventually interfere, and the interference shows up as motion that is not quite smooth rather than as an error message. You also give up some independence: one card failing takes the entire robot with it, where a Pi plus a microcontroller keeps the motors under control even if the bigger board is rebooting. And you give up the option of a graphical tool running alongside your robot, since a desktop and a simulator on the same board are a poor use of what you have. What you get in exchange is a robot with one place to look when something is wrong, which for a first machine is worth more than headroom.

When is ROS 2 the better choice?

ROS 2 is the better choice on a Raspberry Pi whenever the point of your robot is work other people have already done. A machine that must build a map of a room, plan a route and drive to a chosen point is a ROS 2 project, because mapping and navigation packages represent years of effort that nobody reproduces on a weekend. If the sensor you bought ships only a ROS 2 driver, that settles it. ROS 2 also wins when the Pi is one computer among several, when you want to record a run and replay it later, and when you are learning toward a job where ROS 2 is what everyone speaks. HORUS is not the answer for those robots, and choosing it there means writing plumbing you could have inherited. The honest costs on a Pi are real: ROS 2 expects Ubuntu or a container, wants more memory than a bare Python program, and asks for a stretch of learning before the robot does anything new. Whether ROS 2 is too heavy for a small board is worth reading before committing.

Is a Raspberry Pi simply too weak for real robot software?

No, and here is why: the jobs that make robots feel demanding are mostly not the jobs a Pi is bad at. Reading sensors, deciding what to do, driving motors, following a line, avoiding obstacles, running a state machine and talking to a phone are all comfortable on a modern Pi with memory to spare. What a Pi genuinely struggles with is heavy vision on every frame, large learned models running locally, and holding a strict rhythm while the operating system is busy elsewhere. Those are three specific limits, not a general verdict, and each has a normal workaround: ask less of the camera, run the model somewhere else, or hand the rhythm to a microcontroller. The reason people conclude the board is too weak is that power, heat and storage problems produce symptoms that look like weakness. Rule those out before you shop. Most robots that outgrow a Pi do so for the vision workload specifically, and they know precisely which part is too much.

Do you need a real-time operating system on a Raspberry Pi?

Partly, but not the way you think. What people want when they ask this is motion that does not hesitate, and the usual cause of hesitation is not the operating system at all — it is one program doing two jobs, or a camera read sitting in the same loop as a motor update. Fix that first, because it is free, and most robots stop hesitating. Where the operating system genuinely matters is when a control loop must never be interrupted, and there the honest answer for a Pi is that a general-purpose Linux can pause anything at any moment, whatever you do to it. Real-time kernel patches narrow that window and do not close it. The setup people actually ship for this is a division of labour: a small microcontroller holds the timed loop and the safety cutoff, while the Pi does the thinking and sends it goals. That arrangement is simpler than tuning a kernel and it fails more predictably.

How do you decide which Raspberry Pi setup to start with?

Start with the simplest setup that can express your robot's actual job, and let the machine tell you when to add a layer. Write down what the robot must do in one sentence. If that sentence contains mapping, navigating a building, or a sensor with a ROS 2 driver, go to Ubuntu and ROS 2 now, because retrofitting later costs more than starting there. If it does not, install Raspberry Pi OS and write one Python program, and stay there until a specific symptom forces a change. When a symptom does arrive, match it to a fix rather than to a framework: jittery motion means a microcontroller, a stalling camera means a separate program, a corrupted card means an SSD, a robot rebooting means power. Only once you have two programs that must swap data while the robot moves does the middleware question become real, and then it is a choice between borrowed packages and a lighter layer for one board.

Decide by situation rather than by what the popular tutorial used:

• If this is your first Pi robot -> Raspberry Pi OS and one Python program, because every extra layer hides which part is broken.
• If your wheels or joints twitch -> add a microcontroller for timing, because a general-purpose operating system will always pause you sometimes.
• If you need mapping, navigation or a ROS 2 driver -> Ubuntu Server and ROS 2, because those packages are the project.
• If you have a Python program and a Rust or C++ loop on one board -> a shared-memory middleware, because that boundary is the expensive part.
• If a competition is close -> freeze the setup and image the card, because new layers bring new failures at the worst moment.

When two setups stay close, weigh them on the five axes of the HORUS Fit Framework — ecosystem size, setup effort, team size fit, deployment target, and licence — and take the one that loses on the fewest. Five honest questions about your situation rather than about the software. And when your Pi robot grows past one program, star HORUS on GitHub so it is in your list when you start building.