Beta 0.1 – First Linux CLI/backend release

sequence_examples.md

@@ -0,0 +1,162 @@
+# Sequence examples
+
+These profiles are intended as practical starting points for bench work with the current MightyWatt Linux backend.
+
+Important:
+- all examples use the current **JSON** format
+- all examples include the now mandatory `abort_sequence`
+- the values are intentionally conservative and should be adjusted to your real DUT and PSU
+- these are **bench-ready templates**, not guaranteed universal production recipes
+
+---
+
+## 1. Quick constant-current sanity check
+
+File:
+- `examples/quick_cc_test.json`
+
+Purpose:
+- first proof that the backend, hardware, PSU, and measurement gear agree
+- low-risk stepped current check
+
+Highlights:
+- simple linear flow
+- ends with `safe`
+
+Run:
+
+```bash
+./mwcli -d /dev/ttyACM0 --csv quick_cc.csv run-sequence examples/quick_cc_test.json
+```
+
+---
+
+## 2. CC sweep with thermal break guard
+
+File:
+- `examples/cc_step_sweep.json`
+
+Purpose:
+- step/ramp current upward
+- stop early if temperature climbs above a chosen limit
+
+Highlights:
+- `ramp_current`
+- `break_if` for temperature
+
+Run:
+
+```bash
+./mwcli -d /dev/ttyACM0 --csv cc_sweep.csv run-sequence examples/cc_step_sweep.json
+```
+
+---
+
+## 3. Fixed-count pulse loop
+
+File:
+- `examples/repeat_n_pulse_test.json`
+
+Purpose:
+- repeat a pulse/rest pattern a defined number of times
+- useful for basic cyclic load testing
+
+Highlights:
+- `repeat`
+- nested `steps`
+- loop-level `break_if`
+
+Run:
+
+```bash
+./mwcli -d /dev/ttyACM0 --csv pulse_loop.csv run-sequence examples/repeat_n_pulse_test.json
+```
+
+---
+
+## 4. Repeat until voltage cutoff
+
+File:
+- `examples/repeat_until_cutoff.json`
+
+Purpose:
+- run repeated load/rest blocks until the measured voltage falls below a threshold
+- suitable for simple discharge-style tests
+
+Highlights:
+- `repeat_until`
+- timeout protection
+- temperature `break_if`
+
+Run:
+
+```bash
+./mwcli -d /dev/ttyACM0 --csv until_cutoff.csv run-sequence examples/repeat_until_cutoff.json
+```
+
+---
+
+## 5. Battery discharge cutoff profile
+
+File:
+- `examples/battery_discharge_cutoff.json`
+
+Purpose:
+- continuous constant-current discharge until undervoltage cutoff
+
+Highlights:
+- `hold_until`
+- simple thermal guard
+
+Run:
+
+```bash
+./mwcli -d /dev/ttyACM0 --csv discharge.csv run-sequence examples/battery_discharge_cutoff.json
+```
+
+---
+
+## 6. While-loop burn-in style template
+
+File:
+- `examples/repeat_while_burn_in.json`
+
+Purpose:
+- show the new `repeat_while` block
+- keep cycling while a condition remains true
+
+Highlights:
+- `repeat_while`
+- optional timeout
+- loop-level `break_if`
+
+Run:
+
+```bash
+./mwcli -d /dev/ttyACM0 --csv burnin.csv run-sequence examples/repeat_while_burn_in.json
+```
+
+---
+
+## Notes on choosing a template
+
+Use this rough rule:
+- short manual comparison against PSU/DMM -> `quick_cc_test.json`
+- stepped current sweep -> `cc_step_sweep.json`
+- cyclic pulse/load-rest pattern -> `repeat_n_pulse_test.json`
+- stop when voltage drops below cutoff -> `repeat_until_cutoff.json` or `battery_discharge_cutoff.json`
+- experimental loop based on a live condition -> `repeat_while_burn_in.json`
+
+---
+
+## Safety note
+
+For unattended or long tests:
+- keep the `abort_sequence` simple
+- keep thermal `break_if` conservative
+- always validate the profile with a short low-power run first
+
+
+## CSV raw mode
+
+Use `--csv-raw` together with `--csv <file>` to write elapsed time in **ms** and electrical values in **mA / mV / mW**. This is useful for spreadsheet tools that handle decimal separators poorly.