0005-DenryokuBancho/HELP.md

MightyWatt Linux CLI Help

This document matches the current backend/CLI tree in this repository.

Scope

Current features:

• serial communication with MightyWatt hardware
• reusable C backend (libmightywatt_core style project layout)
• CLI control and monitoring
• CSV logging
• JSON-driven sequence runner
• loops in the sequence engine
• mandatory abort_sequence for safe shutdown / cleanup

Current sequence format:

• JSON only
• YAML is not supported in the current C implementation

---

General usage

mwcli -d /dev/ttyACM0 [global options] <command> [command args]

Example:

./mwcli -d /dev/ttyACM0 caps

---

Global options

These options go before the command.

-d, --device PATH

Serial device path.

Example:

./mwcli -d /dev/ttyACM0 caps

-s, --settle-ms N

Delay after opening the serial port, in milliseconds.

Default:

2200

Use this because Arduino-class boards often reset when the port is opened.

Example:

./mwcli -d /dev/ttyACM0 -s 2500 caps

-i, --interval-ms N

Polling interval in milliseconds.

Used by:

• monitor
• hold

Default:

500

-c, --count N

Number of samples.

Used by:

• monitor
• hold

If omitted, the stream continues until interrupted with Ctrl+C.

--sample-period-ms N

Override sample_period_ms from the JSON sequence file.

Used by:

• run-sequence

--csv PATH

Write measurement samples to a CSV file.

Works with:

• report
• monitor
• hold
• load-on
• load-off
• safe
• remote
• set-*
• run-sequence

-j, --json

Print JSON to stdout instead of plain text.

Useful for:

• scripts
• wrappers
• future GUI integration

Current behaviour:

• one-shot commands print one JSON object
• monitor and hold print JSON lines
• run-sequence prints one summary object at the end

-h, --help

Show built-in CLI help.

---

Commands

idn

Query the device identity string.

caps

Read device capabilities.

Typical fields:

• firmware version
• board revision
• max current DAC / ADC
• max voltage DAC / ADC
• max power
• DVM input resistance
• temperature threshold

report

Read one measurement report.

Returns:

• current
• voltage
• power
• temperature
• remote state
• status

monitor

Continuously poll and print measurements.

Examples:

./mwcli -d /dev/ttyACM0 monitor
./mwcli -d /dev/ttyACM0 -i 500 -c 20 monitor
./mwcli -d /dev/ttyACM0 -j monitor

set-current <amps>

Stage/set current target.

set-voltage <volts>

Stage/set voltage target.

set-power <watts>

Stage/set power target.

set-resistance <ohms>

Stage/set resistance target.

set-vinv <volts>

Stage/set inverted-voltage target.

This is a firmware-supported special mode.

hold <mode> <value>

Enable and keep a target alive by polling continuously.

This is the right command for real bench work because the MightyWatt watchdog requires regular host traffic.

Modes:

• current
• voltage
• power
• resistance
• vinv

Aliases accepted:

• CC
• CV
• CP
• CR

Examples:

./mwcli -d /dev/ttyACM0 hold current 0.250
./mwcli -d /dev/ttyACM0 -i 500 -c 10 hold power 1.000
./mwcli -d /dev/ttyACM0 -j hold resistance 20.000

load-on <mode> <value>

Apply a target once and return one report.

Important:

• this is a one-shot command
• the hardware may fall back after ~1–2 seconds if no more host traffic follows
• for sustained load use hold

load-off

Turn the load off.

Current implementation:

• host-side load-off via zero-current target
• the MightyWatt protocol has no dedicated hardware output-enable bit

safe

Go to safe state.

Current implementation:

• load off
• remote sense off

remote on|off

Enable or disable remote sense.

get-series

Read configured series resistance.

Output unit:

• ohms

set-series <ohms>

Set series resistance.

run-sequence <sequence.json>

Run a JSON sequence file.

Examples:

./mwcli -d /dev/ttyACM0 run-sequence profile.json
./mwcli -d /dev/ttyACM0 --csv run.csv run-sequence profile.json
./mwcli -d /dev/ttyACM0 --sample-period-ms 200 run-sequence profile.json

---

CSV logging

When --csv <file> is used, the logger writes:

• timestamp_utc
• elapsed_s
• context
• step_index
• current_a
• voltage_v
• power_w
• temperature_c
• remote
• status_bits
• status_text

Example:

./mwcli -d /dev/ttyACM0 --csv monitor.csv -c 20 monitor

---

JSON sequence format

Top-level structure

A sequence file is a JSON object with these top-level keys:

{
  "name": "example_name",
  "sample_period_ms": 500,
  "safety": {
    "max_voltage": 30.0,
    "max_current": 2.0,
    "max_power": 20.0,
    "abort_on_disconnect": true
  },
  "steps": [
    ...
  ],
  "abort_sequence": [
    { "action": "safe" }
  ]
}

Important:

• steps is required and must be non-empty
• abort_sequence is required and must be non-empty
• abort_sequence runs at the normal end of the main sequence and also after runtime abort/error paths whenever possible

Top-level fields

name

Optional string.

sample_period_ms

Optional number.

Default:

500

Purpose:

• polling interval during hold, hold_until, loops, ramps, and CSV logging

safety

Optional object.

Supported fields:

• max_voltage in volts
• max_current in amps
• max_power in watts
• abort_on_disconnect boolean

Practical note:

• the current engine attempts the abort_sequence on runtime failures in general
• abort_on_disconnect is kept in the profile format for future separation of policies, but is not yet handled as a dedicated branch different from other runtime failures

steps

Required array.

abort_sequence

Required array.

Typical safe form:

"abort_sequence": [
  { "action": "safe" }
]

---

Supported actions

set_mode

Stage the operating mode.

{ "action": "set_mode", "mode": "CC" }

Accepted mode values:

• CC / current
• CV / voltage
• CP / power
• CR / resistance
• CVINV / vinv / voltage_inverted

set_current

{ "action": "set_current", "value": 0.20 }

Unit: amps.

set_voltage

{ "action": "set_voltage", "value": 4.80 }

Unit: volts.

set_power

{ "action": "set_power", "value": 2.00 }

Unit: watts.

set_resistance

{ "action": "set_resistance", "value": 10.0 }

Unit: ohms.

set_vinv

{ "action": "set_vinv", "value": 4.50 }

Unit: volts.

output

Enable or disable the staged output.

{ "action": "output", "enabled": true }

or

{ "action": "output", "enabled": false }

hold

Keep the current staged/active target alive for a duration.

{ "action": "hold", "duration_s": 30 }

hold_until

Keep polling until a condition becomes true or timeout is reached.

{
  "action": "hold_until",
  "timeout_s": 300,
  "condition": {
    "type": "voltage_below",
    "value": 3.00
  }
}

ramp_current

{
  "action": "ramp_current",
  "start": 0.20,
  "stop": 1.00,
  "step": 0.10,
  "dwell_s": 20
}

ramp_voltage

{
  "action": "ramp_voltage",
  "start": 4.0,
  "stop": 5.0,
  "step": 0.1,
  "dwell_s": 10
}

ramp_power

{
  "action": "ramp_power",
  "start": 0.5,
  "stop": 5.0,
  "step": 0.5,
  "dwell_s": 15
}

ramp_resistance

{
  "action": "ramp_resistance",
  "start": 100.0,
  "stop": 10.0,
  "step": 10.0,
  "dwell_s": 5
}

ramp_vinv

{
  "action": "ramp_vinv",
  "start": 4.8,
  "stop": 4.0,
  "step": 0.1,
  "dwell_s": 10
}

repeat

Run a nested block a fixed number of times.

{
  "action": "repeat",
  "times": 5,
  "steps": [
    { "action": "set_current", "value": 0.20 },
    { "action": "output", "enabled": true },
    { "action": "hold", "duration_s": 10 },
    { "action": "output", "enabled": false },
    { "action": "hold", "duration_s": 5 }
  ]
}

repeat_until

Run a nested block until a condition becomes true.

{
  "action": "repeat_until",
  "timeout_s": 1800,
  "condition": { "type": "voltage_below", "value": 3.20 },
  "steps": [ ... ]
}

Notes:

• the block runs at least once
• timeout_s is optional
• if omitted or 0, the loop is unlimited

repeat_while

Run a nested block while a condition remains true.

{
  "action": "repeat_while",
  "timeout_s": 7200,
  "condition": { "type": "temperature_above", "value": 20.0 },
  "steps": [ ... ]
}

Notes:

• the condition is checked before each iteration
• timeout_s is optional
• if omitted or 0, the loop is unlimited

safe

Immediate safe-state action.

{ "action": "safe" }

remote

Set remote sense on or off.

{ "action": "remote", "enabled": true }

---

Conditions

Supported condition types:

• voltage_below
• voltage_above
• current_below
• current_above
• power_below
• power_above
• temperature_above

Units:

• voltage conditions: volts
• current conditions: amps
• power conditions: watts
• temperature condition: °C

---

break_if

Any step can carry an optional break_if object.

Format:

"break_if": {
  "type": "temperature_above",
  "value": 45.0
}

Behaviour:

• break_if is checked whenever a report is read during that step
• on block steps like repeat, repeat_until, or repeat_while, the break_if stays active for the whole nested block
• if break_if becomes true, the main sequence stops and the mandatory abort_sequence starts

Typical use:

• thermal guard during long tests
• abort if measured voltage/current/power crosses a forbidden threshold

---

Sequence execution model

Recommended staging pattern:

1. set_mode
2. set_current / set_voltage / set_power / set_resistance / set_vinv
3. output true
4. hold, hold_until, ramp_*, or loop block
5. output false or rely on abort_sequence

Important:

• the MightyWatt watchdog requires regular host traffic
• hold, hold_until, ramps, and loop checks all provide that traffic
• a plain one-shot output true step with no later polling logic is not suitable for long unattended operation

---

Example sequence with loop and safe abort

{
  "name": "repeat_until_cutoff",
  "sample_period_ms": 1000,
  "safety": {
    "max_voltage": 5.0,
    "max_current": 0.6,
    "max_power": 3.0,
    "abort_on_disconnect": true
  },
  "steps": [
    { "action": "set_mode", "mode": "CC" },
    {
      "action": "repeat_until",
      "timeout_s": 14400,
      "condition": { "type": "voltage_below", "value": 3.20 },
      "break_if": { "type": "temperature_above", "value": 45.0 },
      "steps": [
        { "action": "set_current", "value": 0.30 },
        { "action": "output", "enabled": true },
        { "action": "hold", "duration_s": 60 },
        { "action": "output", "enabled": false },
        { "action": "hold", "duration_s": 10 }
      ]
    }
  ],
  "abort_sequence": [
    { "action": "safe" }
  ]
}

Run it with:

./mwcli -d /dev/ttyACM0 --csv run.csv run-sequence repeat_until_cutoff.json

---

Practical notes

• Use hold or run-sequence for anything longer than a quick manual check.
• Use --csv whenever the data matters.
• Keep abort_sequence simple and safe.
• Start with conservative limits.
• set-vinv / ramp_vinv are advanced functions.
• Loop timing in practice is affected by serial round-trip time and sample period; do not expect hard real-time behaviour.

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.