ZCAN Wrapper

The ZCAN wrapper module provides low-level hardware communication with ZLG USBCANFD devices.

Core Components

Device Types

class pyzlg_dexhand.zcan.ZCANDeviceType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]
ZCAN_CANDTU_MINI = 33
ZCAN_USBCANFD_100U = 42
ZCAN_USBCANFD_200U = 41
ZCAN_USBCAN_2E_U = 21

Status Codes

class pyzlg_dexhand.zcan.ZCANStatus(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]
ERROR = 0
OFFLINE = 3
OK = 1
ONLINE = 2
UNSUPPORTED = 4

Message Types

class pyzlg_dexhand.zcan.ZCANMessageType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]
NORMAL = 0
SELF_TEST = 2
SINGLE = 1
SINGLE_SELF_TEST = 3

Base Wrapper

class pyzlg_dexhand.zcan_wrapper.ZCANWrapperBase[source]

Abstract base class for ZCAN wrapper implementations

abstract close()[source]

Close ZCAN device

Returns:

True if device closed successfully

Return type:

bool

abstract configure_channel(channel, arb_baudrate=1000000, data_baudrate=5000000, enable_resistance=True, tx_timeout=200)[source]

Configure and start a CAN channel

Parameters:

  • channel (int) – Channel number

  • arb_baudrate (int) – Arbitration baudrate in Hz

  • data_baudrate (int) – Data baudrate in Hz

  • enable_resistance (bool) – Enable terminal resistance

  • tx_timeout (int) – TX timeout in ms

Returns:

True if configuration successful

Return type:

bool

abstract open(device_type=None, device_index=None)[source]

Open ZCAN device

Parameters:

  • device_type (Optional[ZCANDeviceType]) – Type of ZCAN device

  • device_index (Optional[int]) – Device index

Returns:

True if device opened successfully

Return type:

bool

abstract receive_fd_messages(channel, max_messages=100, timeout_ms=100)[source]

Receive CANFD messages

Parameters:

  • channel (int) – Channel number

  • max_messages (int) – Maximum number of messages to receive

  • timeout_ms (int) – Receive timeout in milliseconds

Return type:

List[Tuple[int, bytes, int]]

Returns:

List of (id, data, timestamp) tuples for received messages

abstract send_fd_message(channel, id, data, flags=None)[source]

Send a CANFD message

Parameters:

  • channel (int) – Channel number

  • id (int) – Message ID

  • data (bytes) – Message data bytes

  • flags (Optional[ZCANMessageInfo]) – Optional message flags

Returns:

True if message sent successfully

Return type:

bool

abstract set_filter(channel, filters)[source]

Set message filters for a channel

Parameters:

  • channel (int) – Channel number

  • filters (List[ZCANFilterConfig]) – List of filter configurations

Returns:

True if filters set successfully

Return type:

bool

Hardware Implementation

class pyzlg_dexhand.zcan_wrapper.ZCANWrapper(lib_path='../lib/libusbcanfd.so')[source]

Bases: ZCANWrapperBase

High level wrapper for ZCAN operations

__init__(lib_path='../lib/libusbcanfd.so')[source]

Initialize ZCAN wrapper

Parameters:

lib_path (str) – Path to ZLG driver library, relative to the current file.

close()[source]

Close ZCAN device

Returns:

True if device closed successfully

Return type:

bool

configure_channel(channel, arb_baudrate=1000000, data_baudrate=5000000, enable_resistance=True, tx_timeout=200)[source]

Configure and start a CAN channel

Parameters:

  • channel (int) – Channel number to configure

  • arb_baudrate (int) – Arbitration baudrate in Hz

  • data_baudrate (int) – Data baudrate in Hz

  • enable_resistance (bool) – Enable terminal resistance

  • tx_timeout (int) – Transmission timeout in ms

Returns:

True if configuration successful

Return type:

bool

dump_channel_state(channel)[source]

Dump complete channel state for debugging

dump_frame(message)[source]

Dump complete frame details for debugging

Return type:

None

handle_error(channel)[source]

Read and log error information from the device

Return type:

None

monitor_channel_status(channel)[source]

Monitor channel status and handle errors

Return type:

bool

open(device_type=None, device_index=None)[source]

Open ZCAN device

Parameters:

  • device_type (Optional[ZCANDeviceType]) – Type of ZCAN device, defaults to ZCAN_USBCANFD_200U

  • device_index (Optional[int]) – Device index, defaults to 0

Returns:

True if device opened successfully

Return type:

bool

receive_fd_messages(channel, max_messages=100, timeout_ms=100)[source]

Receive CANFD messages

Parameters:

  • channel (int) – Channel number

  • max_messages (int) – Maximum number of messages to receive

  • timeout_ms (int) – Receive timeout in milliseconds

Return type:

List[Tuple[int, bytes, int]]

Returns:

List of (id, data, timestamp) tuples for received messages

reset_channel(channel)[source]

Reset a CAN channel after errors

Return type:

bool

send_fd_message(channel, id, data, flags=None)[source]

Send a single CANFD message

Return type:

bool

send_fd_messages(channel, messages, flags=None)[source]

Send multiple CANFD messages

Parameters:

  • channel (int) – Channel number

  • messages (List[Tuple[int, bytes]]) – List of (id, data) tuples

  • flags (Optional[ZCANMessageInfo]) – Optional message flags to use for all messages

Returns:

Number of messages successfully sent

Return type:

int

set_filter(channel, filters)[source]

Configure message filters for a channel

Parameters:

  • channel (int) – Channel number

  • filters (List[ZCANFilterConfig]) – List of filter configurations

Returns:

True if filters set successfully

Return type:

bool

Mock Implementation

class pyzlg_dexhand.zcan_wrapper.MockZCANWrapper[source]

Bases: ZCANWrapperBase

Mock implementation for testing

__init__()[source]

Initialize mock wrapper

clear_message_history()[source]

Clear message history

close()[source]

Close ZCAN device

Returns:

True if device closed successfully

Return type:

bool

configure_channel(channel, arb_baudrate=1000000, data_baudrate=5000000, enable_resistance=True, tx_timeout=200)[source]

Configure and start a CAN channel

Parameters:

  • channel (int) – Channel number

  • arb_baudrate (int) – Arbitration baudrate in Hz

  • data_baudrate (int) – Data baudrate in Hz

  • enable_resistance (bool) – Enable terminal resistance

  • tx_timeout (int) – TX timeout in ms

Returns:

True if configuration successful

Return type:

bool

get_message_history()[source]

Get history of sent messages for testing

Return type:

List[dict]

Returns:

List of dictionaries containing message details

open(device_type=None, device_index=None)[source]

Open ZCAN device

Parameters:

  • device_type (Optional[ZCANDeviceType]) – Type of ZCAN device

  • device_index (Optional[int]) – Device index

Returns:

True if device opened successfully

Return type:

bool

receive_fd_messages(channel, max_messages=100, timeout_ms=100)[source]

Receive CANFD messages

Parameters:

  • channel (int) – Channel number

  • max_messages (int) – Maximum number of messages to receive

  • timeout_ms (int) – Receive timeout in milliseconds

Return type:

List[Tuple[int, bytes, int]]

Returns:

List of (id, data, timestamp) tuples for received messages

send_fd_message(channel, id, data, flags=None)[source]

Send a CANFD message

Parameters:

  • channel (int) – Channel number

  • id (int) – Message ID

  • data (bytes) – Message data bytes

  • flags (Optional[ZCANMessageInfo]) – Optional message flags

Returns:

True if message sent successfully

Return type:

bool

set_filter(channel, filters)[source]

Set message filters for a channel

Parameters:

  • channel (int) – Channel number

  • filters (List[ZCANFilterConfig]) – List of filter configurations

Returns:

True if filters set successfully

Return type:

bool

Configuration

BitTimingConfig

class pyzlg_dexhand.zcan_wrapper.BitTimingConfig(tseg1, tseg2, sjw, brp)[source]

Bit timing configuration values

brp: int
sjw: int
tseg1: int
tseg2: int

CANFDTimingConfig

class pyzlg_dexhand.zcan_wrapper.CANFDTimingConfig(arb, data)[source]

Complete timing configuration for CANFD

arb: BitTimingConfig
property clock_hz: int

Clock frequency in Hz

data: BitTimingConfig

Filter Configuration

class pyzlg_dexhand.zcan_wrapper.ZCANFilterConfig(type, start_id, end_id)[source]

Configuration for CAN message filtering

end_id: int
start_id: int
type: int

Examples

Basic Usage

from pyzlg_dexhand.zcan_wrapper import ZCANWrapper, ZCANDeviceType

# Initialize wrapper
zcan = ZCANWrapper()
zcan.open(device_type=ZCANDeviceType.ZCAN_USBCANFD_200U)

# Configure channel
zcan.configure_channel(
    channel=0,
    arb_baudrate=1000000,  # 1Mbps
    data_baudrate=5000000  # 5Mbps
)

# Send message
zcan.send_fd_message(
    channel=0,
    id=0x101,
    data=b'\x44\x03\x00\x00\x00\x00'  # Example command
)

# Receive messages
messages = zcan.receive_fd_messages(
    channel=0,
    max_messages=10,
    timeout_ms=100
)
for msg_id, data, timestamp in messages:
    print(f"Message ID: {msg_id:x}, Data: {data.hex()}")

# Clean up
zcan.close()

Message Filtering

# Configure message filters
filters = [
    ZCANFilterConfig(
        type=0,  # Standard frame
        start_id=0x100,
        end_id=0x1FF
    ),
    ZCANFilterConfig(
        type=0,
        start_id=0x600,
        end_id=0x6FF
    )
]
zcan.set_filter(channel=0, filters=filters)

Error Handling

# Monitor channel status
if not zcan.monitor_channel_status(channel=0):
    # Handle error condition
    zcan.handle_error(channel=0)

# Reset channel on severe errors
zcan.reset_channel(channel=0)

Notes

Device Setup

  1. Initialize ZCAN device with appropriate type

  2. Configure channel timing parameters

  3. Set up message filters if needed

  4. Monitor channel status during operation

Timing Configuration

Supported baudrate combinations:

  • Arbitration phase: 1Mbps

  • Data phase: 5Mbps

Default timing parameters:

  • Arbitration phase:

    • TSEG1: 14

    • TSEG2: 3

    • SJW: 3

    • BRP: 2

  • Data phase:

    • TSEG1: 1

    • TSEG2: 0

    • SJW: 0

    • BRP: 2

Error Recovery

  1. Monitor channel status

  2. Read error information when detected

  3. Attempt channel reset if necessary

  4. Reconfigure channel after reset