Skip to content

overview.md

Latest commit

 

History

History
327 lines (262 loc) · 17.7 KB

overview.md

File metadata and controls

327 lines (262 loc) · 17.7 KB
Raw

Control the Simulated OBC from Another PC

Use Dokime's simulated on-board charger (OBC) to learn remote device control, test execution, confirmation prompts and evidence inspection without hardware.

The host PC runs Dokime, its server and the OBC plugin. The remote PC runs the CLI or Python examples. A case describes a test; an execution is one attempt at that case. A cycle groups attempts and their saved evidence. The host can have several Active cycles, with one execution running at a time.

This is a candidate-artifact walkthrough. No matching published Dokime release is claimed here. Obtain one complete CI candidate as described below; its native installation and workflow checks must pass before treating it as validated. A version string alone does not identify compatible candidate bytes.

Obtain One Matching Candidate

Open Dokime's GitHub Actions and select the maintainer-designated pull-request run for the candidate revision. Record its full commit SHA. Use a completed successful run with successful Package / Rust jobs for the required platforms. An artifact appearing on a failed or unfinished run does not establish readiness.

Download these artifacts from that same run:

PC Or Content Artifact Name File Inside The Download
Windows x86-64 installer and host plugin package-dev-rust-windows package-dev-rust-windows.tar
Linux x86-64 installers and host plugin package-dev-rust-linux package-dev-rust-linux.tar

GitHub wraps each artifact in a ZIP. Extract that ZIP, then extract its TAR, for example tar -xf package-dev-rust-windows.tar on Windows or tar -xf package-dev-rust-linux.tar on Linux. These are archive extraction commands, not source-build commands. The extracted target/ directory is packaged content; no repository checkout, Rust compiler, mise or development server is needed.

Use the version shown in the candidate artifact filenames in place of <version>. Find these files after extraction:

Platform Installer Matching Host Plugin
Windows target/package/dev/windows-x86_64/rust/installers/dokime-<version>-x86_64-pc-windows-msvc-setup.exe target/package/dev/windows-x86_64/rust/plugins/plugin-host.dokime
Ubuntu/Debian x86-64 target/package/dev/linux-x86_64/rust/installers/dokime_<version>_amd64.deb target/package/dev/linux-x86_64/rust/plugins/plugin-host.dokime
Fedora x86-64 target/package/dev/linux-x86_64/rust/installers/dokime-<version>-1.x86_64.rpm target/package/dev/linux-x86_64/rust/plugins/plugin-host.dokime

The installer includes the host telemetry bundle. OBC is a source-built test fixture, not a candidate download; build it with mise run build:rust:tests and transfer target/build/dev/<target>/fixtures/plugins/plugin-obc.dokime when running the OBC walkthrough below.

Tutorials remain source examples; native SDK wheels are release assets. For this unreleased candidate, check out the recorded candidate SHA and copy sdk/python/examples/remote/ to remote-demo/ on the remote PC. For Python, follow the local wheel setup before transferring the complete tree. Keep its cli/, python/ and prepared wheels/ directories together. On Windows, set $INSTALL_DOKIME = $false in cli/bootstrap.ps1 for this unreleased candidate, then run cli/bootstrap.bat (or cli/bootstrap.ps1) to install PowerShell 7.6.7, mise and uv without elevation. The default INSTALL_DOKIME=true setup uses mise to install the exact official GitHub release asset for the Dokime CLI; this walkthrough instead uses the matching candidate installer. Follow the Windows bootstrap instructions, then open a new terminal. These are optional client-tool prerequisites; the native Dokime installation itself does not need mise.

Use the plugin for the host's OS. A Windows remote PC can control a Linux host and vice versa; obtain both native artifacts from the same revision when needed. Keep the original archives and commit SHA with your test notes. CI artifacts expire, so download the complete set together. When a matching release combination is published, use that release's own documented artifacts and verification instructions instead of mixing candidates and releases.

Install Dokime

Install the matching native package on both PCs if using CLI scripts. The Python-only remote path needs the examples and Python environment, not a local Dokime server.

On Windows, run dokime-<version>-x86_64-pc-windows-msvc-setup.exe and complete installation. The installer adds its directory to your user PATH. Close existing terminals and open a new one afterward. The installed CLI and GUI stay together; each embeds the server library; do not move only dokime.exe out of that directory.

Linux packages support Ubuntu 22.04+, Debian 12+ and current Fedora; RHEL and Rocky Linux lack WebKitGTK 4.1 and are unsupported.

On Ubuntu or Debian, open a terminal in the extracted installers/ directory:

sudo apt install ./dokime_<version>_amd64.deb

On Fedora, from its installers/ directory:

sudo dnf install ./dokime-<version>-1.x86_64.rpm

Use your package manager to resolve the package's native desktop dependencies. These candidates target Linux and Windows x86-64; this guide does not establish support for another architecture.

On either PC, verify command discovery in a new terminal:

dokime --version

Launch Dokime from the host's application menu. Keep that host application open throughout the walkthrough. The remote PC only needs terminal commands; launching another local server there is unnecessary.

Install the Host Plugin

On the host, open Settings → Plugins. Under Install a Plugin, choose Choose File, then select the host-platform plugin-obc.dokime from the candidate's plugins/ directory. Selecting the bundle installs it directly.

Choose Restart Now in the restart dialog. The installed plugin activates when the host restarts. Return to Plugins and check that the installation is enabled and its programs loaded without an error. The simulated plugin needs no physical device or institute secrets.

Do this before starting any tests: a host/server restart stops work and seals its Active cycles.

Configure Host Remote Access

Use the host's connected local desktop session, then open Settings → Remote Access.

  1. Choose Export Remote Access and confirm enablement if the listener is off. It uses the saved port, or 8765 by default, and detects the hostname and real interface addresses automatically. Save lab.dokime-remote.
  2. Treat this file as a secret. Transfer it privately to the other PC. Loopback addresses work on the same PC only.
  3. Windows installation needs no administrator rights. If Remote Access shows a firewall notice on the host, choose Allow In Firewall… and have an administrator approve the listener's local-subnet rule for the listed network profiles, including Public cable networks. See Direct Cable Between Two PCs. Connecting from the other PC needs no firewall change. On Linux, allow the listener port through the host firewall. Advanced listener settings can change that port.

Transfer that pairing file privately to remote-demo/ on the remote computer. It contains a one-time access key and public CA certificate; keep the file private. The host retains only a verifier. Create a separate pairing for each client, and revoke a lost client's entry in Paired Clients. Revocation leaves other clients usable.

Connect from the Remote PC

Import the pairing once into the native registry; its credential goes to the OS keyring:

dokime backend add --remote lab.dokime-remote --identifier lab
dokime status --backend lab --json
dokime operation list --backend lab
dokime catalog list --backend lab --json

Status must report ready. Discovery must include obc.device.read, obc.device.set_power and the obc.checks.pulse template. The client checks both the TLS certificate and expected backend identity before calling application operations. Python scripts use DokimeClient.from_pairing and keep the credential only in that client's transport. CLI remote import verifies the connection; GUI import also connects and selects the new backend. Python constructs a client first, connecting on async with or await client.connect().

Run the Three Workflows

Choose one family:

  • Native CLI scripts: POSIX shell, PowerShell 7.3 or newer, or Command Prompt. PowerShell 7 is a separate program from Windows PowerShell; see Microsoft's installation instructions.
  • Python scripts: supported CPython versions are >=3.13,<3.16, with a uv environment and a locally built matching wheel.

Edit the globals at the top of each selected script. Native CLI scripts use BACKEND_IDENTIFIER = lab after the import above. Python scripts use PAIRING_FILE = Path("../lab.dokime-remote") when run inside python/. Paths resolve relative to the terminal's working directory. Run scripts without arguments.

control-device reads the manual device, powers it on, verifies its 230 V RMS state, powers it off and reads zero volts. Fixed JSON files in the current directory contain the five replies. This manual device is separate from each execution's simulation; manual commands are not logged as execution evidence.

The device CLI preserves existing response files through its native output policy; use a fresh working directory for another run. Python replaces its fixed response files when rerun.

control-test checks evidence destinations, materializes one case, appends two independent attempts to a new cycle, then spells out each run and export in order. Its default configuration produces two attempts of eight pulse samples each. The client waits for the durable outcomes and final listener drain; Python prints the returned records and samples after each run, while the CLI prints them live. The script downloads execution-1.zip, execution-2.zip and cycle.zip into test-evidence/.

control-prompt creates a separate confirmation attempt, starts it without blocking, displays its pending question and answers the exact prompt UUID with ANSWER (default yes). Sampling begins after confirmation. It downloads execution.zip and cycle.zip into prompt-evidence/. A no answer produces a nonpassing execution outcome. Inspect that outcome rather than treating the demonstration script's exit status as an aggregated verdict.

Use a new evidence directory before rerunning, or explicitly choose overwrite. Shell error handling can stop a script before its later export commands; use the printed identities to inspect and export that attempt. Do not resubmit an uncertain mutation just because a response or connection was lost.

Stop and Recover

Ctrl+C in a test or prompt workflow requests scoped cancellation and evidence recovery. The script's own cycle is sealed, cancelling its unstarted members; other clients' cycles and the shared server remain available. Native scripts write recovery bundles under recovery/; Python saves collected evidence in its configured output directory.

The CLI guide states the exact batch limitations: connection setup, gaps between commands and an unknown cycle after a lost Create reply cannot receive universal automatic cleanup. Keep every printed cycle/execution identity and inspect the same server after reconnecting. For manual device interruption, read its state before resending.

Explicit execution Stop durably sets its cycle's continue_automatically=false. A later explicit Start runs only its selected attempt until an operator explicitly re-enables continuation. Closing a remote client does not shut down the host. Closing a GUI-managed host server does: download evidence before shutting that host down. Saved evidence can be fetched after restarting or reconnecting to the same server without rerunning hardware.

Inspect Saved Evidence

Extract one evidence ZIP into its own new directory, for example unpacked-test/. It contains manifest.json, evidence.sqlite, artifacts/ for captured files, telemetry/ for Arrow IPC files, and saved HTML under reports/. Cycle bundles group artifacts and telemetry under executions/<execution-id>/. Open a report in a browser to inspect the saved document.

The CLI/Python download already checks the archive's size and SHA-256 before publishing it. Check that the manifest has schema_version: 1 and complete: true. It also lists each payload's path, size_bytes and sha256. To compare the database payload manually, open its manifest entry and run sha256sum unpacked-test/evidence.sqlite on Linux, or Get-FileHash .\unpacked-test\evidence.sqlite -Algorithm SHA256 in PowerShell. Compare against the database payload's digest, not the whole ZIP digest.

Install the SQLite command-line tools or use an existing SQLite browser. Use SQLite 3.37 or newer: the database uses STRICT tables. Open the extracted file read-only:

sqlite3 -readonly unpacked-test/evidence.sqlite

Run these queries; they use the exported schema directly:

SELECT cycle_id, phase FROM cycles;
SELECT execution_id, cycle_id, status FROM executions;
SELECT execution_id, direction, identifier, source_kind, value, unit_json
FROM inputs ORDER BY execution_id, direction, identifier;
SELECT execution_id, record_type, count(*) AS records
FROM records GROUP BY execution_id, record_type;
SELECT s.execution_id, s.stream_id, s.rows, f.path, f.size_bytes, f.sha256
FROM streams AS s JOIN files AS f ON f.id = s.file_id
ORDER BY s.execution_id, s.stream_id;
SELECT s.stream_id, n.signal, n.count, n.minimum, n.maximum, n.sum
FROM stream_summaries AS n JOIN streams AS s ON n.file_id = s.file_id;
SELECT a.execution_id, a.relative_path, f.path, f.size_bytes, f.sha256
FROM artifacts AS a JOIN files AS f ON a.file_id = f.id;
SELECT execution_id, relative_path, archive_path, size_bytes, sha256
FROM outputs ORDER BY execution_id, ordinal;

The default successful pulse has eight rows in obc.pulse per execution and one obc.run.started and obc.run.completed record each. Interrupted attempts retain their truthful outcome and whatever rows were saved. An execution bundle taken before cycle sealing can show an Active cycle; the final cycle bundle shows its sealed phase and all members.

Read the exported typed telemetry file with an Arrow-compatible reader. For example, in a Python environment with Polars installed:

from pathlib import Path
import polars as pl

for path in Path("unpacked-test").rglob("telemetry/*.arrow"):
    frame = pl.read_ipc(path)
    print(path, frame.select(pl.col("values").struct.unnest()).head(8))

The Arrow schema carries field units, descriptions and stream identity. SQLite files rows identify each archive member and digest; streams links telemetry to its execution and lists batch offsets and row/time ranges in batches_json. This membership includes captured observer samples whose producer scope remains empty or identifies another owner. Shared files contribute only captured rows. Keep the manifest, database, reports, artifacts and Arrow files together. Use .quit to leave the SQLite CLI.

Troubleshooting

Symptom Check
No package artifact or missing installer/examples Use the same successful candidate run and inspect Package jobs. Expired or partial artifacts are not a complete candidate; ask its maintainer for a complete set.
dokime is not found Reopen the terminal after Windows installation; check where dokime on Windows or command -v dokime on Linux. Repair the native installation rather than moving only its CLI binary.
Linux package dependencies cannot resolve Use the package manager for the matching DEB/RPM and architecture. Retain its error; the candidate does not establish compatibility with every distribution release.
PowerShell rejects a script or JSON argument Run PowerShell 7.3+ (pwsh --version), not Windows PowerShell 5.1. Follow your organization's script-execution policy. Batch is available without PowerShell 7.
Status is unreachable Keep the host running; check Listening On, the host IP, selected port, firewall and network route. A remote client must not use the bind address 0.0.0.0 or its own loopback address.
Certificate verification fails Export a current remote file if every saved address is obsolete. Leaf reissue preserves the pinned CA; use a fresh root only when deliberately replacing CA trust. Do not disable verification.
Authentication fails Check that the paired client has not been revoked. Create and import a new pairing for that client if needed.
OBC operations/template are missing Install the host-OS plugin from the same candidate, restart the host and check Plugins for loading errors.
Existing evidence destination Select a new evidence directory or explicitly choose overwrite. Preserve previous results you need to retain.
A script timed out or disconnected Retain its printed UUIDs; reconnect to the same host and inspect. Remote work may continue. Rerunning a script would create new attempts.
SQLite reports a schema error Confirm the database was extracted fully and use SQLite 3.37+. Compare its SHA-256 with the manifest before interpreting data.

For an institute plugin, install its matching host bundle and follow its own settings and hardware instructions. Discover its operation IDs and templates, then substitute those contracts in the examples. The OBC tutorial supplies no institute secrets or hardware settings.