Why Humanoid Demos Look Better Than Humanoid Products

Humanoid demos look better than humanoid products because a demo is one rehearsed run in a room the team chose, and no middleware changes that. A product repeats that run for strangers, in changed light, around clutter nobody placed on purpose. The gap becomes a software problem only when the demo stutters on a quiet bench, which points at the stack under it: ROS 2, a vendor kit or HORUS. The rest of this post is for someone who watched those videos and now has to choose what to build a real robot on.

You watched a robot fold a shirt, or pour a coffee, or walk down a stairwell, and then read a comment underneath saying the whole thing was driven by a person in a motion capture suit. You do not know which parts to believe, and you have a project that has to work in front of somebody in a few months.

The unease is specific. If the videos are honest, the field is further along than your own progress suggests and you are doing something wrong. If the videos are staged, the sensible response is to ignore them, except that funding and hiring follow those videos, so ignoring them carries its own cost.

Underneath both readings sits a practical question about your own build. Your prototype does the thing once, sometimes twice, and then does something strange on the fourth attempt and you cannot say why. That failure feels related to the distance between a demo and a product, and you want to know whether it is the same problem at a smaller scale, and whether a different software layer helps or just moves it sideways.

Why does a humanoid demo look so much better than the product that follows?

A demo is allowed to fail and a product is not, and nearly everything else follows from that asymmetry. A demo happens in a room the team chose, on a floor they measured, with objects placed where the robot expects them, after enough takes that the failure modes are known and steered around. Somebody stands just outside the frame with a stop button. The battery is fresh, the wireless link is quiet, and when a run goes wrong the camera stops and the run happens again. None of that is dishonest, and it is how any hard demonstration has ever been filmed. A product gets none of those permissions. The machine goes into a building nobody surveyed, in front of people who did not rehearse, and has to do the same thing on a Wednesday afternoon while the engineer who wrote the code is asleep in another country. The behaviour in the video is real. What the video omits is the many variations of that behaviour a product must survive, most of which end in the robot stopping safely rather than succeeding.

What does it actually mean to call software demo-grade?

Demo-grade software produces the right behaviour once, under conditions the author chose. That is a real achievement and it is also a narrow one. Demo-grade code assumes the object is on the table, the light is the light from yesterday, the operator restarts anything that hangs, and nothing walks into the scene halfway through. Product-grade software carries the same behaviour plus the far larger body of code that decides what to do when the assumption breaks. The arm stops before it hits the table. The gripper notices it closed on nothing and tries once more from a different angle. The robot refuses to start when a camera has gone quiet, instead of moving blind. Nobody films that layer, because it looks like a robot standing still. The uncomfortable arithmetic is that the recovery layer is usually bigger than the behaviour it protects, and it is written after the video is published, which is why the gap between an impressive clip and a shipped machine is measured in years rather than sprints. Signs your robot prototype will not survive production lists the tells worth checking in your own build.

What are your options for the software under a humanoid application?

You have five realistic options and most teams combine two of them. The first is the robot maker's own software development kit, which is where every project starts because nothing else can command the machine at all. The second is ROS 2 layered on top of that kit, which is where most developers end up, because mapping, navigation, arm planning, recording and replay already exist there and rewriting them is a career rather than a quarter. The third is a stack you write yourself, honest work for one narrow product and a trap for anything that keeps growing. The fourth is a training setup such as Isaac Lab, chosen when the behaviour has to be learned rather than programmed. The fifth is a single-machine middleware such as HORUS, which matters when everything runs on one onboard computer and your Rust, Python and C++ programs must hand data to each other on a fixed rhythm without being serialised on the way. Vendor kit plus ROS 2 covers most humanoid application work.

How do the humanoid stack options compare?

The rows run from the layer closest to the motors to the layer furthest away, which is roughly the order teams adopt them.

Read the last two columns first. Teams choose on the first two and meet the disqualifier a quarter later.

Which option fits if you are a small team trying to reach a product?

Start on the vendor kit, move to ROS 2 as soon as recovery becomes the work, and resist writing your own layer until you can name the thing the existing ones refuse to do. Small teams fail at the humanoid product stage in a predictable way: they build the demo behaviour quickly, feel encouraged, and then spend the next year discovering that the interesting part was everything around the behaviour. ROS 2 helps there specifically because the parts you would otherwise write badly, such as coordinate frame handling, recording a run and replaying it while you argue about it, and a planner that already knows about obstacles, exist and are used by people who have hit the same walls. The counter-case is a team of two shipping one machine that does one job, where a full ecosystem is weight you carry without using. How small robotics teams ship faster than big ones is worth reading before you decide you need the whole thing.

What if the whole robot runs on one onboard computer?

Then the messaging layer becomes a real choice rather than a formality, because most middleware arguments are arguments about crossing boundaries. Data that stays inside one machine can be handed between programs directly. Data that crosses to a second board, and especially data that crosses a wireless link, is where late frames, dropped messages and the familiar complaints begin. So a humanoid whose perception, decision and logging code all sit on the main onboard computer is in a different situation from one that leans on a laptop over the network, even if the code looks identical. If everything is on one machine, pick for the ecosystem, because the messaging layer is a convenience question. If your design sprays work across boards and a laptop, the messaging layer decides whether the robot behaves the same way twice, and that becomes the thing to design carefully rather than the thing to inherit. Should your robot run one computer or several works through the trade in more depth.

What should you use if a demo is due in a month?

Use the vendor kit alone and add nothing else until the demo is over. A deadline punishes every additional layer, because each one is another place something can be misconfigured on the morning it matters. A humanoid demonstration in front of people needs three things: a reliable stop, a behaviour rehearsed until its failure modes are known, and the smallest number of moving parts in the software you can manage. The vendor's own calls give you all three with the fewest unknowns. If the demo needs something the kit does not do, add exactly one piece rather than an ecosystem, which usually means a short script beside the kit rather than a full graph of programs. Teleoperation is also a legitimate answer to a deadline, and saying plainly that a person is driving is far better than an autonomous claim that collapses on stage. Teleoperation versus autonomy in robot demos is a useful calibration before you promise anything.

What skill level does product-grade humanoid work assume?

More than the tutorials give you and less than a doctorate, with the difficulty in an unexpected place. The entry requirement is comfort in a Linux terminal, one language between Python and C++, and patience with error messages that describe a graph of programs rather than a single program. What makes humanoid work harder than the wheeled robot in the guides is not the code, it is that a humanoid can fall, so every mistake carries a physical cost and the machine belongs on a stand or a gantry until you trust yourself. The second difficulty is coordinate frames, because a humanoid has many joints and several cameras, and confusion about which frame a measurement lives in produces a robot that reaches confidently towards where the object is not. The third is the one nobody warns about: writing recovery code is a different skill from writing behaviour code, and it is learned by watching your own robot fail in ways you did not imagine.

What do teams try first, and why does it stop working?

Teams almost always try to harden the demo, and it stops working because the demo was never the hard part. The sequence is familiar. The behaviour works in the lab, so somebody adds a retry. Then a check that the object is really there. Then a timeout, because sometimes the arm waits forever. Then a special case for the chair that is usually pushed in. Each addition is reasonable and the whole becomes a pile of exceptions nobody can reason about, and the robot's behaviour on any given run depends on which exception fired first. The tell that you are in this pattern is that fixes stop being local: changing the grasp logic breaks the approach, and adding a check for one failure creates a new way to hang. The way out is not more exceptions, it is a structure where the robot has an explicit sense of what it expected and what it observed, and a defined thing to do when those disagree, including doing nothing and calling a human.

What do you give up by choosing a lean single-machine stack?

You give up the packages, and that is a larger loss than it sounds. A single-machine messaging layer hands you a clean way for programs in different languages to share data on one computer, and hands you nothing else. No mapping. No arm planner. No coordinate frame library that other people have already argued about. No vendor bridge, so connecting to the robot is your work. No recording format that a colleague's tool can open. For a humanoid, that list is close to the whole job, because a humanoid application is mostly perception and planning wrapped around a controller you are not allowed to touch. The narrow case where the trade pays is a system where all the code lives on the onboard computer, several languages are genuinely in play, and the fixed-rhythm handoff between them is what keeps failing. That is a real situation, and it is a slice of humanoid work rather than the shape of it.

When is ROS 2 the better choice?

ROS 2 is the better choice for almost every humanoid project aimed at a product rather than a paper. If your work involves mapping a building, navigating it, planning an arm motion around an obstacle, handling coordinate frames without inventing your own conventions, or recording a failed run so five people can watch it again, those capabilities exist in the ROS 2 world in a depth that nothing else matches. ROS 2 also wins when the team is larger than a few people, because it is the only vocabulary a new hire is likely to arrive already speaking, and it wins when the work must be handed to a customer or reviewer who expects a recognisable structure. HORUS is not the answer in those cases, and choosing a shared-memory layer for one machine when what you needed was a planner and a bridge costs you a quarter you will not get back. The narrower case for a different layer is a single onboard computer running mixed-language code on a fixed rhythm.

Is the demo-to-product gap caused by the middleware?

No, and here is why. The gap exists because nobody has solved acting sensibly in unfamiliar rooms, and that would remain unsolved if every messaging layer were replaced tomorrow. A robot that folds laundry in a studio and fails in a stranger's bedroom is failing at perception in unfamiliar conditions, at knowing when it is confused, and at deciding what to do about it. None of those live in the middleware. What the middleware genuinely affects is a narrower and still important band: whether messages arrive before the next control cycle needs them, whether a busy process makes an unrelated part of the robot hesitate, and whether two runs of the same code produce the same sequence of events. Those matter, and they are the reason a robot can look fine on the bench and jittery in the field. But they explain the last part of the gap rather than the first. Why robot demos work and robot products do not goes through the causes in order of size.

Does a rewrite fix a robot that only works sometimes?

Partly, but not the way you think. A rewrite does fix one specific class of problem, which is the accumulated pile of exceptions described earlier, where the structure has been outgrown and nobody can predict what a change will do. Rebuilding around a clear idea of expectation, observation and disagreement genuinely helps, and teams that do it report that the robot becomes explainable again. What a rewrite does not fix is the underlying gap in what the robot can perceive and decide, so the rewritten system fails in the same places for the same reasons, just legibly. The practical test before committing to a rewrite is whether you can name the failures you expect to disappear. If the answer is a list of specific behaviours, a rewrite may be right. If the answer is that everything will be cleaner, you are about to spend six months and arrive at the same robot. Why humanoid startups keep rewriting their software stack covers what usually triggers the decision.

How do you decide what to build the product version on?

Decide by naming the layer your actual work lives in, then pick the smallest thing that reaches it. If your work is application logic, so recognising a situation and deciding what the robot should do, start on the vendor kit and add ROS 2 when you want packages you did not write. If your work is perception and navigation, go to ROS 2 immediately. If your work is a new gait or whole-body control, middleware is not your first question at all, because most platforms do not hand over that authority regardless of what you build on. Then check three practical things. Check which ROS 2 release your vendor supports, since a mismatch there costs weeks. Check whether the onboard computer will hold your whole system or whether the design quietly assumes a laptop nearby. And check the exit, because task logic and learned policies move between platforms while vendor-specific calls and launch files do not. How robotics teams decide to switch middleware is the version of this written by people who did it late.

Where that leaves you, in five lines:

• If you are choosing a platform after watching demos -> the vendor SDK first, because nothing else moves the machine at all.
• If you are a small team heading for a product -> ROS 2, because recovery, mapping and replay already exist there.
• If everything runs on one onboard computer in several languages -> a shared-memory layer, because a network-shaped path buys you nothing there.
• If your prototype already stutters on a quiet bench -> fix the layer underneath before adding behaviours, because new features inherit the wobble.
• If you have a deadline and an audience -> one rehearsed behaviour on the vendor kit, because every extra layer is another thing to misconfigure.

The HORUS Fit Framework is the compact form of that reasoning, along five axes that travel well beyond humanoids: ecosystem size, setup effort, team size fit, deployment target and licence. Humanoid teams reliably underrate deployment target, then discover the design assumed a laptop within wireless range. To see failure modes before you own hardware, the best visualisation and debugging tools for robot projects is the cheaper place to start.

HORUS is open source under Apache-2.0 at github.com/softmata/horus. Star it so it is in your list when you start building.