Bus Parameters

calc_bitrate()

canlib.canlib.busparams.calc_bitrate(target_bitrate, clk_freq)[source]

Calculate nearest available bitrate

Parameters:
  • target_bitrate (int) – Wanted bitrate (bit/s)

  • clk_freq (int) – Device clock frequency (Hz)

Returns:

The returned tuple is a (bitrate, tq) named tuple of –

  1. bitrate (int): Available bitrate, could be a rounded value (bit/s)

  2. tq (int): Number of time quanta in one bit

New in version 1.16.

calc_busparamstq()

canlib.canlib.busparams.calc_busparamstq(target_bitrate, target_sample_point, target_sync_jump_width, clk_freq, target_prop_tq=None, prescaler=1)[source]

Calculate closest matching busparameters.

The device clock frequency, clk_freq, can be obtained via ClockInfo.frequency():

>>> chd = canlib.ChannelData(channel_number=0)
>>> clock_info = chd.clock_info
>>> clock_info.frequency()
80000000.0

Now call calc_busparamstq with target values, and a BusParamsTq object will be returned:

>>> params = calc_busparamstq(
... target_bitrate=470_000,
... target_sample_point=82,
... target_sync_jump_width=15.3,
... clk_freq=clock_info.frequency())
>>> params
BusParamsTq(tq=170, prop=107, phase1=31, phase2=31, sjw=26, prescaler=1)

A target number of time quanta in the propagation segment can also be specified by the user.

The returned BusParamsTq may not be valid on all devices. If Error.NOT_IMPLEMENTED is encountered when trying to set the bitrate with the returned BusParamsTq, provide a prescaler argument higher than one and retry. This will lower the total number of time quanta in the bit and thus make the BusParamsTq valid.

Example

>>> params = calc_busparamstq(
... target_bitrate=470_000,
... target_sample_point=82,
... target_sync_jump_width=15.3,
... clk_freq=clock_info.frequency(),
... target_prop_tq=50,
... prescaler=2)
>>> params
BusParamsTq(tq=85, prop=25, phase1=44, phase2=15, sjw=13, prescaler=2)

Note

  • Minimum sjw returned is 1, maximum sjw is min(phase1, phase2).

Parameters:
  • target_bitrate (float) – Wanted bitrate (bit/s)

  • target_sample_point (float) – Wanted sample point in percentage (0-100)

  • target_sync_jump_width (float) – Wanted sync jump width in percentage (0-100)

  • clk_freq (float) – Device clock frequency (Hz)

  • target_prop_tq (int, Optional) – Wanted propagation segment (time quanta)

  • prescaler (int, Optional) – Wanted prescaler (at most 2 for CAN FD)

Returns:

BusParamsTq – Calculated bus parameters

New in version 1.16.

Changed in version 1.17.

calc_sjw()

canlib.canlib.busparams.calc_sjw(tq, target_sync_jump_width)[source]

Calculate sync jump width

tq: Number of time quanta in one bit target_sync_jump_width: Wanted sync jump width, 0-100 (%)

Note: Minimum sjw_tq returned is 1.

Returns:

The returned named tuple is a (sjw_tq, sync_jump_width) consisting of –

  1. sjw_tq (int): Size of sync jump width in number of time quanta,

  2. sync_jump_width (number): Size of sync jump width in percentage (%))

New in version 1.16.

to_BusParamsTq()

canlib.canlib.busparams.to_BusParamsTq(clk_freq, bus_param, prescaler=1, data=False)[source]

Convert BitrateSetting or tuple to BusParamsTq.

The device clock frequency, clk_freq, can be obtained via ClockInfo.frequency():

>>> chd = canlib.ChannelData(channel_number=0)
>>> clock_info = chd.clock_info
>>> clock_info.frequency()
80000000.0
Parameters:
  • clk_freq (float) – Clock frequency of device.

  • bus_param (BitrateSetting or tuple) – BitrateSetting object or

  • (freq, tseg1, tseg2, sjw) `tuple` to convert.

  • prescaler (int) – The prescaler to use in the created BusParamsTq

  • object.

  • data (bool) – Set to True if the resulting BusParamsTq should be

  • used for CAN FD data bitrate parameters.

Returns:

BusParamsTq object with equivalent settings as the input argument.

New in version 1.17.

to_BitrateSetting()

canlib.canlib.busparams.to_BitrateSetting(clk_freq, bus_param)[source]

Convert BusParamsTq to BitrateSetting.

The device clock frequency, clk_freq, can be obtained via ClockInfo.frequency():

>>> chd = canlib.ChannelData(channel_number=0)
>>> clock_info = chd.clock_info
>>> clock_info.frequency()
80000000.0
Parameters:
Returns:

BitrateSetting object with equivalent settings as the input argument.

New in version 1.17.

ClockInfo

class canlib.canlib.busparams.ClockInfo(numerator, denominator, power_of_ten, accuracy)[source]

Information about clock a oscillator

The clock frequency is set in the form:

frequency = numerator / denominator * 10 ** power_of_ten +/- accuracy

New in version 1.16.

frequency()[source]

Returns an approximation of the clock frequency as a float.

BusParamsTq

class canlib.canlib.busparams.BusParamsTq(tq, phase1, phase2, sjw, prescaler=1, prop=None)[source]

Holds parameters for busparameters in number of time quanta.

If you don’t want to specify the busparameters in time quanta directly, you may use calc_busparamstq which returns an object of this class.

>>> params = calc_busparamstq(
... target_bitrate=470_000,
... target_sample_point=82,
... target_sync_jump_width=33.5,
... clk_freq=clk_freq)
>>> params
BusParamsTq(tq=170, prop=107, phase1=31, phase2=31, sjw=57, prescaler=1)

You may now query for the actual Sample Point and Sync Jump Width expressed as percentages of total bit time quanta:

>>> params.sample_point()
81.76470588235294
>>> params.sync_jump_width()
33.52941176470588

If you supply the clock frequency, you may also calculate the corresponding bitrate:

>>> params.bitrate(clk_freq=80_000_000)
470588.23529411765
Parameters:
  • tq (int) – Number of time quanta in one bit.

  • phase1 (int) – Number of time quanta in Phase Segment 1.

  • phase2 (int) – Number of time quanta in Phase Segment 2.

  • sjw (int) – Number of time quanta in Sync Jump Width.

  • prescaler (int) – Prescaler value (1-2 to enable auto in CAN FD)

  • prop (int, optional) – Number of time quanta in Propagation Segment.

New in version 1.16.

bitrate(clk_freq)[source]

Return bitrate assuming the given clock frequency

Parameters:

clk_freq (int) – Clock frequency (in Hz)

sample_point()[source]

Return sample point in percentage.

sample_point_ns(clk_freq)[source]

Return sample point in ns.

New in version 1.17.

sync_jump_width()[source]

Return sync jump width (SJW) in percentage.

BusParamTqLimits

class canlib.canlib.busparams.BusParamTqLimits(arbitration_min, arbitration_max, data_min, data_max)[source]

Hold min and max values for both arbitration and data phase.

The tq field is ignored during validation since ChannelData.bus_param_limits always returns zero for this field.

If prop is zero for both min and max values, the phase1 limit applies to (phase1 + prop). This is used when a device does not distinguish between phase segment one and the propagation segment.

Example usage:

>>> ch = canlib.openChannel(channel=0)
>>> limits = canlib.ChannelData(channel_number=0).bus_param_limits
>>> limits.arbitration_max._asdict()
{'tq': 0, 'phase1': 32, 'phase2': 32, 'sjw': 32, 'prescaler': 1024, 'prop': 64}
>>> bp_tq = canlib.busparams.BusParamsTq(tq=121, phase1=100, phase2=10, sjw=10,
... prescaler=10, prop=10)
>>> limits.validate(bp_tq)
ValueError: The following does not match:
  Arbitration phase1: 1 <= 100 <= 32

NOTE: This class is preliminary and may change!

New in version 1.20.

validate(bus_param, data_param=None)[source]

Validates busparameters for arbitration and data

Raises a ValueError if busparameters for arbritation and data is not within current limits. The failed validation is provided as an explanation:

ValueError: The following does not match:
  Arbitration phase1: 11 <= 1 <= 21

BitrateSetting

class canlib.canlib.busparams.BitrateSetting(freq, tseg1, tseg2, sjw, nosamp=1, syncMode=0)[source]

Class that holds bitrate setting.

Parameters:
  • freq – Bitrate in bit/s.

  • tseg1 – Number of quanta from (but not including) the Sync Segment to the sampling point.

  • tseg2 – Number of quanta from the sampling point to the end of the bit.

  • sjw – The Synchronization Jump Width.

  • nosamp – The number of sampling points, only 1 is supported.

  • syncMode – Unsupported and ignored.

New in version 1.17.

classmethod from_predefined(bitrate)[source]

Create a BitrateSetting object using one of the Bitrate or BitrateFD enumerations.