241 lines
6.3 KiB
Markdown
241 lines
6.3 KiB
Markdown
# 0005-DenryokuBancho / 電力番長 (Denryoku Banchō)
|
|
|
|
電力番長 (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. |