# Idea Brief: Remote J-Link Setpoint Changer and Soak Step Automation

Status: completed
Type: idea-brief
Updated: 2026-09-07
Next Action: none
Readiness Review: run explicitly with `ts: bs review <idea-id-or-path>`; ordinary brainstorming does not review
Produces: MAP-0006

## Current Synthesis

### Idea

Create two separate host-side components for remotely running controlled thermal setpoint tests
through J-Link without requiring Codex to remain connected:

1. A reusable `setpoint_changer <degrees-c>` utility that connects through J-Link, requests one
   setpoint change, verifies the effective value when suitable readback is available, returns a
   clear success or failure, and exits.
2. A deliberately small `soak_step` script that calls the reusable utility, waits, calls it again,
   and exits. Its defaults are `15 C -> wait 12 hours -> 37 C`, with `--start`, `--end`, and
   `--hours` overrides.

The setpoint changer should cause firmware to use the same canonical setpoint-update behavior as
the touchscreen. A raw write to a live RAM variable is not considered equivalent unless source and
runtime evidence prove that it preserves all validation, persistence, event, and control-state
effects.

### Why It Matters

Remote soak and step-response testing should not depend on a person remaining at the controller or
on an active Codex session. Separating the single-action J-Link mechanism from the timing wrapper
makes the setpoint operation reusable by later automation while keeping the first unattended test
easy to understand and recover.

### Desired Outcome

- `setpoint_changer 15` changes the unit setpoint through a verified, firmware-compatible J-Link
  path and exits with a useful process status.
- `soak_step` independently performs `15 C -> 12-hour wait -> 37 C` and exits.
- `soak_step --start 10 --end 45`, `soak_step --hours 6`, and the combined override behave as
  specified without duplicating any J-Link logic.
- The soak process survives Codex disconnecting and exposes enough passive operational state to
  answer an at-will status query.
- Once installed and commissioned, this setpoint-only sequence requires neither touchscreen use
  nor a USB-drive swap.

## Constraints And Non-Goals

- Keep J-Link connection, command encoding, acknowledgement, and readback entirely inside the
  reusable setpoint changer.
- Keep timing and soak sequencing entirely inside `soak_step`; it must call the changer rather than
  implementing J-Link control itself.
- The changer must fail closed on invalid input, target mismatch, connection failure, incompatible
  command interface, timeout, firmware rejection, or verified readback mismatch.
- The soak script must not begin its wait when the initial setpoint change fails. A failed final
  change must be reported honestly and must not be treated as completion.
- Use the canonical touchscreen setpoint-update path or a small firmware command mailbox that calls
  that path. Do not silently substitute an unverified raw-variable poke.
- Preserve existing temperature limits, units, scaling, persistence policy, and controller safety
  interlocks.
- A minimal status record is operational bookkeeping, not temperature-data logging or continuous
  monitoring.
- Thermal qualification and temperature, heater-output, heat-up, or overshoot analysis are
  explicitly excluded from IDEA-0004. They are not deferred work, follow-up obligations, or
  release blockers for this Idea.
- Do not require USB media for the setpoint sequence. Do not remove or insert an SD card while the
  controller is powered.
- The owner's `ts: run idea 4, end to end work2` instruction authorized Work2 implementation,
  focused verification, deployment to the known non-production Controller A target, live setpoint
  commissioning, candidate registration, and checkpointing. The owner subsequently directed that
  thermal qualification and temperature-data analysis be removed rather than retained as future
  work.

## Possibilities And Tradeoffs

| Possibility | Benefits | Costs / Risks | Evidence / Status |
| --- | --- | --- | --- |
| Firmware command mailbox processed by the normal control loop | Can preserve touchscreen semantics, provide sequence-bound acknowledgement, and avoid calling firmware code from a halted debugger | Requires a bounded firmware interface and compatibility/version checks | Preferred direction; source inspection required |
| Invoke an existing canonical setter through a debug mechanism | May avoid adding a mailbox | ABI, concurrency, CPU halt, and side-effect risks may make it unsafe | Consider only if existing code and J-Link behavior prove it safe |
| Directly write the live setpoint variable | Small host utility | May bypass validation, persistence, events, locking, or state transitions | Rejected unless proven behaviorally equivalent |
| Detached soak process | Minimal way to survive Codex disconnect | Does not automatically survive host reboot or logoff | Fits the stated requirement if host continuity is adequate |
| One-shot scheduled task with persisted deadline | Better unattended and reboot recovery | Adds lifecycle and recovery complexity | Defer unless reboot survival is required |

## Resolved Questions

- Run the host utilities from this workstation through the repository's hostname-only J-Link hub
  route to Controller A / Setup A, assembly 1751136, probe serial 69664082, device R7FS7G27H over
  SWD at 4000 kHz.
- Introduce a versioned firmware mailbox processed by the running firmware and route both mailbox
  and touchscreen requests through one canonical bounded application function.
- Accept finite decimal Celsius values in the active 0.0 through 70.1 C range and encode the exact
  IEEE-754 single-precision bits in the mailbox.
- Codex-disconnect continuity is required; host reboot and logout recovery are deferred.
- Expose passive status through `soak_step --status` backed by a small atomic status record.
- Temperature-data collection and analysis are not part of these two components and create no
  IDEA-0004 follow-up obligation.

## Decisions

- Use exactly two functional components: the reusable single-action changer and the simple
  soak/step orchestrator.
- Default start setpoint to 15 C, end setpoint to 37 C, and wait duration to 12 hours.
- Support independent `--start`, `--end`, and `--hours` overrides.
- Keep timing, soak logic, and long-running behavior out of the setpoint changer.
- Keep J-Link implementation details out of the soak script.
- The soak script exits after the second confirmed setpoint request; it does not continuously
  monitor the controller.
- Do not add hidden retries or an implicit rollback setpoint. Preserve the last confirmed state and
  report failures clearly.

## Don't Forget

- Use decimal hours or another bounded test option so commissioning does not require a multi-hour
  wait.
- Prevent simultaneous utilities from competing for the same J-Link probe or command mailbox.
- Bind requests and acknowledgements with a sequence number plus an interface/build identity so a
  stale acknowledgement cannot look successful.
- Keep target selection explicit and fail on the wrong controller or incompatible firmware.
- Document that manually terminating the soak while waiting leaves the unit at the start setpoint.

## Exploration Log

### 2026-09-06

- Idea Brief created.
- The owner selected a strict two-component design: one reusable J-Link setpoint changer and one
  simple persistent soak/step script.
- The requested default sequence is 15 C, wait 12 hours, then 37 C, with start, end, and duration
  independently overridable from the command line.
- The unattended process must continue after Codex disconnects and remain queryable without Codex
  continuously monitoring it.
- Discussion established that touchscreen-equivalent firmware behavior is required; a raw memory
  write is not automatically acceptable.
- Repository inspection resolved the target, transport, active range, firmware integration,
  persistence, and passive-status decisions. The owner authorized end-to-end Work2 execution.

### 2026-09-07

- The detached 15 C to 37 C sequence completed successfully on Controller A and confirmed the
  requested independent timing and final setpoint behavior.
- Work2 candidate `3b8ab5b44d709a9b65564567963408af3efeed31` was registered in the active
  release cohort with satisfied and reconciled ownership.
- The owner explicitly removed thermal qualification and temperature-data analysis from the
  outcome. They are canceled for IDEA-0004 rather than deferred.
- IDEA-0004 is complete based on the implemented two-component behavior and its recorded Work2
  controller evidence.

Keep the synthesis current and append only useful dated exploration notes. Use `Status: ready-for-prm`
when the owner chooses to promote it, `promoted` after approved project-map direction captures it,
or `parked` when it is intentionally set aside. A promoted brief names its output in `Produces:`.
