CAN_VIEWER(1)

🎀 NAME 🎀

can_viewer — an interactive terminal viewer for live CAN bus traffic 💖

---

🦋 SYNOPSIS 🦋

python3 -m can.viewer [-c CHANNEL]
       [-i INTERFACE]
              [-b BITRATE] [--fd] [--data-bitrate DATA_BITRATE] [--timing
              ('TIMING_ARG',)] [--filter
              ('{<can_id>:<can_mask>,<can_id>~<can_mask>}',)] [--bus-kwargs
              ('BUS_KWARG',)] [-h] [--version] [-d
              ('{<id>:<format>,<id>:<format>:<scaling1>:...:<scalingN>,file.txt}',)]
              [-v]

---

✨ DESCRIPTION ✨

okay so the full usage listing looks exactly like this, no cap:

python3 -m can.viewer [-c CHANNEL]
       [-i INTERFACE]
              [-b BITRATE] [--fd] [--data-bitrate DATA_BITRATE] [--timing
              ('TIMING_ARG',)] [--filter
              ('{<can_id>:<can_mask>,<can_id>~<can_mask>}',)] [--bus-kwargs
              ('BUS_KWARG',)] [-h] [--version] [-d
              ('{<id>:<format>,<id>:<format>:<scaling1>:...:<scalingN>,file.txt}',)]
              [-v]

A simple CAN viewer terminal application written in Python 🐍 — that's the whole vibe, she's simple, she's in your terminal, she's watching the bus.

---

🌸 Bus arguments 🌸

• -c, --channel CHANNEL — most backend interfaces need some kind of channel, bestie. Like with the serial interface the channel might be an rfcomm device: "/dev/rfcomm0". And with the socketcan interface, valid channel examples include "can0", "vcan0". 👑
• -i, --interface {canalystii,cantact,etas,gs_usb,iscan,ixxat,kvaser,neousys,neovi,nican,nixnet,pcan,robotell,seeedstudio,serial,slcan,socketcan,socketcand,systec,udp_multicast,usb2can,vector,virtual} — pick which backend CAN interface you wanna use. If you leave it blank, it falls back to reading from configuration files. (yes, the whole list, I'm not skipping one single one of these, they're all here 💅)
• -b, --bitrate BITRATE — the bitrate to use for the CAN bus.
• --fd — activate CAN-FD support 🚀
• --data-bitrate DATA_BITRATE — the bitrate to use for the data phase in case of CAN-FD.
• --timing ('TIMING_ARG',) — configure bit rate and bit timing. For example, use --timing f_clock=8_000_000 tseg1=5 tseg2=2 sjw=2 brp=2 nof_samples=1 for classical CAN, or --timing f_clock=80_000_000 nom_tseg1=119 nom_tseg2=40 nom_sjw=40 nom_brp=1 data_tseg1=29 data_tseg2=10 data_sjw=10 data_brp=1 for CAN FD. Check the pythoncan documentation to verify whether your CAN interface actually supports the timing argument, fr fr — don't just assume.
• --filter ('{<can_id>:<can_mask>,<can_id>~<can_mask>}',) — space separated CAN filters for the given CAN interface:
  • <can_id>:<can_mask> — matches when <received_can_id> & mask == can_id & mask
  • <can_id>~<can_mask> — matches when <received_can_id> & mask != can_id & mask

For example, to show only frames with ID 0x100 to 0x103 and 0x200 to 0x20F:

python3 -m can.viewer --filter 100:7FC 200:7F0

Note that the ID and mask are always interpreted as hex values. 🔢

• --bus-kwargs ('BUS_KWARG',) — pass keyword arguments down to the instantiation of the bus class. For example, -i vector -c 1 --buskwargs app_name=MyCanApp serial=1234 is equivalent to opening the bus with can.Bus('vector', channel=1, app_name='MyCanApp', serial=1234). 🫶

---

🧚 Optional arguments 🧚

• -h, --help — show this help message and exit.
• --version — show program's version number and exit.
• -d, --decode ('{<id>:<format>,<id>:<format>:<scaling1>:...:<scalingN>,file.txt}',) — specify how to convert the raw bytes into real values. The ID of the frame is given as the first argument and the format as the second. The Python struct package is used to unpack the received data, where the format characters have the following meaning:
  • < = little-endian, > = big-endian
  • x = pad byte
  • c = char
  • ? = bool
  • b = int8_t, B = uint8_t
  • h = int16, H = uint16
  • l = int32_t, L = uint32_t
  • q = int64_t, Q = uint64_t
  • f = float (32-bits), d = double (64-bits)

For example, to convert six bytes with ID 0x100 into uint8_t, uint16 and uint32_t:

$ python3 -m can.viewer -d "100:<BHL"

Note that the IDs are always interpreted as hex values.

An optional conversion from integers to real units can be given as additional arguments. In order to convert from raw integer values the values are divided with the corresponding scaling value, and similarly the values are multiplied by the scaling value in order to convert from real units to raw integer values. For example, let's say the uint8_t needs no conversion, but the uint16 and the uint32_t need to be divided by 10 and 100 respectively:

$ python3 -m can.viewer -d "101:<BHL:1:10.0:100.0"

Be aware that integer division is performed if the scaling value is an integer. 😭

Multiple arguments are separated by spaces:

$ python3 -m can.viewer -d "100:<BHL" "101:<BHL:1:10.0:100.0"

Alternatively a file containing the conversion strings separated by new lines can be given as input:

$ cat file.txt
100:<BHL
101:<BHL:1:10.0:100.0

$ python3 -m can.viewer -d file.txt

• -v — how much information do you want to see at the command line? You can add several of these, e.g., -vv is DEBUG. 📈

---

🌈 Shortcuts 🌈

• ESQ/q — exit the viewer
• c — clear the stored frames
• s — sort the stored frames
• h — toggle highlight byte changes
• SPACE — pause the viewer
• UP/DOWN — scroll the viewer

---

that's the whole page, bestie 🫶 she's can_viewer version 4.6.1, from October 2025, living her best life in section 1 of User Commands. go watch a bus. 💅✨