Skip to content
Back to top
View this page

# Command Line Tools

The following modules are callable from `python-can`.

They can be called for example by `python3 -m can.logger` or `can_logger` (if installed using pip).

## can.logger

Command line help, called with `--help`:

    $ python3 -m can.logger -h
    usage: logger.py [-h] [-f LOG_FILE] [-a] [-s FILE_SIZE] [-v] [--active |
                     --passive] [-c CHANNEL]
                     [-i {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}]
                     [-b BITRATE] [--fd] [--data-bitrate DATA_BITRATE]
                     [--timing TIMING_ARG [TIMING_ARG ...]]
                     [--filter {<can_id>:<can_mask>,<can_id>~<can_mask>} [{<can_id>:<can_mask>,<can_id>~<can_mask>} ...]]
                     [--bus-kwargs BUS_KWARG [BUS_KWARG ...]]
                     ...

    Log CAN traffic, printing messages to stdout or to a given file.

    options:
      -h, --help            show this help message and exit

    logger arguments:
      -f, --file_name LOG_FILE
                            Path and base log filename, for supported types see
                            can.Logger.
      -a, --append          Append to the log file if it already exists.
      -s, --file_size FILE_SIZE
                            Maximum file size in bytes. Rotate log file when size
                            threshold is reached. (The resulting file sizes will
                            be consistent, but are not guaranteed to be exactly
                            what is specified here due to the rollover conditions
                            being logger implementation specific.)
      -v                    How much information do you want to see at the command
                            line? You can add several of these e.g., -vv is DEBUG
      --active              Start the bus as active, this is applied by default.
      --passive             Start the bus as passive.
      extra_args            The remaining arguments will be used for logger/player
                            initialisation. For example, `can_logger -i virtual -c
                            test -f logfile.blf --compression-level=9` passes the
                            keyword argument `compression_level=9` to the
                            BlfWriter.

    bus arguments:
      -c, --channel CHANNEL
                            Most backend interfaces require some sort of channel.
                            For example with the serial interface the channel
                            might be a rfcomm device: "/dev/rfcomm0". 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}
                            Specify the backend CAN interface to use. If left
                            blank, fall back to reading from configuration files.
      -b, --bitrate BITRATE
                            Bitrate to use for the CAN bus.
      --fd                  Activate CAN-FD support
      --data-bitrate DATA_BITRATE
                            Bitrate to use for the data phase in case of CAN-FD.
      --timing TIMING_ARG [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 python-
                            can documentation to verify whether your CAN interface
                            supports the `timing` argument.
      --filter {<can_id>:<can_mask>,<can_id>~<can_mask>} [{<can_id>:<can_mask>,<can_id>~<can_mask>} ...]
                            R|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) Fx to show only frames with ID
                            0x100 to 0x103 and 0x200 to 0x20F: python -m
                            can.viewer --filter 100:7FC 200:7F0 Note that the ID
                            and mask are always interpreted as hex values
      --bus-kwargs BUS_KWARG [BUS_KWARG ...]
                            Pass keyword arguments down to the instantiation of
                            the bus class. For example, `-i vector -c 1 --bus-
                            kwargs app_name=MyCanApp serial=1234` is equivalent to
                            opening the bus with `can.Bus('vector', channel=1,
                            app_name='MyCanApp', serial=1234)

## can.player

    $ python3 -m can.player -h
    usage: player.py [-h] [-f LOG_FILE] [-v] [--ignore-timestamps]
                     [--error-frames] [-g GAP] [-s SKIP] [-c CHANNEL]
                     [-i {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}]
                     [-b BITRATE] [--fd] [--data-bitrate DATA_BITRATE]
                     [--timing TIMING_ARG [TIMING_ARG ...]]
                     [--bus-kwargs BUS_KWARG [BUS_KWARG ...]]
                     input-file ...

    Replay CAN traffic.

    options:
      -h, --help            show this help message and exit

    Player arguments:
      -f, --file_name LOG_FILE
                            Path and base log filename, for supported types see
                            can.LogReader.
      -v                    Also print can frames to stdout. You can add several
                            of these to enable debugging
      --ignore-timestamps   Ignore timestamps (send all frames immediately with
                            minimum gap between frames)
      --error-frames        Also send error frames to the interface.
      -g, --gap GAP         <s> minimum time between replayed frames
      -s, --skip SKIP       <s> skip gaps greater than 's' seconds
      input-file            The file to replay. For supported types see
                            can.LogReader.
      extra_args            The remaining arguments will be used for logger/player
                            initialisation. For example, `can_logger -i virtual -c
                            test -f logfile.blf --compression-level=9` passes the
                            keyword argument `compression_level=9` to the
                            BlfWriter.

    bus arguments:
      -c, --channel CHANNEL
                            Most backend interfaces require some sort of channel.
                            For example with the serial interface the channel
                            might be a rfcomm device: "/dev/rfcomm0". 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}
                            Specify the backend CAN interface to use. If left
                            blank, fall back to reading from configuration files.
      -b, --bitrate BITRATE
                            Bitrate to use for the CAN bus.
      --fd                  Activate CAN-FD support
      --data-bitrate DATA_BITRATE
                            Bitrate to use for the data phase in case of CAN-FD.
      --timing TIMING_ARG [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 python-
                            can documentation to verify whether your CAN interface
                            supports the `timing` argument.
      --bus-kwargs BUS_KWARG [BUS_KWARG ...]
                            Pass keyword arguments down to the instantiation of
                            the bus class. For example, `-i vector -c 1 --bus-
                            kwargs app_name=MyCanApp serial=1234` is equivalent to
                            opening the bus with `can.Bus('vector', channel=1,
                            app_name='MyCanApp', serial=1234)

## can.viewer

A screenshot of the application can be seen below:

The first column is the number of times a frame with the particular ID that has been received, next is the timestamp of the frame relative to the first received message. The third column is the time between the current frame relative to the previous one. Next is the length of the frame, the data and then the decoded data converted according to the `-d` argument. The top red row indicates an error frame. There are several keyboard shortcuts that can be used with the viewer script, they function as follows:

- ESCAPE - Quit the viewer script

- q - as ESCAPE

- c - Clear the stored frames

- s - Sort the stored frames

- h - Toggle highlighting of changed bytes in the data field - see the below image

- SPACE - Pause the viewer

- UP/DOWN - Scroll the viewer

A byte in the data field is highlighted blue if the value is different from the last time the message was received.

### Command line arguments

By default the `can.viewer` uses the SocketCAN interface. All interfaces are supported and can be specified using the `-i` argument or configured following Configuration.

The full usage page can be seen below:

    $ python3 -m can.viewer -h
    Usage: python3 -m can.viewer [-c CHANNEL]
                                 [-i {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}]
                                 [-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

    Bus arguments:
      -c, --channel CHANNEL
                            Most backend interfaces require some sort of channel.
                            For example with the serial interface the channel
                            might be a rfcomm device: "/dev/rfcomm0". 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}
                            Specify the backend CAN interface to use. If left
                            blank, fall back to reading from configuration files.
      -b, --bitrate BITRATE
                            Bitrate to use for the CAN bus.
      --fd                  Activate CAN-FD support
      --data-bitrate DATA_BITRATE
                            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 python-
                            can documentation to verify whether your CAN interface
                            supports the `timing` argument.
      --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)
                            Fx to show only frames with ID 0x100 to 0x103 and 0x200 to 0x20F:
                                  python -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 --bus-
                            kwargs 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)
                            Fx 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,
                            similarly the values are multiplied by the scaling value in order
                            to convert from real units to raw integer values.
                            Fx lets say the uint8_t needs no conversion, but the uint16 and the uint32_t
                            needs 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:
            +---------+-------------------------------+
            |   Key   |       Description             |
            +---------+-------------------------------+
            | 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             |
            +---------+-------------------------------+

## can.bridge

A small application that can be used to connect two can buses:

    $ python3 -m can.bridge -h
    usage: bridge.py [-h] [--bus1-channel CHANNEL]
                     [--bus1-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}]
                     [--bus1-bitrate BITRATE] [--bus1-fd]
                     [--bus1-data-bitrate DATA_BITRATE]
                     [--bus1-timing TIMING_ARG [TIMING_ARG ...]]
                     [--bus1-bus-kwargs BUS_KWARG [BUS_KWARG ...]]
                     [--bus2-channel CHANNEL]
                     [--bus2-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}]
                     [--bus2-bitrate BITRATE] [--bus2-fd]
                     [--bus2-data-bitrate DATA_BITRATE]
                     [--bus2-timing TIMING_ARG [TIMING_ARG ...]]
                     [--bus2-bus-kwargs BUS_KWARG [BUS_KWARG ...]]

    Bridge two CAN buses. Both can buses will be connected so that messages from
    bus1 will be sent on bus2 and messages from bus2 will be sent to bus1.

    options:
      -h, --help            show this help message and exit

    Bus 1 arguments:
      --bus1-channel CHANNEL
                            Most backend interfaces require some sort of channel.
                            For example with the serial interface the channel
                            might be a rfcomm device: "/dev/rfcomm0". With the
                            socketcan interface valid channel examples include:
                            "can0", "vcan0".
      --bus1-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}
                            Specify the backend CAN interface to use. If left
                            blank, fall back to reading from configuration files.
      --bus1-bitrate BITRATE
                            Bitrate to use for the CAN bus.
      --bus1-fd             Activate CAN-FD support
      --bus1-data-bitrate DATA_BITRATE
                            Bitrate to use for the data phase in case of CAN-FD.
      --bus1-timing TIMING_ARG [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 python-
                            can documentation to verify whether your CAN interface
                            supports the `timing` argument.
      --bus1-bus-kwargs BUS_KWARG [BUS_KWARG ...]
                            Pass keyword arguments down to the instantiation of
                            the bus class. For example, `-i vector -c 1 --bus-
                            kwargs app_name=MyCanApp serial=1234` is equivalent to
                            opening the bus with `can.Bus('vector', channel=1,
                            app_name='MyCanApp', serial=1234)

    Bus 2 arguments:
      --bus2-channel CHANNEL
                            Most backend interfaces require some sort of channel.
                            For example with the serial interface the channel
                            might be a rfcomm device: "/dev/rfcomm0". With the
                            socketcan interface valid channel examples include:
                            "can0", "vcan0".
      --bus2-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}
                            Specify the backend CAN interface to use. If left
                            blank, fall back to reading from configuration files.
      --bus2-bitrate BITRATE
                            Bitrate to use for the CAN bus.
      --bus2-fd             Activate CAN-FD support
      --bus2-data-bitrate DATA_BITRATE
                            Bitrate to use for the data phase in case of CAN-FD.
      --bus2-timing TIMING_ARG [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 python-
                            can documentation to verify whether your CAN interface
                            supports the `timing` argument.
      --bus2-bus-kwargs BUS_KWARG [BUS_KWARG ...]
                            Pass keyword arguments down to the instantiation of
                            the bus class. For example, `-i vector -c 1 --bus-
                            kwargs app_name=MyCanApp serial=1234` is equivalent to
                            opening the bus with `can.Bus('vector', channel=1,
                            app_name='MyCanApp', serial=1234)

## can.logconvert

    $ python3 -m can.logconvert -h
    usage: logconvert.py [-h] [-s FILE_SIZE] INFILE OUTFILE

    Convert a log file from one format to another.

    positional arguments:
      INFILE                Input filename. The type is dependent on the suffix,
                            see can.LogReader.
      OUTFILE               Output filename. The type is dependent on the suffix,
                            see can.Logger.

    options:
      -h, --help            show this help message and exit
      -s, --file_size FILE_SIZE
                            Maximum file size in bytes. Rotate log file when size
                            threshold is reached.