.. _xbee-serial-loopback:

********************
XBee Serial Loopback
********************

.. index:: devices; xbee; XBee Serial Loopback

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

XBee Serial Loopback is meant to be an example driver that shows how to
use the `xbee_serial` driver.  It requires a connection to the loopback plug on
the device.

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

A typical XBee Serial Loopback configuration block looks like this::

    - name: serial_loopback
      driver: devices.xbee.xbee_devices.xbee_serial_loopback:XBeeLoopBack
      settings:
          xbee_device_manager: <instance name>
          extended_address: <XBee module address>
          baudrate: 9600
          parity: none
          stopbits: 1
          hardwareflowcontrol: False
          loop_rate_sec: 5
          packet_size: 5
          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.

baudrate (optional, default: 9600)
    Acceptable integer baud rates are from 8 through 921600. If not set,
    the default value of 9600 will be used.

parity (optional, default: none)
    Acceptable parity values are the following
    strings:

    * none
    * even
    * odd
    * mark

stopbits (optional, default: 1)
    Acceptable stopbit values are:

    * 1
    * 2

    .. Note::
        Some XBee/ZigBee Serial firmware do not support setting the stop bit 
        value. In these cases, the stop bit will always be 1.

hardwareflowcontrol (optional, default: False)
    Acceptable hardware flow control values are:

    * **True:** Will set RTS/CTS flow control.
    * **False:** Will turn OFF RTS/CTS flow control.

loop_rate_sec (optional, default: 5)
    How often the program should loopback data.

packet_size (optional, default: 5)
    Tells the test program how much data should go into each
    of the loopback packets.

enable_low_battery (optional, default: Off)
    Force an adapter to enable support for the battery-monitor pin. It should 
    only be enabled if the adapter is using internal batteries. Acceptable 
    enable_low_battery values are:

    * **On:** Will turn ON low battery support.
    * **Off:** Will turn OFF low battery support.

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

attempts (Get, type: integer)
    How many times the program has sent loopback data.

total_bytes_sent (Get, type: integer)
    How many bytes the program has sent (attempts * packet_size).

total_bytes_received (Get, type: integer)
    How many bytes the program has received.  (Generally should
    equal total_bytes_sent, unless data was lost.)

passes (Get, type: integer)
    The number of times the program received a packet with the expected data.
    (Received data should be the same as the Sent data.)

fails (Get, type: integer)
    The number of times the program did NOT receive a packet with the expected data.

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.
