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]	canHnd	An open handle to a CAN channel of a KSI capable device.
[in]	type	DIAG_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]	canHnd	An open handle to a CAN channel with an attached analyzer.
[out]	btr	Contains 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]	canHnd	An open handle to a CAN channel with an attached analyzer.
[in]	id	Id with which the device of interest is sending
[out]	fMin	Minimum drift encountered (parts per trillion)
[out]	fMax	Maximum drift encountered (parts per trillion)
[out]	fMean	Mean drift encountered (parts per trillion)
[out]	fStd	Standard deviation (parts per trillion)
[out]	n	Number 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] canHnd An 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]	canHnd	An open handle to a CAN channel.
[in,out]	info	for 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]	canHnd	An open handle to a CAN channel.
[out]	analyzerCount	Number 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]	canHnd	An open handle to a CAN channel with an attached analyzer.
[out]	sample	Pointer 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]	canHnd	An open handle to a CAN channel with an attached analyzer.
[out]	sample	Pointer to struct to receive the sample.
[in]	timeout	Number 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] canHnd An 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] canHnd An 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]	canHnd	An open handle to a CAN channel with an attached analayzer.
[in]	programType	Analyzer program, either DIAG_PROGRAM_TYPE_NORMAL or DIAG_PROGRAM_TYPE_AUTOBAUD.
[in]	configBuffer	A 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] canHnd An 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] canHnd An 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.

Functions

Detailed Description

Function Documentation

◆ kvDiagAttachAnalyzer()

◆ kvDiagCalculateBitrate()

◆ kvDiagCalculateClockOffset()

◆ kvDiagDetachAnalyzer()

◆ kvDiagGetAnalyzerInfo()

◆ kvDiagGetNumberOfAnalyzers()

◆ kvDiagReadSample()

◆ kvDiagReadSampleWait()

◆ kvDiagResetBitrateCalculation()

◆ kvDiagResetClockOffsetCalculation()

◆ kvDiagSetProgram()

◆ kvDiagStart()

◆ kvDiagStop()