Initial import of Microtracking project

plan_v2_shunt_130mohm.md

@@ -0,0 +1,80 @@
+# V2 Shunt Calibration Deployment Plan
+
+## Objective
+
+Update the live `docker_tracker_hub` calibration for PCB V2 to a nominal
+`0.130 ohm` shunt. Preserve PCB V1 at `0.075 ohm`, raw observations, historical
+analysis and unrelated local or NAS changes. Do not modify firmware.
+
+## Execution
+
+1. Inspect the current local and NAS configuration, compose service and running
+   container. Identify the active V2 device and any environment or persisted
+   overrides that could retain the old resistance. Capture the current state
+   needed to reverse only this deployment if verification fails.
+2. Apply the smallest local change and matching targeted NAS change. Add or
+   update focused regression coverage for V2 current conversion and ensure V1
+   conversion remains unchanged. Run the available hub test suites.
+3. Build the new image while the current service remains running where the
+   deployment permits it. Recreate only `tracker-hub`; do not use `compose down`,
+   remove volumes, overwrite directories or reset repository state.
+4. Check the HTTP endpoint, container status, loaded V2 resistance, actual device
+   version selection and live current conversion. Record any restart-related
+   acquisition interruption. Report precisely if no live sample is available.
+
+## Acceptance Criteria
+
+- The running hub selects `0.130 ohm` for the actual V2 device, not just for an
+  unused default configuration entry.
+- V1 remains `0.075 ohm` and unrelated board settings are preserved.
+- At the same raw current code and amplifier gain, V2 current is twice the value
+  obtained with the former `0.260 ohm` conversion.
+- Relevant tests pass, and the hub is running and responds after deployment.
+- Raw log files, databases, historical calibration metadata and the article's
+  piecewise November 3 analysis are not rewritten or retroactively rescaled.
+- No authentication secret is committed to source, documentation or memory.
+
+## Operational Limits
+
+The experiment is already running. Minimize service interruption, but do not
+claim zero downtime without evidence. If validation fails, restore only the
+captured calibration/deployment state; preserve all newly collected data.
+
+## Ownership
+
+The delegated implementation subagent completed the local calibration change
+and Python integration tests. After its interactive-authentication blocker, the
+main agent completed noninteractive SSH access, targeted NAS patching, deployment
+and independent live verification.
+
+## Execution Record
+
+- Completed on 4 November 2026. New container started at
+  `2026-11-04 16:34:44.608835 UTC` (`10:34:44` on the NAS local clock).
+- Local change: `docker_tracker_hub/app/config.py`; V2 is `0.130 ohm`, V1 remains
+  `0.075 ohm`. `_fleet_test.py` verifies both absolute conversions and isolation.
+- All 23 fleet tests passed in the existing isolated Python environment.
+  The telemetry parser test also passed. The dashboard suite was not run because
+  Node.js was unavailable in the local environment; frontend code was unchanged.
+- The actual NAS compose project is `/mnt/Fast/MICROTRACKING/docker-compose.yml`,
+  with build context `/mnt/Fast/MICROTRACKING`, not a nested hub directory.
+  Only the V2 literal in `/mnt/Fast/MICROTRACKING/app/config.py` was patched.
+- Built while the old container continued running, then deployed only
+  `tracker-hub` using `up -d --no-deps --no-build --wait --wait-timeout 60`.
+- The new image is
+  `sha256:a9772c3b08625f782577622a013c996c2efd268fdd1d7bedd412b1e66eeec0cb`.
+  Container `esp32_tracker_hub` is healthy; `/health` reports a readable store
+  and no store-write error.
+- The actual device `esp32-000000000002` reconnected as V2 and its live API reports
+  `r_shunt=0.13`. V1 device `esp32-000000000001` still reports `0.075`.
+- Verified live sample: raw current `4037629` converts to `379.13 mA`, matching
+  the independent formula. The same sample reports `2.454 V`, `984.0 W/m2` and
+  `762.80 mW` estimated power.
+- The raw log remains in its existing bind mount. The samples bracketing the
+  restart are `10:34:38` and `10:34:59` local time, a 21-second inter-sample gap.
+  This is not a claim of zero acquisition downtime.
+- Rollback safeguards retained: source copy
+  `/tmp/trackerhub-config-before-shunt130-b589a074eba193bc.py` and image tag
+  `microtracking-tracker-hub:pre-shunt130-20261104`. No rollback was needed.
+- No firmware, raw historical observations, article analysis or persistent
+  device identity/settings records were edited.