# DIS OpenLab differential-drive starter

Status: pre-pilot source package, version 0.1.0. Native Webots and physical hardware runs are not yet verified.

## Runtime contract

- Pure controller and tests: CPython 3.11; standard library only.
- Simulator adapter/world target: Webots R2025a.
- The simulator's `controller` Python package is supplied by Webots and must not be installed from PyPI.
- No board firmware is included or claimed compatible. Pico/Pico 2 and ESP32 require separate validated adapters.

## Verify the controller core

From this directory:

```text
python -m unittest discover -s tests -p "test_*.py"
python run_scenarios.py --output controller-scenarios.csv
```

The first command checks bounds, watchdog stop, sensor validation, hysteresis, kinematics, pose integration, and deterministic output. The second writes deterministic computational telemetry. Neither command is a physics simulation or hardware test.

## Run in Webots

1. Install official Webots R2025a for a supported 64-bit OS.
2. Keep `webots/worlds` and `webots/controllers` in the supplied project relationship.
3. Open `webots/worlds/openlab_rover.wbt`.
4. Run the simulation and inspect the e-puck motion and console.
5. Save the Webots version, OS/CPU/GPU, world hash, controller hash, start pose, run duration, collision/stop observations, and screenshot in the validation record.

Command-line launch where the Webots executable is on `PATH`:

```text
webots --batch --mode=fast webots/worlds/openlab_rover.wbt
```

Do not report a pass until the world has loaded, the adapter has run, the rover has reacted to the obstacle, and the evidence record has been reviewed.

## Interface boundary

The core consumes a timestamp, normalized obstacle level, heading error, and enabled flag. It returns left/right angular speed targets and immutable next state. The Webots adapter translates simulator devices. A future board adapter must separately implement sensor reads, PWM/direction outputs, timing, saturation, watchdog, and a physical stop path.

## Licensing

Original starter code is proposed for the MIT License pending DIS rights review. Webots and its bundled PROTO assets retain their upstream Apache-2.0 terms. No third-party asset is relicensed here.
