Class IPDevice

This class provides common functionality for XBee IP devices.

Inheritance
System.Object
AbstractXBeeDevice
IPDevice
CellularDevice
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 IPDevice : AbstractXBeeDevice

Constructors

IPDevice(IConnectionInterface)

Class constructor. Instantiates a new IPDevice object in the given connection interface.

Declaration
public IPDevice(IConnectionInterface connectionInterface)
Parameters
Type Name Description
IConnectionInterface connectionInterface

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

If connectionInterface == null.
See Also

Fields

DEFAULT_PROTOCOL

Declaration
protected const IPProtocol DEFAULT_PROTOCOL = IPProtocol.TCP
Field Value
Type Description
IPProtocol

DEFAULT_SOURCE_PORT

Declaration
protected const short DEFAULT_SOURCE_PORT = 9750
Field Value
Type Description
System.Int16

ipAddress

Declaration
protected IPAddress ipAddress
Field Value
Type Description
System.Net.IPAddress

sourcePort

Declaration
protected int sourcePort
Field Value
Type Description
System.Int32

Properties

IPAddress

The IP address of this IP device.

Declaration
public IPAddress IPAddress { get; }
Property Value
Type Description
System.Net.IPAddress

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.

XBee16BitAddr

The 16-bit address of this XBee device. IP devices don't have a 16-bit address, so this property returns null.

Declaration
public override XBee16BitAddress XBee16BitAddr { get; }
Property Value
Type Description
XBee16BitAddress
Overrides
Remarks

To refresh this value, use the ReadDeviceInfo() method.

See Also

Methods

Close()

Closes the connection interface associated with this XBee device.

Declaration
public void Close()
See Also

GetDestinationIPAddress()

Gets the destination IP address.

Declaration
public IPAddress GetDestinationIPAddress()
Returns
Type Description
System.Net.IPAddress

The destination IP address.
Exceptions
Type Condition
InterfaceNotOpenException

If this device connection is not open.
TimeoutException

If there is a timeout sending the given command.
XBeeException

If there is any other XBee related error.
See Also
System.Net.IPAddress

GetNextFrameID()

Gets the next Frame ID of this XBee device.

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

The next Frame ID.

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

ReadDeviceInfo()

Reads some parameters from this device and obtains its protocol.

Declaration
public override void ReadDeviceInfo()
Overrides
Remarks

This method refresh the values of:

  • 64-bit address only if it is not initialized.
  • Node Identifier.
  • Hardware version if it is not initialized.
  • Firmware version.
  • XBee device protocol.
  • IP address.
Exceptions
Type Condition
InterfaceNotOpenException

If this device connection is not open.
TimeoutException

If there is a timeout reading the parameters.
XBeeException

If there is any other XBee related error.
See Also
System.Net.IPAddress

ReadIPData()

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

Declaration
public IPMessage ReadIPData()
Returns
Type Description
IPMessage

An IPMessage object containing the IP data and the IP address that sent the data. null if this did not receive new IP data during the configured receive timeout.
Remarks

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

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

Before reading IP data you need to start listening for incoming IP data at a specific port. Use the StartListening(Int32) method for that purpose. When finished, you can use the StopListening() method to stop listening for incoming IP data.

Exceptions
Type Condition
InterfaceNotOpenException

If this device connection is not open.
See Also
XBeeLibrary.Core.IPDevice.ReadIPDataPacket(System.Net.IPAddress,System.Int32)

ReadIPData(Int32)

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

Declaration
public IPMessage ReadIPData(int timeout)
Parameters
Type Name Description
System.Int32 timeout

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

A IPMessage object containing the IP data and the IP address that sent the data. null if this did not receive new IP data during timeout milliseconds.
Remarks

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

Exceptions
Type Condition
System.ArgumentException

If timeout < 0.
InterfaceNotOpenException

If this device connection is not open.
See Also

ReadIPDataFrom(IPAddress)

Reads new IP data received from the given IP address during the configured receive timeout.

Declaration
public IPMessage ReadIPDataFrom(IPAddress ipAddress)
Parameters
Type Name Description
System.Net.IPAddress ipAddress

The IP address to read data from.
Returns
Type Description
IPMessage

A IPMessage object containing the IP data and the IP address that sent the data. null if this did not receive new IP data during the configured receive timeout.
Remarks

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

Exceptions
Type Condition
System.ArgumentNullException

If ipAddress == null.
InterfaceNotOpenException

If this device connection is not open.
See Also
System.Net.IPAddress

ReadIPDataFrom(IPAddress, Int32)

Reads new IP data received from the given IP address during the provided timeout.

Declaration
public IPMessage ReadIPDataFrom(IPAddress ipAddress, int timeout)
Parameters
Type Name Description
System.Net.IPAddress ipAddress

The IP address to read data from.
System.Int32 timeout

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

A IPMessage object containing the IP data and the IP address that sent the data. null if this did not receive new IP data during timeout milliseconds.
Remarks

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

Exceptions
Type Condition
System.ArgumentException

If timeout < 0.
System.ArgumentNullException

If ipAddress == null.
InterfaceNotOpenException

If this device connection is not open.
See Also
System.Net.IPAddress

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

SendBroadcastIPData(Int32, Byte[])

Sends the provided IP data to all clients.

Declaration
public void SendBroadcastIPData(int destPort, byte[] data)
Parameters
Type Name Description
System.Int32 destPort

The destination port of the transmission.
System.Byte[] data

Byte array containing the IP 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.

Exceptions
Type Condition
System.ArgumentException

If destPort < 0 or if destPort > 65535.
System.ArgumentNullException

If data == null.
InterfaceNotOpenException

If this device connection is not open.
System.InvalidOperationException

If the device is remote.
TransmitException

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

If there is any other XBee related error.
See Also
System.Net.IPAddress

SendIPData(IPAddress, Int32, IPProtocol, Boolean, Byte[])

Sends the provided IP data to the given IP address and port using the specified IP protocol. For TCP and TCP SSL protocols, you can also indicate if the socket should be closed when data is sent.

Declaration
public void SendIPData(IPAddress ipAddress, int destPort, IPProtocol protocol, bool closeSocket, byte[] data)
Parameters
Type Name Description
System.Net.IPAddress ipAddress

The IP address to send IP data to.
System.Int32 destPort

The destination port of the transmission.
IPProtocol protocol

The IP protocol used for the transmission.
System.Boolean closeSocket

true to close the socket just after the transmission. false to keep it open.
System.Byte[] data

Byte array containing the IP 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 SendIPDataAsync(IPAddress, Int32, IPProtocol, Boolean, Byte[]).

Exceptions
Type Condition
System.ArgumentException

If destPort < 0 or if destPort > 65535 or if protocol == UNKNOWN.
System.ArgumentNullException

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

If this device connection is not open.
System.InvalidOperationException

If the device is remote.
TimeoutException

If there is a timeout sending the given packet synchronously.
TransmitException

If the transmit status generated when sendting the data is not an instance of TransmitStatusPacket or if its transmit status is different from SUCCESS.
XBeeException

If there is any other XBee related error.
See Also
XBeeLibrary.Core.IPDevice.SendIPDataImpl(System.Net.IPAddress,System.Int32,XBeeLibrary.Core.Models.IPProtocol,System.Boolean,System.Byte[])
System.Net.IPAddress

SendIPData(IPAddress, Int32, IPProtocol, Byte[])

Sends the provided IP data to the given IP address and port using the specified IP protocol.

Declaration
public void SendIPData(IPAddress ipAddress, int destPort, IPProtocol protocol, byte[] data)
Parameters
Type Name Description
System.Net.IPAddress ipAddress

The IP address to send IP data to.
System.Int32 destPort

The destination port of the transmission.
IPProtocol protocol

The IP protocol used for the transmission.
System.Byte[] data

Byte array containing the IP 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 SendIPDataAsync(IPAddress, Int32, IPProtocol, Byte[]).

Exceptions
Type Condition
System.ArgumentException

If destPort < 0 or if destPort > 65535 or if protocol == UNKNOWN.
System.ArgumentNullException

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

If this device connection is not open.
System.InvalidOperationException

If the device is remote.
TimeoutException

If there is a timeout sending the given packet synchronously.
TransmitException

If the transmit status generated when sendting the data is not an instance of TransmitStatusPacket or if its transmit status is different from SUCCESS.
XBeeException

If there is any other XBee related error.
See Also
XBeeLibrary.Core.IPDevice.SendIPDataImpl(System.Net.IPAddress,System.Int32,XBeeLibrary.Core.Models.IPProtocol,System.Boolean,System.Byte[])
System.Net.IPAddress

SendIPDataAsync(IPAddress, Int32, IPProtocol, Boolean, Byte[])

Sends the provided IP data to the given IP address and port asynchronously using the specified IP protocol. For TCP and TCP SSL protocols, you can also indicate if the socket should be closed when data is sent.

Declaration
public void SendIPDataAsync(IPAddress ipAddress, int destPort, IPProtocol protocol, bool closeSocket, byte[] data)
Parameters
Type Name Description
System.Net.IPAddress ipAddress

The IP address to send IP data to.
System.Int32 destPort

The destination port of the transmission.
IPProtocol protocol

The IP protocol used for the transmission.
System.Boolean closeSocket

true to close the socket just after the transmission. false to keep it open.
System.Byte[] data

Byte array containing the IP data to be sent.
Remarks

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

Exceptions
Type Condition
System.ArgumentException

If destPort < 0 or if destPort > 65535 or if protocol == UNKNOWN.
System.ArgumentNullException

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

If this device connection is not open.
System.InvalidOperationException

If the device is remote.
XBeeException

If there is any other XBee related error.
See Also
XBeeLibrary.Core.IPDevice.SendIPDataAsyncImpl(System.Net.IPAddress,System.Int32,XBeeLibrary.Core.Models.IPProtocol,System.Boolean,System.Byte[])
System.Net.IPAddress

SendIPDataAsync(IPAddress, Int32, IPProtocol, Byte[])

Sends the provided IP data to the given IP address and port asynchronously using the specified IP protocol.

Declaration
public void SendIPDataAsync(IPAddress ipAddress, int destPort, IPProtocol protocol, byte[] data)
Parameters
Type Name Description
System.Net.IPAddress ipAddress

The IP address to send IP data to.
System.Int32 destPort

The destination port of the transmission.
IPProtocol protocol

The IP protocol used for the transmission.
System.Byte[] data

Byte array containing the IP data to be sent.
Remarks

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

Exceptions
Type Condition
System.ArgumentException

If destPort < 0 or if destPort > 65535 or if protocol == UNKNOWN.
System.ArgumentNullException

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

If this device connection is not open.
System.InvalidOperationException

If the device is remote.
See Also
XBeeLibrary.Core.IPDevice.SendIPDataAsyncImpl(System.Net.IPAddress,System.Int32,XBeeLibrary.Core.Models.IPProtocol,System.Boolean,System.Byte[])
System.Net.IPAddress

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

SetDestinationIPAddress(IPAddress)

Sets the Destination IP address.

Declaration
public void SetDestinationIPAddress(IPAddress destAddress)
Parameters
Type Name Description
System.Net.IPAddress destAddress

The new destination System.Net.IPAddress of the device.
Exceptions
Type Condition
System.ArgumentNullException

If destAddress == null.
InterfaceNotOpenException

If this device connection is not open.
TimeoutException

If there is a timeout sending the set configuration command.
XBeeException

If there is any other XBee related error.
See Also
System.Net.IPAddress

StartListening(Int32)

Starts listening for incoming IP transmissions in the provided port.

Declaration
public void StartListening(int sourcePort)
Parameters
Type Name Description
System.Int32 sourcePort

Port to listen for incoming transmissions.
Exceptions
Type Condition
System.ArgumentException

If sourcePort < 0 or if sourcePort > 65535.
InterfaceNotOpenException

If this device connection is not open.
TimeoutException

If there is a timeout sending the set configuration command.
XBeeException

If there is any other XBee related error.

StopListening()

Stops listening for incoming IP transmissions.

Declaration
public void StopListening()
Exceptions
Type Condition
InterfaceNotOpenException

If this device connection is not open.
TimeoutException

If there is a timeout sending the set configuration command.
XBeeException

If there is any other XBee related error.

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

IPDataReceived

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

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