Metadata-Version: 2.4
Name: can-field-workbench
Version: 0.1.0
Summary: CAN Field Workbench for recording, processing, and analyzing CAN traces.
Author-email: Janosch Meyer <janosch.code@proton.me>
License-Expression: MIT
Keywords: can,can-bus,logger,trc,blf,asc,dbc,sym
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Logging
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cantools<42,>=41.4
Requires-Dist: pydantic>=2
Requires-Dist: python-can
Requires-Dist: PyYAML
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: cyclonedx-bom<8,>=7; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: tdms
Requires-Dist: nptdms; extra == "tdms"
Dynamic: license-file

# 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`:

```bash
pipx install can-field-workbench
```

Install optional TDMS export support together with the CLI:

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

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

```bash
python -m pip install can-field-workbench
```

Verify the installation:

```bash
cfwb --version
cfwb --help
```

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

```bash
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:

```bash
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:

```yaml
recording:
  format: trc

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

Start a bounded 60-second recording:

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

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

```bash
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:

```bash
cfwb convert input.trc output.blf
```

Convert between DBC and PCAN SYM:

```bash
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:

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

Request both CSV and optional TDMS:

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

Signal columns use qualified names:

```text
<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:

```bash
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:

```python
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
`janosch.code@proton.me`.

## 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.
