ChargeLink Native
DEP docs ↗Developed byDEVlink

First Successful Session: 15-Minute Tutorial

This tutorial proves the installation, the profile catalogue, a real EVSE/EVCC protocol exchange over the IPv6 loopback interface, a deterministic simulation with replay, and the gRPC Integration API. It needs no charging equipment, no license and no administrator rights. The expected results were recorded on version 0.5.0-rc2.

Open PowerShell and define the paths from Install and Activate:

$CL   = 'C:\ChargeLink\0.5.0-rc2\pc1\bin\chargelink.exe'
$Data = 'C:\ChargeLinkData'

1. Confirm the environment

chargelink --version
chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json doctor
chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json profile list
chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json profile show iso15118_20_dc

Expected: version 0.5.0-rc2; doctor "status": "ok"; a list of 64 profiles with id, protocol, role and description; the profile iso15118_20_dc shown as an EVSE ISO 15118-20 profile with connector ccs2 and EXI mode chargelink-exi.

2. Validate an EVSE profile without opening sockets

chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json evse start --dry-run --protocol iso15118-20 --profile-id iso15118_20_dc

Expected: "mode": "dry_run", "status": "validated" and a generated run_id. The result also prints the listener.activation_catalog: for each protocol, the exact listener command and the matching EVCC activation command. Keep this output; it is the authoritative recipe for your build.

Inspect and stop the dry-run session:

chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json evse status
chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json evse list-state
chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json evse stop

Expected: status reports "session_status": "dry_run_validated", a heartbeat with a PID, and "process_state": "not_live_mode". The stop command completed successfully.

3. Run the local EVCC-to-EVSE loopback

This runs a ChargeLink EVCC and a ChargeLink EVSE inside one process over ::1, with real SDP-less TCP, V2GTP framing and native EXI encoding:

chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json evcc local-loopback-smoke `
  --protocol iso15118-20 `
  --profile-id iso15118_20_dc `
  --peer-ipv6 '::1' `
  --tcp-port 50118 `
  --max-steps 6 `
  --battery-model constant_power_reference `
  --battery-capacity-kwh 80 `
  --initial-soc-pct 20 `
  --target-soc-pct 80 `
  --requested-power-kw 50 `
  --battery-step-seconds 1

Expected: "status": "completed"; evse_processed_messages lists SupportedAppProtocolBoundary, SessionSetupReq/Res and ServiceDiscoveryReq/Res; evcc_executed_steps is 6 and the final state of charge moved from 20.0 to about 20.1 %. The artifact list names EXI captures under exi\, JSON-lines traces under traces\ and reports under protocol\.

The loopback stops after service discovery by design. It proves transport, framing and codec on this PC. A full charge loop needs the external-EVCC listener with a separate EVCC process, or the deterministic simulation in the next step.

4. Run a deterministic simulation and replay it

Expected: 27 events; transcript SHA-256 d89b78cc48603b4b889d5acf470ed59b86367487f55aef2ca29c3a639c1f05c9. Reported claim_boundary: none_protocol_parity_deterministic_simulation_evidence_only.

chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json sim paired --protocol iso15118-20 --scenario dc-bpt-nominal --seed 42 `
  --run-id first-sim --write-artifacts --output "$Data\tests\first-sim-report.json"
chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json sim replay --trace "$Data\tests\first-sim-report.json"

Expected: the paired simulation walks SDP, session setup, schedule exchange, DC precharge, the DC charge loop and session stop for both roles and writes a transcript with a SHA-256 hash. The replay reports "status": "replay_verified" with identical expected_transcript_sha256 and actual_transcript_sha256 (27 events for this scenario and seed).

5. Start the gRPC Integration API

Open a second PowerShell window and leave it running:

$CL   = 'C:\ChargeLink\0.5.0-rc2\pc1\bin\chargelink.exe'
$Data = 'C:\ChargeLinkData'
chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" `
  integration serve --listen 127.0.0.1:50051 --state-root "$Data\runtime\integration"

Expected on the console: ChargeLink Integration API v1 starting on 127.0.0.1:50051; state_root=C:/ChargeLinkData/runtime/integration. Before the port opens, the server writes a new random access token to $Data\runtime\integration\api-token (readable only by your account and SYSTEM). Every client call must carry that token; the CLI reads it from CHARGELINK_API_TOKEN_FILE or, when that variable is unset, from <runtime-root>\integration\api-token. With the state root chosen above the default path matches, so no variable is needed in this tutorial. A non-loopback --listen address is refused (exit 40).

Back in the first window:

chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json integration health --endpoint http://127.0.0.1:50051
chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json integration capabilities --endpoint http://127.0.0.1:50051
chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json integration session-smoke --endpoint http://127.0.0.1:50051 --protocol iso15118-20 --role evse
chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json signals list --endpoint http://127.0.0.1:50051
chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json signals smoke --endpoint http://127.0.0.1:50051

Expected: health "status": "passed", health_status serving, product_version 0.5.0-rc2, api_version 1.8.0; capabilities with 19 entries, max_page_size 1000, max_signal_batch_size 512; the session smoke passes through session_state_created, session_state_running and session_state_completed and deletes its session; the signal list reports signal_count 94; the signal smoke writes and reads back Vehicle.SocPct (write_read_roundtrip true). A call without a readable token fails locally with CL-RUNTIME-001 and the text "The request does not have valid authentication credentials"; see gRPC Integration Agent.

6. Locate the evidence

chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json runtime list
chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json artifacts index
Get-ChildItem "$Data\artifacts" -Directory | Sort-Object LastWriteTime -Descending | Select-Object -First 5

Each run directory contains manifest.json with a SHA-256 for every file. Verify one:

chargelink --runtime-root "$Data\runtime" --artifact-root "$Data\artifacts" --json artifacts integrity --run-id first-sim

What you have proved

  • The CLI runs from the installed path and reports the expected version.
  • Profiles resolve; an EVSE configuration validates without opening sockets.
  • A native EVCC and EVSE exchange real V2GTP/EXI messages over the IPv6 loopback.
  • Deterministic simulations reproduce byte-identical transcripts.
  • The gRPC server answers health, capability, session and signal requests.
  • Evidence lands under the chosen artifact root with integrity hashes.

What you have not proved: physical-layer interoperability (PLC, control pilot), TLS trust with a real peer, or any behaviour of a third-party charger or vehicle. Continue with First 60 Minutes and then Environment and Bench Preflight.

HomeTop