Pcan operations skill

PCAN Operations

Overview

Operate PCAN interfaces predictably through the native PCANBasic API or the python-can PCAN backend. The workflow is conservative: discover first, use explicit timing, keep ownership unambiguous, classify status/error records before data matching, and always prove recovery with a known-good frame.

When to Use

Use this skill when:

• Enumerating PCAN channels or inspecting capabilities and firmware
• Opening Classic CAN or ISO CAN-FD channels
• Calculating or applying PCANBasic FD timing strings
• Sending and receiving with PCANBasic or python-can
• Configuring acceptance filters, listen-only mode, or status/error records
• Diagnosing ILLPARAMVAL, HWINUSE, queue errors, bus warning, passive, or bus-off
• Building robust reopen/retry behavior

Do not use this skill for generic SocketCAN setup or electrical compliance measurements without PCAN hardware.

Safety Boundary

• Do not run active tests on a vehicle or production network without an approved test plan.
• Do not use vendor firmware update tools on hardware whose provenance and firmware compatibility are uncertain.
• Do not leave PCAN_BUSOFF_AUTORESET enabled during diagnostics; it can hide the original fault.
• A successful Write/send() means the driver accepted the frame, not that another node ACKed or received it.
• Bitrate mismatch can cause hardware auto-retransmission and an error storm. Bound mismatch tests tightly.

1. Establish the Runtime

PCANBasic is a native host API. On Windows, run the Python process on Windows even if orchestration starts in WSL:

py -3.11 -m pip install python-can==4.6.1
py -3.11 your_script.py

From WSL:

py.exe -3.11 C:\path\to\your_script.py

Completion criteria:

• PCANBasic.dll loads without exception.
• PCAN_ATTACHED_CHANNELS_COUNT is nonzero.
• The intended channel handles are available.

2. Discover Before Opening

Query these parameters before assuming channel numbers:

• PCAN_API_VERSION
• PCAN_ATTACHED_CHANNELS_COUNT
• PCAN_ATTACHED_CHANNELS
• PCAN_CHANNEL_CONDITION
• PCAN_CHANNEL_FEATURES
• PCAN_HARDWARE_NAME
• PCAN_FIRMWARE_VERSION
• PCAN_CONTROLLER_NUMBER
• PCAN_DEVICE_ID

Treat device ID as one signal, not a globally unique identity. For multiple devices, combine handle, controller number, hardware name, and USB topology.

Completion criteria: each selected channel reports an available condition and a stable controller number.

3. Classic CAN Initialization

With python-can:

import can

bus = can.Bus(
    interface="pcan",
    channel="PCAN_USBBUS1",
    bitrate=500_000,
    auto_reset=False,
)

With PCANBasic:

from can.interfaces.pcan.basic import PCANBasic, PCAN_USBBUS1, PCAN_BAUD_500K

api = PCANBasic()
result = api.Initialize(PCAN_USBBUS1, PCAN_BAUD_500K)

Check result == PCAN_ERROR_OK; do not continue from a partial pair initialization.

4. CAN-FD Initialization

PCANBasic uses explicit timing values. A bitrate pair alone is insufficient.

Known exact 500 kbit/s nominal / 2 Mbit/s data timing:

FD_500K_2M = {
    "fd": True,
    "f_clock": 80_000_000,
    "nom_brp": 1,
    "nom_tseg1": 127,
    "nom_tseg2": 32,
    "nom_sjw": 32,
    "data_brp": 1,
    "data_tseg1": 31,
    "data_tseg2": 8,
    "data_sjw": 8,
}

Exact 500 kbit/s nominal / 12 Mbit/s data timing on hardware that supports a 60 MHz clock:

FD_500K_12M = {
    "fd": True,
    "f_clock": 60_000_000,
    "nom_brp": 1,
    "nom_tseg1": 95,
    "nom_tseg2": 24,
    "nom_sjw": 24,
    "data_brp": 1,
    "data_tseg1": 2,
    "data_tseg2": 2,
    "data_sjw": 2,
}

Verify the derived rate:

bitrate = f_clock / (brp × (1 + tseg1 + tseg2))

Do not approximate 12 Mbit/s from an 80 MHz clock. Reject any configuration whose derived rate is not exact.

See references/bit-timing.md for the timing workflow.

5. Read and Write Discipline

For every frame, distinguish:

1. Generated by the application
2. Accepted by the driver
3. Received by the peer
4. Matched by ID, frame type, DLC, flags, payload, sequence, and integrity code

A robust receiver must classify records before matching:

• valid — expected current-phase frame
• stale — valid frame from an earlier phase
• status — PCAN_MESSAGE_STATUS
• error — PCAN_MESSAGE_ERRFRAME
• unexpected — other ID/type
• bad — current-phase frame with invalid content

Only valid satisfies a transfer. A status or error record must never be silently accepted as payload.

6. PCAN Status Records

PCANBasic defines:

PCAN_MESSAGE_STATUS = 0x80

The python-can PCAN backend exposes Extended, RTR, FD, BRS, ESI, Echo, and Error flags, but may not surface the status bit as a dedicated can.Message attribute. A PCAN status record can therefore look like an ordinary frame, commonly:

ID 0x001, DLC 4, DATA 00 00 00 00

Inspect raw TPCANMsg.MSGTYPE or disable status records when they are not needed:

api.SetValue(channel, PCAN_ALLOW_STATUS_FRAMES, PCAN_PARAMETER_OFF)

Do not infer wire traffic from an API record until the raw message type has been checked.

7. Filters and Listen-Only

Filter tests must interleave:

1. Allowed frame received
2. Rejected frame not received
3. Allowed frame received again

This prevents a dead receiver from masquerading as a successful filter.

For listen-only mode:

• Enable it only after initialization if the API requires that sequence.
• Do not transmit while passive.
• End the passive phase with uninitialize rather than assuming every implementation supports toggling it live.

8. Safe Cleanup and Bounded Retry

Use one owner per channel. If opening the second channel fails, close the first before retrying.

stop sender → stop receiver → shutdown both buses → uninitialize both handles
→ short backoff → reopen → status check → bidirectional canary

Recommended policy:

• 2–3 attempts
• 20–100 ms incremental backoff
• complete cleanup before each attempt
• retry count and original exception preserved
• success only after GetStatus()==0 and a known-good transfer

Use templates/safe_open.py as a starting point.

9. Timestamp Handling

Classic TPCANTimestamp total microseconds:

micros + 1000 × millis + 0x100000000 × 1000 × millis_overflow

For FD, TPCANTimestampFD.value is already in microseconds.

Use host perf_counter_ns() for intervals and API latency. Do not subtract a hardware timestamp from a host timestamp unless their clock domains and epoch mapping are known.

Common Pitfalls

1. Passing only bitrate and data_bitrate to a PCAN FD channel that requires explicit timing.
2. Treating send() success as proof of ACK or peer reception.
3. Mixing raw PCANBasic ownership with a live python-can bus on the same handle.
4. Calling global uninitialize while another process owns a channel.
5. Draining receive queues before accounting for stale, status, and error records.
6. Retrying application frames automatically and hiding the original loss or creating duplicates.
7. Leaving a partially initialized channel open after its peer fails.
8. Treating a status record as an ordinary CAN frame.
9. Using device ID alone to distinguish multiple interfaces.
10. Applying firmware updates to unsupported hardware.

Verification Checklist

• Runtime is Windows-side and PCANBasic loads
• Intended channels are discovered and available
• Derived nominal/data bitrates are exact
• Both channels initialize or both are cleaned up
• auto_reset=False during diagnosis
• Status and error records are classified explicitly
• Send success is followed by peer payload validation
• Shutdown exceptions do not prevent cleanup of the other channel
• Recovery ends with status zero and a bidirectional canary
• Logs preserve timing, channel, mode, retry count, and raw error code