Metadata-Version: 2.5
Name: pycan-plot
Version: 0.0.1
Summary: Plot CAN signals from a candump log using a KCD database
Author-email: Alexander Becker <nabla@radiation.systems>
License-Expression: GPL-3.0-or-later
Requires-Python: >=3.9
Requires-Dist: cantools
Requires-Dist: click
Requires-Dist: matplotlib
Requires-Dist: rich
Description-Content-Type: text/markdown

# pycan-plot

Graph CAN signals from a recorded `candump` log, decoded through a KCD
database.

## Installation

```console
pip install -e .
```

## Usage

```console
pycan-plot capture.log -d database.kcd -s Status.Voltage -s Status.Mode -o plot.png
```

Signals are named `Message.Signal`, exactly as they appear in the KCD.
With no `-o`, an interactive window opens instead.

| Option | Meaning |
|---|---|
| `-d`, `--kcd` | KCD database (required) |
| `-s`, `--signal` | `Message.Signal` to plot; repeatable |
| `-p`, `--prefix` | Hex stack-position prefix ORed onto each message ID (default `0x0`) |
| `-t`, `--time-window` | `START..END`; each end is relative seconds (`12.5`) or a clock time (`08:25:40`), and either may be omitted |
| `-o`, `--output` | Output file; format taken from the extension (`.png`, `.svg`, `.pdf`) |
| `--show` | Open an interactive window; implied when `-o` is absent |
| `--split` | One subplot per signal instead of overlaying them |
| `--line` | Interpolate between samples instead of holding each value |

Signals are drawn as steps by default, because a CAN signal holds its last
received value until the next frame arrives. `--line` overrides that.

Examples:

```console
# One module in stack position 2, clipped to twenty seconds of the capture
pycan-plot capture.log -d db.kcd -s Status.Voltage -p 0x02000000 -t 10..30 -o v.png

# Two signals on separate stacked axes, clipped by wall-clock time
pycan-plot capture.log -d db.kcd -s Status.Voltage -s Status.Mode \
    --split -t 08:25:40..08:26:10 -o both.svg
```

## Exit codes

| Code | Meaning |
|---|---|
| 0 | success |
| 1 | log, KCD, or output file could not be read or written |
| 2 | CLI usage error (unknown message or signal, bad `-t`, bad `-p`) |
| 3 | no samples found for any requested signal |

Exit code 3 reports which stack-position prefixes *were* present for the
requested messages — usually the fastest way to spot a wrong `-p`.

## Fish tab completion

An editable install writes the completion script automatically. To do it by
hand:

```fish
_PYCAN_PLOT_COMPLETE=fish_source pycan-plot | source                                      # current shell
_PYCAN_PLOT_COMPLETE=fish_source pycan-plot > ~/.config/fish/completions/pycan-plot.fish  # persistent
```

Completion covers log files, KCD files, message and signal names pulled live
from the KCD on the command line, and — once the log file is given — the
stack-position prefixes actually present in that log.

## License

`pycan-plot` is distributed under the terms of the GPL-3.0-or-later license.
