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

Functions

int8_t TSMART_XBEE_802_Init (tsmart_xbee_802_t *TSMART_XBEE_802, tsmart_xbee_802_config_t *TSMART_XBEE_802_config)
 Initialize the XBee module. More...
 
int8_t TSMART_XBEE_802_InitStruct (tsmart_xbee_802_config_device_t *TSMART_XBEE_802_config_device)
 Initializes tsmart_xbee_802_config_device_t structure function. More...
 
int8_t TSMART_XBEE_802_Config (tsmart_xbee_802_t *TSMART_XBEE_802, tsmart_xbee_802_config_device_t *TSMART_XBEE_802_config_device)
 Configures a XBEE 802.15.4 Device. More...
 
int8_t TSMART_XBEE_802_AtCommandMode (tsmart_xbee_802_t *TSMART_XBEE_802, tsmart_xbee_802_flag_t TSMART_XBEE_802_flag)
 Enters or exits from the AT command mode. More...
 
int32_t TSMART_XBEE_802_Send (tsmart_xbee_802_t *TSMART_XBEE_802, uint8_t *TSMART_XBEE_802_buf, uint32_t TSMART_XBEE_802_nbytes, portTickType TSMART_XBEE_802_xticks)
 Sends data to remote XBee module. More...
 
int32_t TSMART_XBEE_802_Receive (tsmart_xbee_802_t *TSMART_XBEE_802, uint8_t *TSMART_XBEE_802_buf, uint32_t TSMART_XBEE_802_nbytes, portTickType TSMART_XBEE_802_xticks)
 Receives data from the XBee module. More...
 
int8_t TSMART_XBEE_802_TransparentMode (tsmart_xbee_802_t *TSMART_XBEE_802, tsmart_xbee_802_flag_t TSMART_XBEE_802_flag)
 Enters/Exits from transparent mode to receive or send data. More...
 
int8_t TSMART_XBEE_802_ReceiveApiFrame (tsmart_xbee_802_t *TSMART_XBEE_802, tsmart_xbee_802_data_received_t *TSMART_XBEE_802_data, portTickType TSMART_XBEE_802_xticks)
 Receives a frame using API mode. More...
 
int8_t TSMART_XBEE_802_SendApiFrame (tsmart_xbee_802_t *TSMART_XBEE_802, tsmart_xbee_802_data_to_send_t *TSMART_XBEE_802_data, portTickType TSMART_XBEE_802_xticks)
 Sends a frame using API mode. More...
 
int8_t TSMART_XBEE_802_PowerSignalReceived (tsmart_xbee_802_t *TSMART_XBEE_802)
 Reports the RF power signal (RSSI) of last received packet. More...
 
int8_t TSMART_XBEE_802_HwSleep (tsmart_xbee_802_t *TSMART_XBEE_802, tsmart_xbee_802_flag_t TSMART_XBEE_802_flag)
 Hardware Sleep. More...
 
int8_t TSMART_XBEE_802_DiscoverNodes (tsmart_xbee_802_t *TSMART_XBEE_802, uint8_t TSMART_XBEE_802_max_nodes, tsmart_xbee_802_discovered_node_t *TSMART_XBEE_802_nodes, uint8_t TSMART_XBEE_802_timeout)
 Discovery nodes. More...
 
int8_t TSMART_XBEE_802_ScanNetworks (tsmart_xbee_802_t *TSMART_XBEE_802, uint8_t TSMART_XBEE_802_max_networks, tsmart_xbee_802_scan_net_t *TSMART_XBEE_802_networks)
 Scans networks. More...
 
int8_t TSMART_XBEE_802_EnergyScan (tsmart_xbee_802_t *TSMART_XBEE_802, tsmart_xbee_802_energy_scan_t *TSMART_XBEE_802_energy_scan)
 Scans energy. More...
 
tsmart_xbee_802_status_t TSMART_XBEE_802_DisassociateNode (tsmart_xbee_802_t *TSMART_XBEE_802)
 Disassociate node. More...
 
int8_t TSMART_XBEE_802_ReadSatus (tsmart_xbee_802_t *TSMART_XBEE_802, portTickType TSMART_XBEE_802_timeout)
 Read one status message. More...
 
uint32_t TSMART_XBEE_802_ReadLowAddress (tsmart_xbee_802_t *TSMART_XBEE_802)
 Reads the low part of the local XBee address. More...
 
uint32_t TSMART_XBEE_802_ReadHighAddress (tsmart_xbee_802_t *TSMART_XBEE_802)
 Reads the high part of the local XBee address. More...
 
uint32_t TSMART_XBEE_802_FirmwareVersion (tsmart_xbee_802_t *TSMART_XBEE_802)
 Reads the Firmware version of the local XBee address. More...
 

Detailed Description

Function Documentation

int8_t TSMART_XBEE_802_AtCommandMode ( tsmart_xbee_802_t TSMART_XBEE_802,
tsmart_xbee_802_flag_t  TSMART_XBEE_802_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_802_Send() and TSMART_XBEE_802_Receive() functions.

Parameters
TSMART_XBEE_802XBee structure handler.
TSMART_XBEE_802_flagLabel to enter/exit the AT command mode.
Returns
  • TSMART_PASS - OK.
  • TSMART_XBEE_802_FAULT_CODE_1 Fails trying to enter AT command mode.
  • TSMART_XBEE_802_FAULT_CODE_2 Fails trying to exit from AT command mode.
  • TSMART_XBEE_802_FAULT_CODE_3 Fails trying to change the receiving mode.
int8_t TSMART_XBEE_802_Config ( tsmart_xbee_802_t TSMART_XBEE_802,
tsmart_xbee_802_config_device_t TSMART_XBEE_802_config_device 
)

Configures a XBEE 802.15.4 Device.

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

Parameters
TSMART_XBEE_802XBee 802 structure handler.
TSMART_XBEE_802_config_deviceContains the XBee 802 configuration.
Returns
  • TSMART_PASS - OK
  • TSMART_XBEE_802_FAULT_CODE_1 - Configuration error: Fails enter in command mode
  • TSMART_XBEE_802_FAULT_CODE_2 - Configuration error: Fails changing API mode
  • TSMART_XBEE_802_FAULT_CODE_3 - Configuration error: Fails applying changes
  • TSMART_XBEE_802_FAULT_CODE_4 - Configuration error: Fails checking API mode
  • TSMART_XBEE_802_FAULT_CODE_5 - Configuration error: Fails exit from command mode
  • TSMART_XBEE_802_FAULT_CODE_6 - Configuration error: Fails changing kind of Device parameter
  • TSMART_XBEE_802_FAULT_CODE_7 - Configuration error: Fails changing channel
  • TSMART_XBEE_802_FAULT_CODE_8 - Configuration error: Fails changing PAN ID
  • TSMART_XBEE_802_FAULT_CODE_9 - Configuration error: Fails changing baud rate
  • TSMART_XBEE_802_FAULT_CODE_10 - Configuration error: Fails changing flow control RTS
  • TSMART_XBEE_802_FAULT_CODE_11 - Configuration error: Fails changing flow control CTS
  • TSMART_XBEE_802_FAULT_CODE_12 - Configuration error: Fails changing power level
  • TSMART_XBEE_802_FAULT_CODE_13 - Configuration error: Fails changing AES encryption
  • TSMART_XBEE_802_FAULT_CODE_14 - Configuration error: Fails changing AES key encryption
  • TSMART_XBEE_802_FAULT_CODE_15 - Configuration error: Fails Low destination address
  • TSMART_XBEE_802_FAULT_CODE_16 - Configuration error: Fails High destination address
  • TSMART_XBEE_802_FAULT_CODE_17 - Configuration error: Fails changing MY parameter
  • TSMART_XBEE_802_FAULT_CODE_18 - Configuration error: Fails changing retries parameter
  • TSMART_XBEE_802_FAULT_CODE_19 - Configuration error: Fails changing sleep parameter
  • TSMART_XBEE_802_FAULT_CODE_20 - Configuration error: Fails changing sleep_option parameter
  • TSMART_XBEE_802_FAULT_CODE_21 - Configuration error: Fails changing cyclic_period parameter
  • TSMART_XBEE_802_FAULT_CODE_22 - Configuration error: Fails changing timer_before_sleep parameter
  • TSMART_XBEE_802_FAULT_CODE_23 - Configuration error: Fails changing n_scan_channels parameter
  • TSMART_XBEE_802_FAULT_CODE_24 - Configuration error: Fails changing scan_channels_time parameter
  • TSMART_XBEE_802_FAULT_CODE_25 - Configuration error: Fails changing eflexibility or cflexibility parameter
  • TSMART_XBEE_802_FAULT_CODE_26 - Configuration error: Fails Enable API mode
Examples:
xbee802_15_4_receiver.c, and xbee802_15_4_sender.c.
int8_t TSMART_XBEE_802_DisassociateNode ( tsmart_xbee_802_t TSMART_XBEE_802)

Disassociate node.

Disassociate node form coordinator. End Device will immediately disassociate from a Coordinator (if associated) and reattempt to associate.

Parameters
TSMART_XBEE_802XBee 802 structure handler.
Returns
  • TSMART_PASS - OK
  • TSMART_FAIL - Failure
int8_t TSMART_XBEE_802_DiscoverNodes ( tsmart_xbee_802_t TSMART_XBEE_802,
uint8_t  TSMART_XBEE_802_max_nodes,
tsmart_xbee_802_discovered_node_t TSMART_XBEE_802_nodes,
uint8_t  TSMART_XBEE_802_timeout 
)

Discovery nodes.

Discover nodes in the same network, this is: same PAN ID and channel.

The user determines the number of nodes to find by creating an array of discovered_node_t type and indicating its maximum size.

The structure tsmart_xbee_802_discovered_node_t contains information about one node.

Attention
This function shall be used in a task of higher priority than the reception task. If this information's ignore, not all nodes of your network will be discovered.
Parameters
TSMART_XBEE_802XBee 802 structure handler.
TSMART_XBEE_802_max_nodesMaximum nodes to look for. Maximum 255 nodes.
TSMART_XBEE_802_nodesPointer to the array of discovered nodes structure(with at least TSMART_XBEE_802_max_nodes elements, (MAX 255 nodes)).
TSMART_XBEE_802_timeoutMaximum timeout to search nodes. this command will be set in hexadecimal and in this range: 0x01 to 0xFC [x 100 ms].
Returns
  • Number of nodes discovered.
  • TSMART_XBEE_802_FAULT_CODE_1 - Fails setting timeout to search nodes.
  • TSMART_XBEE_802_FAULT_CODE_2 - Wrong answer.
  • TSMART_XBEE_802_FAULT_CODE_3 - Failure.
int8_t TSMART_XBEE_802_EnergyScan ( tsmart_xbee_802_t TSMART_XBEE_802,
tsmart_xbee_802_energy_scan_t TSMART_XBEE_802_energy_scan 
)

Scans energy.

Scans energy form channels. The values returned represent the detected energy level in units of -dBm. The actual scan time on each channel is measured as Time = [(2 ^ time scan) * 15.36] ms.

Note
The total scan time is this time multiplied by the number of channels to be scanned
Parameters
TSMART_XBEE_802XBee 802 structure handler.
TSMART_XBEE_802_energy_scanEnergy scan structure.
Returns
  • TSMART_PASS - OK
  • TSMART_FAIL - Failure
uint32_t TSMART_XBEE_802_FirmwareVersion ( tsmart_xbee_802_t TSMART_XBEE_802)

Reads the Firmware version of the local XBee address.

Parameters
TSMART_XBEE_802XBee 802 structure handler.
Returns
  • Firmware Version
  • TSMART_FAIL - Failure
int8_t TSMART_XBEE_802_HwSleep ( tsmart_xbee_802_t TSMART_XBEE_802,
tsmart_xbee_802_flag_t  TSMART_XBEE_802_flag 
)

Hardware Sleep.

Provides to enter/exit to sleep mode using a dedicated line.

Attention
This function only works with following modes:
  • TSMART_XBEE_802_PIN_X
  • TSMART_XBEE_802_CYCLIC_PIN

Parameters
TSMART_XBEE_802XBee 802 structure handler.
TSMART_XBEE_802_flagFlag to enter/exit sleep mode.
Returns
  • TSMART_PASS - OK
Examples:
xbee802_15_4_receiver.c, and xbee802_15_4_sender.c.
int8_t TSMART_XBEE_802_Init ( tsmart_xbee_802_t TSMART_XBEE_802,
tsmart_xbee_802_config_t TSMART_XBEE_802_config 
)

Initialize the XBee module.

This functions initializes the hardware configuration of the XBee 802.15.4 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_802XBee 802 structure handler.
TSMART_XBEE_802_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:
xbee802_15_4_receiver.c, and xbee802_15_4_sender.c.
int8_t TSMART_XBEE_802_InitStruct ( tsmart_xbee_802_config_device_t TSMART_XBEE_802_config_device)

Initializes tsmart_xbee_802_config_device_t structure function.

This function shall be called before configure the XBee 802 module to make sure having a good configuration for XBee 802.15.4 module. Check default values in tsmart_xbee_802_config_device_t definition

Parameters
TSMART_XBEE_802_config_deviceConfiguration device structure. It shall be empty.
Returns
TSMART_PASS - OK
Examples:
xbee802_15_4_receiver.c, and xbee802_15_4_sender.c.
int8_t TSMART_XBEE_802_PowerSignalReceived ( tsmart_xbee_802_t TSMART_XBEE_802)

Reports the RF power signal (RSSI) of last received packet.

Parameters
TSMART_XBEE_802XBee 802 structure handler.
Returns
  • Power signal (-X dBm)
  • TSMART_FAIL - Failure
uint32_t TSMART_XBEE_802_ReadHighAddress ( tsmart_xbee_802_t TSMART_XBEE_802)

Reads the high part of the local XBee address.

Parameters
TSMART_XBEE_802XBee 802 structure handler.
Returns
  • High XBee address
  • TSMART_FAIL - Failure
uint32_t TSMART_XBEE_802_ReadLowAddress ( tsmart_xbee_802_t TSMART_XBEE_802)

Reads the low part of the local XBee address.

Parameters
TSMART_XBEE_802XBee 802 structure handler.
Returns
  • Low XBee address
  • TSMART_FAIL - Failure
int8_t TSMART_XBEE_802_ReadSatus ( tsmart_xbee_802_t TSMART_XBEE_802,
portTickType  TSMART_XBEE_802_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_802XBee 802 structure handler.
TSMART_XBEE_802_timeoutMaximum timeout to wait a new status message.
Returns
  • 0 - Hardware reset
  • 1 - Watchdog timer reset
  • 2 - Associated
  • 3 - Disassociated
  • 4 - Synchronization Lost (Beacon-enabled only )
  • 5 - Coordinator realignment
  • 6 - Coordinator started
  • TSMART_FAIL - Status not available
int32_t TSMART_XBEE_802_Receive ( tsmart_xbee_802_t TSMART_XBEE_802,
uint8_t *  TSMART_XBEE_802_buf,
uint32_t  TSMART_XBEE_802_nbytes,
portTickType  TSMART_XBEE_802_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_802XBee 802 structure handler.
TSMART_XBEE_802_bufData buffer to store data.
TSMART_XBEE_802_nbytesNumber of bytes to receive.
TSMART_XBEE_802_xticksMaximum waiting timeout.
Returns
  • Bytes received
int8_t TSMART_XBEE_802_ReceiveApiFrame ( tsmart_xbee_802_t TSMART_XBEE_802,
tsmart_xbee_802_data_received_t TSMART_XBEE_802_data,
portTickType  TSMART_XBEE_802_xticks 
)

Receives a frame using API mode.

Parameters
TSMART_XBEE_802XBee 802 structure handler.
TSMART_XBEE_802_dataData structure to store data.
TSMART_XBEE_802_xticksMaximum waiting timeout.
Returns
nBytes sent
Examples:
xbee802_15_4_receiver.c.
int8_t TSMART_XBEE_802_ScanNetworks ( tsmart_xbee_802_t TSMART_XBEE_802,
uint8_t  TSMART_XBEE_802_max_networks,
tsmart_xbee_802_scan_net_t TSMART_XBEE_802_networks 
)

Scans networks.

Scans channels indicated in configuration structure and returns a structure with information about 5 or less PANs found.

Parameters
TSMART_XBEE_802XBee 802 structure handler.
TSMART_XBEE_802_max_networksMaximum networks to look for. Maximum: 5 networks.
TSMART_XBEE_802_networksScan net structure.
Returns
  • Number of PAN found
  • TSMART_XBEE_802_FAULT_CODE_1 - Wrong answer
  • TSMART_XBEE_802_FAULT_CODE_2 - Failure
int32_t TSMART_XBEE_802_Send ( tsmart_xbee_802_t TSMART_XBEE_802,
uint8_t *  TSMART_XBEE_802_buf,
uint32_t  TSMART_XBEE_802_nbytes,
portTickType  TSMART_XBEE_802_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_802XBee structure handler.
TSMART_XBEE_802_bufData buffer to send.
TSMART_XBEE_802_nbytesBytes to send
TSMART_XBEE_802_xticksMaximum waiting timeout.
Returns
  • Bytes sent
int8_t TSMART_XBEE_802_SendApiFrame ( tsmart_xbee_802_t TSMART_XBEE_802,
tsmart_xbee_802_data_to_send_t TSMART_XBEE_802_data,
portTickType  TSMART_XBEE_802_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 sent but ensures it.

Parameters
TSMART_XBEE_802XBee 802 structure handler.
TSMART_XBEE_802_dataData buffer to send.
TSMART_XBEE_802_xticksMaximum waiting timeout.
Returns
  • 0 - Success
  • 1 - No ACK (Acknowledgement) received. All retries are expired and no ACK is received.
  • 2 - CCA failure
  • 3 - Purged. Occurs when Coordinator times out of an indirect transmission.
  • TSMART_FAIL - Fail
Examples:
xbee802_15_4_sender.c.
int8_t TSMART_XBEE_802_TransparentMode ( tsmart_xbee_802_t TSMART_XBEE_802,
tsmart_xbee_802_flag_t  TSMART_XBEE_802_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_802_Send() and TSMART_XBEE_802_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_802XBee 802 structure handler.
TSMART_XBEE_802_flagLabel to enter/exit the transparent internal mode.
Returns
  • TSMART_PASS - OK.
  • TSMART_XBEE_802_FAULT_CODE_1 - Fails Changing mode in the XBee 802.15.4 module.
  • TSMART_XBEE_802_FAULT_CODE_2 - It was impossible to change internal operation mode.
  • TSMART_XBEE_802_FAULT_CODE_3 - It was impossible to change internal operation mode.