UWB Localisation for Tabletop Robots

Real time UWB localisation for small spinning robots on a tabletop play field. Three Ai Thinker BU03 anchors and one BU03 tag measure ranges, and a Python host program turns them into a planar position shown live in a browser. Every live run is saved, so the same measurements can be replayed and processed again.

Small robots need reliable positions to move on their own and to interact, for example by chasing or avoiding another robot. Early tests showed that raw ranges at these short distances were biased and sometimes interrupted, so the processing method was developed step by step using recorded data. The repository includes the host software, the final method, the experimental recordings and the evaluation scripts from a university engineering capstone project.

• Live localisation in the browser based Localisation Monitor.
• Processing in five stages, from range filtering and calibration for each anchor to Kalman tracking and display control.
• Recording and replay using the original measurement times.
• Stationary and handheld movement recordings from a 0.6 m layout and a 1 m layout.
• Scripts and tests that reproduce the reported results.

flowchart LR
    A[Raw ranges from A0] --> B[Range filtering]
    B --> C[Calibration for each anchor]
    C --> D[Weighted position solving]
    D --> E[Kalman tracking]
    E --> F[Smoothing and display control]
    F --> G[Displayed position]
    classDef default fill:#f6f8fa,stroke:#d1d9e0,color:#1f2328
    linkStyle default stroke:#59636e

Method details explain each stage and its settings.

The movement tests measure display availability and the handling of reception interruptions.

Use Python 3.11 or later. Run the following commands from the project directory.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[test]'

On Windows, activate the environment with .venv\Scripts\activate.

Replay uses the supplied recordings and needs no hardware.

uwb replay data/one_metre/from_a2_run1

Open the local address printed by the program. The replay interface uses the same layout as the live Localisation Monitor and shows positions and anchor ranges. Playback controls change the viewing time and speed, while processing always uses the original measurement times.

The blue marker shows the tracked position, and the red marker shows the displayed position. Select Original recording to show the saved position in grey. The same explanations appear in the position guide at the bottom of the interface.

To export the processed frame results, run

uwb replay data/one_metre/from_a2_run1 --no-browser --export results/replay.jsonl

Use --config before the command to select a different processing configuration.

uwb --config configs/final.json replay data/one_metre/centre_facing_a0

The boards keep their manufacturer firmware. See hardware setup for board roles and serial connections.

uwb ports
uwb live --port /dev/cu.usbmodemXXXX --output recordings/run01

Replace the example port with the A0 USB data port listed on your computer. Windows ports normally use names such as COM3. Each run creates a new recording directory and stores the received measurements and processing results. Stop the program with Ctrl-C.

To record for 10 s from the terminal, run

uwb capture --port /dev/cu.usbmodemXXXX --seconds 10 --output recordings/run02

python scripts/evaluate.py
python scripts/fit_calibration.py
python -m pytest

The evaluation reprocesses the 1 m recordings with the final method and an earlier version. Both versions use the same settings apart from two refinements made late in development. The calibration script refits the curve for each anchor from the supplied stationary data.

Data descriptions explain the reference positions, the split between fitting and checking data, and the recorded files.

The original code, documentation and supplied experimental data are provided under the MIT licence. References and dependencies identify the method references and separately installed dependencies.