digi.xbee.xsocket module¶

class digi.xbee.xsocket.socket(xbee_device, ip_protocol=<IPProtocol.TCP: (1, 'TCP')>)[source]¶

Bases: object

This class represents an XBee socket and provides methods to create, connect, bind and close a socket, as well as send and receive data with it.

Class constructor. Instantiates a new XBee socket object for the given XBee device.

Parameters

xbee_device (XBeeDevice) – XBee device of the socket.
ip_protocol (IPProtocol) – protocol of the socket.

Raises

ValueError – if xbee_device is None or if xbee_device is not an instance of CellularDevice.
ValueError – if ip_protocol is None.
XBeeException – if the connection with the XBee device is not open.

connect(address)[source]¶

Connects to a remote socket at the given address.

Parameters

address (Tuple) – A pair (host, port) where host is the domain name or string representation of an IPv4 and port is the numeric port value.

Raises

TimeoutException – If the connect response is not received in the configured timeout.
ValueError – If address is None or not a pair (host, port).
ValueError – If port is less than 1 or greater than 65535.
XBeeException – If the connection with the XBee device is not open.
XBeeSocketException – If the connect status is not SUCCESS.

bind(address)[source]¶

Binds the socket to the given address. The socket must not already be bound.

Parameters

address (Tuple) – A pair (host, port) where host is the local interface (not used) and port is the numeric port value.

Raises

TimeoutException – If the bind response is not received in the configured timeout.
ValueError – If address is None or not a pair (host, port).
ValueError – If port is less than 1 or greater than 65535.
XBeeException – If the connection with the XBee device is not open.
XBeeSocketException – If the bind status is not SUCCESS.
XBeeSocketException – If the socket is already bound.

listen(backlog=1)[source]¶

Enables a server to accept connections.

Parameters: backlog (Integer, optional) – The number of unaccepted connections that the system will allow before refusing new connections. If specified, it must be at least 0 (if it is lower, it is set to 0).
Raises: XBeeSocketException – If the socket is not bound.

accept()[source]¶

Accepts a connection. The socket must be bound to an address and listening for connections.

Returns

A pair (conn, address) where conn is a new socket object: usable to send and receive data on the connection, and address is a pair (host, port) with the address bound to the socket on the other end of the connection.

Return type

Tuple

Raises

XBeeException – If the connection with the XBee device is not open.
XBeeSocketException – If the socket is not bound or not listening.

gettimeout()[source]¶

Returns the configured socket timeout in seconds.

Returns: The configured timeout in seconds.
Return type: Integer

settimeout(timeout)[source]¶

Sets the socket timeout in seconds.

Parameters: timeout (Integer) – The new socket timeout in seconds.

getblocking()[source]¶

Returns whether the socket is in blocking mode or not.

Returns: True if the socket is in blocking mode, False otherwise.
Return type: Boolean

setblocking(flag)[source]¶

Sets the socket in blocking or non-blocking mode.

Parameters: flag (Boolean) – True to set the socket in blocking mode, False to set it in no blocking mode and configure the timeout with the default value (5 seconds).

recv(bufsize)[source]¶

Receives data from the socket.

Parameters: bufsize (Integer) – The maximum amount of data to be received at once.
Returns: The data received.
Return type: Bytearray
Raises: ValueError – If bufsize is less than 1.

recvfrom(bufsize)[source]¶

Receives data from the socket.

Parameters

bufsize (Integer) – The maximum amount of data to be received at once.

Returns

Pair containing the data received: (Bytearray) and the address of the socket sending the data. The address is also a pair (host, port) where host is the string representation of an IPv4 and port is the numeric port value.

Return type

Tuple (Bytearray, Tuple)

Raises

ValueError – If bufsize is less than 1.

send(data)[source]¶

Sends data to the socket and returns the number of bytes sent. The socket must be connected to a remote socket. Applications are responsible for checking that all data has been sent; if only some of the data was transmitted, the application needs to attempt delivery of the remaining data.

Parameters

data (Bytearray) – The data to send.

Returns

The number of bytes sent.

Return type

Integer

Raises

ValueError – If the data to send is None.
ValueError – If the number of bytes to send is 0.
XBeeException – If the connection with the XBee device is not open.
XBeeSocketException – If the socket is not valid.
XBeeSocketException – If the socket is not open.

sendall(data)[source]¶

Sends data to the socket. The socket must be connected to a remote socket. Unlike send(), this method continues to send data from bytes until either all data has been sent or an error occurs. None is returned on success. On error, an exception is raised, and there is no way to determine how much data, if any, was successfully sent.

Parameters

data (Bytearray) – The data to send.

Raises

TimeoutException – If the send status response is not received in the configured timeout.
ValueError – If the data to send is None.
ValueError – If the number of bytes to send is 0.
XBeeException – If the connection with the XBee device is not open.
XBeeSocketException – If the socket is not valid.
XBeeSocketException – If the send status is not SUCCESS.
XBeeSocketException – If the socket is not open.

sendto(data, address)[source]¶

Sends data to the socket. The socket should not be connected to a remote socket, since the destination socket is specified by address.

Parameters

data (Bytearray) – The data to send.
address (Tuple) – The address of the destination socket. It must be a pair (host, port) where host is the domain name or string representation of an IPv4 and port is the numeric port value.

Returns

The number of bytes sent.

Return type

Integer

Raises

TimeoutException – If the send status response is not received in the configured timeout.
ValueError – If the data to send is None.
ValueError – If the number of bytes to send is 0.
XBeeException – If the connection with the XBee device is not open.
XBeeSocketException – If the socket is already open.
XBeeSocketException – If the send status is not SUCCESS.

close()[source]¶

Closes the socket.

Raises

TimeoutException – If the close response is not received in the configured timeout.
XBeeException – If the connection with the XBee device is not open.
XBeeSocketException – If the close status is not SUCCESS.

setsocketopt(option, value)[source]¶

Sets the value of the given socket option.

Parameters

option (SocketOption) – The socket option to set its value.
value (Bytearray) – The new value of the socket option.

Raises

TimeoutException – If the socket option response is not received in the configured timeout.
ValueError – If the option to set is None.
ValueError – If the value of the option is None.
XBeeException – If the connection with the XBee device is not open.
XBeeSocketException – If the socket option response status is not SUCCESS.

getsocketopt(option)[source]¶

Returns the value of the given socket option.

Parameters

option (SocketOption) – The socket option to get its value.

Returns

The value of the socket option.

Return type

Bytearray

Raises

TimeoutException – If the socket option response is not received in the configured timeout.
ValueError – If the option to set is None.
XBeeException – If the connection with the XBee device is not open.
XBeeSocketException – If the socket option response status is not SUCCESS.

add_socket_state_callback(callback)[source]¶

Adds a callback for the event digi.xbee.reader.SocketStateReceived.

Parameters

callback (Function) –

The callback. Receives two arguments.

The socket ID as an Integer.
The state received as a SocketState

del_socket_state_callback(callback)[source]¶

Deletes a callback for the callback list of digi.xbee.reader.SocketStateReceived event.

Parameters: callback (Function) – The callback to delete.
Raises: ValueError – If callback is not in the callback list of digi.xbee.reader.SocketStateReceived event.

get_sock_info()[source]¶

Returns the information of this socket.

Returns

The socket information.

Return type

SocketInfo

Raises

InvalidOperatingModeException – If the XBee device’s operating mode is not API or ESCAPED API. This method only checks the cached value of the operating mode.
TimeoutException – If the response is not received before the read timeout expires.
XBeeException – If the XBee device’s communication interface is closed.