Building a Web Development Workbench for Unitree G1 with C++17, SDK2 and WebSockets

liershui2500 — Fri, 04 Sep 2026 09:10:03 +0000

I’ve been building UniRoboGui, an open-source browser-based development and debugging workbench for the Unitree G1 EDU.

GitHub:

https://github.com/ershui2500/UniRoboGui

The main idea is simple: keep the robot-facing stack in C++17 on the G1 PC2, communicate directly through Unitree SDK2 DDS, and expose a browser interface through HTTP and WebSocket.

That gives me one place to inspect telemetry, 29DoF joints, URDF, point clouds, SLAM, navigation, RealSense, joint-debugging state and voice/LLM workflows without creating a separate desktop tool for each subsystem.

Why I built it

A robotics SDK can expose every API you need and still leave a lot of integration work to the application developer.

While working with the G1, I repeatedly needed small tools for things like:

checking fresh LowState data
inspecting BMS, IMU, FSM and odometry
visualizing all 29 joints
checking Livox Mid-360 PointCloud2 data
watching SLAM mapping progress
setting localization/navigation targets
checking RealSense RGB and depth
debugging joint control conditions
recording upper-body motions
testing ASR/TTS
connecting an LLM

Writing a one-off tool for each problem works until those “one-off” tools become part of your daily workflow.

So I started consolidating them.

High-level architecture

The architecture intentionally stays small:

Browser
  |
  | HTTP / WebSocket
  v
C++17 web server
Boost.Asio + Boost.Beast
  |
  | Unitree SDK2 DDS
  v
Unitree G1 EDU

By default:

eth0  -> SDK2 DDS
wlan0 -> browser / Internet
8080  -> UniRoboGui web service

I did not add a ROS bridge just to support the browser UI. The robot-facing communication path remains SDK2 DDS.

Backend services

The executable composes a few focused services:

UnitreeDataSource
SnapshotStore
ControlService
PerceptionService
CameraService
VoiceService
HttpServer

The implementation lives mostly in:

src/unitree_data_source.cpp
src/snapshot_store.cpp
src/json_serializer.cpp
src/http_server.cpp
src/control_service.cpp
src/perception_service.cpp
src/camera_service.cpp
src/voice_service.cpp

The goal is not a complicated framework. The separation mainly keeps DDS callbacks, robot state, HTTP handlers, perception and control from turning into one large file.

SDK2 telemetry

The backend subscribes directly to SDK2 DDS topics including:

rt/lf/lowstate
rt/lf/bmsstate
rt/lf/secondary_imu
rt/lf/mainboardstate
rt/odommodestate
rt/sportmodestate

Callbacks update a shared snapshot instead of exposing SDK2 message types directly to the frontend.

The flow looks like this:

DDS subscribers
      |
      v
SnapshotStore
      |
      +------> HTTP snapshot/status endpoints
      |
      +------> WebSocket telemetry

This gives the browser a stable application-level representation of the current robot state.

WebSocket telemetry at 10 Hz

General robot telemetry is pushed through:

/ws/telemetry

The default rate is 10 Hz.

The WebSocket session is implemented with Boost.Beast. After each snapshot is written, a timer schedules the next write.

The main telemetry stream is used for lightweight state such as:

DDS status
FSM
battery state
IMUs
odometry
joint state
control status
voice status

Large perception data is fetched separately instead of being forced into every telemetry message.

29DoF URDF visualization

The frontend uses Three.js and URDF Loader to render the G1.

Live joint data follows this path:

LowState
   |
   v
Snapshot JSON
   |
   v
WebSocket
   |
   v
29 joint mapping
   |
   v
Three.js URDF model

I keep both the 3D view and a numeric joint table.

The 3D model is great for spotting posture/mapping problems. The table is still necessary for exact values like temperature, torque and velocity.

PointCloud2 processing for the browser

Sending a full raw point cloud to a browser is not always a great idea.

The perception service can decode PointCloud2 and apply web-oriented filtering:

PointCloud2
    |
    v
field decoding
    |
    v
range crop
    |
    v
height crop
    |
    v
voxel filtering
    |
    v
optional isolated-voxel removal
    |
    v
maximum point count

The web representation is intentionally small:

struct PointSample {
  float x;
  float y;
  float z;
  float intensity;
};

The purpose is not to reproduce every feature of RViz in a browser. It is to make the perception chain easy to inspect from the same development interface.

Accumulated SLAM map

During mapping, the backend also maintains an accumulated global map.

Instead of only rendering the latest LiDAR frame, the UI can show:

current point cloud
+
accumulated map
+
robot pose
+
trajectory
+
navigation target

A sequence number lets the frontend know when the global map changed and should be fetched again.

For obstacles, I currently prefer a semi-transparent 2.5D voxel representation over aggressive contour smoothing.

That choice came from a debugging concern: a visualization should not hide a short wall or small obstacle just because removing it makes the map look cleaner.

Navigation as a state machine

A navigation UI is not just a “send target” button.

The workflow needs to represent states such as:

idle
mapping
localizing
navigating
paused
cancelled

The current interface supports:

selecting an initial pose
selecting a goal and heading
single-goal navigation
multi-goal navigation
pause
resume
cancel
saved local navigation tasks
exiting the current map

The backend owns the robot-side transitions; the frontend reflects the current state and available actions.

Real navigation is treated as an explicitly enabled physical capability.

RealSense D435i without assuming device numbers

The camera service supports both librealsense2 and V4L2.

One lesson from physical robot deployment is that this is fragile:

RGB   = /dev/video0
Depth = /dev/video2

USB device numbers can change after re-enumeration.

So the service can scan the current V4L2 devices and use capabilities/pixel formats to distinguish RGB from Z16 depth input.

Manual device paths still exist as overrides.

The service also detects stale frames instead of indefinitely serving the last successful frame as though the camera were still online.

Joint debugging: backend checks matter more than UI controls

The joint-debug page supports upper-body and full-body workflows.

Before a real command is accepted, the backend can verify conditions such as:

fresh LowState
allowed FSM state
control/DDS readiness
URDF joint limits
browser control lease / heartbeat

A disabled button is useful UX, but it is not a safety boundary.

The backend still rejects invalid operations independently.

20 Hz kinesthetic motion recording

There is also an upper-body hand-guided teaching workflow.

At a high level:

start recording
      |
      v
manually guide joints
      |
      v
sample LowState at 20 Hz
      |
      v
save trajectory
      |
      v
play it back later

A saved action can either:

release control after playback, or
hold the final pose after playback.

Local actions can also be mapped to reserved G1 controller button combinations.

This makes simple interactive/demo motions much faster to create than manually authoring every trajectory point.

Voice and LLM integration

The voice service currently handles:

ASR
Unitree native TTS
local Kokoro TTS
built-in G1 conversation path
customer OpenAI-compatible LLM

The customer LLM mode supports configuration such as:

API URL
model
role prompt
fixed Q&A entries
wake phrase
TTS backend

The API URL is normalized to a Chat Completions endpoint, and the API key is not sent back as normal plaintext telemetry.

The main reason I used an OpenAI-compatible interface is portability. I do not want the rest of the robot application to depend on a single model provider.

Local Kokoro TTS

The customer LLM can optionally feed a local Kokoro TTS service:

LLM response
    |
    v
local Kokoro HTTP TTS
    |
    v
16 kHz PCM
    |
    v
Unitree AudioClient
    |
    v
G1 speaker

The robot can therefore use a remote language model while keeping speech synthesis local.

Unitree’s native TTS path remains available as well.

HTTP API

The built-in web UI is only one possible client.

Some of the current routes are:

GET  /api/health
GET  /api/snapshot
WS   /ws/telemetry

GET  /api/control/status
POST /api/control/command
POST /api/control/velocity

GET  /api/perception/status
GET  /api/perception/frame
GET  /api/perception/global-map
POST /api/perception/command

GET  /api/camera/status
POST /api/camera/command

GET  /api/voice/status
POST /api/voice/tts
POST /api/voice/llm/chat

That makes it possible to build another tablet, Electron or custom application UI on top of the same robot-side service.

Mock mode

The server supports:

--mock

In mock mode it does not initialize real DDS.

The mock data source continuously updates simulated robot state, which is enough to exercise large parts of:

the web UI
HTTP endpoints
WebSocket telemetry
perception UI
camera UI
control-state behavior
voice UI

This is not meant to replace a simulator.

It exists so that a CSS change or frontend state-machine regression does not require a real humanoid robot to move.

Deployment: online and from another PC

If the G1 can reach GitHub:

git clone https://github.com/ershui2500/UniRoboGui.git /home/unitree/UniRoboGui
cd /home/unitree/UniRoboGui
bash scripts/deploy_g1_online.sh

If the robot itself cannot reliably reach GitHub/PyPI, an Internet-connected Linux PC can prepare the resources and deploy over SSH/rsync:

git clone https://github.com/ershui2500/UniRoboGui.git
cd UniRoboGui
bash scripts/deploy_g1_from_pc.sh

Robots often live on much less convenient networks than developer laptops, so I wanted both workflows to be first-class rather than treating offline-ish deployment as an edge case.

Current target environment

Robot:    Unitree G1 EDU
DoF:      29DoF body preferred
PC2:      Ubuntu 20.04 AArch64
SDK:      Unitree SDK2
LiDAR:    Livox Mid-360 / Mid360s
Camera:   Intel RealSense D435i
Browser:  Chromium / Chrome / Edge

Firmware and hardware combinations vary, so compatibility should always be checked against the actual robot rather than assumed from an old test environment.

Repository