Class XBeeBLEDevice

This class represents an XBee Bluetooth Low Energy (BLE) device.

Inheritance
System.Object
AbstractXBeeDevice
XBeeBLEDevice
CellularBLEDevice
DigiMeshBLEDevice
Raw802BLEDevice
ZigBeeBLEDevice
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.Xamarin
Assembly: XBeeLibrary.Xamarin.dll
Syntax
public class XBeeBLEDevice : AbstractXBeeDevice

Constructors

XBeeBLEDevice(IDevice, String)

Class constructor. Instantiates a new XBeeBLEDevice object with the given parameters.

Declaration
public XBeeBLEDevice(IDevice device, string password)
Parameters
Type Name Description
Plugin.BLE.Abstractions.Contracts.IDevice device

Bluetooth device to connect to.
System.String password

Bluetooth password (can be null).
Remarks

The Bluetooth password must be provided before calling the Open() method, either through this constructor or the SetBluetoothPassword(String) method.

See Also
Plugin.BLE.Abstractions.Contracts.IDevice

XBeeBLEDevice(String, String)

Class constructor. Instantiates a new XBeeBLEDevice object with the given parameters.

Declaration
public XBeeBLEDevice(string deviceAddress, string password)
Parameters
Type Name Description
System.String deviceAddress

The address of the Bluetooth device. It must follow the format 00112233AABB or 00:11:22:33:AA:BB.
System.String password

Bluetooth password (can be null).
Remarks

The Bluetooth password must be provided before calling the Open() method, either through this constructor or the SetBluetoothPassword(String) method.

Exceptions
Type Condition
System.ArgumentException

If deviceAddress does not follow the format 00112233AABB or 00:11:22:33:AA:BB.

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

Indicates whether this XBee device is a remote device.

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

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

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 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

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.

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

SendSerialData(Byte[])

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

Declaration
public void SendSerialData(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 serial data.
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

SetBluetoothPassword(String)

Sets the password of this Bluetooth device in order to connect to it.

Declaration
public void SetBluetoothPassword(string password)
Parameters
Type Name Description
System.String password

The password of this Bluetooth device.
Remarks

The Bluetooth password must be provided before calling the Open() method.

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

ToString()

Returns the string representation of this device.

Declaration
public override string ToString()
Returns
Type Description
System.String

The string representation of this device.
Overrides

Events

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

PacketReceived

Represents the method that will handle the Data received event.

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

If the event handler is null.
See Also

SerialDataReceived

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

Declaration
public event EventHandler<SerialDataReceivedEventArgs> SerialDataReceived
Event Type
Type Description
System.EventHandler<SerialDataReceivedEventArgs>
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