175 lines
9.9 KiB
Markdown
175 lines
9.9 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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.
|