Skip to content

Getting started

Everything below runs on a laptop. Python 3.10 or newer for the simulator; PlatformIO for the firmware.

git clone https://github.com/akeanti/ariadne && cd ariadne
pip install -e ".[dev]"          # simulator, tests, lint; also installs the `ariadne` command

python -m sim.run compare --seed 7 --plot compare.png   # pivots vs smooth vs diagonals, physics
python -m sim.run drive --seed 7 --mode smooth --log run.csv --plot drive.png
python -m sim.run solve --seed 7 --plot solve.png        # exploration + all three plans
python -m sim.run montecarlo --mazes 7 42 --n 8 --mode smooth diag --errors realistic
python -m sim.run benchmark --n 100                      # planned times over 100 mazes
python -m sim.turns --plot turns.png                     # the turn library
python -m sim.calibrate --error 0.03                     # the gyro calibration, simulated

--maze mazes/gen_7.txt (or any maze in the common ASCII +---+ format) replaces --seed. --preset safe|normal|fast picks the speed setting; --errors realistic|stress|legacy the Monte Carlo error model.

python -m sim.studies control      # Bode, margins, sensitivity, root locus (seconds)
python -m sim.studies profiles     # turn and speed profiles
python -m sim.studies montecarlo   # reliability with 95 % intervals (minutes)
python -m sim.studies sensors      # ToF vs 1 kHz IR
python -m sim.studies pareto       # run time against reliability, lateral acceleration swept
python -m sim.studies width        # redesigns the turns for narrower chassis
python -m sim.studies alpha        # angular-acceleration budget against time and reliability
python -m sim.studies site         # rebuilds the website's interactive charts

Figures land in docs/img/studies/, data in docs/assets/data/. Physics studies use every core (--workers).

cd firmware
pio test -e native             # maze, planner and motion maths on your PC, against the simulator
pio run -e esp32 -t upload     # build and flash
pio device monitor             # 115200 baud; type h

Every release has one merged image for an ESP32 DevKit (4 MB):

pip install esptool
esptool.py --chip esp32 --baud 921600 write_flash 0x0 ariadne-esp32-v3.0.0.bin

On the robot

Modes are cycled with the BOOT button (the LED blinks the mode number) and armed with GO; a run starts when you wave a hand in front of the front sensors, so nobody knocks the robot off the start line.

Blinks Mode What it does
1 search explore to the goal and back until the path is proven optimal; map saved to flash after every leg
2 fast run, smooth turns the default fast run: clothoid S90 / L90 turns, path following
3 fast run, diagonals adds 45, 135 and V90 turns; only after the gyro calibration
4 fast run, pivots the v1 run, the conservative fallback
5 sensor test ToF, gyro, battery and pose at 10 Hz
6 to 9 calibrate ToF offsets, track width, wheel radius, gyro scale
10 clear maze forget the saved map

Serial console (h lists them): m maze, s sensors, p both fast-run plans with their planned times, v next speed preset, l flight log as CSV, c stored calibration.

python tools/plot_log.py robot.txt --sim sim.csv    # a real run over the simulated one

The order of business on a new robot, with a pass criterion for every step, is the bring-up plan.