tgohle/0005-DenryokuBancho
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Beta 0.1 – First Linux CLI/backend release

Browse Source
This commit is contained in:
Thomas Gohle
2026-04-12 18:06:47 +02:00
parent dda62c2a37
commit ce1d6e52ab
7 changed files with 1147 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

671
HELP.md Normal file
View File

@ -0,0 +1,671 @@
# 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
```bash
mwcli -d /dev/ttyACM0 [global options] <command> [command args]
```
Example:
```bash
./mwcli -d /dev/ttyACM0 caps
```
---
## Global options
These options go before the command.
### `-d, --device PATH`
Serial device path.
Example:
```bash
./mwcli -d /dev/ttyACM0 caps
```
### `-s, --settle-ms N`
Delay after opening the serial port, in milliseconds.
Default:
```text
2200
```
Use this because Arduino-class boards often reset when the port is opened.
Example:
```bash
./mwcli -d /dev/ttyACM0 -s 2500 caps
```
### `-i, --interval-ms N`
Polling interval in milliseconds.
Used by:
- `monitor`
- `hold`
Default:
```text
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:
```bash
./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:
```bash
./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:
```bash
./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:
```bash
./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:
```json
{
"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:
```text
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:
```json
"abort_sequence": [
{ "action": "safe" }
]
```
---
# Supported actions
## `set_mode`
Stage the operating mode.
```json
{ "action": "set_mode", "mode": "CC" }
```
Accepted `mode` values:
- `CC` / `current`
- `CV` / `voltage`
- `CP` / `power`
- `CR` / `resistance`
- `CVINV` / `vinv` / `voltage_inverted`
## `set_current`
```json
{ "action": "set_current", "value": 0.20 }
```
Unit: amps.
## `set_voltage`
```json
{ "action": "set_voltage", "value": 4.80 }
```
Unit: volts.
## `set_power`
```json
{ "action": "set_power", "value": 2.00 }
```
Unit: watts.
## `set_resistance`
```json
{ "action": "set_resistance", "value": 10.0 }
```
Unit: ohms.
## `set_vinv`
```json
{ "action": "set_vinv", "value": 4.50 }
```
Unit: volts.
## `output`
Enable or disable the staged output.
```json
{ "action": "output", "enabled": true }
```
or
```json
{ "action": "output", "enabled": false }
```
## `hold`
Keep the current staged/active target alive for a duration.
```json
{ "action": "hold", "duration_s": 30 }
```
## `hold_until`
Keep polling until a condition becomes true or timeout is reached.
```json
{
"action": "hold_until",
"timeout_s": 300,
"condition": {
"type": "voltage_below",
"value": 3.00
}
}
```
## `ramp_current`
```json
{
"action": "ramp_current",
"start": 0.20,
"stop": 1.00,
"step": 0.10,
"dwell_s": 20
}
```
## `ramp_voltage`
```json
{
"action": "ramp_voltage",
"start": 4.0,
"stop": 5.0,
"step": 0.1,
"dwell_s": 10
}
```
## `ramp_power`
```json
{
"action": "ramp_power",
"start": 0.5,
"stop": 5.0,
"step": 0.5,
"dwell_s": 15
}
```
## `ramp_resistance`
```json
{
"action": "ramp_resistance",
"start": 100.0,
"stop": 10.0,
"step": 10.0,
"dwell_s": 5
}
```
## `ramp_vinv`
```json
{
"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.
```json
{
"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.
```json
{
"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.
```json
{
"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.
```json
{ "action": "safe" }
```
## `remote`
Set remote sense on or off.
```json
{ "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:
```json
"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
```json
{
"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:
```bash
./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.