can-field-workbench 0.1.0

CAN Field Workbench for recording, processing, and analyzing CAN traces.

CAN Field Workbench

CAN Field Workbench is a CLI-first Python tool for recording, converting, and processing CAN traces during field tests. It records one or more CAN interfaces, preserves suite and session metadata, converts common trace and symbol formats, and decodes DBC or PCAN SYM signals to CSV and optional TDMS.

The project is currently alpha software. Its core workflows are implemented and tested, but configuration, CLI behavior, and the Python API may still change incompatibly before version 1.0.

The distribution and canonical CLI are named can-field-workbench. The CLI aliases are cfwb and can-wb, and Python callers import can_field_workbench.

Safety Warning

CAN Field Workbench can record CAN traffic and, when explicitly configured, send individual CAN messages or message sequences. Sending CAN data can affect connected devices, vehicles, machinery, or test systems.

Do not use CAN Field Workbench to send CAN messages on public roads, while driving, or on production, safety-critical, medical, industrial, aviation, railway, or other life-safety systems. Use sending features only on isolated test benches or explicitly approved systems, and only after verifying the interface, bitrate, identifiers, payloads, timing, routing, and message sequences.

The software is not certified for safety-critical use. Operators are responsible for authorization, risk assessment, legal compliance, and safe operation.

Trademarks and Affiliation

CAN Field Workbench is an independent project. It is not affiliated with, endorsed, sponsored, or certified by any hardware, vehicle, software, or format vendor.

All product names, company names, brands, and logos referenced here are the property of their respective owners. They are used only for identification and to describe technical compatibility (nominative use); their use does not imply any affiliation or endorsement. Open-source components this tool depends on are governed by their own licenses (see THIRD_PARTY_NOTICES.md).

Capabilities

• Record one or more CAN interfaces concurrently
• Write PCAN TRC, Vector ASC/BLF, can-utils LOG, or python-can CSV traces
• Preserve campaign, recording, configuration, and session metadata
• Convert supported trace formats with known-loss reports
• Convert DBC and PCAN SYM symbol files with validation
• Decode DBC/SYM signals from individual traces or complete suites
• Export PlotJuggler-friendly wide CSV and optional TDMS
• Print raw messages or decoded signals during recording
• Stream selected decoded numeric signals to PlotJuggler over UDP/JSON
• Dispatch validated automatic or manual CAN message sequences

The gui command is currently a no-window placeholder. CAN Field Workbench is intended to be used through its CLI or supported Python API at this stage.

Requirements

• Python 3.10 or newer
• Windows or Linux
• A python-can compatible interface and its operating-system driver for live recording
• DBC or PCAN SYM files for signal decoding

Converting and processing existing trace files does not require CAN hardware. Live recording requires hardware, drivers, and a valid python-can backend configuration.

Installation

For an isolated command-line installation, use pipx:

pipx install can-field-workbench

Install optional TDMS export support together with the CLI:

pipx install "can-field-workbench[tdms]"

For use inside an existing virtual environment or through the Python API:

python -m pip install can-field-workbench

Verify the installation:

cfwb --version
cfwb --help

The alternative alias, long command, and module entry point are equivalent:

can-wb --help
can-field-workbench --help
python -m can_field_workbench --help

Quick Start

Prepare a Session Without Hardware

The record command does not open CAN hardware unless --autostart is provided or autostart is enabled in configuration. This command validates the effective defaults and prepares suite artifacts safely:

cfwb record --output-dir traces --no-prompt

The default interface is read-only, sequence sending is disabled, and the prepared session is written below traces/suites/.

Record CAN Traffic

Create a YAML or JSON configuration for the intended CAN backend, channel, and bitrate. Review the interface and sending policy before enabling autostart:

recording:
  format: trc

can:
  interfaces:
    - name: primary
      type: pcan
      channel: PCAN_USBBUS1
      bitrate: 500000
      read_only: true

Start a bounded 60-second recording:

cfwb record --config config.yaml --autostart --duration 60

Without --duration, an autostarted recording runs until Ctrl+C or a terminal recorder condition stops it:

cfwb record --config config.yaml --autostart

Use --print-messages for live raw CAN output. Use --print-signals for live decoded output after configuring DBC or SYM files.

Convert Traces and Symbols

Convert a trace by selecting the target suffix:

cfwb convert input.trc output.blf

Convert between DBC and PCAN SYM:

cfwb convert network.dbc network.sym
cfwb convert network.sym network.dbc

Every conversion writes a JSON report next to the output. Review its warnings because target formats cannot preserve every source-format feature.

Process a Trace

Decode a trace and write the default wide CSV export:

cfwb process input.trc --symbols network.dbc --output-dir exports

Request both CSV and optional TDMS:

cfwb process input.trc --symbols network.dbc --export csv --export tdms

Signal columns use qualified names:

<symbol-alias>.<message-name>.<signal-name>

For example, Powertrain.EngineData.Speed.

Process a Suite

Recordings are grouped into suites. Decode every recording explicitly listed in a suite metadata file with:

cfwb process-suite traces/suites/suite_<suite-id>

process-suite does not scan arbitrary traces in the directory. It processes the recording entries stored in suite.metadata.json.

Main Commands

Command	Purpose
cfwb record	Prepare or start a recording session
cfwb convert	Convert a trace or symbol file
cfwb process	Decode and export one trace
cfwb process-suite	Decode recordings listed in suite metadata
cfwb gui	Run the current no-window GUI placeholder

Use cfwb --help and cfwb <command> --help for the complete installed command reference.

Configuration Overview

Configuration files may use JSON, YAML, or YML. Built-in defaults are applied first, followed by each --config file in command-line order and then explicit CLI overrides. Nested objects merge recursively; arrays and scalar values replace earlier values.

The main sections are:

Section	Purpose
recording	Output, format, timing, live output, and failure policy
can.interfaces	python-can backends, channels, bitrate, and send policy
metadata	Campaign and per-recording values
symbols.files	DBC/SYM files and optional aliases
sequences	Reusable message sequences and interface routes
streaming.plotjuggler	Selected live-signal UDP output
processing	Suite-processing export defaults

Sending requires both sequences.enabled: true and read_only: false on the selected interface. Keep interfaces read-only until sending is deliberately configured and reviewed.

Only use live recording and sending on systems for which you have explicit authorization. Test writing functions on an isolated bench first, verify the selected interface, bus parameters, identifiers, payloads, and sequences, and do not use them during driving or on safety-critical equipment without the responsible approval.

Supported Formats

Format	Record	Convert	Process
PCAN TRC	Yes	Yes	Yes
Vector ASC	Yes	Yes	Yes
Vector BLF	Yes	Yes	Yes
can-utils LOG	Yes	Yes	Yes
python-can CSV	Yes	Yes	Yes
DBC symbols	Not applicable	To SYM	Yes
PCAN SYM symbols	Not applicable	To DBC	Yes

Trace conversion preserves supported CAN message fields through a common message model. Format-specific comments, markers, statistics, J1939 transport objects, and unsupported events are not preserved.

Important target limitations include:

• TRC output skips CAN FD, error, and remote frames.
• python-can CSV loses channel, Tx direction, and CAN FD state.
• can-utils LOG normalizes numeric channels to canN.
• DBC/SYM conversion rejects structures that cannot be represented safely and reports remaining known losses.

Output and Reliability

Each interface has an independent bus connection, reader, writer, and bounded writer queue. A full queue drops and counts new messages instead of blocking CAN reception.

Multi-interface recordings support independent reconnect attempts and either stop-all or continue-remaining failure policies. Slow live terminal output and PlotJuggler streaming use separate bounded queues so they do not block trace writing.

Suites preserve the effective configuration, copied configuration sources, campaign metadata, per-recording metadata, session logs, trace files, and processing exports.

Python API

The supported package-level API consists of:

• start_recording
• convert_trace
• process_trace
• process_suite
• launch_gui
• OperationResult
• __version__

Example:

from pathlib import Path

import can_field_workbench

result = can_field_workbench.process_trace(
    Path("input.trc"),
    [Path("network.dbc")],
    Path("exports"),
)
if not result.success:
    raise RuntimeError(result.message)

Every operation returns an OperationResult with command, message, success, and operation-specific details. Expected request failures are usually represented by success=False; invalid configuration, unsupported formats, and file-access failures may raise exceptions.

Project Status and Support

CAN Field Workbench is an alpha release:

• Core CLI recording, conversion, and processing workflows are implemented.
• Automated tests run on Windows and Linux across supported Python versions.
• Built wheels and source distributions are validated before publishing.
• Backward compatibility is not guaranteed before version 1.0.
• The GUI command remains a no-window placeholder.

Report problems or request support by email at [e-mail].

Security and Data Handling

Report suspected vulnerabilities privately as described in SECURITY.md. Do not include unreviewed traces, DBC or SYM files, logs, configurations, credentials, personal data, customer data, or other confidential material in public issues or support requests.

Operators remain responsible for authorization, legal grounds, retention, access control, backups, and applicable safety requirements for all recorded, processed, stored, or shared data.

License

CAN Field Workbench is open source under the MIT License.

Runtime dependencies are installed separately by the package manager and are not bundled with the project wheel. Their direct license indications and the current LGPL distribution boundary are documented in THIRD_PARTY_NOTICES.md.

This project was created with the assistance of artificial intelligence.