# Bus Parameters

## calc_bitrate()

canlib.canlib.busparams.calc_bitrate(target_bitrate, clk_freq)

  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)

  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)

  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)

  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)

  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

    - clk_freq (`float`) – Clock frequency of device.

    - bus_param (`BusParamsTq`) – `BusParamsTq` object to convert.

  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)

  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()

    Returns an approximation of the clock frequency as a float.

## BusParamsTq

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

  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)

    Return bitrate assuming the given clock frequency

    Parameters

      clk_freq (`int`) – Clock frequency (in Hz)

  sample_point()

    Return sample point in percentage.

  sample_point_ns(clk_freq)

    Return sample point in ns.

    New in version 1.17.

  sync_jump_width()

    Return sync jump width (SJW) in percentage.

## BusParamTqLimits

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

  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)

    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)

  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)

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