API  2.3.0
TSmarT Software Library
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions
Functions
XBee ZigBee

Functions

int8_t TSMART_XBEE_ZB_Init (tsmart_xbee_zb_t *TSMART_XBEE_ZB, tsmart_xbee_zb_config_t *TSMART_XBEE_ZB_config)
 Initialize the XBee module. More...
 
int8_t TSMART_XBEE_ZB_InitStructEndDevice (tsmart_xbee_zb_config_device_t *TSMART_XBEE_ZB_config_device)
 Default configuration function for end device. More...
 
int8_t TSMART_XBEE_ZB_InitStructCoordinator (tsmart_xbee_zb_config_device_t *TSMART_XBEE_ZB_config_device)
 Default configuration function for coordinator. More...
 
int8_t TSMART_XBEE_ZB_InitStructRouter (tsmart_xbee_zb_config_device_t *TSMART_XBEE_ZB_config_device)
 Default configuration function for router. More...
 
int8_t TSMART_XBEE_ZB_Config (tsmart_xbee_zb_t *TSMART_XBEE_ZB, tsmart_xbee_zb_config_device_t *TSMART_XBEE_ZB_config_device)
 Configuration for XBee zigbee Device. More...
 
int8_t TSMART_XBEE_ZB_SendAtCommandApiConfiguration (tsmart_xbee_zb_t *TSMART_XBEE_ZB, uint8_t *TSMART_XBEE_ZB_answer_buffer, uint8_t TSMART_XBEE_ZB_frame_id,uint8_t *TSMART_XBEE_ZB_payload, uint8_t TSMART_XBEE_ZB_payload_size, portTickType TSMART_XBEE_ZB_timeout)
 Sends a configuration command. More...
 
tsmart_xbee_zb_status_message_t TSMART_XBEE_ZB_ReadSatus (tsmart_xbee_zb_t *TSMART_XBEE_ZB, portTickType TSMART_XBEE_ZB_timeout)
 Reads one status message. More...
 
int8_t TSMART_XBEE_ZB_PowerSignalReceived (tsmart_xbee_zb_t *TSMART_XBEE_ZB)
 Reports the RF power signal (RSSI) of last received packet. More...
 
int8_t TSMART_XBEE_ZB_NumberRemainingChildren (tsmart_xbee_zb_t *TSMART_XBEE_ZB)
 Number of Remaining Children. More...
 
int8_t TSMART_XBEE_ZB_NetworkReset (tsmart_xbee_zb_t *TSMART_XBEE_ZB, tsmart_xbee_zb_rts_network_type TSMART_XBEE_ZB_type)
 Network reset. More...
 
int8_t TSMART_XBEE_ZB_DiscoverNodes (tsmart_xbee_zb_t *TSMART_XBEE_ZB, uint8_t TSMART_XBEE_ZB_max_nodes, tsmart_xbee_zb_discovered_node_t *TSMART_XBEE_ZB_discovered_node, uint8_t TSMART_XBEE_ZB_Timeout)
 Node Discovery Timeout. More...
 
tsmart_xbee_zb_ai_t TSMART_XBEE_ZB_AssociationIndication (tsmart_xbee_zb_t *TSMART_XBEE_ZB)
 Association Indication. More...
 
int32_t TSMART_XBEE_ZB_ReceiveApiFrame (tsmart_xbee_zb_t *TSMART_XBEE_ZB, tsmart_xbee_zb_data_received_t *TSMART_XBEE_ZB_data, portTickType TSMART_XBEE_ZB_xticks)
 Receives ZigBee API frame. More...
 
tsmart_xbee_zb_tx_status_t TSMART_XBEE_ZB_SendApiFrame (tsmart_xbee_zb_t *TSMART_XBEE_ZB, tsmart_xbee_zb_data_to_send_t *TSMART_XBEE_ZB_data, portTickType TSMART_XBEE_ZB_xticks)
 Sends a ZigBee API frame. More...
 
uint32_t TSMART_XBEE_ZB_ReadHighAddress (tsmart_xbee_zb_t *TSMART_XBEE_ZB)
 Reads the high XBee address. More...
 
uint32_t TSMART_XBEE_ZB_ReadLowAddress (tsmart_xbee_zb_t *TSMART_XBEE_ZB)
 Reads the low XBee address. More...
 
uint16_t TSMART_XBEE_ZB_ReadNetworkAddress (tsmart_xbee_zb_t *TSMART_XBEE_ZB)
 Reads the MY XBee address. More...
 
int8_t TSMART_XBEE_ZB_HWSleep (tsmart_xbee_zb_t *TSMART_XBEE_ZB, tsmart_xbee_zb_flag_t TSMART_XBEE_ZB_flag)
 Hardware Sleep. More...
 
int8_t TSMART_XBEE_ZB_CheckOnSleep (tsmart_xbee_zb_t *TSMART_XBEE_ZB)
 Checks OnSleep state. More...
 

Detailed Description

Function Documentation

tsmart_xbee_zb_ai_t TSMART_XBEE_ZB_AssociationIndication ( tsmart_xbee_zb_t *  TSMART_XBEE_ZB)

Association Indication.

Reads information regarding last node join request.

Parameters
TSMART_XBEE_ZBXBee zigbee structure handler.
Returns
        @arg TSMART_XBEE_ZB_AI_1 - Successfully formed or joined a network. (Coordinators form a network, routers and end devices join a network
        @arg TSMART_XBEE_ZB_AI_2 - Scan found no PANs
    @arg TSMART_XBEE_ZB_AI_3 - Scan found no valid PANs based on current SC and ID settings
    @arg TSMART_XBEE_ZB_AI_4 - Valid coordinator or routers found, but they are not allowing joining (NJ expired)
    @arg TSMART_XBEE_ZB_AI_5 - No joinable beacons were found
    @arg TSMART_XBEE_ZB_AI_6 - Unexpected state, node should not be attempting to join at this time
    @arg TSMART_XBEE_ZB_AI_7 - Node joining attempt failed (typically due to incompatible security settings)
    @arg TSMART_XBEE_ZB_AI_8 - Coordinator Start attempt failed
    @arg TSMART_XBEE_ZB_AI_9 - Checking for an existing coordinator
    @arg TSMART_XBEE_ZB_AI_10 - Attempt to leave the network failed
    @arg TSMART_XBEE_ZB_AI_11 - Attempted to join a device that did not respond
    @arg TSMART_XBEE_ZB_AI_12 - Secure join error - network security key received unsecured
    @arg TSMART_XBEE_ZB_AI_13 - Secure join error - network security key not received
    @arg TSMART_XBEE_ZB_AI_14 - Secure join error - joining device does not have the right preconfigured link key
    @arg TSMART_XBEE_ZB_AI_15 - Scanning for a ZigBee network (routers and end devices)
    @arg TSMART_XBEE_ZB_AI_16 - Wrong answer or there's not answer
int8_t TSMART_XBEE_ZB_CheckOnSleep ( tsmart_xbee_zb_t *  TSMART_XBEE_ZB)

Checks OnSleep state.

Parameters
TSMART_XBEE_ZB
Returns
  • 1 - The module is awake
  • 0 - The module is asleep
int8_t TSMART_XBEE_ZB_Config ( tsmart_xbee_zb_t *  TSMART_XBEE_ZB,
tsmart_xbee_zb_config_device_t *  TSMART_XBEE_ZB_config_device 
)

Configuration for XBee zigbee Device.

This function configures XBEE zigbee device with user's values.

Parameters
TSMART_XBEE_ZBXBee zigbee structure handler.
TSMART_XBEE_ZB_config_deviceContains the XBee zigbee configuration.
Returns
  • TSMART_PASS - OK
  • TSMART_XBEE_ZB_FAULT_CODE_1 - Configuration error: Fails getting sleep mode control to prevent the device to sleep
  • TSMART_XBEE_ZB_FAULT_CODE_2 - Configuration error: Fails changing PAN ID
  • TSMART_XBEE_ZB_FAULT_CODE_3 - Configuration error: Fails changing baud rate
  • TSMART_XBEE_ZB_FAULT_CODE_4 - Configuration error: Fails changing flow control RTS
  • TSMART_XBEE_ZB_FAULT_CODE_5 - Configuration error: Fails changing flow control CTS
  • TSMART_XBEE_ZB_FAULT_CODE_6 - Configuration error: Fails changing power level
  • TSMART_XBEE_ZB_FAULT_CODE_7 - Configuration error: Fails changing number of unicast hops parameter
  • TSMART_XBEE_ZB_FAULT_CODE_8 - Configuration error: Fails changing number of broadcast hops parameter
  • TSMART_XBEE_ZB_FAULT_CODE_9 - Configuration error: Fails changing number of channels to scan parameter
  • TSMART_XBEE_ZB_FAULT_CODE_10 - Configuration error: Fails changing time discover nodes parameter
  • TSMART_XBEE_ZB_FAULT_CODE_11 - Configuration error: Fails selecting profile
  • TSMART_XBEE_ZB_FAULT_CODE_12 - Configuration error: Fails changing time join node parameter
  • TSMART_XBEE_ZB_FAULT_CODE_13 - Configuration error: Fails enabling AES encryption parameter
  • TSMART_XBEE_ZB_FAULT_CODE_14 - Configuration error: Fails changing AES key
  • TSMART_XBEE_ZB_FAULT_CODE_15 - Configuration error: Fails changing AES option parameter
  • TSMART_XBEE_ZB_FAULT_CODE_16 - Configuration error: Fails changing network encryption key parameter
  • TSMART_XBEE_ZB_FAULT_CODE_17 - Configuration error: Fails changing number of sleep period parameter
  • TSMART_XBEE_ZB_FAULT_CODE_18 - Configuration error: Fails changing sleep period parameter
  • TSMART_XBEE_ZB_FAULT_CODE_19 - Configuration error: Fails enabling channel verification parameter
  • TSMART_XBEE_ZB_FAULT_CODE_20 - Configuration error: Fails changing network watchdog timeout parameter
  • TSMART_XBEE_ZB_FAULT_CODE_21 - Configuration error: Fails changing sleep option parameter
  • TSMART_XBEE_ZB_FAULT_CODE_22 - Configuration error: Fails changing time before sleep parameter
  • TSMART_XBEE_ZB_FAULT_CODE_23 - Configuration error: Fails changing wake host parameter
  • TSMART_XBEE_ZB_FAULT_CODE_24 - Configuration error: Fails changing polling rate parameter
  • TSMART_XBEE_ZB_FAULT_CODE_25 - Configuration error: Fails changing sleep mode parameter
Examples:
zigbee_receiver.c, and zigbee_sender.c.
int8_t TSMART_XBEE_ZB_DiscoverNodes ( tsmart_xbee_zb_t *  TSMART_XBEE_ZB,
uint8_t  TSMART_XBEE_ZB_max_nodes,
tsmart_xbee_zb_discovered_node_t *  TSMART_XBEE_ZB_discovered_node,
uint8_t  TSMART_XBEE_ZB_Timeout 
)

Node Discovery Timeout.

Sets the node discovery timeout and when is executed, the node discovery timeout value is included in the transmission to provide all remote devices with a response timeout. Remote devices wait a random time, less than node discovery timeout, before sending their response.

Parameters
TSMART_XBEE_ZBXBee ZigBee structure handler.
TSMART_XBEE_ZB_max_nodesMaximum number of nodes to search.
TSMART_XBEE_ZB_discovered_nodeDiscovered node structure.
TSMART_XBEE_ZB_TimeoutNode discovery timeout value [0x20 - 0xFF [x 100 msec]].
Returns
  • number of nodes found
  • TSMART_FAIL - Failure
int8_t TSMART_XBEE_ZB_HWSleep ( tsmart_xbee_zb_t *  TSMART_XBEE_ZB,
tsmart_xbee_zb_flag_t  TSMART_XBEE_ZB_flag 
)

Hardware Sleep.

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

Attention
This function only works with following modes:
  • TSMART_XBEE_ZB_END_DEVICE
Parameters
TSMART_XBEE_ZBXBee ZB structure handler.
TSMART_XBEE_ZB_flagFlag to enter/exit sleep mode.
Returns
  • TSMART_PASS - OK
Examples:
zigbee_receiver.c, and zigbee_sender.c.
int8_t TSMART_XBEE_ZB_Init ( tsmart_xbee_zb_t *  TSMART_XBEE_ZB,
tsmart_xbee_zb_config_t *  TSMART_XBEE_ZB_config 
)

Initialize the XBee module.

This functions initializes the hardware configuration of the selected XBee 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.
Parameters
TSMART_XBEE_ZBXBee ZigBee structure handler.
TSMART_XBEE_ZB_configIndicates the Baud rate for the microcontroller's UART, enables/disables flow control and priority reception task.
Returns
  • TSMART_PASS - OK
  • TSMART_FAIL - Failure
Examples:
zigbee_receiver.c, and zigbee_sender.c.
int8_t TSMART_XBEE_ZB_InitStructCoordinator ( tsmart_xbee_zb_config_device_t *  TSMART_XBEE_ZB_config_device)

Default configuration function for coordinator.

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

Parameters
TSMART_XBEE_ZB_config_deviceConfiguration device structure. It shall be empty.
Returns
  • TSMART_PASS - OK
Examples:
zigbee_receiver.c.
int8_t TSMART_XBEE_ZB_InitStructEndDevice ( tsmart_xbee_zb_config_device_t *  TSMART_XBEE_ZB_config_device)

Default configuration function for end device.

This function shall be called before configure the XBee ZigBee end device module to make sure having a good configuration for XBee module. Check default values in tsmart_xbee_zb_config_device_t definition

Parameters
TSMART_XBEE_ZB_config_deviceConfiguration device structure. It shall be empty.
Returns
  • TSMART_PASS - OK
Examples:
zigbee_sender.c.
int8_t TSMART_XBEE_ZB_InitStructRouter ( tsmart_xbee_zb_config_device_t *  TSMART_XBEE_ZB_config_device)

Default configuration function for router.

This function shall be called before configure the XBee zigbee router module to make sure having a good configuration for Xbee module. Check default values in tsmart_xbee_zb_config_device_t definition

Parameters
TSMART_XBEE_ZB_config_deviceConfiguration device structure. It shall be empty.
Returns
  • TSMART_PASS - OK
int8_t TSMART_XBEE_ZB_NetworkReset ( tsmart_xbee_zb_t *  TSMART_XBEE_ZB,
tsmart_xbee_zb_rts_network_type  TSMART_XBEE_ZB_type 
)

Network reset.

Reset network layer parameters on one or more modules within a PAN. All network configuration and routing information is consequently lost. Two types of reset:

  • TSMART_XBEE_ZB_RST_NETWORK_TYPE1: Resets network layer parameters on the node issuing the command.
  • TSMART_XBEE_ZB_RST_NETWORK_TYPE2: Sends broadcast transmission to reset network layer parameters on all nodes in the PAN
Parameters
TSMART_XBEE_ZBXBee structure handler.
TSMART_XBEE_ZB_typeType of reset: TSMART_XBEE_ZB_RST_NETWORK_TYPE1 or TSMART_XBEE_ZB_RST_NETWORK_TYPE2.
Returns
  • TSMART_PASS - OK
  • TAMART_FAIL - Failure
int8_t TSMART_XBEE_ZB_NumberRemainingChildren ( tsmart_xbee_zb_t *  TSMART_XBEE_ZB)

Number of Remaining Children.

Reports about how many child can be joined to the router or coordinator

Note
It must be only executed by the router or the coordinator.
Parameters
TSMART_XBEE_ZBXBee structure handler.
Returns
  • Number of associated nodes
  • TSMART_XBEE_ZB_FAULT_CODE_1 - Failure
  • TSMART_XBEE_ZB_FAULT_CODE_2 - Operation not allowed in End device.
int8_t TSMART_XBEE_ZB_PowerSignalReceived ( tsmart_xbee_zb_t *  TSMART_XBEE_ZB)

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

Parameters
TSMART_XBEE_ZBXBee ZB structure handler.
Returns
  • Power signal (-X dBm)
  • TSMART_FAIL - Failure
uint32_t TSMART_XBEE_ZB_ReadHighAddress ( tsmart_xbee_zb_t *  TSMART_XBEE_ZB)

Reads the high XBee address.

Parameters
TSMART_XBEE_ZBXBee ZB structure handler.
Returns
  • Low XBee address
  • TSMART_FAIL - Failure
uint32_t TSMART_XBEE_ZB_ReadLowAddress ( tsmart_xbee_zb_t *  TSMART_XBEE_ZB)

Reads the low XBee address.

Parameters
TSMART_XBEE_ZBXBee ZB structure handler.
Returns
  • Low XBee address
  • TSMART_FAIL - Failure
uint16_t TSMART_XBEE_ZB_ReadNetworkAddress ( tsmart_xbee_zb_t *  TSMART_XBEE_ZB)

Reads the MY XBee address.

Parameters
TSMART_XBEE_ZBXBee ZB structure handler.
Returns
  • Network XBee address
  • TSMART_FAIL - Failure
tsmart_xbee_zb_status_message_t TSMART_XBEE_ZB_ReadSatus ( tsmart_xbee_zb_t *  TSMART_XBEE_ZB,
portTickType  TSMART_XBEE_ZB_timeout 
)

Reads 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_ZBXBee ZB structure handler.
TSMART_XBEE_ZB_timeoutMaximum waiting timeout.
Returns
    @arg TSMART_XBEE_ZB_HARDWARE_RESET                                     - Hardware reset
    @arg TSMART_XBEE_ZB_WATCHDOG_TIMER_RESET                               - Watchdog timer reset
    @arg TSMART_XBEE_ZB_JOINED_NETWORK                                     - Joined network (routers and end devices)
    @arg TSMART_XBEE_ZB_DISASSOCIATED                                      - Disassociated
@arg TSMART_XBEE_ZB_COORDINATOR_STARTED                                - Coordinator started
@arg TSMART_XBEE_ZB_NETWORK_SECURITY_KEY_WAS_UPDATED                   - Network security key was updated
@arg TSMART_XBEE_ZB_VOLTAGE_SUPPLY_LIMIT_EXCEEDED                      - Voltage supply limit exceeded (PRO S2B only)
@arg TSMART_XBEE_ZB_MODEM_CONFIGURATION_CHANGED_WHILE_JOIN_IN_PROGRESS - Modem configuration changed while join in progress
@arg TSMART_XBEE_ZB_STACK_ERROR                                        - Stack error
@arg TSMART_XBEE_ZB_WRONG_ANSWER                                       - Failure
Examples:
zigbee_receiver.c, and zigbee_sender.c.
int32_t TSMART_XBEE_ZB_ReceiveApiFrame ( tsmart_xbee_zb_t *  TSMART_XBEE_ZB,
tsmart_xbee_zb_data_received_t *  TSMART_XBEE_ZB_data,
portTickType  TSMART_XBEE_ZB_xticks 
)

Receives ZigBee API frame.

Parameters
TSMART_XBEE_ZBXBee ZB structure handler.
TSMART_XBEE_ZB_dataData structure to store data.
TSMART_XBEE_ZB_xticksMaximum waiting timeout.
Returns
nBytes received
Examples:
zigbee_receiver.c.
tsmart_xbee_zb_tx_status_t TSMART_XBEE_ZB_SendApiFrame ( tsmart_xbee_zb_t *  TSMART_XBEE_ZB,
tsmart_xbee_zb_data_to_send_t *  TSMART_XBEE_ZB_data,
portTickType  TSMART_XBEE_ZB_xticks 
)

Sends a ZigBee API frame.

This function can wait for ACK(id different than 0), this can delay the sent but ensures it.

Parameters
TSMART_XBEE_ZBXBee ZigBee structure handler.
TSMART_XBEE_ZB_dataData buffer to send.
TSMART_XBEE_ZB_xticksMaximum waiting timeout.
Returns
  • status struct.
Examples:
zigbee_sender.c.
int8_t TSMART_XBEE_ZB_SendAtCommandApiConfiguration ( tsmart_xbee_zb_t *  TSMART_XBEE_ZB,
uint8_t *  TSMART_XBEE_ZB_answer_buffer,
uint8_t  TSMART_XBEE_ZB_frame_id,
uint8_t *  TSMART_XBEE_ZB_payload,
uint8_t  TSMART_XBEE_ZB_payload_size,
portTickType  TSMART_XBEE_ZB_timeout 
)

Sends a configuration command.

This function sends configuration command and returns a semi-answer API frame, user must know the structure of the API frame received because not returns the complete API frame, the checksum, length and start flag field are processed and remove form the frame, the rest of the frame has the same fields and the same order in the API frame.

Parameters
TSMART_XBEE_ZBXBee ZigBee structure handler.
TSMART_XBEE_ZB_answer_bufferData buffer received.
TSMART_XBEE_ZB_frame_idID frame for API frame.
TSMART_XBEE_ZB_payloadPayload.
TSMART_XBEE_ZB_payload_sizePayload size.
TSMART_XBEE_ZB_timeoutMaximum waiting timeout.
Returns
  • nb - Number of bytes received
  • TSMART_FAIL - Fails to get answer or there isn't answer.