Beta 0.1 – First Linux CLI/backend release
This commit is contained in:
242
README.md
242
README.md
@ -1,3 +1,241 @@
|
||||
# 0005-DenryokuBancho
|
||||
# 0005-DenryokuBancho / 電力番長 (Denryoku Banchō)
|
||||
|
||||
電力番長 (Denryoku Banchō) is a Linux-native CLI fork of the MightyWatt electronic load project by Jakub Polonský (kaktus85). Focused on headless operation, automation pipelines, CSV logging, and JSON-driven test sequences — built to run lean on SBC hardware.
|
||||
電力番長 (Denryoku Banchō) is a Linux-native CLI fork of the MightyWatt electronic load project by Jakub Polonský (`kaktus85`). It is focused on headless operation, automation pipelines, CSV logging, and JSON-driven test sequences, built to run lean on SBC hardware.
|
||||
|
||||
This repository is intentionally backend-first. The goal is to provide a practical Linux control and automation path for MightyWatt hardware before building a GTK frontend on top of it.
|
||||
|
||||
---
|
||||
|
||||
## Attribution and upstream
|
||||
|
||||
This project builds on the original **MightyWatt** work by **Jakub Polonský** (`kaktus85`) back in 2014 to 2017. I own on MightyWatt since 2016.
|
||||
|
||||
Jakub designed the MightyWatt hardware and created the original Arduino firmware and Windows control program. Many thanks to him for publishing such a useful open hardware / software project.
|
||||
|
||||
Original upstream project:
|
||||
- [GitHub - MightyWatt](https://github.com/kaktus85/MightyWatt)
|
||||
- [KaktusCircuits Blog Entry](https://kaktuscircuits.blogspot.com/2014/02/mightywatt-arduino-electronic-load.html)
|
||||
- [Archive.Org - Blog Entry](https://web.archive.org/web/20260101000000*/https://kaktuscircuits.blogspot.com/2014/02/mightywatt-arduino-electronic-load.html)
|
||||
|
||||
Please also see:
|
||||
- `NOTICE.md`
|
||||
- `LICENSE`
|
||||
|
||||
---
|
||||
|
||||
## Current release status
|
||||
|
||||
### Beta 0.1 - Scope:
|
||||
|
||||
This beta provides a usable Linux-native backend and CLI for real MightyWatt hardware, with emphasis on:
|
||||
|
||||
- serial communication from Linux
|
||||
- headless bench operation
|
||||
- watchdog-safe sustained load control
|
||||
- CSV logging
|
||||
- raw CSV export for spreadsheet workflows
|
||||
- JSON-driven automated test sequences
|
||||
- loop-based sequence execution for repeated test patterns
|
||||
|
||||
### Already validated on real my real hardware
|
||||
|
||||
- device identification and capability query
|
||||
- measurement readout
|
||||
- manual CLI control
|
||||
- watchdog-safe `hold` operation
|
||||
- CSV logging
|
||||
- sequence execution on real hardware
|
||||
- raw CSV export mode
|
||||
|
||||
### Implemented but still beta-level
|
||||
|
||||
- `repeat`
|
||||
- `repeat_until`
|
||||
- `repeat_while`
|
||||
- inherited `break_if`
|
||||
- mandatory `abort_sequence`
|
||||
- nested sequence blocks
|
||||
- controller/backend layering for later GUI reuse
|
||||
|
||||
The backend is useful now, but the sequence engine should still be treated as bench-validated step by step, not as a finished production automation framework.
|
||||
|
||||
### Deliberately not the focus of this release
|
||||
|
||||
- GTK4 frontend
|
||||
- persistent settings store
|
||||
- profile editor GUI
|
||||
- plotting GUI
|
||||
|
||||
---
|
||||
|
||||
## Repository layout
|
||||
|
||||
```text
|
||||
include/
|
||||
mightywatt.h
|
||||
mightywatt_app.h
|
||||
mightywatt_controller.h
|
||||
mightywatt_log.h
|
||||
mightywatt_sequence.h
|
||||
|
||||
src/
|
||||
mightywatt.c low-level protocol + serial transport
|
||||
mightywatt_app.c synchronous backend layer
|
||||
mightywatt_controller.c long-running controller/polling layer
|
||||
mightywatt_log.c CSV logger
|
||||
mightywatt_sequence.c JSON sequence engine
|
||||
mwcli.c CLI frontend
|
||||
|
||||
examples/
|
||||
*.json sequence examples
|
||||
mw_controller_example.c controller example
|
||||
```
|
||||
|
||||
### Layering
|
||||
|
||||
- `mightywatt.c` = raw device communication
|
||||
- `mightywatt_app.c` = safe synchronous operations
|
||||
- `mightywatt_controller.c` = GUI-ready async/controller layer
|
||||
- `mightywatt_sequence.c` = reusable sequence engine on top of the backend
|
||||
- `mwcli.c` = thin user-facing CLI
|
||||
|
||||
This keeps a future GTK frontend from reimplementing protocol or automation logic.
|
||||
|
||||
---
|
||||
|
||||
## Build
|
||||
|
||||
Requirements:
|
||||
- Linux
|
||||
- GCC or Clang
|
||||
- POSIX serial/thread support
|
||||
- no external runtime dependencies for the current CLI/backend build
|
||||
|
||||
Build:
|
||||
|
||||
```bash
|
||||
make
|
||||
```
|
||||
|
||||
This builds:
|
||||
- `mwcli`
|
||||
- `mw_controller_example`
|
||||
|
||||
---
|
||||
|
||||
## Typical CLI usage
|
||||
|
||||
Read capabilities:
|
||||
|
||||
```bash
|
||||
./mwcli -d /dev/ttyACM0 caps
|
||||
```
|
||||
|
||||
Read one measurement:
|
||||
|
||||
```bash
|
||||
./mwcli -d /dev/ttyACM0 report
|
||||
```
|
||||
|
||||
Hold a constant current safely against the watchdog:
|
||||
|
||||
```bash
|
||||
./mwcli -d /dev/ttyACM0 hold current 0.250 --interval-ms 500
|
||||
```
|
||||
|
||||
Run a sequence and log CSV:
|
||||
|
||||
```bash
|
||||
./mwcli -d /dev/ttyACM0 --csv run.csv run-sequence examples/quick_cc_test.json
|
||||
```
|
||||
|
||||
Run a sequence with raw CSV output for spreadsheet import:
|
||||
|
||||
```bash
|
||||
./mwcli -d /dev/ttyACM0 --csv run_raw.csv --csv-raw run-sequence examples/repeat_until_cutoff.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sequence engine overview
|
||||
|
||||
Current sequence engine features:
|
||||
- linear step execution
|
||||
- `hold`
|
||||
- `hold_until`
|
||||
- ramps
|
||||
- `repeat`
|
||||
- `repeat_until`
|
||||
- `repeat_while`
|
||||
- per-step and per-block `break_if`
|
||||
- mandatory `abort_sequence`
|
||||
- CSV logging during polling/report events
|
||||
|
||||
The format is **JSON only** in the current implementation.
|
||||
|
||||
See:
|
||||
- `HELP.md`
|
||||
- `sequence_examples.md`
|
||||
- `examples/*.json`
|
||||
|
||||
---
|
||||
|
||||
## Safety model
|
||||
|
||||
There are three layers of protection:
|
||||
|
||||
1. **Sequence safety limits**
|
||||
- max voltage
|
||||
- max current
|
||||
- max power
|
||||
|
||||
2. **`break_if` conditions**
|
||||
- especially useful for thermal guard behaviour
|
||||
- also usable for voltage/current/power-based aborts
|
||||
|
||||
3. **Mandatory `abort_sequence`**
|
||||
- runs at the normal end of a sequence
|
||||
- also runs after runtime abort paths whenever possible
|
||||
- should usually contain at least:
|
||||
|
||||
```json
|
||||
"abort_sequence": [
|
||||
{ "action": "safe" }
|
||||
]
|
||||
```
|
||||
|
||||
Practical note:
|
||||
- if the serial/device link is already gone, the backend will still attempt the abort sequence, but that can of course fail physically
|
||||
|
||||
---
|
||||
|
||||
## Documentation files
|
||||
|
||||
- `HELP.md` — CLI help and full JSON format reference
|
||||
- `sequence_examples.md` — practical example overview
|
||||
- `examples/*.json` — ready-to-edit starting profiles
|
||||
- `NOTICE.md` — attribution and upstream note
|
||||
|
||||
---
|
||||
|
||||
## Known limitations
|
||||
|
||||
- no YAML parser yet
|
||||
- no `validate-sequence` or dry-run command yet
|
||||
- no explicit boolean condition combiner (`AND` / `OR`) yet
|
||||
- no profile include/import system
|
||||
- no persistence layer for CLI settings
|
||||
- no active GUI in this beta release
|
||||
- loop timing is not hard real-time; it depends on polling interval and serial turnaround
|
||||
|
||||
Also important:
|
||||
- `sample_period_ms` is the visible/logging interval, not the low-level keepalive interval
|
||||
- loop-heavy profiles should still be validated carefully on the bench before trusting them unattended
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
This repository is released under the [**GNU GPL v3**](https://www.gnu.org/licenses/gpl-3.0.en.html).
|
||||
|
||||
The original upstream MightyWatt repository contains its own license files for its original contents. Review the upstream repository for the exact license structure of the original project components.
|
||||
Reference in New Issue
Block a user