.. _xbee-dio:

********************
XBee Digital I/O
********************

.. index:: devices;xbee;digital adapter

Overview
====================
A Dia Driver for the XBee Digital I/O Adapter

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

A typical XBee Digital Adapter configuration block looks like this::

    - name: dio0
      driver: devices.xbee.xbee_devices.xbee_dio:XBeeDIO
      settings:
        xbee_device_manager: <instance name>
        extended_address: <sensor address>
        power: False
        channel1_dir: In
        channel2_dir: Out
        channel3_dir: In
        channel4_dir: Out
        channel2_default: True
        channel4_source: dio0.channel1_value
        enable_low_battery: Off
        
Settings
--------------------
xbee_device_manager (required)
    The name of an XBeeDeviceManager instance to manage this device.

extended_address (required)
    The extended address of the XBee Sensor device you would like to
    monitor.

sleep (optional, default: False)
    True/False setting which determines if the device should sleep
    between samples. 

power (required)
    True/False setting to enable/disable the power output
    on terminal 6 of the adapter.

sleep_time_ms (optional, default: 60000)
    If set for sleep, specifies the length of time that the module
    will sleep after a period of awake_time_ms each cycle.

channel(1-4)_dir (required)
    Operating I/O mode for appropriate pin of the adapter.
                  
    Must be a string value comprised of one of the following:

    ``In``
        Pin is configured to be an input.
    ``Out``
        Pin is configured to be an output.

channel(1-4)_default (optional)
    If channel<x>_dir is configured as an output, this optional setting
    may be specified to set a default value that should be applied on
    the channel when Dia starts/restarts.

    Must be a boolean value comprised of one of the following:

    ``True``
        Pin is configured to output a logical high/True/1.
    ``False``
        Pin is configured to output a logical low/False/0.

    .. note::
        To leave the channel at whatever state it is currently in,
        simply don't configure this setting.

channel(1-4)_source (optional)
    If channel<x>_dir is configured as an output, this option setting
    may be specified to a ``device.channel`` channel name.  The Boolean
    value of this channel will specify to logic state for pin ``x`` on the
    adapter.

    .. note::
        This setting, if set, overrides the channel(1-4)_default setting.

awake_time_ms (optional, default: 5000)
    How many milliseconds the device should remain awake after waking
    from sleep.

sample_predelay (optional, default: 1000)
    How long, in milliseconds, to wait after waking up from sleep
    before taking a sample from the inputs.
    
enable_low_battery (optional, default: Off)
    Force an adapter to enable support for battery-monitor pin. 
    This should be only enabled if the adapter is using internal batteries.    

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

channel(1-4)_input (Get, type: bool, units: bool)
    The value measured by the device.  The units will depend on the
    configuration of the appropriate ``mode`` setting.

low_battery (Get, type: bool)
    Low battery indication condition as reported by the adapter.
    This will be only added if the adapter is using internal batteries. 
    See enable_low_battery setting. 


