****************************
Rabbit XBee Named Attributes
****************************

.. index:: devices; rabbit; Rabbit XBee Named Attributes

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

This Dia device lets clients get and (for read/write attributes) set the
remote rabbit attributes by name. Requests are sent as plain text, using
the following format:

Requests (sent to the Rabbit):

* ``name?`` Requests the value of attribute <name>.
* ``name`` Requests the value of attribute <name> (? operator is implied).
* ``name=value`` Sets attribute <name> to <value>.

In requests, name can end with an asterisk (*) as a wildcard to match
any remaining characters.  For example, "led*?" will match "led1", "led2",
"led3" and "led4" (and therefore generate 4 responses). Wildcards work
for setting values as well (e.g., dout*=1 to set all digital outputs to 1).

.. Note::
    Due to limits of the frame buffering between the BL4S100 and its XBee
    module, some responses may be dropped if too many attributes are
    requested at once (i.e., via the autorefresh web page).

Responses (from the Rabbit):

* ``name!`` Error response, no attribute called <name>.
* ``name!value`` Error response, unable to set <name> to <value>.
* ``name:value`` Successful response, attribute <name> is set to 
  <value>. Sent in response to query (?) or assign (=) operators.

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

A typical Rabbit XBee Named Attributes configuration block looks like this::

    - name: rabbit_string0
      driver: devices.rabbit.xbee_named_attributes:XBeeNamedAttributes
      settings:
          xbee_device_manager: <instance name>
          extended_address: <XBee module address>
          endpoint: 2
          profile: 42
          cluster: 7
          poll_rate: 2.0
          attributes:
              led1: [str, settable, "off"]
              led2: [str, settable, "on"]
              led3: [str, settable, "off"]
              led4: [str, settable, "on"]

              sw1: [str, gettable]
              sw2: [str, gettable]
              sw3: [str, gettable]
              sw4: [str, gettable]

              ain0: [float, gettable]
              ain1: [float, gettable]

              uptime: [int, gettable]

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

xbee_device_manager (required)
    Name of the XBee_device_manager device declared in the devices
    section. This setting is necessary because this device will configure all
    the XBee devices.

extended_address (required)
    MAC address of the BL4S100's XBee module.

    Notice that the value must have an exclamation sign at end and
    is between quotes.

local (optional, default: local)
    Name for the local channel.

remote (optional, default: remote)
    Name for the remote channel.

endpoint (required)
    Endpoint of local and remote device.

profile (required)
    Profile of local and remote device.

cluster (required)
    Cluster of local and remote device.

poll_rate (optional)
    How often (in seconds) the driver should poll the target.

attributes (optional)
    Each attribute name becomes a Dia channel. The list of options to
    declare an attribute (in order) is:

    * **type** (required) Choose from:

      * str
      * int
      * float

    * **settable/gettable** (required) If initial value set,
      otherwise defaults to gettable.
    * **initial value of type** (optional) defaults to:

      * **""** If attribute type is string.
      * **0** If attribute type is int.
      * **0.0** If attribute type is float.

    * The '*' attribute requests that the values of all attributes
      be sent.

        ``*: [str, gettable, "Refresh all"]``

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

A channel for each configured attribute will be generated. The access 
(get/set), type and initial value have been configured with the 
attribute declaration.


