.. _xbee-autoenum:

****************************
XBee Device Auto-Enumeration
****************************

.. index:: devices;xbee;auto-enumeration

Overview
====================

The auto-enumeration driver allows the creation of systems where the
specific pre-configured MAC address of XBee nodes that will be
populated for a solution is not known at the time of configuration,
but the profile of device types or names that should be found is
known.  

Devices found will have instances created in the channel database
according to the following naming scheme:

* If the ``NI`` value is set on the device, that value will be the instance name.
* Otherwise, the instance name will be ``name + _ + extended_address``.

For example, the following configuration block may result in an
instance name like ``auto_aio_00:13:a2:00:40:32:15:87!``.

.. note:: Only device drivers which properly sub-class from the
          :class:`~devices.xbee.xbee_devices.xbee_base.XBeeBase`
          object will work with the auto-enumeration driver currently.

Configuration
====================

A typical autoenumeration configuration block looks like this::

  - name: xbee_autoenum
    driver: devices.xbee.xbee_devices.xbee_autoenum:XBeeAutoEnum
    settings:
        xbee_device_manager: xbee_device_manager
        extended_address: ""
        discover_rate: 600  
        devices:
            - name: auto_aio
              driver: devices.xbee.xbee_devices.xbee_aio:XBeeAIO 
              settings:
                  xbee_device_manager: xbee_device_manager
                  extended_address: ""
                  sample_rate_ms: 900000
                  power: On
                  sleep: True
                  channel1_mode: CurrentLoop
                  channel2_mode: CurrentLoop
                  channel3_mode: CurrentLoop
                  channel4_mode: CurrentLoop

Settings
--------------------

xbee_device_manager (required)
    The :ref:`xbee-device-manager` instance that will be used to
    manage devices that do not specify one of their
    own in their ``devices`` entry below.

discover_rate (required)
    How often the auto-enumeration driver will check for new devices
    having associated to the PAN.

devices (required)
    A list of device setting blocks similar to those that would be
    configured for a device at the top level ``devices`` section of
    the configuration file.  

    If the setting block omits ``xbee_device_manager`` the value
    configured for the auto-enumeration driver will be used.  The
    block should omit or set to ``""`` the ``extended_address``
    parameter of the block.  This is required for XBee devices but
    will be provided at enumeration time.

short_names (optional, defaults to False)
    Shortens the discovered device names, when NI is not used,
    to only include the last two octets of the XBee MAC Address.
    User must confirm uniqueness of these 2 octets.
    Example: 'aio_[00:13:a2:00:40:52:e0:fc]!'
    becomes 'aio_E0_FC'


Channels
====================

This driver publishes no channels of its own.
