API  2.2
TSmarT Software Library
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions

Functions

int8_t TSMART_XBEE_868_Init (tsmart_xbee_868_t *TSMART_XBEE_868, tsmart_xbee_868_config_t *TSMART_XBEE_868_config)
 Initialize the XBee module. More...
 
void TSMART_XBEE_868_InitStruct (tsmart_xbee_868_config_device_t *TSMART_XBEE_868_config_device)
 Initializes tsmart_xbee_868_config_device_t structure. More...
 
int8_t TSMART_XBEE_868_Config (tsmart_xbee_868_t *TSMART_XBEE_868, tsmart_xbee_868_config_device_t *TSMART_XBEE_868_config_device)
 Configures a XBEE 868 Device. More...
 
int8_t TSMART_XBEE_868_TransparentMode (tsmart_xbee_868_t *TSMART_XBEE_868, tsmart_xbee_868_flag_t TSMART_XBEE_868_flag)
 Enters/Exits from transparent mode to receive or send data. More...
 
int8_t TSMART_XBEE_868_AtCommandMode (tsmart_xbee_868_t *TSMART_XBEE_868, tsmart_xbee_868_flag_t TSMART_XBEE_868_flag)
 Enters or exits from the AT command mode. More...
 
int32_t TSMART_XBEE_868_Send (tsmart_xbee_868_t *TSMART_XBEE_868, uint8_t *TSMART_XBEE_868_buf, uint32_t TSMART_XBEE_868_nbytes, portTickType TSMART_XBEE_868_xticks)
 Sends data to remote XBee module. More...
 
int32_t TSMART_XBEE_868_Receive (tsmart_xbee_868_t *TSMART_XBEE_868, uint8_t *TSMART_XBEE_868_buf, uint32_t TSMART_XBEE_868_nbytes, portTickType TSMART_XBEE_868_xticks)
 Receives data from the XBee module. More...
 
int16_t TSMART_XBEE_868_ReceiveApiFrame (tsmart_xbee_868_t *TSMART_XBEE_868, tsmart_xbee_868_data_received_t *TSMART_XBEE_868_data, portTickType TSMART_XBEE_868_xticks)
 Receives a frame using API mode. More...
 
int8_t TSMART_XBEE_868_SendApiFrame (tsmart_xbee_868_t *TSMART_XBEE_868, tsmart_xbee_868_data_to_send_t *TSMART_XBEE_868_data, portTickType TSMART_XBEE_868_xticks)
 Sends a frame using API mode. More...
 
int8_t TSMART_XBEE_868_PowerSignalReceived (tsmart_xbee_868_t *TSMART_XBEE_868)
 Reports the received signal strength (RSSI) of last received packet. More...
 
int8_t TSMART_XBEE_868_ReadSatus (tsmart_xbee_868_t *TSMART_XBEE_868, portTickType TSMART_XBEE_868_timeout)
 Read one status message. More...
 
int32_t TSMART_XBEE_868_ReadLowAddress (tsmart_xbee_868_t *TSMART_XBEE_868)
 Reads the low part of the local XBee address. More...
 
int32_t TSMART_XBEE_868_ReadHighAddress (tsmart_xbee_868_t *TSMART_XBEE_868)
 Reads the high part of the local XBee address. More...
 
int8_t TSMART_XBEE_868_ChangePowerLevel (tsmart_xbee_868_t *TSMART_XBEE_868, uint8_t TSMART_XBEE_868_power_level)
 Changes transmitter RF power. More...
 

Detailed Description

Function Documentation

int8_t TSMART_XBEE_868_AtCommandMode ( tsmart_xbee_868_t TSMART_XBEE_868,
tsmart_xbee_868_flag_t  TSMART_XBEE_868_flag 
)

Enters or exits from the AT command mode.

Using this function is possible to send AT commands to the XBee module using the TSMART_XBEE_868_Send() and TSMART_XBEE_868_Receive() functions.

Parameters
TSMART_XBEE_868XBee structure handler.
TSMART_XBEE_868_flagLabel to enter/exit the AT command mode.
Returns
  • TSMART_PASS - OK.
  • TSMART_XBEE_868_FAULT_CODE_1 Fails trying to enter AT command mode.
  • TSMART_XBEE_868_FAULT_CODE_2 Fails trying to exit from AT command mode.
  • TSMART_XBEE_868_FAULT_CODE_3 Fails trying to change the receiving mode.
int8_t TSMART_XBEE_868_ChangePowerLevel ( tsmart_xbee_868_t TSMART_XBEE_868,
uint8_t  TSMART_XBEE_868_power_level 
)

Changes transmitter RF power.

Parameters
TSMART_XBEE_868XBee 868 structure handler.
TSMART_XBEE_868_power_levelPower level. Range[0(lowest)-4(highest)]
Returns
  • TSMART_PASS - Value changed.
  • TSMART_FAIL - Failed change.
int8_t TSMART_XBEE_868_Config ( tsmart_xbee_868_t TSMART_XBEE_868,
tsmart_xbee_868_config_device_t TSMART_XBEE_868_config_device 
)

Configures a XBEE 868 Device.

This function configures a XBEE 868 device with user's values.

Parameters
TSMART_XBEE_868XBee 868 structure handler.
TSMART_XBEE_868_config_deviceContains the XBee 868 configuration.
Returns
  • TSMART_PASS - OK
  • TSMART_XBEE_868_FAULT_CODE_1 - Configuration error: Fails enter in command mode.
  • TSMART_XBEE_868_FAULT_CODE_2 - Configuration error: Fails changing API mode.
  • TSMART_XBEE_868_FAULT_CODE_3 - Configuration error: Fails applying changes.
  • TSMART_XBEE_868_FAULT_CODE_4 - Configuration error: Fails checking API mode.
  • TSMART_XBEE_868_FAULT_CODE_5 - Configuration error: Fails exit from command mode.
  • TSMART_XBEE_868_FAULT_CODE_6 - Configuration error: Fails setting VID.
  • TSMART_XBEE_868_FAULT_CODE_7 - Configuration error: Fails setting flow control RTS.
  • TSMART_XBEE_868_FAULT_CODE_8 - Configuration error: Fails setting flow control CTS.
  • TSMART_XBEE_868_FAULT_CODE_9 - Configuration error: Fails setting mac retries.
  • TSMART_XBEE_868_FAULT_CODE_10 - Configuration error: Fails setting multiple transmissions.
  • TSMART_XBEE_868_FAULT_CODE_11 - Configuration error: Fails changing power level.
  • TSMART_XBEE_868_FAULT_CODE_12 - Configuration error: Fails enabling/disabling security.
  • TSMART_XBEE_868_FAULT_CODE_13 - Configuration error: Fails setting security key
  • TSMART_XBEE_868_FAULT_CODE_14 - Configuration error: Fails setting destination address high.
  • TSMART_XBEE_868_FAULT_CODE_15 - Configuration error: Fails setting destination address low.
  • TSMART_XBEE_868_FAULT_CODE_16 - Configuration error: Fails setting API mode.
Examples:
xbee868_receiver.c, and xbee868_sender.c.
int8_t TSMART_XBEE_868_Init ( tsmart_xbee_868_t TSMART_XBEE_868,
tsmart_xbee_868_config_t TSMART_XBEE_868_config 
)

Initialize the XBee module.

This functions initializes the hardware configuration of the XBee 868 and the associated OS mechanisms.

Attention
This function creates one task to receive, reception task. This task should set with a high priority in the user application (14 is advisable) and has a own stack. Its target is to pick packets up quickly avoiding lose packets and parsing them. In addition this function creates several queues to manage the information received properly. This task can be change its operation mode, API to transparent or command mode and transparent or command to API mode. Check the specific TSmarT functions to make this change of operation:
Parameters
TSMART_XBEE_868XBee 868 structure handler.
TSMART_XBEE_868_configIndicates the baud rate for the microcontroller's UART, enables/disables flow control and the priority reception task.
Returns
  • TSMART_PASS - OK
  • TSMART_FAIL - Fail
Examples:
xbee868_receiver.c, and xbee868_sender.c.
void TSMART_XBEE_868_InitStruct ( tsmart_xbee_868_config_device_t TSMART_XBEE_868_config_device)

Initializes tsmart_xbee_868_config_device_t structure.

This function shall be called before configure the XBee 868 module to set the default values. Check default values in tsmart_xbee_868_config_device_t definition.

Parameters
TSMART_XBEE_868_config_deviceConfiguration device structure. It shall be empty.
Returns
TSMART_PASS - OK
Examples:
xbee868_receiver.c, and xbee868_sender.c.
int8_t TSMART_XBEE_868_PowerSignalReceived ( tsmart_xbee_868_t TSMART_XBEE_868)

Reports the received signal strength (RSSI) of last received packet.

The returned value only indicates the signal strength of the last hop. It does not provide an accurate quality measurement for a multihop link. The returned value is measured in -dBm.

Parameters
TSMART_XBEE_868XBee 868 structure handler.
Returns
  • Power signal (-X dBm)
  • TSMART_FAIL - Failure
int32_t TSMART_XBEE_868_ReadHighAddress ( tsmart_xbee_868_t TSMART_XBEE_868)

Reads the high part of the local XBee address.

Parameters
TSMART_XBEE_868XBee 868 structure handler.
Returns
  • High XBee address
  • TSMART_FAIL - Failure
int32_t TSMART_XBEE_868_ReadLowAddress ( tsmart_xbee_868_t TSMART_XBEE_868)

Reads the low part of the local XBee address.

Parameters
TSMART_XBEE_868XBee 868 structure handler.
Returns
  • Low XBee address
  • TSMART_FAIL - Failure
int8_t TSMART_XBEE_868_ReadSatus ( tsmart_xbee_868_t TSMART_XBEE_868,
portTickType  TSMART_XBEE_868_timeout 
)

Read one status message.

This function remains blocked until expires a selected timeout or until one status message is received. The messages will be queued in the proper buffer until it's full (it can store 5 messages). Users should empty the buffer executing this function to avoid lose new messages.

Parameters
TSMART_XBEE_868XBee 868 structure handler.
TSMART_XBEE_868_timeoutMaximum timeout to wait a new status message.
Returns
  • 0x00 - Hardware reset
  • 0x01 - Watchdog timer reset
  • 0x0B - Network Woke Up
  • 0x0C - Network Went To Sleep
  • TSMART_FAIL - Status not available
int32_t TSMART_XBEE_868_Receive ( tsmart_xbee_868_t TSMART_XBEE_868,
uint8_t *  TSMART_XBEE_868_buf,
uint32_t  TSMART_XBEE_868_nbytes,
portTickType  TSMART_XBEE_868_xticks 
)

Receives data from the XBee module.

This function should be used to receive AT response command in command mode or to receive data in transparent mode.

Parameters
TSMART_XBEE_868XBee 868 structure handler.
TSMART_XBEE_868_bufData buffer to store data.
TSMART_XBEE_868_nbytesNumber of bytes to receive.
TSMART_XBEE_868_xticksMaximum waiting timeout.
Returns
  • Bytes received
int16_t TSMART_XBEE_868_ReceiveApiFrame ( tsmart_xbee_868_t TSMART_XBEE_868,
tsmart_xbee_868_data_received_t TSMART_XBEE_868_data,
portTickType  TSMART_XBEE_868_xticks 
)

Receives a frame using API mode.

Parameters
TSMART_XBEE_868XBee 868 structure handler.
TSMART_XBEE_868_dataData structure to store data.
TSMART_XBEE_868_xticksMaximum waiting timeout.
Returns
nBytes received
Examples:
xbee868_receiver.c.
int32_t TSMART_XBEE_868_Send ( tsmart_xbee_868_t TSMART_XBEE_868,
uint8_t *  TSMART_XBEE_868_buf,
uint32_t  TSMART_XBEE_868_nbytes,
portTickType  TSMART_XBEE_868_xticks 
)

Sends data to remote XBee module.

This function should be used to send AT command in command mode or to send data in transparent mode.

Parameters
TSMART_XBEE_868XBee structure handler.
TSMART_XBEE_868_bufData buffer to send.
TSMART_XBEE_868_nbytesBytes to send
TSMART_XBEE_868_xticksMaximum waiting timeout.
Returns
  • Bytes sent
int8_t TSMART_XBEE_868_SendApiFrame ( tsmart_xbee_868_t TSMART_XBEE_868,
tsmart_xbee_868_data_to_send_t TSMART_XBEE_868_data,
portTickType  TSMART_XBEE_868_xticks 
)

Sends a frame using API mode.

This function can be waiting for ACK setting the ID frame different than 0. Waiting ACK can delay the sending but ensures it.

Parameters
TSMART_XBEE_868XBee 868 structure handler.
TSMART_XBEE_868_dataData structure to send.
TSMART_XBEE_868_xticksMaximum waiting timeout.
Returns
  • 0x00 = Success
  • 0x01 = MAC ACK Failure
  • 0x15 = Invalid destination endpoint
  • 0x21 = Network ACK Failure
  • 0x25 = Route Not Found
  • TSMART_FAIL - Fail
Examples:
xbee868_sender.c.
int8_t TSMART_XBEE_868_TransparentMode ( tsmart_xbee_868_t TSMART_XBEE_868,
tsmart_xbee_868_flag_t  TSMART_XBEE_868_flag 
)

Enters/Exits from transparent mode to receive or send data.

Using this function is possible to send or receive transparent data to the XBee module using the TSMART_XBEE_868_Send() and TSMART_XBEE_868_Receive() functions.

Note
It must be executed after a guard time (1sg by default) because uses the "+++" sequence to enter in transparent mode.
Parameters
TSMART_XBEE_868XBee 868 structure handler.
TSMART_XBEE_868_flagLabel to enter/exit the transparent internal mode.
Returns
  • TSMART_PASS - OK.
  • TSMART_XBEE_868_FAULT_CODE_1 - Fails Changing mode in the XBee 868 module.
  • TSMART_XBEE_868_FAULT_CODE_2 - It was impossible to change internal operation mode.
  • TSMART_XBEE_868_FAULT_CODE_3 - It was impossible to change internal operation mode.