# Discovery

## Address

class `canlib.kvrlib.``Address`

  An IP or MAC address

  Variables: | Address.type (`canlib.kvrlib.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 `canlib.kvrlib.kvrAddress` object

  `to_c`()

    Create a `canlib.kvrlib.kvrAddress` from this object

## DeviceInfo

class `canlib.kvrlib.``DeviceInfo`(device_info=None)

  Information about a device that can be written to the registry

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

  `accessibility`

    The accessibility of this device

    Type: | `canlib.kvrlib.Accessibility`

  `availability`

    The availability of this device

    Type: | `canlib.kvrlib.Availability`

  `base_station_id`

    Address of the base station

    Type: | `canlib.kvrlib.Address`

  `client_address`

    Address of connected client

    Type: | `canlib.kvrlib.Address`

  `connect`

    Whether the service should connect to this device

    Type: | `bool`

  `device_address`

    Address of remote device

    Type: | `canlib.kvrlib.Address`

  `ean`

    EAN of device

    Type: | `canlib.ean.EAN`

  `encryption_key`

    The encryption key to use when encrypting communication

    Note

    This attribute is write-only.

    Type: | `bytes`

  `firmware_version`

    Firmware version

    Type: | `canlib.versionnumber.VersionNumber`

  `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.

  `name`

    User-defined name of device

    Type: | `str`

  `password`

    The accessibility password to use when connecting to a device

    Note

    This attribute is write-only.

    Type: | `str`

  `serial`

    The serial number of the device

    Type: | `int`

  `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 `canlib.kvrlib.ServiceState`, `start_info` is a `canlib.kvrlib.StartInfo`, and `text` is a `str` with local connection status.

    Type: | `canlib.kvrlib.ServiceStatus`

  `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).

  `usage`

    Usage status (Free/Remote/USB/Config)

    Type: | `canlib.kvrlib.DeviceUsage`

## Discovery

class `canlib.kvrlib.``Discovery`(handle)

  A kvrlib “Discovery” process

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

  Even when interacted with directly, instnances of this class are normally not instantiated directly, but created using `canlib.kvrlib.start_discovery`, or sometimes using `canlib.kvrlib.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.

  `addresses`

    The list of addresses to use for discovery

    Note

    This attribute is write-only.

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

    If the `Discovery` object was created by `canlib.kvrlib.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 `canlib.kvrlib.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 `canlib.kvrlib.Address` objects.

## openDiscovery()

`canlib.kvrlib.``openDiscovery`()

  Creates and returns a `canlib.kvrlib.Discovery` object

  Device discovery is normally done using `canlib.kvrlib.discover_info_set`.

## ServiceStatus

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

    Alias for field number 1

  `state`

    Alias for field number 0

  `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 `canlib.kvrlib.Discovery`

  Device discovery is normally done using `canlib.kvrlib.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 `canlib.kvrlib.DeviceInfo` objects in the registry

  See `canlib.kvrlib.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 `canlib.kvrlib.DeviceInfo` objects