Repository navigation
Web UI Guide
The Cockpit is a robotics supervisor in your web browser at http://<robot-computer>:8000. This page walks a beginner through a first run. Every control is described once, in Web UI Layout; the steps below link to the matching section there.
In This Guide: Quick Start Walkthrough · Best Practices · Interface Layout Map
flowchart LR
A["1. Connect<br/>Open Web UI"] --> B["2. 1-Click<br/>Click Start 1-Click"]
B --> C["3. Map Viewer<br/>Switch Tab & Connect"]
C --> D["4. Watch Live<br/>Robot Moving & SLAM"]
D --> E["5. Explore Tabs<br/>Tabs 1–11 Hardware Tuning"]
classDef s fill:#0b3b8c,stroke:#7db8ff,stroke-width:2px,color:#fff,font-weight:bold;
class A,B,C,D,E s;
Open http://<robot-computer>:8000 with the access token once; see The access token.
Tip
🚀 First thing to do: Click "Start 1-Click", switch to Map Viewer (Step 11), and press "Connect"! You do not need to configure pins, tune PID gains, or solder any wires before testing:
- Click 🚀 Start 1-Click in the header. With a board plugged in (RP2350, RP2040, ESP32, ESP32-S3, the UNO Q's STM32U585) or none at all (the Sim MCU), the run identifies the board, writes its configuration, starts the agent and bringup, checks the topic rates, then runs SLAM and Nav2: by default the robot maps by frontier exploration and returns to its start. The eight-manoeuvre drive suite runs at the end. Details: The One-Click Pipeline.
- Switch to the Map Viewer tool tab (top right), Step 11, and click Connect.
- Watch the robot move on the canvas: its footprint drives, the laser scan hits the walls, and the occupancy grid fills in.
Once you've seen the run, go through the numbered tabs (1–11) below to describe your own hardware.
Warning
On a real robot the 1-Click moves the robot by itself. A real robot (built from a reference design, or with any pin assigned) is held until steps 1 to 5 of the Real-robot bring-up card on Hardware Tests have passed: sensors, battery, motors, wheel speed and LiDAR, for the parts it has (The bring-up checklist). Once they have, the run drives it: SLAM, exploration and the goals. Measure the drivetrain first (test_acc) on the Operations tab is ticked by default, and test_acc drives every wheel at full power, with 1.0 m clear all round (more for a fast robot). Start asks you to confirm before a real robot's run, and ⏹ Abort shows in the header while it goes. Put the robot on open floor and stay next to it.
The header's controls, status chips and settings drawer: Application Header.
Name your robot in the header first; everything you pick from here on is saved to it. Then pick a reference design (its controller side becomes your robot's, your chassis stays), or leave it at No design to run the board as a bare module with every device simulated. With no board plugged in and no robot of yours selected, the cockpit uses the Sim MCU robot (bare_sim); a robot of yours, real or a bare module, stays selected. See Tab 1: MCU & Sim.
Enter the chassis type, wheel and body dimensions, and motor data; the physics HUD shows what the drivetrain can do. See Tab 2: Base.
Choose the motor driver and fix any wheel or encoder that runs backwards. See Tab 3: Drive & Motors.
Probe the I2C bus, pick the LiDAR, and set up the battery monitor and sonar. See Tab 4: Sensors.
Assign the GPIOs, clear every error the safety inspector reports, and print the wiring table. See Tab 5: Pin Matrix.
Enter the tool to check motors, encoders and sensors before ROS. Drives are refused on simulated wheels. See Tab 6: Hardware Tests.
Run the LiDAR driver on its own and check the live scan. See Tab 7: LiDAR / Scan.
Start the robot stack and run the health check on /odom, /imu/data, /scan and the TF chain. See Tab 8: Bringup.
Drive the robot with the virtual gamepad (Tab 9), map and navigate with SLAM, Nav2 and RViz in the browser (Tab 10), and set up and rerun the 1-Click pipeline (Tab 11). On a real robot the 1-Click waits for the bring-up card's steps 1 to 5, and its Measure the drivetrain first (test_acc) box is ticked by default: untick it to keep the robot off full power.
Click Map Viewer (top right), then Connect. To send the robot somewhere, click 🎯 Nav Goal and click/drag on the map; Nav2 plans around the obstacles. The viewer follows the goal (distance to go, ETA, recoveries) to its outcome, reached, aborted with Nav2's reason, or canceled, and ⏹ Cancel goal stops it. See Map Viewer.
The other tool tabs (Secrets, Config Studio, Install): The 4 Tool Tabs.
- Configure one subsystem at a time, in the tab order (MCU ➔ Base ➔ Motors ➔ Sensors ➔ Pins ➔ Tests).
- Validate in simulation first: use the Sim MCU or a bare module to check odometry, transforms and Nav2 before connecting motors. See Simulation Mode & the Bare Module.
-
Run the bringup health check on Tab 8 before autonomous navigation:
/odomand/imu/datashould be near 50 Hz and/scannear 10 Hz. - Save maps when finished: click Save map on Tab 10 once the room is cleanly enclosed.
Related Documentation:
- Web UI Layout & Interface Architecture
- The One-Click Pipeline
- Simulation Mode & the Bare Module
- Pin Matrix & Wiring Tables
Next: Web UI Layout (every tab, field and button).
