kirby-ocpp 0.2.0 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026
+Copyright (c) 2026 Kirill Belolipetsky
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -23,7 +23,7 @@ With Cargo (Rust 1.88 or newer):
 cargo install kirby-ocpp
 ```
 
-Or download a prebuilt binary for Linux, macOS or Windows from the [GitHub releases](https://github.com/archhaze24/kirby-ocpp/releases). To build from a checkout: `cargo install --path crates/kirby-ocpp`.
+Or download a prebuilt binary for Linux (x86_64 glibc, aarch64 glibc, x86_64 static musl for Alpine and minimal containers), macOS or Windows from the [GitHub releases](https://github.com/archhaze24/kirby-ocpp/releases). To build from a checkout: `cargo install --path crates/kirby-ocpp`.
 
 ## Quick start
 
@@ -48,11 +48,14 @@ kirby-ocpp --url ws://localhost:9000/ocpp run --scenario charge-session
 | `-c, --connector` | | `1` | Initial connector |
 | `--connectors` | | `1` | Number of connectors |
 | `--heartbeat` | | `30` | Fallback heartbeat interval (s) |
+| `--nominal-power-w` | | `7200` | Nominal charging power per connector (W); charging profiles can only lower it |
+| `--voltage-v` | | `230` | Voltage per phase (V), used for A to W conversion and the `Voltage` reading |
+| `--phases` | | `1` | Number of phases (1-3) |
 | `--ws-subprotocol` | `OCPP_WS_SUBPROTOCOL` | `ocpp1.6` | Requested subprotocol |
 | `--ws-ping` | `OCPP_WS_PING_INTERVAL` | `30` | WebSocket ping interval (s), `0` disables |
 | `--reconnect <BOOL>` | `OCPP_RECONNECT` | `true` | Auto-reconnect after unexpected disconnect |
 | `--no-reconnect` | | | Disable auto-reconnect (wins over `--reconnect`) |
-| `--reconnect-initial-ms` | `OCPP_RECONNECT_INITIAL_MS` | `1000` | Initial backoff |
+| `--reconnect-initial-ms` | `OCPP_RECONNECT_INITIAL_MS` | `1000` | Initial backoff; `0` is rejected (exit 2) unless `--reconnect-max-attempts` is set or reconnect is off |
 | `--reconnect-max-ms` | `OCPP_RECONNECT_MAX_MS` | `30000` | Maximum backoff |
 | `--reconnect-max-attempts` | `OCPP_RECONNECT_MAX_ATTEMPTS` | `0` | `0` = unlimited |
 | `--call-timeout-ms` | `OCPP_CALL_TIMEOUT_MS` | `30000` | CALL response timeout |
@@ -62,6 +65,11 @@ kirby-ocpp --url ws://localhost:9000/ocpp run --scenario charge-session
 | `--tls-skip-verify` | `OCPP_TLS_SKIP_VERIFY` | off | Skip certificate verification (testing only) |
 | `--no-persist` | `KIRBY_OCPP_NO_PERSIST` | off | Do not load or save station state |
 | `--state-dir` | `KIRBY_OCPP_STATE_DIR` | `~/.kirby-ocpp/stations` | State directory (`%USERPROFILE%` on Windows) |
+| `--count` | `OCPP_COUNT` | `1` | Number of stations (fleet mode, 1-1000), see [Fleet mode](#fleet-mode) |
+| `--id-template` | `OCPP_ID_TEMPLATE` | the `--id` value | Charge point id template with `{n}` / `{n:03}` |
+| `--first-index` | `OCPP_FIRST_INDEX` | `1` | Index of the first station |
+| `--stagger-ms` | `OCPP_STAGGER_MS` | `0` | Delay between starting two stations (ms) |
+| `--rule ACTION=BEHAVIOR[*N]` | `KIRBY_OCPP_RULES` (`;` separates rules) | none | Response rule for a CSMS command, repeatable; see [Response rules](#response-rules) |
 | `--print-config` | | | Print the effective configuration as JSON and exit |
 | `--no-tui` | | | Never start the TUI; log to stdout |
 | `--json` | | | JSON lines instead of text (events and the `run` report) |
@@ -77,7 +85,7 @@ Options are global and may be placed before or after a subcommand.
 
 ## State persistence
 
-Per charge point id, one JSON file `<state dir>/<id>.station.json` holds the local authorization list and its version, authorization cache, charging profiles, writable configuration values, availability, connector count and per-connector state (status, meter, reservation, transaction) and the offline transaction queue. Files are versioned and written atomically (temp file plus rename); a corrupt file or one belonging to another charge point is moved to `<file>.bak` and the station starts clean. `--no-persist` disables both loading and saving.
+Per charge point id, one JSON file `<state dir>/<id>.station.json` holds the local authorization list and its version, authorization cache, charging profiles, writable configuration values, availability (including a `Scheduled` change waiting for a transaction to end), connector count and per-connector state (status, meter, reservation, transaction) and the offline transaction queue. Ids whose escaped name would exceed 100 bytes are shortened and get a hash suffix (`...~<16 hex>.station.json`) so the name always fits the filesystem limit. Files are versioned and written atomically (temp file plus rename, then the directory is fsynced); a corrupt file or one belonging to another charge point is moved to `<file>.bak` and the station starts clean. `--no-persist` disables both loading and saving.
 
 ## Terminal UI
 
@@ -94,7 +102,17 @@ Seven tabs, switched with `1`-`7` or `Tab`/`Shift-Tab`: Station, Connector, Tran
 | `?` | Help |
 | `q`, `Ctrl-C` | Quit |
 
-Actions: connect/disconnect/reconnect, BootNotification, Heartbeat, add connector; plug/unplug, set status, StatusNotification, fault toggle; Authorize, StartTransaction, StopTransaction (with reason), MeterValues; set diagnostics/firmware outcome and send their status notifications; DataTransfer, vendor ping and raw CALLs.
+Actions: connect/disconnect/reconnect, BootNotification, Heartbeat, add connector, response rules (`m` adds one, `Action=off` removes one, `M` clears all; active rules are listed in the Station pane); plug/unplug, set status, StatusNotification, fault toggle; Authorize, StartTransaction, StopTransaction (with reason), MeterValues; set diagnostics/firmware outcome and send their status notifications; DataTransfer, vendor ping and raw CALLs.
+
+Data browser (Station tab: `K` config keys, `L` local authorization list, `P` charging profiles; also in the palette): one popup with three pages, switched with `Tab`/`Shift-Tab`, `Left`/`Right` or `1`-`3`. `/` filters the rows fuzzily (`Enter` keeps the filter, `Esc` clears it), `Up/Down`/`j/k`/`PageUp/PageDown`/`g`/`G` move, `Esc`/`q` closes. Forms and confirmations opened from the browser return to it. Edits are local commands that behave like the CSMS-triggered ones, without a CSMS round trip:
+
+| Page | Keys |
+| --- | --- |
+| Config keys | `Enter`/`e` edits the selected key (read-only keys are marked `(ro)` and refuse); the value is checked live with the station's own rules, as `ChangeConfiguration` would, and applied with the same side effects (heartbeat/metering timers) and persistence |
+| Local auth list | `a` adds, `Enter`/`e` edits (idTag, status, expiry, parent), `d` removes, `c` clears (asks first). Each add/edit/remove is a differential update that bumps the list version by one; clear empties the list and resets the version to 0 |
+| Charging profiles | `i` installs a profile from JSON (a template is prefilled; paste your own: `csChargingProfiles` object plus connector, validated against the `SetChargingProfile` schema and the station's profile rules), `e` edits the selected one (same id replaces it), `Enter` shows its JSON (`c` there copies), `d` deletes it, `c` clears all (asks first) |
+
+The snapshot behind it (`Snapshot::config`, `local_list`, `charging_profiles`) is also available to API users; the local list view holds at most 500 entries (`total` has the real count).
 
 Log view (Logs tab): CALL/RESULT/ERROR correlation, filters (all, calls, errors, station, csms; `f`), search (`s`), pause/follow (`p`), jump to newest (`G`), detail view with scroll (`Enter`; `c`/`y` copies), copy row (`y`) or visible rows (`Y`), export as JSONL (`e`, default `./kirby-ocpp-<id>-<timestamp>.jsonl`), clear with confirmation (`c`). The buffer keeps the last 2000 entries. Copying tries external clipboard tools first and falls back to the terminal's OSC 52 sequence.
 
@@ -111,10 +129,36 @@ Without a TTY (or with `--no-tui`) the tool connects and prints events until SIG
 | 0 | Success (scenario passed, normal shutdown) |
 | 1 | Scenario failed or timed out, or a runtime error |
 | 2 | Usage or configuration error |
+| 130 | `run` interrupted by SIGINT (Ctrl-C); SIGTERM still ends it with 1 |
+
+## Fleet mode
+
+`--count N` runs N independent stations in one process against the same CSMS, for load and multi-station tests (terminal UI on a TTY, headless with `--no-tui` or without one).
+
+```
+kirby-ocpp --url ws://localhost:9000/ocpp --id 'CP-{n:03}' --count 50 --stagger-ms 100 --no-tui
+kirby-ocpp --url ws://localhost:9000/ocpp --id 'CP-{n}' --count 20 run --scenario charge-session
+```
+
+- The id comes from `--id-template`, or from `--id` when no template is given. `{n}` is the station index, `{n:03}` the index zero-padded to 3 digits; `{{` and `}}` are literal braces. With `--count` above 1 the template needs a placeholder (otherwise exit 2). `--first-index` (default 1) is the index of the first station, so `--count 3 --first-index 10` gives `CP-10`, `CP-11`, `CP-12`. `--count 1` without `--id-template` uses `--id` as is; with an explicit template it is expanded too.
+- Every station is a normal station (own connection, transactions, state file named after its id, so state files never collide). `--stagger-ms` waits that long between starting two stations.
+- The terminal UI shows a selector row on top (`1 CP-001+* 2 CP-002- ...`: index, id, connection glyph `+` connected, `~` connecting/retrying, `-` offline, `*` a transaction is running) and the selected station below. Everything else (status, log, actions, `K`/`L`/`P` browsers, forms, scenarios) works on the selected station only; each station keeps its own log (last 500 rows), dialogs and scenario progress, and events of the other stations keep being recorded. `Alt` combinations may need "Option as Meta" in macOS terminals. With `--count 1` there is no selector and no extra keys. Quit stops the whole fleet.
+- Output is tagged with the station id: `[CP-001] ...` in front of every human line, a `"station"` field in every JSON line, stdout and `--log-file` alike. With `--count 1` nothing is tagged.
+- `run --scenario` runs the scenario on every station at the same time and prints one report per station (tagged), then one aggregate line: `fleet: 3/3 stations PASSED`, or `fleet: 2/3 stations passed, FAILED: CP-2`. With `--json` the aggregate is `{"type":"fleet_report","passed":bool,"total":n,"passed_count":n,"failed":[ids],"stations":[...]}`. `--timeout` covers the whole fleet, stagger included. `--report out.json` writes one file per station: `out.CP-001.json` (characters of the id other than letters, digits, `-` and `_` become `_`).
+
+| Fleet key | Action |
+|---|---|
+| `<` `>` | Previous / next station |
+| `Alt-1` .. `Alt-9` | Jump to station 1..9 |
+| `Alt-c` / `Alt-d` | Connect / disconnect all stations |
+
+Selector keys work in normal mode only (inside a dialog they are plain input).
+- Exit codes: 0 only if every station passes, 1 if any fails or times out, 2 usage error, 130 SIGINT.
+- `--print-config` with `--count > 1` prints `{"fleet": {...}, "config": {...}}` where `config` is the first station.
 
 ## Scenarios
 
-`kirby-ocpp scenarios list` lists the built-in scenarios (`charge-session`, `fault-recovery`, `finish-session`, `offline-sync`); `kirby-ocpp scenarios show <name>` prints one as TOML. Built-ins target connector 1 unless `--connector` is given.
+`kirby-ocpp scenarios list` lists the built-in scenarios (`charge-session`, `fault-recovery`, `finish-session`, `offline-sync`); `kirby-ocpp scenarios show <name>` prints one as TOML. Built-ins target connector 1 unless `--connector` is given. `offline-sync` works on a stock station: `LocalAuthorizeOffline` and `AllowOfflineTxForUnknownId` default to `true` (switch them off with `ChangeConfiguration` to test the CSMS-side rejection path).
 
 ```toml
 name = "my-session"
@@ -146,7 +190,28 @@ reason = "Local"
 expect = { status = "Accepted" }
 ```
 
-Actions: `connect`, `disconnect`, `reconnect`, `boot`, `heartbeat`, `plug`, `unplug`, `authorize`, `start_tx`, `stop_tx`, `meter`, `status`, `fault`, `clear_fault`, `sleep`, `wait_for`, `expect_call` (`call`, optional `direction`, `match` payload subset), `send_raw` (`call`, `payload`, `validate`), `data_transfer`. Every step may have `name` and `expect` (`status`, `payload` subset, `error = true`). `wait_for` takes `condition = { kind = ... }` with kinds `connected`, `disconnected`, `registration`, `connector_status`, `tx_active`, `tx_idle`, `no_pending_messages`, and `timeout_ms` (default 5000). Unknown fields are rejected.
+Actions: `connect`, `disconnect`, `reconnect`, `boot`, `heartbeat`, `plug`, `unplug`, `authorize`, `start_tx`, `stop_tx`, `meter`, `status`, `fault`, `clear_fault`, `sleep`, `wait_for`, `expect_call` (`call`, optional `direction`, `match` payload subset), `send_raw` (`call`, `payload`, `validate`), `data_transfer`, `set_rule` (`rule`), `clear_rules` (optional `call`). Every step may have `name` and `expect` (`status`, `payload` subset, `error = true`). `wait_for` takes `condition = { kind = ... }` with kinds `connected`, `disconnected`, `registration`, `connector_status`, `tx_active`, `tx_idle`, `no_pending_messages`, and `timeout_ms` (default 5000). Unknown fields are rejected.
+
+## Response rules
+
+Response rules make the station misbehave on purpose, to test how a CSMS reacts. A rule overrides how one CSMS command (any of the 19 the station handles, e.g. `Reset`, `RemoteStartTransaction`, `ChangeConfiguration`) is answered. Form: `ACTION=BEHAVIOR[*COUNT]`, action names case-insensitive.
+
+| Behavior | Effect |
+| --- | --- |
+| `reject` | The action's own rejection (`Rejected`; `NotSupported` for `SendLocalList` and `UnlockConnector`). `GetConfiguration`, `GetLocalListVersion`, `ClearChargingProfile`, `GetDiagnostics` and `UpdateFirmware` have no rejection status, so they get CALLERROR `NotSupported`. |
+| `delay:MS` | The command is handled normally; only the reply is sent `MS` ms later (0 to 3600000). The station keeps working meanwhile. |
+| `error:CODE[:TEXT]` | CALLERROR with an OCPP 1.6 code (`NotImplemented`, `NotSupported`, `InternalError`, `ProtocolError`, `SecurityError`, `FormationViolation`, `PropertyConstraintViolation`, `OccurenceConstraintViolation`, `TypeConstraintViolation`, `GenericError`). |
+| `drop` | Close the WebSocket without replying; the normal reconnect lifecycle follows (disabled by `--no-reconnect`). |
+| `ignore` | Never reply, so the CSMS call timeout fires. |
+
+`*COUNT` applies the rule that many times and then removes it (default: unlimited). There is one rule per action; setting another replaces it. Except for `delay`, the command is **not executed** (no side effects). Rules are runtime only, never persisted. Set them with `--rule` (repeatable) or `KIRBY_OCPP_RULES`; in both, `;` separates several rules, so a rule (e.g. an `error:` text) must not contain `;`, in the TUI (Station tab, `m`), as scenario steps, or through `Command::SetResponseRule` / `ClearResponseRules` in the core API. Each application is logged (`response rule: Reset -> reject, 2 more`).
+
+```sh
+kirby-ocpp --url ws://localhost:9000/ocpp --rule Reset=reject --rule GetConfiguration=delay:5000 \
+  --rule ChangeConfiguration=error:InternalError*3 --rule RemoteStartTransaction=ignore*1
+```
+
+In scenarios: `action = "set_rule"` with `rule = "Reset=reject*2"`, and `action = "clear_rules"` with an optional `call = "Reset"` (all rules when omitted).
 
 ## Testing against a mock
 
@@ -166,4 +231,4 @@ Protocol coverage is documented in [docs/OCPP_1.6J_CONFORMANCE.md](docs/OCPP_1.6
 
 ## License
 
-MIT, see [LICENSE](LICENSE). The bundled OCPP JSON schemas belong to the Open Charge Alliance; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) or run `kirby-ocpp --licenses`. Crate licences are recorded in `Cargo.lock` and the crates' metadata.
+MIT, see [LICENSE](LICENSE). The bundled OCPP JSON schemas belong to the Open Charge Alliance; see [THIRD_PARTY_NOTICES.md](crates/kirby-ocpp/THIRD_PARTY_NOTICES.md) or run `kirby-ocpp --licenses`. Crate licences are recorded in `Cargo.lock` and the crates' metadata.

package/bin/kirby-ocpp.js

@@ -5,34 +5,56 @@
 const { spawnSync } = require("node:child_process");
 const path = require("node:path");
 
+// Candidate packages per platform, in order of preference. The musl build is fully static,
+// so on Linux x64 it is also a valid fallback when the glibc package was not installed.
 const PLATFORMS = {
-  "linux-x64": "@archhaze24/kirby-ocpp-linux-x64",
-  "linux-arm64": "@archhaze24/kirby-ocpp-linux-arm64",
-  "darwin-x64": "@archhaze24/kirby-ocpp-darwin-x64",
-  "darwin-arm64": "@archhaze24/kirby-ocpp-darwin-arm64",
-  "win32-x64": "@archhaze24/kirby-ocpp-win32-x64",
+  "linux-x64": ["@archhaze24/kirby-ocpp-linux-x64", "@archhaze24/kirby-ocpp-linux-x64-musl"],
+  "linux-arm64": ["@archhaze24/kirby-ocpp-linux-arm64"],
+  "darwin-x64": ["@archhaze24/kirby-ocpp-darwin-x64"],
+  "darwin-arm64": ["@archhaze24/kirby-ocpp-darwin-arm64"],
+  "win32-x64": ["@archhaze24/kirby-ocpp-win32-x64"],
 };
 
+// True on a musl-based Linux (Alpine etc.): glibc reports its version, musl does not.
+function isMusl() {
+  if (process.platform !== "linux") return false;
+  try {
+    const report = process.report.getReport();
+    const header = typeof report === "string" ? JSON.parse(report).header : report.header;
+    if (header && "glibcVersionRuntime" in header) return !header.glibcVersionRuntime;
+  } catch {
+    // fall through to the file check
+  }
+  try {
+    return require("node:fs").readdirSync("/lib").some((name) => name.startsWith("ld-musl-"));
+  } catch {
+    return false;
+  }
+}
+
 function binaryPath() {
   const key = `${process.platform}-${process.arch}`;
-  const pkg = PLATFORMS[key];
-  if (!pkg) {
+  const candidates = PLATFORMS[key];
+  if (!candidates) {
     throw new Error(
       `kirby-ocpp has no prebuilt binary for ${key}. Supported: ${Object.keys(PLATFORMS).join(", ")}. ` +
         "Build from source instead: cargo install kirby-ocpp",
     );
   }
-  let manifest;
-  try {
-    manifest = require.resolve(`${pkg}/package.json`);
-  } catch {
-    throw new Error(
-      `The platform package ${pkg} is not installed (npm skipped the optional dependency). ` +
-        "Reinstall without --omit=optional, or run: cargo install kirby-ocpp",
-    );
-  }
+  const ordered = key === "linux-x64" && isMusl() ? [...candidates].reverse() : candidates;
   const exe = process.platform === "win32" ? "kirby-ocpp.exe" : "kirby-ocpp";
-  return path.join(path.dirname(manifest), "bin", exe);
+  for (const pkg of ordered) {
+    try {
+      const manifest = require.resolve(`${pkg}/package.json`);
+      return path.join(path.dirname(manifest), "bin", exe);
+    } catch {
+      // not installed, try the next candidate
+    }
+  }
+  throw new Error(
+    `The platform package ${ordered[0]} is not installed (npm skipped the optional dependency). ` +
+      "Reinstall without --omit=optional, or run: cargo install kirby-ocpp",
+  );
 }
 
 let binary;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kirby-ocpp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Terminal OCPP 1.6J charge point emulator for testing a CSMS (TUI, headless and scenarios)",
   "keywords": [
     "ocpp",
@@ -31,10 +31,11 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@archhaze24/kirby-ocpp-linux-x64": "0.2.0",
-    "@archhaze24/kirby-ocpp-linux-arm64": "0.2.0",
-    "@archhaze24/kirby-ocpp-darwin-x64": "0.2.0",
-    "@archhaze24/kirby-ocpp-darwin-arm64": "0.2.0",
-    "@archhaze24/kirby-ocpp-win32-x64": "0.2.0"
+    "@archhaze24/kirby-ocpp-linux-x64": "0.3.0",
+    "@archhaze24/kirby-ocpp-linux-x64-musl": "0.3.0",
+    "@archhaze24/kirby-ocpp-linux-arm64": "0.3.0",
+    "@archhaze24/kirby-ocpp-darwin-x64": "0.3.0",
+    "@archhaze24/kirby-ocpp-darwin-arm64": "0.3.0",
+    "@archhaze24/kirby-ocpp-win32-x64": "0.3.0"
   }
 }