CANtegrity API

CANtegrity API. More...

Functions

canStatus kvDiagGetNumberOfAnalyzers (const canHandle canHnd, int *analyzerCount)
 
canStatus kvDiagGetAnalyzerInfo (const canHandle canHnd, kvAnalyzerInfo_t *info)
 
canStatus kvDiagAttachAnalyzer (const canHandle canHnd, int type)
 
canStatus kvDiagDetachAnalyzer (const canHandle canHnd)
 
canStatus kvDiagSetProgram (const canHandle canHnd, int programType, const char *const configBuffer)
 
canStatus kvDiagStart (const canHandle canHnd)
 
canStatus kvDiagStop (const canHandle canHnd)
 
canStatus kvDiagReadSample (const canHandle canHnd, kvDiagSample *sample)
 
canStatus kvDiagReadSampleWait (const canHandle canHnd, kvDiagSample *sample, int timeout)
 
canStatus kvDiagCalculateBitrate (const canHandle canHnd, bitrates_t *btr)
 
canStatus kvDiagResetBitrateCalculation (const canHandle canHnd)
 
canStatus kvDiagCalculateClockOffset (const canHandle canHnd, int id, double *fMin, double *fMax, double *fMean, double *fStd, int *n)
 
canStatus kvDiagResetClockOffsetCalculation (const canHandle canHnd)
 

Detailed Description

CANtegrity API.

The kvDiagXxx functions specify the CANtegrity API, which is based on high frequency sampling of the CAN bus. To check if a device has CANtegrity support, use canGetChannelData() with the item canCHANNELDATA_CHANNEL_CAP and the flag canCHANNEL_CAP_CANTEGRITY.

Function Documentation

◆ kvDiagAttachAnalyzer()

canStatus kvDiagAttachAnalyzer ( const canHandle  canHnd,
int  type 
)

Attach an analyzer to the a CAN channel handle. The device needs to have the CANtegrity capability. See CANtegrity API (kvDiag) for how to check this.

Note
A CAN channel can currently only have one attached Analyzer.
The kvDiag API is preliminary and will change!
Parameters
[in]canHndAn open handle to a CAN channel of a KSI capable device.
[in]typeDIAG_ANALYZER_TYPE_XXX.
Returns
canOK (zero) if success
canERR_xxx (negative) if failure
See also
kvDiagDetachAnalyzer()
Examples:
example/c/kvdiag/autobaud.c, and example/c/kvdiag/normal.c.

◆ kvDiagCalculateBitrate()

canStatus kvDiagCalculateBitrate ( const canHandle  canHnd,
bitrates_t btr 
)

Run with DIAG_PROGRAM_TYPE_AUTOBAUD, see CANtegrity API (kvDiag).

Calculate the bitrate on the CAN bus by sampling a series of CAN frames. Uses all the sampled frames in the device buffer on each call. Stores information between calls. May require several calls until the quality value is sufficiently high.

Note
The Analyzer program DIAG_PROGRAM_TYPE_AUTOBAUD will stop processing after 100 frames have been received. To restart processing, call kvDiagResetBitrateCalculation().
Note
For classic CAN btr.bitrate contains the calculated bitrate and quality. Currently, FD is not supported so btr.bitrate_brs can be disregarded.
Note
The kvDiag API is preliminary and will change!
Parameters
[in]canHndAn open handle to a CAN channel with an attached analyzer.
[out]btrContains two sets of values for bitrate and quality.
Returns
canOK (zero) if success
canERR_xxx (negative) if failure
See also
kvDiagAttachAnalyzer()
kvDiagSetProgram()
kvDiagStart()
kvDiagResetBitrateCalculation()
Examples:
example/c/kvdiag/autobaud.c.

◆ kvDiagCalculateClockOffset()

canStatus kvDiagCalculateClockOffset ( const canHandle  canHnd,
int  id,
double *  fMin,
double *  fMax,
double *  fMean,
double *  fStd,
int *  n 
)

Run with DIAG_PROGRAM_TYPE_NORMAL, see CANtegrity API (kvDiag).

Get the clock offset of a device relative to the clock of the measuring device. This roughly equates to the relative difference of the two frequencies.

clockoffset = (T_id - T_diag) / T_diag = (f_diag - f_id) / f_id

where

T_diag Time elapsed on the measuring device.
T_id Time elapsed on the target device.
f_diag Frequency of the measuring device.
f_id Frequency of the target device.

The result is expressed as a normal distribution over the sampled frames used. The unit of measurement is ppt (parts per trillion, 1e-12).

The function stores information between calls. Call until sufficient precision is reached. Each call will consume one sampled frame from the device buffer.

Note
This function is in an alpha state!
Note
The kvDiag API is preliminary and will change!
Parameters
[in]canHndAn open handle to a CAN channel with an attached analyzer.
[in]idId with which the device of interest is sending
[out]fMinMinimum drift encountered (parts per trillion)
[out]fMaxMaximum drift encountered (parts per trillion)
[out]fMeanMean drift encountered (parts per trillion)
[out]fStdStandard deviation (parts per trillion)
[out]nNumber of sampled frames used.
Returns
canOK (zero) if success
canERR_xxx (negative) if failure
See also
kvDiagAttachAnalyzer()
kvDiagSetProgram()
kvDiagStart()
kvDiagResetClockOffsetCalculation()

◆ kvDiagDetachAnalyzer()

canStatus kvDiagDetachAnalyzer ( const canHandle  canHnd)

Detach the analyzer from the CAN channel handle.

Note
Currently only one analyzer is supported.
Note
The kvDiag API is preliminary and will change!
Parameters
[in]canHndAn open handle to a CAN channel with an attached analyzer.
Returns
canOK (zero) if success
canERR_xxx (negative) if failure
See also
kvDiagAttachAnalyzer()
Examples:
example/c/kvdiag/autobaud.c, and example/c/kvdiag/normal.c.

◆ kvDiagGetAnalyzerInfo()

canStatus kvDiagGetAnalyzerInfo ( const canHandle  canHnd,
kvAnalyzerInfo_t info 
)

Get analyzer info.

Note
The kvDiag API is preliminary and will change!
Parameters
[in]canHndAn open handle to a CAN channel.
[in,out]infofor analyzer info.
Returns
canOK (zero) if success
canERR_xxx (negative) if failure
See also
kvDiagGetAnalyzerInfo()

◆ kvDiagGetNumberOfAnalyzers()

canStatus kvDiagGetNumberOfAnalyzers ( const canHandle  canHnd,
int *  analyzerCount 
)

Get the number of analyzers.

Note
The kvDiag API is preliminary and will change!
Parameters
[in]canHndAn open handle to a CAN channel.
[out]analyzerCountNumber of analyzers.
Returns
canOK (zero) if success
canERR_xxx (negative) if failure
See also
kvDiagGetNumberOfAnalyzers()

◆ kvDiagReadSample()

canStatus kvDiagReadSample ( const canHandle  canHnd,
kvDiagSample sample 
)

Run with DIAG_PROGRAM_TYPE_NORMAL, see CANtegrity API (kvDiag).

Read (and consume) one full sample from an analyzer.

Note
The kvDiag API is preliminary and will change!
Parameters
[in]canHndAn open handle to a CAN channel with an attached analyzer.
[out]samplePointer to struct to receive the sample.
Returns
canOK (zero) if success
canERR_NOMSG (negative) if there was no message available.
canERR_xxx (negative) if failure
See also
kvDiagAttachAnalyzer()
kvDiagSetProgram()
kvDiagStart()
kvDiagReadSampleWait()

◆ kvDiagReadSampleWait()

canStatus kvDiagReadSampleWait ( const canHandle  canHnd,
kvDiagSample sample,
int  timeout 
)

Run with DIAG_PROGRAM_TYPE_NORMAL, see CANtegrity API (kvDiag).

Read (and consume) one full sample from an analyzer. Will wait until a message arrives or a timeout occurs.It can take up to 100 ms for this function to return after a new sample is available.

Note
The kvDiag API is preliminary and will change!
Parameters
[in]canHndAn open handle to a CAN channel with an attached analyzer.
[out]samplePointer to struct to receive the sample.
[in]timeoutNumber of milliseconds to wait for the next sample.
Returns
canOK (zero) if success
canERR_NOMSG (negative) if there was no message available.
canERR_xxx (negative) if failure
See also
kvDiagAttachAnalyzer()
kvDiagSetProgram()
kvDiagStart()
kvDiagReadSample()
Examples:
example/c/kvdiag/normal.c.

◆ kvDiagResetBitrateCalculation()

canStatus kvDiagResetBitrateCalculation ( const canHandle  canHnd)

Resets the bitrate calculation of kvDiagCalculateBitrate().

Note
The kvDiag API is preliminary and will change!
Parameters
[in]canHndAn open handle to a CAN channel with an attached analyzer.
Returns
canOK (zero) if success
canERR_xxx (negative) if failure
See also
kvDiagCalculateBitrate()
Examples:
example/c/kvdiag/autobaud.c.

◆ kvDiagResetClockOffsetCalculation()

canStatus kvDiagResetClockOffsetCalculation ( const canHandle  canHnd)

Resets the clock offset calculation of kvDiagCalculateClockOffset().

Note
The kvDiag API is preliminary and will change!
Parameters
[in]canHndAn open handle to a CAN channel with an attached analyzer.
Returns
canOK (zero) if success
canERR_xxx (negative) if failure
See also
kvDiagCalculateClockOffset()

◆ kvDiagSetProgram()

canStatus kvDiagSetProgram ( const canHandle  canHnd,
int  programType,
const char *const  configBuffer 
)

Choose analyzer program to run.

configBuffer is a JSON string containing configuration parameters. The following is an example configuration yielding a bitrate of 1MBit/s:

const char *configBuffer = "{\"tseg1\" : 59, \"tseg2\" : 20, \"sjw\" : 16, \"brp\" : 1}";

where

tseg1 Time segment 1, that is, the number of quanta from (but not
including) the Sync Segment to the sampling point.
tseg2 Time segment 2, that is, the number of quanta from the sampling
point to the end of the bit.
sjw The Synchronization Jump Width.
brp Bitrate prescaler.
Parameters
[in]canHndAn open handle to a CAN channel with an attached analayzer.
[in]programTypeAnalyzer program, either DIAG_PROGRAM_TYPE_NORMAL or DIAG_PROGRAM_TYPE_AUTOBAUD.
[in]configBufferA configuration string in JSON format specifying bus parameters.
Returns
canOK (zero) if success.
canERR_xxx (negative) if failure.
Examples:
example/c/kvdiag/autobaud.c, and example/c/kvdiag/normal.c.

◆ kvDiagStart()

canStatus kvDiagStart ( const canHandle  canHnd)

Start data acquisition.

Note
The kvDiag API is preliminary and will change!
Parameters
[in]canHndAn open handle to a CAN channel with an attached analyzer.
Returns
canOK (zero) if success
canERR_xxx (negative) if failure
See also
kvDiagStop()
Examples:
example/c/kvdiag/autobaud.c, and example/c/kvdiag/normal.c.

◆ kvDiagStop()

canStatus kvDiagStop ( const canHandle  canHnd)

Stop data acquisition.

Note
The kvDiag API is preliminary and will change!
Parameters
[in]canHndAn open handle to a CAN channel with an attached analyzer.
Returns
canOK (zero) if success
canERR_xxx (negative) if failure
See also
kvDiagAttachAnalyzer()
kvDiagSetProgram()
kvDiagStart()
Examples:
example/c/kvdiag/autobaud.c, and example/c/kvdiag/normal.c.