Documentation / Location quickstart

Location quickstart

Survey fixed anchors, flash their configuration, and read the mobile tag's position over USB.

1. Survey before flashing

1. Open Console → Location and choose 2D location or 3D location first. Changing dimensions resets the planner's anchor positions.
2. Set room width, depth, and height before entering anchor coordinates. Resizing the room also rescales the planner's anchors.
3. Use one coordinate origin: the front-left floor corner. Enter each anchor's measured X, Y, and Z in feet. Label the physical units A0, A1, A2, and A3 for 3D.
4. Keep the anchors spread around the working area. A0 is the time master and needs a clear radio path to the slaves. For 3D, do not put all four anchors in the same plane.
5. For 2D, enter the mobile tag's fixed Z height under TDOA calibration before flashing the tag. This height is included in its firmware configuration.

The preset and geometry heatmap are planning aids, not measured positions or accuracy results. Save a separate record of your survey; the planner is not a saved installation profile.

2. Flash each device

1. Put one anchor in DFU mode: unplug it, hold BOOT0, and reconnect USB.
2. Choose its Anchor number, then select Flash selected anchor. After flashing, unplug, release BOOT0, and reconnect to power.
3. Repeat for A0–A2 in 2D, or A0–A3 in 3D. Each anchor number must be used once.
4. Put the mobile tag in DFU mode and select Flash location tag. Reconnect normally afterward.

The console configures the images from the current survey. Reflash the affected configuration after moving anchors; a full changed survey requires updating the tag and the anchors. Downloading an unconfigured location binary alone does not apply your installation's coordinates.

3. Connect only the mobile tag

Power all anchors. Select Connect tag USB for the mobile tag; the anchors do not connect to the visualizer. Confirm the status reports mode=TDOA, the correct dimension, and three or four anchors. Live fixes should appear once reports arrive.

The tag solves position onboard. The room planner uses feet, the USB P record uses millimetres, and ROS 2 publishes metres. See the Location serial protocol.

4. Calibrate at a surveyed point

1. Keep the tag still at a measured X/Y/Z point. Enter those coordinates in feet under TDOA calibration.
2. Choose 10–500 samples and select Calibrate connected tag. Wait for the completed bias values.
3. To preserve those values across a power cycle, reflash the mobile tag from the same configured console session after calibration.

5. Check other surveyed points

Keep the calibration fixed. Move to another measured point, update the ground-truth X/Y/Z fields, select Clear, and collect a fresh static dataset. In 2D, keep the tag at its configured height. Do not mix measurements from different truth points in one static accuracy result.

The live error metrics compare fixes with the entered static truth point. Walking around without updating truth does not measure tracking accuracy. Use Import CSV with externally recorded ground truth for a moving path; CSV template gives the required columns. Run example uses synthetic data, not hardware.

The browser currently keeps only the latest 2,000 live rows and has no live Location CSV export. Record USB P and MISS lines through your own reader or ROS 2 for a longer test. The Python distance tools do not collect Location records.

If fixes are missing or wrong

• No fixes: check anchor power, unique IDs, selected dimensions, and that the tag and anchors were flashed from the same survey.
• Geometry or solve misses: check coordinates and units, anchor spread, 2D height, and radio obstructions.
• Large constant error: verify ground truth and installation-specific bias calibration.
• Lost setup after reload: re-enter the saved survey before flashing again; do not flash the default room layout onto your installation.

For USB/DFU problems, use the connection checks. Save the INFO response, survey, and raw records when requesting help.