- README / CLAUDE.md layout: dongle/, hardware/, tools/ submodule, make_remote_hmi.py; telemetry in the protocol; the PC can take the robot's place on the radio. CLAUDE.md: NextionUI is on Serial2 (said Serial1); remote-without-robot via the dongle + sim. - remote/README: MPU6050 supply row; stick calibration button names of the new SETUP page; upload/USB-port hints. - remote/NEXTION.md: display on Serial2, how the Editor upload goes. - robot/README: Battery in the file list, Comms/ServoDriver roles, packet structs instead of payload size, check the IMU gives live data (the remote's MPU6050 needed a full reset; RobotIMU::begin() only wakes it). - sim/README: smoke test covers telemetry and servo calibration; OpenScadModel. - dongle/README: AT2401C test result, app command table, SignalRGB note, air settings incl. ack payloads. - PLANNING.md: the display direction is in the generated HMI. - Unity README: what the project is. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
136 lines
6.2 KiB
Markdown
136 lines
6.2 KiB
Markdown
# Firmware simulation (software-in-the-loop)
|
||
|
||
This folder compiles the **unchanged** robot firmware (`robot/*.cpp` plus
|
||
`robot.ino`) into a Windows DLL. The Unity project
|
||
(`Hexapod_Simulation_Unity/`) runs that DLL, so the code you test in the
|
||
simulation is exactly the code you flash to the Teensy. `robot/` has no
|
||
`#ifdef SIM` anywhere.
|
||
|
||
```
|
||
robot/ (unchanged) ──► PlatformIO + Teensy core ──► Teensy 3.6 firmware
|
||
└─► CMake + g++ + sim/shim/ ──► sim/build/hexapod_sim.dll ──► Unity
|
||
```
|
||
|
||
## How it works
|
||
|
||
`shim/` provides PC stand-ins for the only hardware the firmware touches:
|
||
|
||
| Firmware uses | Simulated as |
|
||
|---|---|
|
||
| `analogWrite()` hardware PWM (how `ServoDriver` drives the servos) | the pulse width per pin, worked out from duty, resolution and frequency, then decoded back to angles through `Config.h`'s per-servo `SERVOS` table |
|
||
| `Wire` + MPU6050 registers | a register-level fake MPU6050 at 0x68, fed from the simulated body's tilt and rotation |
|
||
| `RF24` | a simulated radio: packets are received only if channel, address, data rate and **payload size** match (any length up to 32 once `enableAckPayload()` turns on dynamic payloads, as on the chip), and the RX FIFO holds 3. `writeAckPayload()` goes back with the next packet received: `hxsim_get_ack_payload` returns it (the robot's `Telemetry`) |
|
||
| `millis()` / `micros()` / `Serial` | a simulated clock that Unity advances, and captured serial I/O |
|
||
|
||
`robot_ino.cpp` compiles `robot.ino` itself and exposes read-only views of
|
||
its globals (state machine, heading, IMU filter, gait phase) for status
|
||
display. `HexapodSimApi.h` is the C API. Its forward kinematics is written
|
||
separately from `robot/Kinematics.cpp` on purpose, so it can catch IK
|
||
mistakes.
|
||
|
||
## Build
|
||
|
||
Needs a 64-bit g++ and CMake. Strawberry Perl's `C:\Strawberry\c\bin` has
|
||
g++, cmake and ninja, and the script falls back to it automatically. From
|
||
the `2026-current` folder in PowerShell:
|
||
|
||
```
|
||
.\sim\build.ps1 # configure (first time) + build + smoke test
|
||
.\sim\build.ps1 -NoTest # build only
|
||
.\sim\build.ps1 -Clean # rebuild from scratch
|
||
```
|
||
|
||
To run the steps by hand, use separate lines. Windows PowerShell 5.1 has
|
||
no `&&`:
|
||
|
||
```
|
||
cmake -S sim -B sim\build -G Ninja
|
||
cmake --build sim\build
|
||
.\sim\build\sim_smoke.exe
|
||
```
|
||
|
||
Rebuild after any change in `robot/` or `shared/`. In Unity, press **Play**
|
||
(or **Reload firmware** in the panel) to pick up the new DLL. Unity copies
|
||
the DLL before loading it, so it never locks the build output and you
|
||
don't need to restart the editor.
|
||
|
||
## Headless smoke test (`tests/sim_smoke.cpp`)
|
||
|
||
It drives the firmware the way the remote would and checks:
|
||
- disarmed at power-on,
|
||
- arm lands in SIT,
|
||
- stand reaches STAND,
|
||
- **IK gives valid solutions and the feet end up at `STANCE_HEIGHT`**,
|
||
- `FLAG_WALK` leads to WALKING,
|
||
- **`+vx` moves the body forward**,
|
||
- link loss disarms,
|
||
- a wrong-size packet is ignored,
|
||
- the robot's telemetry comes back in the ack payload, and every servo
|
||
calibration command (HOLD / SET / SAVE / REVERT, arming refused) works,
|
||
- the serial harness still works,
|
||
- plus the body-pose, leg-clearance, heading and robot-gyro checks listed
|
||
in the file.
|
||
|
||
## Using it in Unity
|
||
|
||
Open `Hexapod_Simulation_Unity` and press Play in `Main.unity`. No scene
|
||
edits are needed: `HexapodSimBootstrap` adds a `HexapodSimulation` object,
|
||
disables the old movement scripts (`Walk`, `RotationControl`, `Leg`), and
|
||
binds the existing leg rig by name (`Leg` → `hip1` / `Hip2` / `Knie`). By
|
||
default `OpenScadModel` swaps the old scene's robot for the OpenSCAD model
|
||
of the real one (`HexapodSimulation.useOpenScadModel`). The on-screen panel
|
||
(F1 toggles it) offers two input sources:
|
||
|
||
- **Keyboard:** test without a remote. WASD walks, Q/E turns, IJKL + U/O
|
||
drive the right stick, 1–7 flip the toggles, Backspace disarms, +/-
|
||
change speed. The panel has every remote toggle, the speed slider and
|
||
simulated handset tilt (remote gyro).
|
||
- **Real remote (radio):** the real handheld remote, over the air. The USB
|
||
nRF24 dongle (`../dongle/`, bridge mode) receives its packets, they go
|
||
into the firmware byte for byte, and the robot's `Telemetry` goes back as
|
||
the radio's ack payload, exactly like the real robot's `Comms`. The
|
||
remote's display then shows the simulated robot (state, IMU, joint
|
||
angles, servo calibration). `DongleLink.cs` finds the dongle's CH340 port
|
||
by itself (or set `SimRemote.donglePort`, e.g. `COM7`); quit SignalRGB
|
||
first, it grabs CH340 ports. Don't run the real robot at the same time:
|
||
both would answer the remote.
|
||
|
||
There's no USB link to the remote or the robot any more (the old joystick
|
||
and serial-harness inputs and the `Serial*` / `HandleHoystick` scripts are
|
||
gone): everything goes over the radio.
|
||
|
||
The panel also has a **ground tilt** slider (to test the robot gyro), and
|
||
live firmware state, joint angles, foot contact, the packet on air and the
|
||
robot's debug prints.
|
||
|
||
The body moves **kinematically**, computed in the DLL (`SimBody.cpp`), so
|
||
Unity shows what the smoke test checks:
|
||
- The body rests on the support plane of its feet, the plane all feet are
|
||
on or above.
|
||
- Grounded feet don't slide.
|
||
- The simulated MPU6050 reads that body's tilt and rotation rate.
|
||
|
||
The sphere at each foot (`Point`) is placed by the DLL's forward
|
||
kinematics. If it doesn't sit on the tibia tip, the rig and `Config.h`
|
||
disagree.
|
||
|
||
Setup that lives in the Inspector on `HexapodSimulation`:
|
||
- `forwardAxis`: robot forward = Unity −X by default, taken from the old
|
||
scene's `invertForLeftLeg` naming.
|
||
- `unitsPerMm`: 0.1, since the model is in cm.
|
||
- `kneeRestDeg`: −90, the rig's knee pose at rotation 0.
|
||
|
||
For a custom setup instead of the bootstrap, add a `HexapodSimulation`
|
||
component to the scene yourself.
|
||
|
||
## What is not simulated
|
||
|
||
- Physics (mass, falling, slipping, servo torque and speed).
|
||
- Whether the calibration matches the real servos. The sim decodes pulses
|
||
through the same `SERVOS` table the firmware uses, so it shows what the
|
||
firmware *intends*, including pulse-limit clamping (which is how it
|
||
caught the old ±90° coxa offsets). Whether a real servo turns that way is
|
||
a bench check.
|
||
- The remote firmware, in Keyboard mode: `SimRemote.cs` mirrors its packet
|
||
rules instead. With the real remote over the radio, its own firmware runs.
|