# Remote Device

## AddressInfo

class canlib.kvrlib.AddressInfo(address1, address2, netmask, gateway, is_dhcp)
  property address1

    Alias for field number 0

  property address2

    Alias for field number 1

  property gateway

    Alias for field number 3

  property is_dhcp

    Alias for field number 4

  property netmask

    Alias for field number 2

## ConfigProfile

class canlib.kvrlib.ConfigProfile(device, profile_number)

  A configuration profile of a remote-capable device

  The active profile for a `RemoteDevice`, `rdev`, is accessed with:

      profile = rdev.active_profile

  Other profiles are accessed with `profiles`:

      first = rdev.profiles[0]

  See the documentation for `RemoteDevice` for more information on how to get `ConfigProfile` objects.

  The specific configuration of a profile can be read:

      xml_string = profile.read()

  And it can also be written back:

      profile.write(xml_string)

  The password used by this object is taken from its parent `RemoteDevice` object. See that documentation for how to set the password.

  XML_BUFFER_SIZE = 2046
  property channel_number

    The CANlib channel number used to communicate with the device

    Type

      `int`

  clear()

    Clear the configuration

    This will also clear any previously set device password.

    Note

    This method requires the parent `RemoteDevice` to have the correct password.

  property info

    A simplified version of the configuration

    It is not necessary to know the configuration password to access this information. Note that the partial XML data returned is not enough to reconfigure a device.

    Type

      `str`

  property password

    The password used to communicate with the device

    Type

      `str`

  read()

    Read the configuration

    Returns either an XML string, or `None` if there is no configuration.

    Note that `ConfigProfile.write` can handle `None`; in other words:

        xml = profile.read()

        # Do anything, including writing new configurations
        ...

        profile.write(xml)

    Will always work even if `xml` is `None`. This would mean that the profile originally had an empty configuration, and it will once again have an empty configuration at the end.

    Note

    This method requires the parent `RemoteDevice` to have the correct password.

  write(xml)

    Write the configuration area

    This function takes as its single argument either an xml string that will be written to this profile, or `None` in which case the configuration will be cleared.

    Note

    This method requires the parent `RemoteDevice` to have the correct password.

## ConnectionStatus

class canlib.kvrlib.ConnectionStatus(state, tx_rate, rx_rate, channel_number, rssi, tx_power)
  property channel_number

    Alias for field number 3

  property rssi

    Alias for field number 4

  property rx_rate

    Alias for field number 2

  property state

    Alias for field number 0

  property tx_power

    Alias for field number 5

  property tx_rate

    Alias for field number 1

## ConnectionTestResult

class canlib.kvrlib.ConnectionTestResult(rssi, rtt)
  property rssi

    Alias for field number 0

  property rtt

    Alias for field number 1

## ConnectionTest

class canlib.kvrlib.ConnectionTest(config_handle)

  A connection test for a specific device

  A connection test for a `RemoteDevice`, `rdev`, is created by:

      test = rdev.connection_test()

  While a connection test is running, the device will connect and start pinging itself to measure round-trip time (RTT) and Receive Signal Strength Indicator (RSSI).

  A `ConnectionTest` is started with `ConnectionTest.start` and stopped with `ConnectionTest.stop`, after which its results are retrieved by `ConnectionTest.results`. If it is acceptable to block while the test is running, these three calls can be combined into `ConnectionTest.run`:

      results = test.run(duration=10)
      print(results)

  Connection tests are automatically closed when garbage-collected, but they can also be closed manually with `ConnectionTest.close`.

  close()

    Close the internal handle

  results(maxresults=20)

    Get the results from a connection test

    The test must have been running for any results to be available.

    This function returns a `ConnectionTestResult`, which is a namedtuple of `(rssi, rtt)`. Both `rssi` and `rtt` are tuples containing a number of individual results for RSSI and RTT.

    Parameters

      maxresults (`int`) – The maximum number of rssi and rtt numbers to return. The returned `rssi` and `rtt` will be tuples with this long or the number of results available long, whichever is shortest.

  run(duration, maxresults=20)

    Run a connection test and return its results.

    This function calls `ConnectionTest.start`, then blocks for `duration` seconds, then calls `ConnectionTest.stop` before finally returning the `ConnectionTestResult` from `ConnectionTest.results`.

    Parameters

      - duration (`int`) – Seconds to run the test for.

      - maxresults (`int`) – Passed to `ConnectionTest.results` as `maxlen`.

  start()

    Start the connection test

  stop()

    Stop the connection test

## openDevice()

canlib.kvrlib.openDevice(channel_number, password='', validate_password=False)

  Create a `RemoteDevice` object bound to a channel number

  Parameters

    - channel_number (`int`) – CANlib channel number of the device to open

    - password (`str`) – Password of the device, if any

    - validate_password (`bool`) – Whether the password should be validated (defaults to `False`).

  This function checks that a remote-capable device is currently connection on the channel `channel_number`. If `validate_password` is `True`, it also checks that the password supplied is correct. If any of these checks fail, a `ValueError` will be raised.

## RemoteDevice

class canlib.kvrlib.RemoteDevice(channel_number, password)

  A remote-capable Kvaser device

  This class is normally instantiated with `openDevice`:

      rdev = kvrlib.openDevice(CHANNEL_NUMBER)

  Once this is done, the currently active profile can be accessed:

      active = rdev.active_profile

  All profiles, including the active one, are `ConfigProfile` objects, see that documentation for all the operations available for profile objects.

  The full list of profiles a device has can be inspected using `rdev.profiles`. This is a `RemoteDevice.ProfileList` object, which works much like a list:

      # The profile list can be indexed
      first = rdev.profiles[0]

      # We can check if a configuration belongs to this device with 'in'
      assert first in rdev.profiles

      # The length of the profile list is the number of profiles
      num_profiles = len(rdev.profiles)

      # Using the number of profiles, we can get the last one
      last = rdev.profiles[num_profiles - 1]

      # But negative indexes also work and are a better way of getting
      # the last profile
      last = rdev.profiles[-1]

      # You can also iterate over all profiles
      for profile in rdev.profiles:
          ...

  `RemoteDevice` also lets you access a variety of information about the specific device, as well as the ability to do a WLAN scan with `RemoteDevice.wlan_scan`.

  If the device is password protected, that password can be passed to `openDevice`:

      protected_device = kvrlib.openDevice(0, password="Once upon a playground rainy")

  After the object is created, the password is available as:

      password = protected_device.password

  The password can be changed with:

      protected_device.password = "Wolves without teeth"

  The reason the password is stored as clear-text is because it must be supplied to the underlying library each time an operation is done using this and related classes. This also means that the password is only validated, and required, when one of the functions requiring a password is called.

  If the device is not password-protected, the password should be an empty string:

      unprotected_device = kvrlib.openDevice(1)
      assert unprotected_device.password == ''

  class ProfileList(channel_number)

    The available profiles in a remote-capable device

    This is the type of `RemoteDevice.profiles`. It implements the following:

    - `len(profiles)`

    - `profile in profiles`

    - `profile[index]`

  property active_profile

    The currently active profile

    Activating another profile is done by assigning this attribute to another profile:

        new_profile = remote_device.profiles[index]
        remote_device.active_profile = new_profile

    The value assigned to this property must be a `ConfigProfile` that belongs to this device, i.e. the following must be `True`:

        new_profile in remote_device.profiles

    Type

      `ConfigProfile`

  property address_info

    Information about network address settings

    Note

    Accessing this attribute requires the correct password be set on the object.

    Type

      `AddressInfo`

  property connection_status

    Connection status information

    The returned tuple is a `(state, tx_rate, rx_rate, channel, rssi, tx_power)` namedtuple of:

    1. `state` (`NetworkState`): Network connection state

    2. `tx_rate` (`int`): Transmit rate in kbit/s

    3. `rx_rate` (`int`): Receive rate in kbit/s

    4. `channel` (`int`): Channel

    5. `rssi` (`int`): Receive Signal Strength Indicator

    6. `tx_power` (`int`): Transmit power level in dB

    Note

    Accessing this attribute requires the correct password be set on the object.

    Type

      `ConnectionStatus`

  connection_test()

    Creates a connection test for this device

    Returns

      `ConnectionTest`

    See the documentation of `ConnectionTest` for more information.

    Note

    Accessing this attribute requires the correct password be set on the object.

  property hostname

    Device’s hostname

    Note

    Accessing this attribute requires the correct password be set on the object.

    Type

      `str`

  password_valid()

    Checks whether the password set is valid

    Returns

      `bool` – `True` if the password is valid, `False` otherwise.

  wlan_scan(active=False, bss_type=BasicServiceSet.ANY, domain=RegulatoryDomain.WORLD)

    Creates and starts a wlan scan for this device

    Returns

      `WlanScan`

    See the documentation of `WlanScan` for more information.

    Note

    Accessing this attribute requires the correct password be set on the object.

## WlanScan

class canlib.kvrlib.WlanScan(config_handle)

  A wlan scan for this device

  The device starts scanning as soon as this object is created by `RemoteDevice.wlan_scan`:

      scan = rdev.wlan_scan()

  When calling `RemoteDevice.wlan_scan`, you can also specify whether the scan should be an active one, the Basic Service Set (bss) to use, and the regulatory domain:

      scan = rdev.wlan_scan(
          active=True,
          bss=kvrlib.BasicServiceSet.INFRASTRUCTURE,
          domain=kvrlib.RegulatoryDomain.EUROPE_ETSI,
      )

  Results from the scan are retrieved by iterating over the `WlanScan` object:

  > for result in scan:

  >   print(result)

  When getting the next result, the code will block until a new result is available or until no more results are available, in which case the iteration stops.

  Wlan scans are automatically closed when garbage-collected, but they can also be closed manually with `WlanScan.close`.

  close()

    Closes the internal handle

## WlanScanResult

class canlib.kvrlib.WlanScanResult(rssi, channel_number, mac, bss_type, ssid, security_text)
  property bss_type

    Alias for field number 3

  property channel_number

    Alias for field number 1

  property mac

    Alias for field number 2

  property rssi

    Alias for field number 0

  property security_text

    Alias for field number 5

  property ssid

    Alias for field number 4