mangavalkandClaude Opus 5.5
5ff85c4eb8
- LEGACY/Hexapod_Teensy/: old robot sketch (reference only). - platformio.ini: robot env targets teensy36 (owner-confirmed board). - Config.h: per-servo SERVOS table (pin, pulse at 0 deg, signed us/deg, pulse limits) built from the old sketch's pins, ranges, trims and the old Unity servo directions. Rear-left/front-left coxa offsets set to 0: the owner re-horns those two servos (the old +-90 left them at the end of travel; the sim showed them clamping). - ServoDriver: 18 servos on hardware PWM (50 Hz, 16-bit); the Teensy 3.6 Servo library stops at 12. - Radio on CE 39 / CSN 15 with SPI SCK on pin 14. - sim: analogWrite/PWM shims, pulses decoded through SERVOS (API v6). - Docs: CLAUDE.md, READMEs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
123 lines
5.1 KiB
Markdown
123 lines
5.1 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, and the RX FIFO holds 3 |
|
||
| `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 repo root 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 serial harness still works.
|
||
|
||
## 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`,
|
||
`HandleHoystick`), and binds the existing leg rig by name (`Leg` → `hip1`
|
||
/ `Hip2` / `Knie`). The on-screen panel (F1 toggles it) offers three input
|
||
sources:
|
||
|
||
- **Joystick:** the real remote as a USB controller, on input axes
|
||
`"1"`–`"6"` like the old `HandleHoystick`. Axis assignment and inversion
|
||
are set on the `SimRemote` component. The panel shows the raw axes so you
|
||
can fix them.
|
||
- **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.
|
||
- **Robot serial:** no radio at all. Keystrokes go to `robot.ino`'s own
|
||
`TEST_SERIAL_INPUT` harness.
|
||
|
||
The panel also has every remote toggle, the speed slider, simulated
|
||
handset tilt (remote gyro), a **ground tilt** slider (to test the robot
|
||
gyro), and live firmware state, joint angles, foot contact, the packet on
|
||
air and robot serial output.
|
||
|
||
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. `SimRemote.cs` mirrors its packet rules instead.
|