Pass documentation

Introduction

Pass is a software package providing an API for the following features:

• Measurement and calibration with XCP over CAN, CAN-FD and TCP/IP

• Measurement of classic CAN buses defined in DBC files

• Calibration upload do DCM and CDFX files

• Calibration download from DCM and CDFX files

• Recording to MDF3, MDF4 and CSV files

• Loading of MDF files

• Sending of classic CAN frames defined in a DBC file

• Software download download via UDS 14229 and XCP from S19 or ihex format

• Applying calibration defined in DCM or CDFX files to an image file in S19 or ihex format

• Supported devices for classic CAN are Kvaser, Peak, ETAS and Vector

• Supported devices for CAN-FD are Kvaser, Peak and Vector

Error handling

Pass functions will raise exceptions in case of errors. The most common exception is RuntimeError but may also raise ValueError and IndexError.

Listing available CAN devices

To retrieve a list of CAN devices supporting classic CAN, you can use the Pass.getAvailableDevicesCanClassic() function:

Pass.getAvailableDevicesCanClassic() → list[str]

List currently connected CAN devices supporting classic CAN.

Returns:

All currently connected CAN devices supporting classic CAN.

Return type:

list[str]

To retrieve a list of CAN devices supporting CAN-FD, you can use the Pass.getAvailableDevicesCanFd() function:

Pass.getAvailableDevicesCanFd() → list[str]

List currently connected CAN devices supporting CAN-FD.

Returns:

All currently connected CAN devices supporting CAN-FD.

Return type:

list[str]

XCP ECU connection handling

Pass.addXcpEcu(ecuName: str, a2lPath: str, connectionType: int, deviceToConnectWith: str) → None

Load an XCP file describing an ECU and prepare to connect

Parameters:

• ecuname – Name of the ECU. Needed to refer to measurements and characteristics in this ECU.

• a2lPath – Full path to the A2L file.

• connectionType – Any XcpConnectionType constant (XCP_CAN_CLASSIC, XCP_CAN_FD, XCP_UDP, MEMORY_IMAGE, CCP_CAN_CLASSIC)

• deviceToConnectWith – CAN device to connect with. Leave empty to use first available physical CAN device. Ignored for UDP/IP.

Returns:

None

Pass.unloadXcpEcus() → None

Unloading A2l file and associated data freeing up resources

Pass.connectToXcpEcus() → None

Connect to all added Xcp ecus

Pass.disconnectFromXcpEcu(ecu: str) → None

Disconnect from an ECU

Parameters:

ecu – The ECU to disconnect from.

Pass.disconnectFromAllXcpEcus() → None

Disconnect from all ECUs

Pass.isConnectedToAnyXcpEcu() → bool

Whether connected to any Xcp ECU or not

Returns:

Whether connected to any Xcp ECU or not.

Pass.isConnectedToXcpEcu(ecu: str) → bool

Whether connected to a specific Xcp ECU or not.

Parameters:

ecu – The ECU to check connection status for.

Returns:

Whether connected to a specific Xcp ECU or not.

XCP ECU image file handling

Pass.xcpEcuMemoryImageWriteToFile(ecu: str, imageFile: str)

” Writes current content of memory image to file. Only applicable when connected to memory image

Parameters:

• ecu – The ECU to write.

• imageFile – Path to the image file to write.

Connection health checks

Pass.checkHealthXcpConnectionExcept(ecu: str)

Throws an exception if an exception has occurred in XCP master

Parameters:

ecu – The ECU which connection shall be checked.

Pass.checkHealthXcpConnectionNoExcept(ecu: str) → bool

Returns whether an exception has occurred in XCP master

Parameters:

ecu – The ECU which connection shall be checked.

Returns:

Whether connection is still good or not.

Pass.checkHealthCanBusMonitorDbcExcept(ecu: str)

Throws an exception if an exception has occurred in background task in DBC monitoring

List available measurements and characteristics

Pass.availableXcpMeasurements() → list[str]

Returns a list of all available XCP measurements from loaded A2l files.

Returns:

A list of all available XCP measurements from loaded A2l files.

Return type:

list[str]

Pass.availableXcpCharacteristics() → list[str]

Returns a list of all available characteristics from loaded A2l files.

Returns:

A list of all available characteristics from loaded A2l files.

Return type:

list[str]

Pass.availableDbcMeasurements() → list[str]

Returns a list of all available XCP measurements from loaded Dbc files.

Returns:

A list of all available XCP measurements from loaded Dbc files.

Return type:

list[str]

XCP calibration

Pass.activeXcpCalibrationPage(ecu: str) → int

Return current active Xcp calibration page

Parameters:

ecu – The ECU which active page shall be returned.

Returns:

Return current active Xcp calibration page (PageType.REFERENCE or PageType.WORKING)

Return type:

int

Pass.setActiveXcpCalibrationPage(page: int) → None

Sets active Xcp calibration page for all ECUs (PageType.REFERENCE or PageType.WORKING)

Pass.isPageSwitchSupportedByAnyXcpEcu() → bool

Whether any connected Xcp slave supports page switching

Returns:

Whether any connected Xcp slave supports page switching.

Return type:

bool

Pass.downloadCalibration(identifier: str, value: Any) → None

Download a calibration parameter to an ECU

Parameters:

• identifier – Identifier of the parameter to download in form <ecu>.<variablename>.

• value – Value to download.

Pass.uploadCalibration(identifier: str) → Any

Upload a calibration parameter from an ECU

Parameters:

identifier – Identifier of the parameter to upload in form <ecu>.<variablename>.

Returns:

The uploaded value.

Return type:

Any

Pass.updateCalibrationsInFile(ecu: str, file: str, srcPage: int) → None

Updated values of all calibration parameters in a dataset on file from ECU values

Parameters:

• ecu – The ECU to upload values from.

• file – The dataset file (cdfx or dcm) to update.

• srcPage – Xcp calibration page to take values from (PageType.REFERENCE or PageType.WORKING).

Pass.uploadCalibrationsToFileAll(ecu: str, file: str, srcPage: int) → None

Upload all calibration parameters in ECU to file.

Parameters:

• ecu – The ECU to upload values from.

• file – The dataset file (cdfx or dcm) to upload to.

• srcPage – Xcp calibration page to take values from (PageType.REFERENCE or PageType.WORKING).

Pass.uploadCalibrationsToFileSelected(ecu: str, file: str, srcPage: int, itemsToUpload: list[str]) → None

Upload selected calibration parameters from ECU to file.

Parameters:

• ecu – The ECU to upload values from.

• file – The dataset file (cdfx or dcm) to upload to.

• srcPage – Xcp calibration page to take values from (PageType.REFERENCE or PageType.WORKING).

• itemsToUpload – The parameters to upload.

Pass.downloadCalibrationFromFile(ecu: str, file: str) → None

Download calibration parameters from file to ECU

Parameters:

• ecu – The ECU to upload values from.

• file – The dataset file (cdfx or dcm) to upload to.

Pass.downloadCalibrationsFromFileSelected(ecu: str, file: str, itemsDownload: list[str]) → None

Download selected calibration parameters from file to ECU

Parameters:

• ecu – The ECU to upload values from.

• file – The dataset file (cdfx or dcm) to upload to.

• itemsDownload – The parameters do download.

DBC measurement setup

Pass.addDbcNetworkConfiguration(dbcFilePath: str, networkName: str, canDevice: str, bitRate: int) → None

Load a CAN network configuration defined by DBC files

Parameters:

• dbcFilePath – Dbc file to use.

• networkName – Network name. Will be used to identify signals. Must be unique.

• canDevice – CAN device to use.

• int – CAN bitrate.

Pass.unloadDbcNetworkConfiguration(networkName: str) → None

Load a CAN network configuration defined by DBC files

Parameters:

networkName – Name of network to unload.

Start / stop data acquisition

Pass.startDaq(xcpMeasurements: str, timestampSource: int, dbcSignals: str) → None

Start data acquisition

Parameters:

• xcpMeasurements – XCP measurements.

• timestampSource – TimestampSource.SLAVE or TimestampSource.TRANSPORT_PROTOCOL.

• dbcSignals – DBC signals.

Pass.stopDaq() → None

Stop data acquisition

Pass.stopDaqAndDisconnect() → None

Shortcut for stopDaq followed by disconnect

Pass.getLatestMeasurementSample(identifier: str) → Any

Get latest sample of a measurement (Xcp or Dbc)

Parameters:

identifier – Identifier of the measurement data to get in form <scope>.<variablename>.

Returns:

The latest received value.

Return type:

Any

Data recording

Pass.activateRecording(recorderType: int, preTrigTime: float) → None

Prepare to start recording recording. If there is a pretrigger time data will be recorded to a temp buffer.

Parameters:

• recorderType – CSV, MDF3_3 or MDF4_2

• preTrigTime – If > 0, data will be recorded before triggered with startRecording.

Pass.startRecording() → None

Start recording

Pass.stopRecording() → None

Stop recording

Pass.discardRecording() → None

Discard recorded data

Pass.saveRecording(dst: str) → None

Save recorded data to file.

Parameters:

dst – File to save to.

Pass.openRecording(file: str) → Any

Open MDF recording

Parameters:

dst – File to save to.

Returns:

On object with the data in the file

Return type:

Any

Software download

Pass.swDownloadStartUds(fileToDownload: str, swDownloadScriptFile: str, canDevice: str) → None

Start Sw download with Uds

Parameters:

• fileToDownloadst – SREC/ihex file to download.

• swDownloadScriptFile – SW download script

• canDevice – CAN device to use. Leave empty for first physical device.

Pass.swDownloadStartXcp(fileToDownload: str, swDownloadScriptFile: str, xcpConnectionType: int, canDevice: str) → None

Start Sw download with Uds

Parameters:

• fileToDownloadst – SREC/ihex file to download.

• swDownloadScriptFile – SW download script

• xcpConnectionType – XCP_CAN_CLASSIC, XCP_CAN_FD, XCP_UDP

• canDevice – CAN device to use. Leave empty for first physical device.

Pass.swDownloadTearDown() → None

Free resources used in latest sw download operation

Pass.swDownloadCurrentAction() → str

Return a descriptive string for the current step in the running sw download operation

Returns:

A descriptive string for the current step in the running sw download operation

Return type:

str

Pass.swDownloadProgressPercent() → float

Return the progress in percent of the running sw download operation

Returns:

The progress in percent of the running sw download operation

Return type:

float

Pass.swDownloadIsInProgress() → bool

Check whether the sw download operation is in progress

Returns:

Whether the sw download operation is in progress

Return type:

bool

Pass.swDownloadAbort() → None

Abort a sw download in progress

Pass.swDownloadCheckHealth() → None

Check health of sw download process running in background

Sending CAN frames defined by DBC files

Pass.sendCanFrameDbc(msgIdentifier: str, signalsToValues: dict) → None

Send CAN frame defined by Dbc file

Parameters:

• msgIdentifier – Identifier of the CAN frame to send

• signalsToValues – dictionary, key is signal name and values are the signal values.