3.4.17. xbee_client — XBee client

This is a high level driver for XBee modules, providing functions to execute AT commands, and receive and transmit data from/to a remote XBee module.

An XBee client consists of an object and a thread. The thread asynchronously receives frames from the XBee module, leaving this logic out of the user application. The user can read received packets (stored in a queue in the client object), transmit data with or without acknowledgement, and execute AT commands with acknowledgement.

3.4.17.1. Example usage

This example shows how to receive and tramsmit data from/to a remote XBee module and control IO on the local XBee module.

See examples/xbee_client/main.c for the full example, including initialization and error handling.

Declaration of the variables used in this example:

static struct xbee_client_t client;
ssize_t size;
uint8_t buf[XBEE_DATA_MAX];
struct xbee_client_address_t sender;

/* See full example for initialization. */

Reception and transmission of packets from/to a remote XBee module:

/* Wait for a packet from a remote XBee module. */
size = xbee_client_read_from(&client,
                             &buf[0],
                             sizeof(buf),
                             &sender);

/* Print the read packet and its sender. */
xbee_client_print_address(sys_get_stdout(), &sender);
std_hexdump(sys_get_stdout(), &buf[0], size);

/* Send the packet back to the sender. */
size = xbee_client_write_to(&client,
                            &buf[0],
                            sizeof(buf),
                            0,
                            &sender);

The classic blink example using a LED connected to the XBee:

/* Configure DIO0 as output. */
xbee_client_pin_set_mode(&client,
                         XBEE_PIN_DIO0,
                         XBEE_CLIENT_PIN_OUTPUT);

/* Blink the LED. */
while (1) {
   xbee_client_pin_toggle(&client, XBEE_PIN_DIO0);
   thrd_sleep(0.5);
}

Source code: src/drivers/network/xbee_client.h, src/drivers/network/xbee_client.c

Example code: examples/xbee_client/main.c


Defines

XBEE_CLIENT_PIN_OUTPUT
XBEE_CLIENT_PIN_INPUT
XBEE_CLIENT_PIN_ADC
XBEE_CLIENT_NON_BLOCKING_READ
XBEE_CLIENT_NO_ACK

Enums

enum xbee_client_address_type_t

Values:

xbee_client_address_type_invalid_t = 0
xbee_client_address_type_16_bits_t
xbee_client_address_type_64_bits_t

Functions

int xbee_client_module_init(void)

Initialize the xbee module. This function must be called before calling any other function in this module.

The module will only be initialized once even if this function is called multiple times.

Return
zero(0) or negative error code.

int xbee_client_init(struct xbee_client_t *self_p, void *chin_p, void *chout_p, void *buf_p, size_t size, int flags)

Initialize given driver object from given configuration.

Return
zero(0) or negative error code.
Parameters
  • self_p: Driver object to initialize.
  • chin_p: Input channel from the XBee module, often a UART driver.
  • chout_p: Output channel to the XBee module, often a UART driver output channel.
  • buf_p: Frame reception buffer.
  • size: Frame reception buffer size in words.
  • flags: Client configuration flags. May be any combination of XBEE_CLIENT_NON_BLOCKING_READ.

void *xbee_client_main(void *arg_p)

The client thread entry function.

Return
zero(0) or negative error code.
Parameters
  • self_p: Initialized client object.

ssize_t xbee_client_read_from(struct xbee_client_t *self_p, void *buf_p, size_t size, struct xbee_client_address_t *address_p)

Read data from one RX packet into given buffer. The sender 16 or 64 bits address is written to address_p.

Return
Number of bytes read or negative error code.
Parameters
  • self_p: Initialized client object.
  • buf_p: Buffer to read into.
  • size: Number of bytes to read.
  • address_p: Sender address.

ssize_t xbee_client_write_to(struct xbee_client_t *self_p, const void *buf_p, size_t size, int flags, struct xbee_client_address_t *address_p)

Create a TX packet of given data and write it to given 16 or 64 bits XBee address.

Return
Number of bytes written or negative error code.
Parameters
  • self_p: Initialized client object.
  • buf_p: Buffer to write.
  • size: Number of bytes to write.
  • flags: Read flags.
  • flags: May be any combination of XBEE_CLIENT_NO_ACK.
  • address_p: Receiver address.

int xbee_client_pin_set_mode(struct xbee_client_t *self_p, int pin, int mode)

Configure given pin to given mode.

Return
zero(0) or negative error code.
Parameters
  • self_p: Initialized client object.
  • pin: Pin to set mode for.
  • mode: Pin mode to set.

int xbee_client_pin_read(struct xbee_client_t *self_p, int pin)

Read the current value of given pin.

Return
zero(0), one(1) or negative error code.
Parameters
  • self_p: Initialized client object.
  • pin: Pin to read from.

int xbee_client_pin_write(struct xbee_client_t *self_p, int pin, int value)

Write given value to given pin.

Return
zero(0) or negative error code.
Parameters
  • self_p: Initialized client object.
  • pin: Pin to write to.
  • value: 1 for high and 0 for low output.

int xbee_client_pin_toggle(struct xbee_client_t *self_p, int pin)

Toggle the pin output value (high/low).

Return
zero(0) or negative error code.
Parameters
  • self_p: Initialized client object.
  • pin: Pin to toggle.

int xbee_client_pin_convert(struct xbee_client_t *self_p, int pin)

Start a synchronous convertion of an analog signal a digital sample.

Return
Sample or negative error code.
Parameters
  • self_p: Initialized client object.
  • pin: ADC pin to convert.

ssize_t xbee_client_at_command_read(struct xbee_client_t *self_p, const char *command_p, uint8_t *parameter_p, size_t size)

Execute given AT command and store its read parameter in given buffer.

Return
Number of read bytes or negative error code.
Parameters
  • self_p: Initialized client object.
  • command_p: Two letters AT command.
  • parameter_p: Parameter buffer to read into.
  • size: Buffer size in bytes.

int xbee_client_at_command_write(struct xbee_client_t *self_p, const char *command_p, const uint8_t *parameter_p, size_t size)

Execute given AT command with given parameter.

Return
zero(0 or negative error code.
Parameters
  • self_p: Initialized client object.
  • command_p: Two letters AT command.
  • parameter_p: Parameter buffer to write.
  • size: Buffer size in bytes.

int xbee_client_at_command_read_u8(struct xbee_client_t *self_p, const char *command_p, uint8_t *parameter_p)

Execute given AT command and store its read 8 bits parameter in given variable.

Return
zero(0) or negative error code.
Parameters
  • self_p: Initialized client object.
  • command_p: Two letters AT command.
  • parameter_p: Read parameter.

int xbee_client_at_command_write_u8(struct xbee_client_t *self_p, const char *command_p, uint8_t parameter)

Execute given AT command with given 8 bits parameter.

Return
zero(0) or negative error code.
Parameters
  • self_p: Initialized client object.
  • command_p: Two letters AT command.
  • parameter: Parameter to write.

int xbee_client_at_command_read_u16(struct xbee_client_t *self_p, const char *command_p, uint16_t *parameter_p)

Execute given AT command and store its read 16 bits parameter in given variable.

Return
zero(0) or negative error code.
Parameters
  • self_p: Initialized client object.
  • command_p: Two letters AT command.
  • parameter_p: Read parameter.

int xbee_client_at_command_write_u16(struct xbee_client_t *self_p, const char *command_p, uint16_t parameter)

Execute given AT command with given 16 bits parameter.

Return
zero(0) or negative error code.
Parameters
  • self_p: Initialized client object.
  • command_p: Two letters AT command.
  • parameter: Parameter to write.

int xbee_client_at_command_read_u32(struct xbee_client_t *self_p, const char *command_p, uint32_t *parameter_p)

Execute given AT command and store its read 32 bits parameter in given variable.

Return
zero(0) or negative error code.
Parameters
  • self_p: Initialized client object.
  • command_p: Two letters AT command.
  • parameter_p: Read parameter.

int xbee_client_at_command_write_u32(struct xbee_client_t *self_p, const char *command_p, uint32_t parameter)

Execute given AT command with given 32 bits parameter.

Return
zero(0) or negative error code.
Parameters
  • self_p: Initialized client object.
  • command_p: Two letters AT command.
  • parameter: Parameter to write.

int xbee_client_print_address(void *chan_p, struct xbee_client_address_t *address_p)

Format and print given address to given channel.

Return
zero(0) or negative error code.
Parameters
  • chan_p: Channel to print to.
  • address_p: Address to print.

struct xbee_client_address_t

Public Members

xbee_client_address_type_t type
uint8_t buf[8]
struct xbee_client_t

Public Members

struct queue_t chin
struct xbee_driver_t driver
uint8_t frame_id
uint8_t value
struct xbee_client_t::@18 xbee_client_t::pins
struct mutex_t mutex
struct cond_t cond
struct xbee_frame_t *frame_p
void *buf_p
size_t *size_p
int res
struct xbee_client_t::@19::@20 xbee_client_t::rx
struct xbee_client_t::@19 xbee_client_t::rpc
struct log_object_t log