Unitree G1 and ROS 2: What Works Out of the Box

Plan a Unitree G1 project around ROS 2 for perception and autonomy, and around Unitree's own kit for anything that keeps the robot upright. The robot speaks its own message format over a network interface you must configure, and nothing in the box is a maintained ROS 2 driver. That flips only if your own Rust, Python and C++ processes on the robot must trade data every tick, the problem HORUS addresses. The rest of this post is for someone with a G1 on order or on the bench, deciding what to build first.

You have watched the videos. The robot walks, dances, gets shoved and recovers, and none of that tells you what you will be looking at on the first Monday. What you have found instead is a scatter of repositories: one with message definitions, one with examples written against an older release, one full of model files, and a configuration file wanting the name of a network interface on your machine.

Half the forum answers you find are about a different robot from the same maker, and you cannot tell which parts carry across. Someone says the whole thing is just topics and works fine. Someone else spent two days seeing nothing at all until they changed one line in a configuration file. Both are probably telling the truth.

Underneath the confusion is a decision you have to make before the crate arrives, because it shapes what you buy and who you hire. Is this a ROS 2 project with a humanoid attached, or a vendor kit project with some ROS 2 tools on the side? Nobody writes that question down, and it is the one that matters.

Should you plan a Unitree G1 project around ROS 2?

Yes for everything above the ankles, and no for balance and walking. Perception, mapping, logging, teleoperation interfaces, behaviour logic and anything you want to visualise belong in ROS 2, because those tools already exist there and none of them are worth writing again. Balance, gait and joint-level control belong where Unitree put them, inside a controller running on the robot itself, reached through the development kit rather than through topics from your laptop. The split matters because people who ignore it build a project where a network hiccup can affect whether a humanoid stays standing, which is a bad property for a machine this heavy. Treat ROS 2 as the outer layer, where sensing, decisions and tooling live, and treat the vendor stack as the thing you talk to rather than the thing you replace. The one condition that changes this is a project whose subject is locomotion itself, and even then the loop lives on the robot's own computer while ROS 2 stays outside it.

What does it mean for a robot to support ROS 2?

It means one of three quite different things, and buyers routinely assume the strongest one. The strongest is a maintained driver: a package your package manager installs, a hardware interface that plugs into the standard control framework, launch files, model files, sensor bring-up and a version policy that tracks distributions as they come out. The middle version is what most robots in this category actually ship: message definitions matching the robot's own protocol, a network configuration to make your machine see the robot's traffic, and a handful of examples pinned to whichever distribution the vendor was using when they wrote them. The weakest is a community wrapper written by someone who needed it once. A Unitree G1 sits in the middle, and that placement predicts your first week accurately. Nothing is broken, nothing is missing that you were promised, and nothing is finished either. What you get is access; what you do not get is a supported path, a navigation configuration, an arm planning configuration, or a guarantee that today's release builds on today's distribution.

What are your options for getting your own software onto a G1?

Six, and most projects use three of them at once. The handset and phone application drive the robot with no code at all, which is the right way to spend the first hour. The C++ development kit is the primary interface, the one the vendor examples use, and the only route to the lower control levels. The Python binding wraps the same interface and is where prototypes and data collection should start. The ROS 2 packages give you the message definitions and network configuration that let ordinary nodes see the robot's topics. Sensor drivers come from the sensor makers rather than from Unitree, and behave as they would on any robot. And the vendor's MuJoCo-based simulation lets all of this be written before the robot reaches your bench.

Below that sits the question of what your own processes talk over, which for almost every G1 project should be ROS 2, because that is where the drivers, recording and viewers are. A single-machine layer such as HORUS is the other kind of answer, and earns a place only when several processes you wrote yourself, in Rust, Python and C++ on the robot's own computer, must hand each other data every tick without copying it. That is a real situation on a humanoid, and a narrow one, and it removes none of the vendor stack underneath.

How do the options compare side by side?

The order below is roughly the order you will meet them in, not a ranking.

What should you use if you are one person with a G1 and no robotics team?

The Python binding first, then ROS 2 only for the tools you actually need. Alone, every layer you add is another suspect when something does not work, and a humanoid already gives you plenty. A short script that connects, prints joint positions, commands a posture and writes a log file teaches you more in an afternoon than a node graph you cannot yet debug. Once that works, add ROS 2 for the things it is genuinely better at: bringing up the camera and lidar, viewing what the robot believes, and recording a session so you can replay it after the battery dies. What a solo builder should not do is wrap everything in nodes on day one because that is how tutorials are written. You will end up debugging your own architecture instead of the robot. There is also a physical point that nobody puts in a repository: a humanoid needs a person to catch it and a safe place to fall. Plan the gantry, the mat and the second pair of hands before you plan the software.

Which computer should your code run on, the robot's or your laptop?

Anything that affects whether the robot stays upright runs on the robot's own computer, and everything else can run wherever it is convenient. This is the rule people break first, usually by accident: a control script started on a laptop over Wi-Fi feels fine in a quiet room, then the link hiccups mid-step and the robot does something ugly. Wireless links are for viewing, teleoperation, recording and development, not for closing a loop, and the reasons this bites in ROS 2 specifically are set out in why ROS 2 breaks on normal Wi-Fi. On-robot compute is shared, which is the second thing to plan: heavy vision work and a timing-sensitive control loop on one machine will compete, and the loop loses. Teams doing serious perception carry a second computer for it. And before purchase, confirm which model lets you run your own code on board and which control levels it exposes, because that is decided by what you buy rather than what you write.

What can you actually have working in the first week?

Walking under the handset on day one, sensor streams and recording by day three, and your own commands moving the robot by the end of the week. That is a realistic week, and it assumes a day lost to networking. The order that works is: unbox and drive it with the handset until you trust the physical handling; get your machine onto the robot's network and confirm you can see its traffic at all; run a vendor example that prints the robot's state, which is the single best proof that everything below you works; bring up the camera and lidar as ordinary ROS 2 drivers; record a session and replay it. What is not a first week: navigation through a building, manipulation with the arms, whole-body control, or a learned policy on hardware. Those sit on top of a foundation that has to exist first. Teams who promise a demo in two weeks usually deliver the handset video, which everyone in the room recognises for what it is.

How much ROS 2 do you need to know before the G1 is useful?

Enough to launch nodes, list topics, read a message and fix a build error, which is a couple of weekends rather than a course. The G1 does not ask for the deep parts of ROS 2. There is no maintained hardware interface to write against, no supported navigation configuration to tune, no planning pipeline waiting for you. What it asks for instead is patience with networking and comfort reading somebody else's C++ example, and neither of those is taught in a ROS 2 tutorial. If you have never used ROS 2 at all, learn four things and stop: how to run a node, how to see what topics exist, how to record and replay, and how to read a launch file. That is the part that pays off here. The rest can wait until you have a reason for it, which usually arrives with your first mapping task. For a realistic sense of that curve before committing a team, how long it really takes to learn ROS 2 is the honest version.

What do you give up by putting the whole project behind ROS 2?

You give up directness, and you gain a second suspect in every debugging session. When your command goes through your node, through the bridge configuration, through the robot's own message layer and into its controller, a failure could live in any of those, and the error you see is usually from the wrong one. Working directly with the vendor kit is less pleasant and far easier to reason about, which is why almost every vendor example is written that way. You also inherit version drift, because the examples target an older distribution than the one you installed and somebody owns the job of keeping them building. And a chain of nodes sits between your decision and the robot's, which is fine for deciding where to walk and wrong for deciding how to catch a stumble. None of this is an argument against ROS 2 on a G1. It is an argument for keeping the vendor path intact underneath, so that when something behaves strangely you can drop below the layer and ask the robot directly.

When is ROS 2 the better choice?

ROS 2 is the better choice for nearly everything a G1 owner will actually build, and this is the section to take literally. If you want the depth camera and the lidar producing data you can see, drivers exist and they work. If you want to know what the robot believed when it did something odd, the viewer and the recording tools are worth the whole setup cost on their own. If you want mapping, a teleoperation interface or a way to replay yesterday's session, all of it exists and none of it exists anywhere else here. If you plan to hire, ROS 2 is the vocabulary candidates already speak. HORUS is the wrong tool for a stock G1: it carries no Unitree message definitions, no sensor drivers and no viewer, it does not replace the development kit, and it is validated in simulation rather than across fielded humanoids. Someone unpacking a G1 this month should be building on ROS 2, and should only look at a single-machine layer later, if their own on-robot processes start fighting each other for data.

Does a Unitree G1 come with a ROS 2 driver that works without setup?

No, and here is why. The robot publishes and subscribes on its own message set over its own network link, and your machine sees none of it until it is configured to listen on the right interface with matching settings. Once that is done, ROS 2 nodes can read the robot's state and send it commands, which feels like a driver and is genuinely useful, but there is no installable package that brings the humanoid up as a standard piece of hardware, no supported navigation or arm planning configuration, and no promise that the examples build on the distribution you chose. There is a second trap underneath the first: this maker sells several robot families and they do not share message definitions. A tutorial written for the quadruped will give you field names that do not exist on the humanoid, and the error will read like your mistake rather than a mismatch. Read which robot a repository targets before you follow it, every time.

Can you replace the G1's walking controller from ROS 2?

Partly, but not the way you think. There are two levels to talk to. At the high level you send something like a walking or posture command and the shipped controller does the hard part, keeping the robot balanced while it executes. At the low level you command the joints yourself, and nothing is catching the robot if your numbers are wrong or your loop is late; it falls, and it is heavy. Replacing the controller therefore does not mean swapping a component, it means taking on the entire balance problem including everything the vendor solved quietly. Teams who do this successfully run the loop on the robot's own computer rather than over topics from a laptop, spend months in simulation before hardware, and keep the robot in a gantry the first several times. It is a legitimate research direction and people do it. It is not a configuration change, and access to the lower level depends on which model you bought.

What goes wrong first when a G1 is connected to ROS 2?

Networking, almost every time, and it looks like the robot is broken when it is not. The usual sequence is that everything is wired correctly, the robot is walking happily under the handset, and your ROS 2 tools show an empty topic list. The cause is nearly always that the middleware is listening on the wrong network interface, or your settings do not match the robot's, or two configurations on the same machine disagree about which one is in charge. The fix is a line of configuration; finding it costs a day if you did not know to look. After that the usual list: examples that will not build against your distribution, message definitions borrowed from the wrong robot family, and a command stream that stalls so the robot drops into a protective posture and you assume you crashed it. One more that people rarely mention: batteries, tethers and stop buttons need a routine before the software does. Decide who holds the robot and who holds the stop before anyone runs anything new.

How do you decide what to build before the robot arrives?

Write down the one thing you want this robot to do that the shipped controller cannot already do, and let that sentence assign the layers. If the sentence is about going somewhere, seeing something or remembering what happened, you are building a ROS 2 project and the vendor stack is a driver you talk to. If the sentence is about how the robot moves, steps or catches itself, you are building a control project on the robot's own computer, and ROS 2 is the tooling around it. Most teams discover they are the first kind, which is good news, because that path has far more existing work under it. Then spend the waiting weeks in the vendor's simulation rather than in reading, since behaviour, logging and message handling all transfer, and a simulator is the cheapest place to be wrong; the ranked list of simulators for beginners covers what carries across. Last, confirm the model and access level in writing before purchase.

Where that leaves you, in six lines:

• If you need a demo this month -> the handset and the shipped controller, because nothing you write will walk better in week one.
• If you want mapping, logging or a teleoperation interface -> ROS 2, because the drivers and viewers already exist.
• If your project is balance, gait or whole-body control -> the vendor kit on the robot's own computer, because that loop cannot depend on a laptop and a link.
• If the robot has not arrived yet -> the vendor simulation, because a wrong week costs nothing there.
• If processes you wrote, in different languages, must share data on the robot every tick -> a shared-memory layer, because copying between them is the cost you keep paying.
• If you cannot tell which of these you are -> ROS 2, because it is the cheapest place to find out.

The HORUS Fit Framework is the short form of that reasoning for any layer you are choosing here: judge each option on five axes, which are ecosystem size, setup effort, team size fit, deployment target and licence, then take the one that loses least on the axis you cannot afford to lose. On a bought humanoid, ecosystem size and setup effort dominate, which is why ROS 2 carries most of the stack and the vendor kit sits underneath it.

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.