# Discovery

## Address

class canlib.kvrlib.Address(type, address)

  An IP or MAC address

  Parameters

    - type (`AddressType`) – Address type.

    - address (`list[int]`) – A list of integers, the numbers in the address.

  classmethod from_c(c_addr)

    Create an `Address` object from a `kvrAddress` object

  to_c()

    Create a `kvrAddress` from this object

## DeviceInfo

class canlib.kvrlib.DeviceInfo(device_info=None)

  Information about a device that can be written to the registry

  See `DeviceInfoSet` for information about how to get `DeviceInfo` objects, process them, and then write them to the registry.

  property accessibility

    The accessibility of this device

    Type

      `Accessibility`

  property availability

    The availability of this device

    Type

      `Availability`

  property base_station_id

    Address of the base station

    Type

      `Address`

  property client_address

    Address of connected client

    Type

      `Address`

  property connect

    Whether the service should connect to this device

    Type

      `bool`

  property device_address

    Address of remote device

    Type

      `Address`

  property ean

    EAN of device

    Type

      `EAN`

  property encryption_key

    The encryption key to use when encrypting communication

    Note

    This attribute is write-only.

    Type

      `bytes`

  property firmware_version

    Firmware version

    Type

      `VersionNumber`

  property hostname

    DNS hostname if available, otherwise an empty string

    Type

      `str`

  info()

    Create a string with information about the `DeviceInfo`

    To be used when the `str()` representation is not detailed enough.

  property name

    User-defined name of device

    Type

      `str`

  property password

    The accessibility password to use when connecting to a device

    Note

    This attribute is write-only.

    Type

      `str`

  property serial

    The serial number of the device

    Type

      `int`

  property service_status

    A tuple with the service status of the device

    The returned tuple has the format `(state, start_info, text)`, where `state` is a `ServiceState`, `start_info` is a `StartInfo`, and `text` is a `str` with local connection status.

    Type

      `ServiceStatus`

  property stored

    Whether this `DeviceInfo` was read from the registry

    Type

      `bool`

  update(other)

    Update the attributes of this instance

    This function takes a `dict`, and will set the attributes given by the keys to the corresponding value (on this object).

  property usage

    Usage status (Free/Remote/USB/Config)

    Type

      `DeviceUsage`

## Discovery

class canlib.kvrlib.Discovery(handle)

  A kvrlib “Discovery” process

  Most of the time the discovery process can be handled by `discover_info_set`, which returns the results of the discovery as a `DeviceInfoSet`.

  Even when interacted with directly, instnances of this class are normally not instantiated directly, but created using `start_discovery`, or sometimes using `openDiscovery`.

  Instances of this class can be used as context handlers, in which case the discovery will be closed when the context is exited. The discovery will also be closed when the instance is garbage collected, if it hasn’t already.

  property addresses

    The list of addresses to use for discovery

    Note

    This attribute is write-only.

    This attribute should be a list of `Address` objects.

    If the `Discovery` object was created by `start_discovery`, the addresses are automatically set. Otherwise, they must be assigned before `Discovery.start` can be called.

  close()

    Close the discovery process

    This function is called when the `Discovery` object is garbage-collected.

    If the `Discovery` object is used as a context handler, this function will be called when the context exits.

  results()

    Return an iterator of the result from the discovery

    The results are yielded as `DeviceInfo` objects.

  start(delay, timeout, report_stored=True)

    Run the discovery

    If the `Discovery` object was created by `start_discovery`, the discovery has already been run, and this function does not need to be called.

    After the discovery has been run, its results can be retrieved using `Discovery.results`.

    Parameters

      - delay (`int`) – The millisecond delay between sending discovery messages to addresses in the address list.

      - timeout (`int`) – The millisecond timeout after all discovery messages have been sent, before returning.

      - report_stored (`bool`) – if `True` (the default), stored devices will be discovered.

## get_default_discovery_addresses()

canlib.kvrlib.get_default_discovery_addresses(broadcast=True, stored=False)

  Retrieve the default discovery addresses

  Parameters

    - broadcast (`bool`) – If `True` (the default), then the returned list will contain broadcast addresses.

    - stored (`bool`) – If `True` (defaults to `False`), then the returned list will contain earlier stored addresses.

  If both arguments are `False`, a `ValueError` will be raised.

  Retruns a `list` of `Address` objects.

## openDiscovery()

canlib.kvrlib.openDiscovery()

  Creates and returns a `Discovery` object

  Device discovery is normally done using `discover_info_set`.

## ServiceStatus

class canlib.kvrlib.ServiceStatus(state, start_info, text)
  property start_info

    Alias for field number 1

  property state

    Alias for field number 0

  property text

    Alias for field number 2

## set_clear_stored_devices_on_exit()

canlib.kvrlib.set_clear_stored_devices_on_exit(val)

  Sets whether kvrlib should clear stored devices when the application exist

## start_discovery()

canlib.kvrlib.start_discovery(delay, timeout, addresses=None, report_stored=True)

  Start and return a `Discovery`

  Device discovery is normally done using `discover_info_set`.

  The returned object should usually be used as a context handler:

      with kvrlib.start_discovery(delay=100, timeout=1000) as disc:
          for result in disc.results():
              # process the discovery result
              print(result)

## store_devices()

canlib.kvrlib.store_devices(devices)

  Store a collection of `DeviceInfo` objects in the registry

  See `DeviceInfoSet` for a simpler way of dealing with device infos and the registry.

  Note

  Previously stored devices are cleared.

## stored_devices()

canlib.kvrlib.stored_devices()

  Read the devices stored in the registry as a tuple of `DeviceInfo` objects