Class XBeeDevice

This class represents a local XBee device.

Inheritance
System.Object
AbstractXBeeDevice
XBeeDevice
DigiMeshDevice
DigiPointDevice
Raw802Device
ZigBeeDevice
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
Namespace: XBeeLibrary.Core
Assembly: XBeeLibrary.Core.dll
Syntax
public class XBeeDevice : AbstractXBeeDevice

Constructors

XBeeDevice(IConnectionInterface)

Class constructor. Instantiates a new XBeeDevice object with the given connection interface.

Declaration
protected XBeeDevice(IConnectionInterface connectionInterface)
Parameters
Type Name Description
IConnectionInterface connectionInterface

The connection interface with the physical XBee device.
Exceptions
Type Condition
System.ArgumentNullException

If connectionInterface == null.
See Also

Properties

IsOpen

The status of the connection interface associated to this device. It indicates if the connection is open or not.

Declaration
public bool IsOpen { get; }
Property Value
Type Description
System.Boolean
See Also

IsRemote

Always false, since this is always a local device.

Declaration
public override bool IsRemote { get; }
Property Value
Type Description
System.Boolean
Overrides

OperatingMode

The Operating mode (AT, API or API escaped) of this XBee device for a local device, and the operating mode of the local device used as communication interface for a remote device.

Declaration
public OperatingMode OperatingMode { get; }
Property Value
Type Description
OperatingMode
See Also

ReceiveTimeout

The XBee device timeout in milliseconds for received packets in synchronous operations.

Declaration
public int ReceiveTimeout { get; set; }
Property Value
Type Description
System.Int32
Exceptions
Type Condition
System.ArgumentException

If the value to be set is lesser than 0.

Methods

Close()

Closes the connection interface associated with this XBee device.

Declaration
public void Close()
See Also

GetDestinationAddress()

Returns the 64-bit destination extended address of this XBee device.

Declaration
public XBee64BitAddress GetDestinationAddress()
Returns
Type Description
XBee64BitAddress

64-bit destination address.
Remarks

BROADCAST_ADDRESS is the broadcast address for the PAN. COORDINATOR_ADDRESS can be used to address the Pan Coordinator.

Exceptions
Type Condition
ATCommandEmptyException

If DH or DL values are empty.
InterfaceNotOpenException

If this device connection is not open.
TimeoutException

If there is a timeout reading the destination address.
XBeeException

If there is any other XBee related error.
See Also

GetDIOChangeDetection()

Returns the set of IO lines of this device that are monitored for change detection.

Declaration
public ISet<IOLine> GetDIOChangeDetection()
Returns
Type Description
System.Collections.Generic.ISet<IOLine>

Set of digital IO lines that are monitored for change detection, null if there are no monitored lines.
Remarks

A null set means the DIO change detection feature is disabled.

Modules can be configured to transmit to the configured destination address a data sample immediately whenever a monitored digital IO line changes state.

Exceptions
Type Condition
ATCommandEmptyException

If IC value is empty.
InterfaceNotOpenException

If this device connection is not open.
TimeoutException

If there is a timeout reading the IO change detect command.
XBeeException

If there is any other XBee related error.
See Also

GetIOSamplingRate()

Returns the IO sampling rate of this XBee device.

Declaration
public int GetIOSamplingRate()
Returns
Type Description
System.Int32

IO sampling rate in milliseconds.
Remarks

A sample rate of 0 ms. means the IO sampling feature is disabled.

Periodic sampling allows this XBee module to take an IO sample and transmit it to a remote device (configured in the destination address) at the configured periodic rate (ms).

Exceptions
Type Condition
ATCommandEmptyException

If IR value is empty.
InterfaceNotOpenException

If this device connection is not open.
TimeoutException

If there is a timeout reading the IO sampling rate command.
XBeeException

If there is any other XBee related error.
See Also

GetNetwork()

Returns the network associated with this XBee device.

Declaration
public virtual XBeeNetwork GetNetwork()
Returns
Type Description
XBeeNetwork

The XBee network of the device.
Exceptions
Type Condition
InterfaceNotOpenException

If this device connection is not open.
See Also

GetNextFrameID()

Gets the next Frame ID of this XBee device.

Declaration
public byte GetNextFrameID()
Returns
Type Description
System.Byte

The next Frame ID.

GetPANID()

Returns the operating PAN ID (Personal Area Network Identifier) of this XBee device.

Declaration
public byte[] GetPANID()
Returns
Type Description
System.Byte[]

The operating PAN ID of this XBee device.
Remarks

For modules to communicate they must be configured with the same identifier. Only modules with matching IDs can communicate with each other. This parameter allows multiple networks to co-exist on the same physical channel.

Exceptions
Type Condition
ATCommandEmptyException

If the ID command returns a null or an empty value.
InterfaceNotOpenException

If this device connection is not open.
TimeoutException

If there is a timeout reading the operating PAN ID.
XBeeException

If there is any other XBee related error.
See Also

GetPowerLevel()

Returns the output power level at which this XBee device transmits conducted power.

Declaration
public PowerLevel GetPowerLevel()
Returns
Type Description
PowerLevel

The output power level of this XBee device.
Exceptions
Type Condition
ATCommandEmptyException

If the PL command returns a null or an empty value.
InterfaceNotOpenException

If this device connection is not open.
TimeoutException

If there is a timeout reading the power level command.
XBeeException

If there is any other XBee related error.
See Also

Open()

Opens the connection interface associated with this XBee device.

Declaration
public virtual void Open()
Remarks

When opening the device an information reading process is automatically performed. This includes:

Exceptions
Type Condition
InterfaceAlreadyOpenException

If this device connection is already open.
InvalidOperatingModeException

If the operating mode of the device is UNKNOWN or AT
BluetoothAuthenticationException

If the BLE authentication process fails.
TimeoutException

If the timeout to read settings when initializing the device elapses without response.
XBeeException

If there is any problem opening this device connection.
See Also

ReadData()

Reads new data received by this XBee device during the configured received timeout.

Declaration
public XBeeMessage ReadData()
Returns
Type Description
XBeeMessage

An XBeeMessage object containing the data and the source address of the remote node that sent the data. null if this did not receive new data during the configured receive timeout.
Remarks

This method blocks until new data is received or the configured receive timeout expires.

The receive timeout can be consulted/configured using the ReceiveTimeout property.

Exceptions
Type Condition
InterfaceNotOpenException

If this device connection is not open.
See Also

ReadData(Int32)

Reads new data received by this XBee device during the provided timeout.

Declaration
public XBeeMessage ReadData(int timeout)
Parameters
Type Name Description
System.Int32 timeout

The time to wait for new data in milliseconds.
Returns
Type Description
XBeeMessage

An XBeeMessage object containing the data and the source ddress of the remote node that sent the data. null if this did not receive new data during timeout milliseconds.
Remarks

This method blocks until new data is received or the provided timeout expires.

Exceptions
Type Condition
System.ArgumentException

If timeout < 0.
InterfaceNotOpenException

If this device connection is not open.
See Also

ReadDataFrom(RemoteXBeeDevice)

Reads new data received from the given remote XBee device during the configured received timeout.

Declaration
public XBeeMessage ReadDataFrom(RemoteXBeeDevice remoteXBeeDevice)
Parameters
Type Name Description
RemoteXBeeDevice remoteXBeeDevice

The remote device to read data from.
Returns
Type Description
XBeeMessage

An XBeeMessage object containing the data and the source address of the remote node that sent the data. null if this did not receive new data during the configured timeout.
Remarks

This method blocks until new data is received or the provided timeout expires.

The receive timeout can be consulted/configured using the ReceiveTimeout property.

Exceptions
Type Condition
System.ArgumentNullException

If remoteXBeeDevice is null.
InterfaceNotOpenException

If this device connection is not open.
See Also

ReadDataFrom(RemoteXBeeDevice, Int32)

Reads new data received from the given remote XBee device during the provided timeout.

Declaration
public XBeeMessage ReadDataFrom(RemoteXBeeDevice remoteXBeeDevice, int timeout)
Parameters
Type Name Description
RemoteXBeeDevice remoteXBeeDevice

The remote device to read data from.
System.Int32 timeout

The time to wait for new data in milliseconds.
Returns
Type Description
XBeeMessage

An XBeeMessage object containing the data and the source address of the remote node that sent the data. null if this did not receive new data during timeout milliseconds.
Remarks

This method blocks until new data from the provided remote XBee device is received or the given timeout expires.

Exceptions
Type Condition
System.ArgumentException

If timeout < 0.
System.ArgumentNullException

If remoteXBeeDevice is null.
InterfaceNotOpenException

If this device connection is not open.
See Also

ReadUserDataRelay()

Reads a new User Data Relay packet received by this XBee device during the configured receive timeout.

Declaration
public UserDataRelayMessage ReadUserDataRelay()
Returns
Type Description
UserDataRelayMessage

A UserDataRelayMessage object containing the source interface and data. null if this device did not receive new User Data Relay during the configured receive timeout.
Remarks

This method blocks until new User Data Relay is received or the configured receive timeout expires.

Exceptions
Type Condition
InterfaceNotOpenException

If the interface is not open.
See Also

ReadUserDataRelay(Int32)

Reads a new User Data Relay packet received by this XBee device during the provided timeout.

Declaration
public UserDataRelayMessage ReadUserDataRelay(int timeout)
Parameters
Type Name Description
System.Int32 timeout

The time to wait for new User Data Relay in milliseconds.
Returns
Type Description
UserDataRelayMessage

A UserDataRelayMessage object containing the source interface and data. null if this device did not receive new User Data Relay during timeout milliseconds.
Remarks

This method blocks until new User Data Relay is received or the given timeout expires.

Exceptions
Type Condition
InterfaceNotOpenException

If the interface is not open.
See Also

Reset()

Performs a software reset on this XBee device and blocks until the process is completed.

Declaration
public override void Reset()
Overrides
Exceptions
Type Condition
InterfaceNotOpenException

If this device connection is not open.
TimeoutException

If there is a timeout resetting the device.
XBeeException

If there is any other XBee related error.

SendBluetoothData(Byte[])

Sends the given data to the XBee Bluetooth interface in a User Data Relay frame.

Declaration
public void SendBluetoothData(byte[] data)
Parameters
Type Name Description
System.Byte[] data

Data to send.
Exceptions
Type Condition
XBeeException

If there is any XBee related error sending the Bluetooth data.
See Also

SendBroadcastData(Byte[])

Sends the provided data to all the XBee nodes of the network (broadcast).

Declaration
public virtual void SendBroadcastData(byte[] data)
Parameters
Type Name Description
System.Byte[] data

Byte array containing the data to be sent.
Remarks

This method blocks till a success or error transmit status arrives or the configured receive timeout expires.

The receive timeout can be consulted/configured using the ReceiveTimeout property.

Exceptions
Type Condition
System.ArgumentNullException

If data == null.
InterfaceNotOpenException

If this device connection is not open.
OperationNotSupportedException

If the sender device is remote.
TimeoutException

If there is a timeout sending the data.
TransmitException

If the transmit status generated when sending the packet is not an instance of TransmitStatusPacket or if it is not an instance of TXStatusPacket or if when it is correct, its status is different from SUCCESS.
XBeeException

If there is any other XBee related error.
See Also

SendData(RemoteXBeeDevice, Byte[])

Sends the provided data to the given XBee device choosing the optimal send method depending on the protocol of the local XBee device.

Declaration
public virtual void SendData(RemoteXBeeDevice xbeeDevice, byte[] data)
Parameters
Type Name Description
RemoteXBeeDevice xbeeDevice

The XBee device of the network that will receive the data.
System.Byte[] data

Byte array containing the data to be sent.
Remarks

This method blocks till a success or error response arrives or the configured receive timeout expires.

The receive timeout can be consulted/configured using the ReceiveTimeout property.

For non-blocking operations use the method SendData(RemoteXBeeDevice, Byte[]).

Exceptions
Type Condition
System.ArgumentNullException

If xbeeDevice == null or if data == null.
InterfaceNotOpenException

If this device connection is not open.
OperationNotSupportedException

If the sender device is remote.
TimeoutException

If there is a timeout sending the data.
TransmitException

If the transmit status generated when sending the packet is not an instance of TransmitStatusPacket or if it is not an instance of TXStatusPacket or if when it is correct, its status is different from SUCCESS.
XBeeException

If there is any other XBee related error.
See Also

SendDataAsync(RemoteXBeeDevice, Byte[])

Sends the provided data to the provided XBee device asynchronously.

Declaration
public virtual void SendDataAsync(RemoteXBeeDevice xbeeDevice, byte[] data)
Parameters
Type Name Description
RemoteXBeeDevice xbeeDevice

The XBee device of the network that will receive the data.
System.Byte[] data

Byte array containing the data to be sent.
Remarks

Asynchronous transmissions do not wait for answer from the remote device or for transmit status packet.

Exceptions
Type Condition
InterfaceNotOpenException

If this device connection is not open.
System.ArgumentNullException

If xbeeDevice == null or if data == null.
InterfaceNotOpenException

If this device connection is not open.
OperationNotSupportedException

If the sender device is remote.
XBeeException

If a remote device is trying to send data or if there is any other XBee related error.
See Also

SendMicroPythonData(Byte[])

Sends the given data to the XBee MicroPython interface in a User Data Relay frame.

Declaration
public void SendMicroPythonData(byte[] data)
Parameters
Type Name Description
System.Byte[] data

Data to send.
Exceptions
Type Condition
XBeeException

If there is any XBee related error sending the MicroPython data.
See Also

SendPacket(XBeePacket)

Sends the given XBee packet synchronously and blocks until the response is received or the configured receive timeout expires.

Declaration
public XBeePacket SendPacket(XBeePacket packet)
Parameters
Type Name Description
XBeePacket packet

The XBee packet to be sent.
Returns
Type Description
XBeePacket

An XBeePacket object containing the response of the sent packet or null if there is no response.
Remarks

The receive timeout is consulted/configured using the ReceiveTimeoutproperty.

Use SendPacketAsync(XBeePacket) or SendPacket(XBeePacket, EventHandler<PacketReceivedEventArgs>) for non-blocking operations.

Exceptions
Type Condition
System.ArgumentNullException

If packet == null.
InterfaceNotOpenException

If this device connection is not open.
InvalidOperatingModeException

If the operating mode is different from API and API_ESCAPE.
TimeoutException

If the configured time expires while waiting for the packet reply.
XBeeException

If there is any other XBee related error.
See Also

SendPacket(XBeePacket, EventHandler<PacketReceivedEventArgs>)

Sends the given XBee packet and registers the given packet handler (if not null) to manage what happens when the answers is received.

Declaration
public void SendPacket(XBeePacket packet, EventHandler<PacketReceivedEventArgs> handler)
Parameters
Type Name Description
XBeePacket packet

XBee packet to be sent.
System.EventHandler<PacketReceivedEventArgs> handler

Event handler for the operation, null not to be notified when the answer arrives.
Remarks

This is a non-blocking operation. To wait for the answer use SendPacket(XBeePacket).

Exceptions
Type Condition
System.ArgumentNullException

If packet == null.
InterfaceNotOpenException

If this device connection is not open.
InvalidOperatingModeException

If the operating mode is different from API and API_ESCAPE.
XBeeException

If there is any other XBee related error.
See Also

SendPacketAsync(XBeePacket)

Sends the given XBee packet asynchronously.

Declaration
public void SendPacketAsync(XBeePacket packet)
Parameters
Type Name Description
XBeePacket packet

The XBee packet to be sent asynchronously.
Remarks

To be notified when the answer is received, use the PacketReceived event handler.

Exceptions
Type Condition
System.ArgumentNullException

If packet == null.
InterfaceNotOpenException

If this device connection is not open.
InvalidOperatingModeException

If the operating mode is different from API and API_ESCAPE.
XBeeException

If there is any other XBee related error.
See Also

SendUserDataRelay(XBeeLocalInterface, Byte[])

Sends the provided data to the given XBee local interface.

Declaration
public void SendUserDataRelay(XBeeLocalInterface destinationInterface, byte[] data)
Parameters
Type Name Description
XBeeLocalInterface destinationInterface

Destination XBee local interface.
System.Byte[] data

Data to send.
Exceptions
Type Condition
System.ArgumentException

If the destination interface is unknown.
XBeeException

If there is any XBee related error sending the User Data Relay.
See Also

SetDestinationAddress(XBee64BitAddress)

Sets the 64-bit destination extended address of this XBee device.

Declaration
public void SetDestinationAddress(XBee64BitAddress xbee64BitAddress)
Parameters
Type Name Description
XBee64BitAddress xbee64BitAddress

64-bit destination address to be configured.
Remarks

BROADCAST_ADDRESS is the broadcast address for the PAN. COORDINATOR_ADDRESS can be used to address the Pan Coordinator.

Exceptions
Type Condition
System.ArgumentNullException

If xbee64BitAddress is null.
InterfaceNotOpenException

If this device connection is not open.
TimeoutException

If there is a timeout setting the destination address.
XBeeException

If there is any other XBee related error.
See Also

SetDIOChangeDetection(ISet<IOLine>)

Sets the digital IO lines of this XBee device to be monitored and sampled whenever their status changes.

Declaration
public void SetDIOChangeDetection(ISet<IOLine> lines)
Parameters
Type Name Description
System.Collections.Generic.ISet<IOLine> lines

Set of IO lines to be monitored, null to disable this feature.
Remarks

A null set of lines disables this feature.

If a change is detected on an enabled digital IO pin, a digital IO sample is immediately transmitted to the configured destination address.

The destination address can be configured using the SetDestinationAddress(XBee64BitAddress) method and retrieved by GetDestinationAddress().

Exceptions
Type Condition
InterfaceNotOpenException

If this device connection is not open.
TimeoutException

If there is a timeout sending the set IO change detect command.
XBeeException

If there is any other XBee related error.
See Also

SetIOSamplingRate(Int32)

Sets the IO sampling rate to enable periodic sampling in this XBee device.

Declaration
public void SetIOSamplingRate(int rate)
Parameters
Type Name Description
System.Int32 rate

IO sampling rate in milliseconds.
Remarks

A sample rate of 0 ms. disables this feature.

All enabled digital IO and analog inputs will be sampled and transmitted every rate milliseconds to the configured destination address.

Exceptions
Type Condition
System.ArgumentException

If rate < 0 or if rate > 0xFFFF.
InterfaceNotOpenException

If this device connection is not open.
TimeoutException

If there is a timeout sending the set IO sampling rate command.
XBeeException

If there is any other XBee related error.
See Also

SetPANID(Byte[])

Sets the PAN ID (Personal Area Network Identifier) of this XBee device.

Declaration
public void SetPANID(byte[] panID)
Parameters
Type Name Description
System.Byte[] panID

The new PAN ID of this XBee device.
Remarks

For modules to communicate they must be configured with the same identifier. Only modules with matching IDs can communicate with each other. This parameter allows multiple networks to co-exist on the same physical channel.

Exceptions
Type Condition
System.ArgumentException

If the length of panID is 0 or if panID > 8.
System.ArgumentNullException

If panID == null.
InterfaceNotOpenException

If this device connection is not open.
TimeoutException

If there is a timeout setting the operating PAN ID.
XBeeException

If there is any other XBee related error.
See Also

SetPowerLevel(PowerLevel)

Sets the output power level at which this XBee device transmits conducted power.

Declaration
public void SetPowerLevel(PowerLevel powerLevel)
Parameters
Type Name Description
PowerLevel powerLevel

The new output power level to be set in this XBee device.
Exceptions
Type Condition
System.ArgumentException

If powerLevel is LEVEL_UNKNOWN.
InterfaceNotOpenException

If this device connection is not open.
TimeoutException

If there is a timeout setting the power level command.
XBeeException

If there is any other XBee related error.
See Also

Events

BluetoothDataReceived

Represents the method that will handle the Bluetooth data received event.

Declaration
public event EventHandler<BluetoothDataReceivedEventArgs> BluetoothDataReceived
Event Type
Type Description
System.EventHandler<BluetoothDataReceivedEventArgs>
Exceptions
Type Condition
System.ArgumentNullException

If the event handler is null.
See Also

DataReceived

Represents the method that will handle the Data received event.

Declaration
public virtual event EventHandler<DataReceivedEventArgs> DataReceived
Event Type
Type Description
System.EventHandler<DataReceivedEventArgs>
Exceptions
Type Condition
System.ArgumentNullException

If the event handler is null.
See Also

IOSampleReceived

Represents the method that will handle the IO Sample received event.

Declaration
public virtual event EventHandler<IOSampleReceivedEventArgs> IOSampleReceived
Event Type
Type Description
System.EventHandler<IOSampleReceivedEventArgs>
Exceptions
Type Condition
System.ArgumentNullException

If the event handler is null.
See Also

MicroPythonDataReceived

Represents the method that will handle the MicroPython data received event.

Declaration
public event EventHandler<MicroPythonDataReceivedEventArgs> MicroPythonDataReceived
Event Type
Type Description
System.EventHandler<MicroPythonDataReceivedEventArgs>
Exceptions
Type Condition
System.ArgumentNullException

If the event handler is null.
See Also

ModemStatusReceived

Represents the method that will handle the Modem status received event.

Declaration
public event EventHandler<ModemStatusReceivedEventArgs> ModemStatusReceived
Event Type
Type Description
System.EventHandler<ModemStatusReceivedEventArgs>
Exceptions
Type Condition
System.ArgumentNullException

If the event handler is null.
See Also

PacketReceived

Represents the method that will handle the Data received event.

Declaration
public virtual event EventHandler<PacketReceivedEventArgs> PacketReceived
Event Type
Type Description
System.EventHandler<PacketReceivedEventArgs>
Exceptions
Type Condition
System.ArgumentNullException

If the event handler is null.
See Also

UserDataRelayReceived

Represents the method that will handle the User Data Relay received event.

Declaration
public event EventHandler<UserDataRelayReceivedEventArgs> UserDataRelayReceived
Event Type
Type Description
System.EventHandler<UserDataRelayReceivedEventArgs>
Exceptions
Type Condition
System.ArgumentNullException

If the event handler is null.
See Also

See Also