feat: surface offset + balance/TOF safety + CI workflow#4
Merged
Conversation
- New SURFACE_TARGET_OFFSET_M (default 0.10 m) and CMD_SET_SURFACE_OFFSET (18) so the float can hold its top at a configurable depth below the surface. Tunable at runtime via the SURFACE_OFFSET command (ESPB bridge + direct USB). - TOF_SAFE_RANGE_MAX_MM raised 80 → 85 mm to give 10 mm of margin above the homing threshold without risking the rear mechanical stop. - moveToMax() and balance() now use uToMotorPos() instead of hard-coded signs, staying consistent with MOTOR_INVERT_LOGICAL. - MotorController::_clampTarget extended to a symmetric range, matching the current geometry where u=1 maps to a negative motor position. - balance() refactored: deduplicated extend/retract via _balanceStrokeTo helper, and refuses to start without a prior homing (was forcing pos=0 — mechanically risky). - profile.cpp surface-hold reference now derived from FLOAT_LENGTH + surfaceTargetOffset(); the misleading "logica invertita" comment is gone. - ESPB parser: SURFACE_OFFSET added to PROTOCOL_COMMANDS and given a dedicated arg-parsing block; protocol_contract test updated to cover commands 14–18.
- Uniform header block on every firmware .cpp and .h: filename, 2–4 lines of module description, and "Maintainers: Colabella Davide, Benevenga Filippo — Team PoliTOcean". - Updates the existing headers on src/espA/main.cpp and src/espB/main.cpp: Fachechi and Gullotta move to "Past contributors"; current maintainers added. - Adds the same maintainers line to include/config.h, include/float_common.h, and the public headers of every module under lib/ (except the upstream libraries DebugSerial and RGBLed, which are kept untouched). - Fixes a stale "VL53L4CD" mention in src/espA/main.cpp module map (sensor was swapped to VL53L7CX in 2a74291). No behavioural change.
- TOF sensor model corrected from VL53L4CD to VL53L7CX (multi-zone 4×4 with central-zone mask 0x0660); driver, pin notes, hardware table, mermaid diagram, glossary and library links all updated. - MOTOR_TRAVEL_MM corrected: 45 → 35 mm to match include/config.h. - New "Syringe / Motor Convention" subsection: explains the u ∈ [0,1] PID contract, home / extension semantics, and the TOF safety thresholds (75 / 50 / 40 / 85 mm) with their rationale. - New "Surface Target Offset" subsection covering SURFACE_TARGET_OFFSET_M and how to change it at compile time or at runtime. - FLOAT Commands and GUI/ESPB/ESPA Protocol Contract tables now include the previously undocumented commands 14–18 (PARAMS_EXT, SYRINGE_SET, PID_HOLD, PID_STEP, SURFACE_OFFSET). - ESPA State Machine diagram extended with the matching states/transitions. - LED States table realigned to LEDState (scoped enum in led.h); added a note on the deliberate split between LEDState (ESPA) and FloatLEDState (ESPB). - BALANCE description reflects the new behaviour (requires homing first). - Version bumped to 11.2.0; changelog entry appended at the bottom. - New "Direct USB Tuning Commands (ESPA)" subsection documents the line-based bench tuning commands accepted on ESPA's serial port.
- .github/workflows/ci.yml: builds all three PlatformIO environments (espA, espB, espA_pool) in parallel on push to any branch and on pull requests to master. PlatformIO core and per-env build caches keep warm runs under a couple of minutes. Concurrency group cancels superseded runs on the same ref. Step summary prints the firmware size table. - .github/workflows/release.yml: on every v* tag, builds the three environments, renames the artifacts as <env>-<tag>.bin/.elf, and attaches them to a GitHub Release with auto-generated notes. - CONTRIBUTING.md: documents the trunk-based git workflow, branch and commit conventions, PR expectations, the release procedure (tag v*), and the one-time branch-protection setup (UI steps and gh CLI command). - README.md: CI badge in the header and a new "Continuous Integration" subsection under DEVELOPMENT AND TESTING, linking to the workflows and to CONTRIBUTING. CI does not run the hardware test suites under test/unit_hw and test/integration — they need a real ESP32 with motor/TOF/Bar02 wired up.
Skeitt
approved these changes
May 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Five-commit branch that covers everything from yesterday's analysis session plus the new CI/CD plumbing:
checkpoint: pre-analysis float behavior baseline— the safety snapshot before the analysis started (refactor from yesterday's direction-of-travel change).feat: surface target offset + balance/TOF safety hardening— runtime-tunableSURFACE_TARGET_OFFSET_M(new command 18SURFACE_OFFSET), TOF safe range widened to 85 mm,moveToMax/balanceuseuToMotorPos(), motor_clampTargetis now symmetric,balancerefuses to start without homing, profile.cpp uses the new offset, ESPB parser + protocol contract test updated.docs: standardize file headers and add current maintainers— uniform header block on every firmware .cpp/.h with module description and current maintainers (Colabella + Benevenga). No behavioural change.docs(readme): bring README in sync with current firmware— corrects TOF model (VL53L4CD → VL53L7CX), MOTOR_TRAVEL_MM (45 → 35), adds Syringe/Motor Convention and Surface Target Offset sections, fills in commands 14–18 in the command tables, updates the state machine diagram and LED states table, bumps version to 11.2.0.ci: GitHub Actions workflows + CONTRIBUTING guide—ci.ymlbuilds all three PlatformIO environments on push/PR,release.ymlpublishes firmware onv*tags,CONTRIBUTING.mddocuments the trunk-based git workflow and the one-time branch-protection setup.Test plan
pio run -e espA -e espB -e espA_poolpasses locally on all three environmentspio test -e espB -f unit_hw/espb_bridge/test_protocol_contract --without-uploading --without-testingcompiles (the updated test now assertscount == 18)python3 -c "import yaml; yaml.safe_load(...)")HOME_MOTOR→ check the TOF reaches ≈ 75 mm without "TOF above safe range" intermittent errorsBALANCEwithout a prior homing must fail withBalance: homing requiredin the debug logBALANCEafter homing must cycle until Bar02 pressure rises by 5 kPaSURFACE_OFFSET 0.10then a shallow PID hold — float top should sit ~10 cm below the surface; changing the offset to 0.05 should shift the equilibrium by ~5 cmSYRINGE_SET,PID_HOLD,PID_STEPstill work identically via both USB direct and ESPB bridgeNotes for the reviewer
v11.2.0tag to trigger the release workflow and confirm the binary publication end-to-end.