.. Pass documentation master file, created by
   sphinx-quickstart on Mon Mar 10 18:47:46 2025.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Pass documentation
==================

.. contents:: Table of Contents
   :local:


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:

.. autofunction:: Pass.getAvailableDevicesCanClassic

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

.. autofunction:: Pass.getAvailableDevicesCanFd 

XCP ECU connection handling
-------------------------------------------------------------------------------
.. autofunction:: Pass.addXcpEcu 
.. autofunction:: Pass.unloadXcpEcus
.. autofunction:: Pass.connectToXcpEcus

.. autofunction:: Pass.disconnectFromXcpEcu
.. autofunction:: Pass.disconnectFromAllXcpEcus
.. autofunction:: Pass.isConnectedToAnyXcpEcu
.. autofunction:: Pass.isConnectedToXcpEcu

XCP ECU image file handling
-------------------------------------------------------------------------------
.. autofunction:: Pass.xcpEcuMemoryImageWriteToFile
   

Connection health checks
-------------------------------------------------------------------------------
.. autofunction:: Pass.checkHealthXcpConnectionExcept
.. autofunction:: Pass.checkHealthXcpConnectionNoExcept
.. autofunction:: Pass.checkHealthCanBusMonitorDbcExcept

List available measurements and characteristics
-------------------------------------------------------------------------------
.. autofunction:: Pass.availableXcpMeasurements
.. autofunction:: Pass.availableXcpCharacteristics
.. autofunction:: Pass.availableDbcMeasurements
    
XCP calibration
-------------------------------------------------------------------------------
.. autofunction:: Pass.activeXcpCalibrationPage
.. autofunction:: Pass.setActiveXcpCalibrationPage
.. autofunction:: Pass.isPageSwitchSupportedByAnyXcpEcu
.. autofunction:: Pass.downloadCalibration
.. autofunction:: Pass.uploadCalibration
.. autofunction:: Pass.updateCalibrationsInFile
.. autofunction:: Pass.uploadCalibrationsToFileAll
.. autofunction:: Pass.uploadCalibrationsToFileSelected
.. autofunction:: Pass.downloadCalibrationFromFile
.. autofunction:: Pass.downloadCalibrationsFromFileSelected

DBC measurement setup
-------------------------------------------------------------------------------
.. autofunction:: Pass.addDbcNetworkConfiguration
.. autofunction:: Pass.unloadDbcNetworkConfiguration

Start / stop data acquisition
-------------------------------------------------------------------------------
.. autofunction:: Pass.startDaq
.. autofunction:: Pass.stopDaq
.. autofunction:: Pass.stopDaqAndDisconnect
.. autofunction:: Pass.getLatestMeasurementSample

Data recording
-------------------------------------------------------------------------------
.. autofunction:: Pass.activateRecording
.. autofunction:: Pass.startRecording
.. autofunction:: Pass.stopRecording
.. autofunction:: Pass.discardRecording
.. autofunction:: Pass.saveRecording
.. autofunction:: Pass.openRecording

Software download
-------------------------------------------------------------------------------
.. autofunction:: Pass.swDownloadStartUds
.. autofunction:: Pass.swDownloadStartXcp
.. autofunction:: Pass.swDownloadTearDown
.. autofunction:: Pass.swDownloadCurrentAction
.. autofunction:: Pass.swDownloadProgressPercent
.. autofunction:: Pass.swDownloadIsInProgress
.. autofunction:: Pass.swDownloadAbort
.. autofunction:: Pass.swDownloadCheckHealth

Sending CAN frames defined by DBC files
-------------------------------------------------------------------------------
.. autofunction:: Pass.sendCanFrameDbc