ferrasdh/Microtracking
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Microtracking/plan_axis_ratio_xy.md
T

9.9 KiB
Raw Permalink Blame History

Plan: Configurable X:Y Tracking Allocation

Objective And Limits

Implement a configurable preference for X-axis tracking in the ESP32 firmware and docker_tracker_hub, with a 3:1 profile. The requested ratio concerns fine-tune work allocation, not motor microstep amplitude or energy consumption. Do not flash a board, activate OTA, publish an OTA image or deploy/restart the NAS hub as part of this implementation task.

The experiment established that very short movements and very low delays can make positional changes indistinguishable from thermal/time-dependent drift. Preserve existing delay, step limits, thresholds, calibration and NVS values. Do not restore the rejected 200-step / 2-second profile or claim that C/G compensates cell temperature.

Scheduling Contract

  • Preserve cicleMax as the existing base count of fine-tune iterations.
  • Add bounded positive integer X and Y allocation factors. Use a 3:1 profile; 1:1 must reproduce the previous symmetric allocation.
  • Define each axis budget as cicleMax * axis_factor. For example, base 4 with factors 3 and 1 means 12 X iterations followed by 4 Y iterations, not three physical X microsteps followed by one Y microstep. Base 1 gives 3 then 1.
  • Show these effective budgets explicitly in the hub UI. Do not silently multiply a user's setting without explaining the resulting schedule.
  • Count fine-tune actuation iterations, not every ADC sample or loop pass. Standby, rejected spikes and deadband returns must not consume the schedule. Handle travel-limit-blocked attempts without starving the other axis.
  • Keep Y correction periodic; the elevation axis is not fixed. Allocation is configurable because relative X/Y demand can vary with time and geometry.

Work Packages

  1. Inspect historical sketches for the earlier asymmetric mechanism. Report whether it was found; a symmetric cicleMAX=3 alone is not a 3:1 schedule. Inspect the current engine, NVS, cloud/local parameter handlers, hub command validation, dashboard and regression tests before editing.
  2. Implement the allocation factors and deterministic axis budgets in firmware. Persist the new factors in NVS without renaming existing keys. Validate zero, negative, fractional, non-finite and excessive values on every exposed input path. Bound multiplication to prevent overflow or starvation. Keep pending scheduling state coherent when parameters change or standby is entered.
  3. Expose the factors through the current command protocol, local ESP interface and hub dashboard. Preserve multi-device isolation. Clearly distinguish a requested setting from one confirmed by the board; older running firmware must not appear to have applied an unsupported setting.
  4. Extend offline tests using the actual engine and the hub test doubles. Cover 3:1, 1:1, non-default base counts, bounds, runtime changes, persistence, skipped samples, standby/recovery, travel limits, per-device routing and requested-versus-confirmed UI state. Retain all 1.1.4 tracking regressions and V1/V2 identity/calibration coverage.
  5. Run the available firmware, hub and dashboard suites. Use existing isolated tooling rather than modifying global packages. Increment the firmware version and compile waveshare_esp32_s3_nano_v2 without an upload target. Verify the image checksum, version and Tarjeta 02 identity. Report hardware-validation limits and the exact controls needed to select the 3:1 profile.

Acceptance Evidence

  • A test trace demonstrates base 4 / ratio 3:1 as 12 X then 4 Y iterations, repeated without losing Y updates; base 1 demonstrates 3 then 1.
  • Both firmware and hub reject invalid ratios, and new parameter names pass the valid-command allowlist with focused regression coverage.
  • The dashboard shows effective budgets and does not label a merely sent command, stale board state or placeholder as a confirmed applied value.
  • Existing persisted tuning parameters, V1=0.075 ohm and V2=0.130 ohm remain unchanged. Existing 1.1.4 fixes stay covered by passing tests.
  • The V2 binary is built and validated but no installation or live deployment has occurred.

Ownership

One implementation subagent owns the coordinated firmware/hub changes, historical-code inspection, tests and build. The main agent owns this plan, coordination and independent review of the delivered changes and evidence.

Implementation Notes

  • New command parameters are axisXFactor and axisYFactor, with integer factors from 1 to 8. New NVS keys are axisxf and axisyf.
  • Each effective axis budget must be at most 64 iterations. Changes that would exceed that bound are rejected, rather than clipping one budget and silently changing the requested ratio. Valid existing NVS settings are preserved; invalid legacy schedules are explicitly logged and sanitized to a safe state.
  • Firmware reports AXISCFG:x:y:base after successful changes and on reconnect. The hub checks the complete record, adds the authenticated device identity, and forwards exact effective budgets to the selected device's dashboard.
  • The dashboard keeps requested and board-confirmed state separately. A partial acknowledgment cannot confirm a two-factor request. Disconnecting the board, reconnecting a session or changing the selected device clears confirmation.
  • The available three legacy autotune sketches contained symmetric alternation, not a recovered 3:1 mechanism. This implementation defines the asymmetric behavior explicitly instead of assuming an unavailable historical version.
  • With base 4, ratio 3:1 and a 4-second sample period, an uninterrupted sequence nominally allocates about 48 seconds to X and 16 seconds to Y. Rejected samples, standby and motor travel can extend those times. This is not an angular-rate model, and 3:1 is not claimed to be optimal at every time of day.
  • Hardware tracking, physical movement and thermal discrimination still require a field test. The ratio feature does not measure or compensate cell temperature.

Final Verification Record

Completed locally on 4 November 2026 after independent integration review.

  • Firmware version: 1.1.5-ws, environment waveshare_esp32_s3_nano_v2, public device esp32-000000000002.
  • Firmware tests: 23 native control-engine cases plus 6 identity/transport cases, all passing. The native tests include the 15 previous tracking regressions and 8 scheduling cases for actual axis transitions, bounds, NVS restoration, runtime changes, skipped samples, standby/recovery and travel-limit release.
  • Hub verification: 24 fleet tests, TEL regression and the dashboard JavaScript suite passed. Dashboard cases cover partial acknowledgments, stale or foreign acknowledgments, requested base changes, invalid inputs and disconnected state.
  • Build command: pio run -e waveshare_esp32_s3_nano_v2, successful without an upload target.
  • Artifact: platformio_microtracking/.pio/build/waveshare_esp32_s3_nano_v2/firmware.bin.
  • Artifact size: 1083600 bytes.
  • SHA-256: fa3b2a4ec61aabce29294a8d3b6733ca7d34eab557cbba10fa45634abbb9fa51.
  • Parent independently verified the file hash, embedded version and Tarjeta 02 identity. esptool image_info confirmed ESP32-S3 and valid checksum/hash.
  • At initial local delivery, no board was flashed and no OTA image was published, uploaded or pushed. The NAS deployment subsequently authorized by the user is recorded below; installing firmware remains a separate operation.

After installing both components, the explicit base-4 / ratio-3:1 profile is:

SET_PARAM:cicleMax=4
SET_PARAM:axisXFactor=3
SET_PARAM:axisYFactor=1

These commands are instructions only; they were not sent to a device. Confirm the resulting 12 X / 4 Y allocation in the board-confirmed dashboard state, not merely in the requested input fields.

Authorized NAS Deployment

The user subsequently authorized deployment to 192.168.0.207 under /mnt/Fast/MICROTRACKING. After the user repaired the VPN connection, deployment completed on 4 November 2026.

  • Reviewed and updated only app/main.py, app/hub.py and static/index.html. Remote differences matched the intended X:Y feature; no compose, credentials, calibration configuration, raw observations or database files were replaced.
  • Reran all 24 fleet tests, TEL regression and dashboard JavaScript tests; all passed. An isolated, network-disabled container verified exact source hashes, command validation, V1/V2 calibration and a parsed 3:1 / base 4 acknowledgment.
  • Built the new image while the previous service remained running, then recreated only tracker-hub using up -d --no-deps --no-build --wait --wait-timeout 60.
  • Running image: sha256:1b90e5206b613789e507ad444e5087d55f6758c6839d8a4b62892f991abcb1f7.
  • Container started at 2026-11-04 22:36:43.550630 UTC (16:36:43 on the NAS local clock), with healthy status. /health reported a readable store, no store-write error and both registered devices.
  • http://192.168.0.207:4000/ returned HTTP 200 and served both X:Y controls and the requested/confirmed-state logic.
  • V1 remained 0.075 ohm; V2 remained 0.130 ohm. Automatic OTA remained false for both devices. The existing OTA artifact/manifest was not replaced.
  • Both boards were disconnected before and after this restart. The last V2 firmware version reported before restart was 1.1.5-ws; no live board ACK was available to confirm a newly applied ratio. No control or OTA command was sent.
  • The existing V2 raw log remained at /mnt/Fast/MICROTRACKING/data_logs/esp32-000000000002/log_2026-11-04.txt with 2006038 bytes at verification. With no connected board producing samples, a restart inter-sample interval could not be measured. In-memory plot buffers restart with the service; persistent raw logs are retained.
  • Rollback source copies: /tmp/trackerhub-axis-backup-20261104-223311. Previous image tag: microtracking-tracker-hub:pre-axis-20261104-2233. No rollback was needed.
Reference in new issue View Git Blame Copy Permalink