Command line runner

The same analysis as the browser, from a shell or a test pipeline: how to build it, which files and options it takes, and what its exit code means.

Build and run

The runner needs Node.js 20 or newer. Build it once from the repository: npm run build:cli bundles it into the single file dist-cli/v2g-analyze.mjs, with the message codec inside, which you can copy to another machine and run there.

npm run build:cli
node dist-cli/v2g-analyze.mjs capture.pcapng
  • From a checkout you can also run it straight from the source: npm run cli -- capture.pcapng.
  • make cli builds it and tries it on two demo captures.
  • It makes no network request and needs no browser. -h or --help prints the usage.

Files

  • Give up to five files, in any order: a capture (pcap, pcapng, or a CAN log such as candump, Vector ASC or a PEAK trace), a Control Pilot log (CSV), a TLS key log (NSS format), an OCPP-J log and OCPI records (JSON). At most one of each.
  • Files are recognised by their content, as in the browser; the name and the extension do not matter.
  • A capture or a Control Pilot log is required. A key log, an OCPP log or OCPI records on their own are refused.
  • A saved project is not accepted: give the files it names instead.
node dist-cli/v2g-analyze.mjs session.pcapng cp.csv keys.log ocpp.log

Options

OptionDoes
--jsonPrints the result as JSON instead of text: the tool version, the profile, each file with its size and SHA-256, the warnings, and per session the verdict, the stages, the findings, every check with its status, and why the session fails the --fail-on condition, if it does
--junit <file>Writes a JUnit XML file: one test suite per session, named with its verdict, and one test case per check. A failed check carries its findings; a check that did not apply is marked skipped
--html <file>Writes the self-contained HTML report
--shortWith --html, makes the report the one page summary for a ticket
--profile <file or id>Checks with this limit profile: a JSON file exported from Limits, or a shipped profile by its id, iec61851-iso15118-2-default, sae-j1772-j3400 or open-rth. Without it the default profile applies. Custom checks saved in the profile run too
--fail-on <what>When a session counts as failed: not-completed (the default), error, warning or never
--testcase <ids>Judges the capture against test cases, for example DC-06 or AC-03,BE-02; auto takes the ids from the file name. The test cases then decide the exit code. See Running test cases
--testplan <file>Test cases of your own, as JSON; without --testcase all of them run
--annotate <file>Writes the capture again as pcapng with every finding as a packet comment and the verdicts as the file comment, to open in Wireshark
-h, --helpPrints the usage

Without --json the runner prints a short report per session to standard output: the verdict with the likely party and the confidence, the explanation, the stages, the number of errors and warnings, and up to 50 findings with their time in the session. --junit and --html write their files in addition to that.

Exit codes

CodeWhen
0Every session passes the --fail-on condition
1At least one session fails it, or the files hold no charging session at all (with --fail-on never that is 0 too)
2The runner could not start: a file could not be read or is not a format it knows, two files of the same kind, neither a capture nor a Control Pilot log, a profile it cannot read, an unknown option, or no files at all
--fail-onA session fails when
not-completedIts verdict is anything other than Completed
errorIt has at least one finding of severity error, whatever the verdict
warningIt has at least one finding of severity error or warning
neverNever; only a file problem gives a non zero code

error and warning look at findings only. A session that never charged without an error finding passes --fail-on error, and the iso20 demo completes yet fails --fail-on warning because of its two HS-03 warnings (TLS switched off on the bench). Run twice if both the outcome and the findings matter.

In a test pipeline

A generic shell step that analyses every capture in a folder, keeps a JUnit file and an HTML report per capture, and fails with the highest exit code it saw:

npm ci && npm run build:cli || exit 2
mkdir -p reports
rc=0
for f in captures/*.pcapng; do
  name=$(basename "$f" .pcapng)
  node dist-cli/v2g-analyze.mjs "$f" --profile lab-profile.json --fail-on error \
    --junit "reports/$name.xml" --html "reports/$name.html"
  code=$?
  [ "$code" -gt "$rc" ] && rc=$code
done
exit $rc
  • Point the test report of your pipeline at reports/*.xml to see one test per check, and keep the HTML reports as build artifacts; each is one file that opens in any browser.
  • Keep the limit profile in the repository next to the captures, so a change of limits is a reviewed change like any other.
  • Give the Control Pilot log, key log or OCPP log of the same session in the same call when you have them. The checks that need them report not applicable otherwise.
  • A file with several sessions is fine: each session gets its own test suite, and one failing session makes the call fail.
  • For your own summaries, read the JSON: for example node dist-cli/v2g-analyze.mjs s.pcapng --json | jq -r '.sessions[].verdict.category'.

The analysis API (Team plan)

When a pipeline cannot run Node, the hosted edition analyses a capture for it: send the files to POST /api/analyze and get the same JSON the runner prints with --json. It is part of the Team plan and off until an owner or admin of the team creates a key under Account, API. The key is shown once; store it as a secret of your pipeline.

curl -sS https://YOUR-SITE/api/analyze \
  -H "Authorization: Bearer $V2G_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"capture\": \"$(base64 -w0 session.pcapng)\", \"failOn\": \"error\"}" \
  | jq '.failed, .sessions[].verdict.category'
  • capture is required: the capture or CAN log, base64. cp, ocpp, keylog and ocpi add the Control Pilot log, the OCPP log, the TLS key log and the OCPI records of the same session, also base64.
  • failOn is never (the default), not-completed, error or warning, as --fail-on of the runner. The answer is 200 either way; failed in the JSON says whether the files fail by that rule, so a pipeline step fails on jq -e '.failed == false'.
  • Each file may be up to 20 MB and all files together 40 MB, before base64. A team runs up to 60 analyses an hour.
  • Errors: 401 without a valid key, 403 when the team is not on the Team plan, 413 for a file over the limit, 429 when the hour is used up, 504 when an analysis runs longer than a minute.
  • Unlike the browser analyzer, this sends the capture to the server. It is written to a temporary folder, analysed and deleted; nothing of it is kept, and only the time, the key and the size are logged.

Compared with the browser

  • Same engine, same checks and the same verdicts for the same files and profile.
  • There is no column mapping dialog. A Control Pilot log is read with the mapping the analyzer detects; when it finds no voltage column it prints a warning and the Control Pilot checks report not applicable.
  • There is no alignment step either: the Control Pilot log is placed with the alignment the analyzer proposes.
  • Batch trends, comments and projects are browser features. The runner looks at one set of files per call.