Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# Vector

This interface adds support for CAN controllers by Vector. Only Windows is supported.

## Configuration

By default this library uses the channel configuration for CANalyzer. To use a different application, open Vector Hardware Configuration program and create a new application and assign the channels you may want to use. Specify the application name as `app_name='Your app name'` when constructing the bus or in a config file.

Channel should be given as a list of channels starting at 0.

Here is an example configuration file connecting to CAN 1 and CAN 2 for an application named “python-can”:

    [default]
    interface = vector
    channel = 0, 1
    app_name = python-can

## VectorBus

class can.interfaces.vector.VectorBus(channel, can_filters=None, poll_interval=0.01, receive_own_messages=False, timing=None, bitrate=None, rx_queue_size=16384, app_name='CANalyzer', serial=None, fd=False, data_bitrate=None, sjw_abr=2, tseg1_abr=6, tseg2_abr=3, sjw_dbr=2, tseg1_dbr=6, tseg2_dbr=3, listen_only=False, **kwargs)

  Bases: `BusABC`

  The CAN Bus implemented for the Vector interface.

  Parameters:

    - channel (int | Sequence[int] | str) – The channel indexes to create this bus with. Can also be a single integer or a comma separated string.

    - can_filters (Sequence[CanFilter | CanFilterExtended] | None) – See `can.BusABC`.

    - receive_own_messages (bool) – See `can.BusABC`.

    - timing (BitTiming | BitTimingFd | None) – An instance of `BitTiming` or `BitTimingFd` to specify the bit timing parameters for the VectorBus interface. The f_clock value of the timing instance must be set to 8_000_000 (8MHz) or 16_000_000 (16MHz) for CAN 2.0 or 80_000_000 (80MHz) for CAN FD. If this parameter is provided, it takes precedence over all other timing-related parameters. Otherwise, the bit timing can be specified using the following parameters: bitrate for standard CAN or fd, data_bitrate, sjw_abr, tseg1_abr, tseg2_abr, sjw_dbr, tseg1_dbr, and tseg2_dbr for CAN FD.

    - poll_interval (float) – Poll interval in seconds.

    - bitrate (int | None) – Bitrate in bits/s.

    - rx_queue_size (int) – Number of messages in receive queue (power of 2). CAN: range 16…32768 CAN-FD: range 8192…524288

    - app_name (str | None) – Name of application in Vector Hardware Config. If set to None, the channel should be a global channel index.

    - serial (int | None) – Serial number of the hardware to be used. If set, the channel parameter refers to the channels ONLY on the specified hardware. If set, the app_name does not have to be previously defined in Vector Hardware Config.

    - fd (bool) – If CAN-FD frames should be supported.

    - data_bitrate (int | None) – Which bitrate to use for data phase in CAN FD. Defaults to arbitration bitrate.

    - sjw_abr (int) – Bus timing value sample jump width (arbitration).

    - tseg1_abr (int) – Bus timing value tseg1 (arbitration)

    - tseg2_abr (int) – Bus timing value tseg2 (arbitration)

    - sjw_dbr (int) – Bus timing value sample jump width (data)

    - tseg1_dbr (int) – Bus timing value tseg1 (data)

    - tseg2_dbr (int) – Bus timing value tseg2 (data)

    - listen_only (bool | None) – if the bus should be set to listen only mode.

    - kwargs (Any)

  Raises:

    - CanInterfaceNotImplementedError – If the current operating system is not supported or the driver could not be loaded.

    - CanInitializationError – If the bus could not be set up. This may or may not be a `VectorInitializationError`.

  send(msg, timeout=None)

    Transmit a message to the CAN bus.

    Override this method to enable the transmit path.

    Parameters:

      - msg (Message) – A message object.

      - timeout (float | None) – If > 0, wait up to this many seconds for message to be ACK’ed or for transmit queue to be ready depending on driver implementation. If timeout is exceeded, an exception will be raised. Might not be supported by all interfaces. None blocks indefinitely.

    Raises:

      CanOperationError – If an error occurred while sending

    Return type:

      None

  flush_tx_buffer()

    Flush the TX buffer of the bus.

    Implementation does not use function `xlCanFlushTransmitQueue` of the XL driver, as it works only for XL family devices.

    Warning

    Using this function will flush the queue and send a high voltage message (ID = 0, DLC = 0, no data).

    Return type:

      None

  shutdown()

    Called to carry out any interface specific cleanup required in shutting down a bus.

    This method can be safely called multiple times.

    Return type:

      None

  static popup_vector_hw_configuration(wait_for_finish=0)

    Open vector hardware configuration window.

    Parameters:

      wait_for_finish (int) – Time to wait for user input in milliseconds.

    Return type:

      None

  static get_application_config(app_name, app_channel)

    Retrieve information for an application in Vector Hardware Configuration.

    Parameters:

      - app_name (str) – The name of the application.

      - app_channel (int) – The channel of the application.

    Returns:

      Returns a tuple of the hardware type, the hardware index and the hardware channel.

    Raises:

      can.interfaces.vector.VectorInitializationError – If the application name does not exist in the Vector hardware configuration.

    Return type:

      Tuple[int | XL_HardwareType, int, int]

  static set_application_config(app_name, app_channel, hw_type, hw_index, hw_channel, **kwargs)

    Modify the application settings in Vector Hardware Configuration.

    This method can also be used with a channel config dictionary:

        import can
        from can.interfaces.vector import VectorBus

        configs = can.detect_available_configs(interfaces=['vector'])
        cfg = configs[0]
        VectorBus.set_application_config(app_name="MyApplication", app_channel=0, **cfg)

    Parameters:

      - app_name (str) – The name of the application. Creates a new application if it does not exist yet.

      - app_channel (int) – The channel of the application.

      - hw_type (int | XL_HardwareType) – The hardware type of the interface. E.g XL_HardwareType.XL_HWTYPE_VIRTUAL

      - hw_index (int) – The index of the interface if multiple interface with the same hardware type are present.

      - hw_channel (int) – The channel index of the interface.

      - kwargs (Any)

    Raises:

      can.interfaces.vector.VectorInitializationError – If the application name does not exist in the Vector hardware configuration.

    Return type:

      None

  set_filters(filters=None)

    Apply filtering to all messages received by this Bus.

    All messages that match at least one filter are returned. If filters is None or a zero length sequence, all messages are matched.

    Calling without passing any filters will reset the applied filters to `None`.

    Parameters:

      filters (Sequence[CanFilter | CanFilterExtended] | None) –

      A iterable of dictionaries each containing a “can_id”, a “can_mask”, and an optional “extended” key:

          [{"can_id": 0x11, "can_mask": 0x21, "extended": False}]

      A filter matches, when `<received_can_id> & can_mask == can_id & can_mask`. If `extended` is set as well, it only matches messages where `<received_is_extended> == extended`. Else it matches every messages based only on the arbitration ID and mask.

    Return type:

      None

  recv(timeout=None)

    Block waiting for a message from the Bus.

    Parameters:

      timeout (float | None) – seconds to wait for a message or None to wait indefinitely

    Returns:

      `None` on timeout or a `Message` object.

    Raises:

      CanOperationError – If an error occurred while reading

    Return type:

      Message | None

  send_periodic(msgs, period, duration=None, store_task=True, autostart=True, modifier_callback=None)

    Start sending messages at a given period on this bus.

    The task will be active until one of the following conditions are met:

    - the (optional) duration expires

    - the Bus instance goes out of scope

    - the Bus instance is shutdown

    - `stop_all_periodic_tasks()` is called

    - the task’s `stop()` method is called.

    Parameters:

      - msgs (Message | Sequence[Message]) – Message(s) to transmit

      - period (float) – Period in seconds between each message

      - duration (float | None) – Approximate duration in seconds to continue sending messages. If no duration is provided, the task will continue indefinitely.

      - store_task (bool) – If True (the default) the task will be attached to this Bus instance. Disable to instead manage tasks manually.

      - autostart (bool) – If True (the default) the sending task will immediately start after creation. Otherwise, the task has to be started by calling the tasks `start()` method on it.

      - modifier_callback (Callable[[Message], None] | None) – Function which should be used to modify each message’s data before sending. The callback modifies the `data` of the message and returns `None`.

    Returns:

      A started task instance. Note the task can be stopped (and depending on the backend modified) by calling the task’s `stop()` method.

    Return type:

      CyclicSendTaskABC

    Note

    Note the duration before the messages stop being sent may not be exactly the same as the duration specified by the user. In general the message will be sent at the given rate until at least duration seconds.

    Note

    For extremely long-running Bus instances with many short-lived tasks the default api with `store_task==True` may not be appropriate as the stopped tasks are still taking up memory as they are associated with the Bus instance.

  stop_all_periodic_tasks(remove_tasks=True)

    Stop sending any messages that were started using `send_periodic()`.

    Note

    The result is undefined if a single task throws an exception while being stopped.

    Parameters:

      remove_tasks (bool) – Stop tracking the stopped tasks.

    Return type:

      None

## Exceptions

exception can.interfaces.vector.VectorError(error_code, error_string, function)

  Bases: `CanError`

exception can.interfaces.vector.VectorInitializationError(error_code, error_string, function)

  Bases: `VectorError`, `CanInitializationError`

exception can.interfaces.vector.VectorOperationError(error_code, error_string, function)

  Bases: `VectorError`, `CanOperationError`

## Miscellaneous

can.interfaces.vector.get_channel_configs()

  Read channel properties from Vector XL API.

  Return type:

    List[VectorChannelConfig]

class can.interfaces.vector.VectorChannelConfig(name, hw_type, hw_index, hw_channel, channel_index, channel_mask, channel_capabilities, channel_bus_capabilities, is_on_bus, connected_bus_type, bus_params, serial_number, article_number, transceiver_name)

  Bases: `NamedTuple`

  NamedTuple which contains the channel properties from Vector XL API.

  Parameters:

    - name (str)

    - hw_type (int | XL_HardwareType)

    - hw_index (int)

    - hw_channel (int)

    - channel_index (int)

    - channel_mask (int)

    - channel_capabilities (XL_ChannelCapabilities)

    - channel_bus_capabilities (XL_BusCapabilities)

    - is_on_bus (bool)

    - connected_bus_type (XL_BusTypes)

    - bus_params (VectorBusParams | None)

    - serial_number (int)

    - article_number (int)

    - transceiver_name (str)

class can.interfaces.vector.canlib.VectorBusParams(bus_type, can, canfd)

  Bases: `NamedTuple`

  Parameters:

    - bus_type (XL_BusTypes)

    - can (VectorCanParams)

    - canfd (VectorCanFdParams)

class can.interfaces.vector.canlib.VectorCanParams(bitrate, sjw, tseg1, tseg2, sam, output_mode, can_op_mode)

  Bases: `NamedTuple`

  Parameters:

    - bitrate (int)

    - sjw (int)

    - tseg1 (int)

    - tseg2 (int)

    - sam (int)

    - output_mode (XL_OutputMode)

    - can_op_mode (XL_CANFD_BusParams_CanOpMode)

class can.interfaces.vector.canlib.VectorCanFdParams(bitrate, data_bitrate, sjw_abr, tseg1_abr, tseg2_abr, sam_abr, sjw_dbr, tseg1_dbr, tseg2_dbr, output_mode, can_op_mode)

  Bases: `NamedTuple`

  Parameters:

    - bitrate (int)

    - data_bitrate (int)

    - sjw_abr (int)

    - tseg1_abr (int)

    - tseg2_abr (int)

    - sam_abr (int)

    - sjw_dbr (int)

    - tseg1_dbr (int)

    - tseg2_dbr (int)

    - output_mode (XL_OutputMode)

    - can_op_mode (XL_CANFD_BusParams_CanOpMode)

class can.interfaces.vector.xldefine.XL_HardwareType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  Bases: `IntEnum`

  XL_HWTYPE_NONE = 0
  XL_HWTYPE_VIRTUAL = 1
  XL_HWTYPE_CANCARDX = 2
  XL_HWTYPE_CANAC2PCI = 6
  XL_HWTYPE_CANCARDY = 12
  XL_HWTYPE_CANCARDXL = 15
  XL_HWTYPE_CANCASEXL = 21
  XL_HWTYPE_CANCASEXL_LOG_OBSOLETE = 23
  XL_HWTYPE_CANBOARDXL = 25
  XL_HWTYPE_CANBOARDXL_PXI = 27
  XL_HWTYPE_VN2600 = 29
  XL_HWTYPE_VN2610 = 29
  XL_HWTYPE_VN3300 = 37
  XL_HWTYPE_VN3600 = 39
  XL_HWTYPE_VN7600 = 41
  XL_HWTYPE_CANCARDXLE = 43
  XL_HWTYPE_VN8900 = 45
  XL_HWTYPE_VN8950 = 47
  XL_HWTYPE_VN2640 = 53
  XL_HWTYPE_VN1610 = 55
  XL_HWTYPE_VN1630 = 57
  XL_HWTYPE_VN1640 = 59
  XL_HWTYPE_VN8970 = 61
  XL_HWTYPE_VN1611 = 63
  XL_HWTYPE_VN5240 = 64
  XL_HWTYPE_VN5610 = 65
  XL_HWTYPE_VN5620 = 66
  XL_HWTYPE_VN7570 = 67
  XL_HWTYPE_VN5650 = 68
  XL_HWTYPE_IPCLIENT = 69
  XL_HWTYPE_VN5611 = 70
  XL_HWTYPE_IPSERVER = 71
  XL_HWTYPE_VN5612 = 72
  XL_HWTYPE_VX1121 = 73
  XL_HWTYPE_VN5601 = 74
  XL_HWTYPE_VX1131 = 75
  XL_HWTYPE_VT6204 = 77
  XL_HWTYPE_VN1630_LOG = 79
  XL_HWTYPE_VN7610 = 81
  XL_HWTYPE_VN7572 = 83
  XL_HWTYPE_VN8972 = 85
  XL_HWTYPE_VN0601 = 87
  XL_HWTYPE_VN5640 = 89
  XL_HWTYPE_VX0312 = 91
  XL_HWTYPE_VH6501 = 94
  XL_HWTYPE_VN8800 = 95
  XL_HWTYPE_IPCL8800 = 96
  XL_HWTYPE_IPSRV8800 = 97
  XL_HWTYPE_CSMCAN = 98
  XL_HWTYPE_VN5610A = 101
  XL_HWTYPE_VN7640 = 102
  XL_HWTYPE_VX1135 = 104
  XL_HWTYPE_VN4610 = 105
  XL_HWTYPE_VT6306 = 107
  XL_HWTYPE_VT6104A = 108
  XL_HWTYPE_VN5430 = 109
  XL_HWTYPE_VTSSERVICE = 110
  XL_HWTYPE_VN1530 = 112
  XL_HWTYPE_VN1531 = 113
  XL_HWTYPE_VX1161A = 114
  XL_HWTYPE_VX1161B = 115
  XL_HWTYPE_VGNSS = 116
  XL_HWTYPE_VXLAPINIC = 118
  XL_MAX_HWTYPE = 120

class can.interfaces.vector.xldefine.XL_ChannelCapabilities(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  Bases: `IntFlag`

  XL_CHANNEL_FLAG_TIME_SYNC_RUNNING = 1
  XL_CHANNEL_FLAG_NO_HWSYNC_SUPPORT = 1024
  XL_CHANNEL_FLAG_SPDIF_CAPABLE = 16384
  XL_CHANNEL_FLAG_CANFD_BOSCH_SUPPORT = 536870912
  XL_CHANNEL_FLAG_CMACTLICENSE_SUPPORT = 1073741824
  XL_CHANNEL_FLAG_CANFD_ISO_SUPPORT = 2147483648

class can.interfaces.vector.xldefine.XL_BusCapabilities(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  Bases: `IntFlag`

  XL_BUS_COMPATIBLE_CAN = 1
  XL_BUS_ACTIVE_CAP_CAN = 65536
  XL_BUS_COMPATIBLE_LIN = 2
  XL_BUS_ACTIVE_CAP_LIN = 131072
  XL_BUS_COMPATIBLE_FLEXRAY = 4
  XL_BUS_ACTIVE_CAP_FLEXRAY = 262144
  XL_BUS_COMPATIBLE_MOST = 16
  XL_BUS_ACTIVE_CAP_MOST = 1048576
  XL_BUS_COMPATIBLE_DAIO = 64
  XL_BUS_ACTIVE_CAP_DAIO = 4194304
  XL_BUS_COMPATIBLE_J1708 = 256
  XL_BUS_ACTIVE_CAP_J1708 = 16777216
  XL_BUS_COMPATIBLE_KLINE = 2048
  XL_BUS_ACTIVE_CAP_KLINE = 134217728
  XL_BUS_COMPATIBLE_ETHERNET = 4096
  XL_BUS_ACTIVE_CAP_ETHERNET = 268435456
  XL_BUS_COMPATIBLE_A429 = 8192
  XL_BUS_ACTIVE_CAP_A429 = 536870912

class can.interfaces.vector.xldefine.XL_BusTypes(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  Bases: `IntFlag`

  XL_BUS_TYPE_NONE = 0
  XL_BUS_TYPE_CAN = 1
  XL_BUS_TYPE_LIN = 2
  XL_BUS_TYPE_FLEXRAY = 4
  XL_BUS_TYPE_AFDX = 8
  XL_BUS_TYPE_MOST = 16
  XL_BUS_TYPE_DAIO = 64
  XL_BUS_TYPE_J1708 = 256
  XL_BUS_TYPE_KLINE = 2048
  XL_BUS_TYPE_ETHERNET = 4096
  XL_BUS_TYPE_A429 = 8192

class can.interfaces.vector.xldefine.XL_OutputMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  Bases: `IntEnum`

  XL_OUTPUT_MODE_SILENT = 0
  XL_OUTPUT_MODE_NORMAL = 1
  XL_OUTPUT_MODE_TX_OFF = 2
  XL_OUTPUT_MODE_SJA_1000_SILENT = 3

class can.interfaces.vector.xldefine.XL_CANFD_BusParams_CanOpMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  Bases: `IntFlag`

  XL_BUS_PARAMS_CANOPMODE_CAN20 = 1
  XL_BUS_PARAMS_CANOPMODE_CANFD = 2
  XL_BUS_PARAMS_CANOPMODE_CANFD_NO_ISO = 8

class can.interfaces.vector.xldefine.XL_Status(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  Bases: `IntEnum`

  XL_SUCCESS = 0
  XL_PENDING = 1
  XL_ERR_QUEUE_IS_EMPTY = 10
  XL_ERR_QUEUE_IS_FULL = 11
  XL_ERR_TX_NOT_POSSIBLE = 12
  XL_ERR_NO_LICENSE = 14
  XL_ERR_WRONG_PARAMETER = 101
  XL_ERR_TWICE_REGISTER = 110
  XL_ERR_INVALID_CHAN_INDEX = 111
  XL_ERR_INVALID_ACCESS = 112
  XL_ERR_PORT_IS_OFFLINE = 113
  XL_ERR_CHAN_IS_ONLINE = 116
  XL_ERR_NOT_IMPLEMENTED = 117
  XL_ERR_INVALID_PORT = 118
  XL_ERR_HW_NOT_READY = 120
  XL_ERR_CMD_TIMEOUT = 121
  XL_ERR_CMD_HANDLING = 122
  XL_ERR_HW_NOT_PRESENT = 129
  XL_ERR_NOTIFY_ALREADY_ACTIVE = 131
  XL_ERR_INVALID_TAG = 132
  XL_ERR_INVALID_RESERVED_FLD = 133
  XL_ERR_INVALID_SIZE = 134
  XL_ERR_INSUFFICIENT_BUFFER = 135
  XL_ERR_ERROR_CRC = 136
  XL_ERR_BAD_EXE_FORMAT = 137
  XL_ERR_NO_SYSTEM_RESOURCES = 138
  XL_ERR_NOT_FOUND = 139
  XL_ERR_INVALID_ADDRESS = 140
  XL_ERR_REQ_NOT_ACCEP = 141
  XL_ERR_INVALID_LEVEL = 142
  XL_ERR_NO_DATA_DETECTED = 143
  XL_ERR_INTERNAL_ERROR = 144
  XL_ERR_UNEXP_NET_ERR = 145
  XL_ERR_INVALID_USER_BUFFER = 146
  XL_ERR_INVALID_PORT_ACCESS_TYPE = 147
  XL_ERR_NO_RESOURCES = 152
  XL_ERR_WRONG_CHIP_TYPE = 153
  XL_ERR_WRONG_COMMAND = 154
  XL_ERR_INVALID_HANDLE = 155
  XL_ERR_RESERVED_NOT_ZERO = 157
  XL_ERR_INIT_ACCESS_MISSING = 158
  XL_ERR_WRONG_VERSION = 160
  XL_ERR_CANNOT_OPEN_DRIVER = 201
  XL_ERR_WRONG_BUS_TYPE = 202
  XL_ERR_DLL_NOT_FOUND = 203
  XL_ERR_INVALID_CHANNEL_MASK = 204
  XL_ERR_NOT_SUPPORTED = 205
  XL_ERR_CONNECTION_BROKEN = 210
  XL_ERR_CONNECTION_CLOSED = 211
  XL_ERR_INVALID_STREAM_NAME = 212
  XL_ERR_CONNECTION_FAILED = 213
  XL_ERR_STREAM_NOT_FOUND = 214
  XL_ERR_STREAM_NOT_CONNECTED = 215
  XL_ERR_QUEUE_OVERRUN = 216
  XL_ERROR = 255
  XL_ERR_INVALID_DLC = 513
  XL_ERR_INVALID_CANID = 514
  XL_ERR_INVALID_FDFLAG_MODE20 = 515
  XL_ERR_EDL_RTR = 516
  XL_ERR_EDL_NOT_SET = 517
  XL_ERR_UNKNOWN_FLAG = 518