420 lines
17 KiB
C
420 lines
17 KiB
C
|
/**************************************************************************************************
|
|||
|
|
Filename: sapi.h
|
|||
|
|
Revised: $Date: 2008-03-14 11:20:21 -0700 (Fri, 14 Mar 2008) $
|
|||
|
|
Revision: $Revision: 16590 $
|
|||
|
|
|
|||
|
|
Description: Z-Stack Simple Application Interface.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Copyright 2007 Texas Instruments Incorporated. All rights reserved.
|
|||
|
|
|
|||
|
|
IMPORTANT: Your use of this Software is limited to those specific rights
|
|||
|
|
granted under the terms of a software license agreement between the user
|
|||
|
|
who downloaded the software, his/her employer (which must be your employer)
|
|||
|
|
and Texas Instruments Incorporated (the "License"). You may not use this
|
|||
|
|
Software unless you agree to abide by the terms of the License. The License
|
|||
|
|
limits your use, and you acknowledge, that the Software may not be modified,
|
|||
|
|
copied or distributed unless embedded on a Texas Instruments microcontroller
|
|||
|
|
or used solely and exclusively in conjunction with a Texas Instruments radio
|
|||
|
|
frequency transceiver, which is integrated into your product. Other than for
|
|||
|
|
the foregoing purpose, you may not use, reproduce, copy, prepare derivative
|
|||
|
|
works of, modify, distribute, perform, display or sell this Software and/or
|
|||
|
|
its documentation for any purpose.
|
|||
|
|
|
|||
|
|
YOU FURTHER ACKNOWLEDGE AND AGREE THAT THE SOFTWARE AND DOCUMENTATION ARE
|
|||
|
|
PROVIDED <EFBFBD>AS IS<EFBFBD> WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
|
|||
|
|
INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE,
|
|||
|
|
NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL
|
|||
|
|
TEXAS INSTRUMENTS OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER CONTRACT,
|
|||
|
|
NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, BREACH OF WARRANTY, OR OTHER
|
|||
|
|
LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES
|
|||
|
|
INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, INDIRECT, PUNITIVE
|
|||
|
|
OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF PROCUREMENT
|
|||
|
|
OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY CLAIMS BY THIRD PARTIES
|
|||
|
|
(INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), OR OTHER SIMILAR COSTS.
|
|||
|
|
|
|||
|
|
Should you have any questions regarding your right to use this Software,
|
|||
|
|
contact Texas Instruments Incorporated at www.TI.com.
|
|||
|
|
**************************************************************************************************/
|
|||
|
|
|
|||
|
|
#ifndef SAPI_H
|
|||
|
|
#define SAPI_H
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* INCLUDES
|
|||
|
|
*/
|
|||
|
|
#include "ZComDef.h"
|
|||
|
|
#include "af.h"
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* CONSTANTS
|
|||
|
|
*/
|
|||
|
|
|
|||
|
|
// Simple Task Events
|
|||
|
|
#define ZB_ALLOW_BIND_TIMER 0x4000 //0x0001
|
|||
|
|
#define ZB_BIND_TIMER 0x2000 //0x0002
|
|||
|
|
#define ZB_ENTRY_EVENT 0x1000 //0x0004
|
|||
|
|
#define ZB_USER_EVENTS 0x00FF
|
|||
|
|
|
|||
|
|
// Find Device Search Types
|
|||
|
|
#define ZB_IEEE_SEARCH 1
|
|||
|
|
|
|||
|
|
// Device Info Constants
|
|||
|
|
#define ZB_INFO_DEV_STATE 0
|
|||
|
|
#define ZB_INFO_IEEE_ADDR 1
|
|||
|
|
#define ZB_INFO_SHORT_ADDR 2
|
|||
|
|
#define ZB_INFO_PARENT_SHORT_ADDR 3
|
|||
|
|
#define ZB_INFO_PARENT_IEEE_ADDR 4
|
|||
|
|
#define ZB_INFO_CHANNEL 5
|
|||
|
|
#define ZB_INFO_PAN_ID 6
|
|||
|
|
#define ZB_INFO_EXT_PAN_ID 7
|
|||
|
|
|
|||
|
|
// SAPI SendDataRequest destinations
|
|||
|
|
#define ZB_BINDING_ADDR INVALID_NODE_ADDR
|
|||
|
|
#define ZB_BROADCAST_ADDR 0xffff
|
|||
|
|
|
|||
|
|
// SAPI Status Codes
|
|||
|
|
#define ZB_SUCCESS ZSuccess
|
|||
|
|
#define ZB_FAILURE ZFailure
|
|||
|
|
#define ZB_INVALID_PARAMETER ZInvalidParameter
|
|||
|
|
#define ZB_ALREADY_IN_PROGRESS ZSapiInProgress
|
|||
|
|
#define ZB_TIMEOUT ZSapiTimeout
|
|||
|
|
#define ZB_INIT ZSapiInit
|
|||
|
|
#define ZB_AF_FAILURE afStatus_FAILED
|
|||
|
|
#define ZB_AF_MEM_FAIL afStatus_MEM_FAIL
|
|||
|
|
#define ZB_AF_INVALID_PARAMETER afStatus_INVALID_PARAMETER
|
|||
|
|
|
|||
|
|
// SAPI Scan Duration Values
|
|||
|
|
#define ZB_SCAN_DURATION_0 0 // 19.2 ms
|
|||
|
|
#define ZB_SCAN_DURATION_1 1 // 38.4 ms
|
|||
|
|
#define ZB_SCAN_DURATION_2 2 // 76.8 ms
|
|||
|
|
#define ZB_SCAN_DURATION_3 3 // 153.6 ms
|
|||
|
|
#define ZB_SCAN_DURATION_4 4 // 307.2 ms
|
|||
|
|
#define ZB_SCAN_DURATION_5 5 // 614.4 ms
|
|||
|
|
#define ZB_SCAN_DURATION_6 6 // 1.23 sec
|
|||
|
|
#define ZB_SCAN_DURATION_7 7 // 2.46 sec
|
|||
|
|
#define ZB_SCAN_DURATION_8 8 // 4.92 sec
|
|||
|
|
#define ZB_SCAN_DURATION_9 9 // 9.83 sec
|
|||
|
|
#define ZB_SCAN_DURATION_10 10 // 19.66 sec
|
|||
|
|
#define ZB_SCAN_DURATION_11 11 // 39.32 sec
|
|||
|
|
#define ZB_SCAN_DURATION_12 12 // 78.64 sec
|
|||
|
|
#define ZB_SCAN_DURATION_13 13 // 157.28 sec
|
|||
|
|
#define ZB_SCAN_DURATION_14 14 // 314.57 sec
|
|||
|
|
|
|||
|
|
// Device types definitions ( from ZGlobals.h file )
|
|||
|
|
#define ZG_DEVICETYPE_COORDINATOR 0x00
|
|||
|
|
#define ZG_DEVICETYPE_ROUTER 0x01
|
|||
|
|
#define ZG_DEVICETYPE_ENDDEVICE 0x02
|
|||
|
|
/******************************************************************************
|
|||
|
|
* TYPEDEFS
|
|||
|
|
*/
|
|||
|
|
typedef struct
|
|||
|
|
{
|
|||
|
|
uint16 panID;
|
|||
|
|
uint8 channel;
|
|||
|
|
} zb_NetworkList_t;
|
|||
|
|
|
|||
|
|
typedef struct
|
|||
|
|
{
|
|||
|
|
osal_event_hdr_t hdr;
|
|||
|
|
uint16 data;
|
|||
|
|
} sapi_CbackEvent_t;
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* PUBLIC VARIABLES
|
|||
|
|
*/
|
|||
|
|
|
|||
|
|
extern uint8 sapi_TaskID;
|
|||
|
|
extern endPointDesc_t sapi_epDesc;
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* PUBLIC FUNCTIONS
|
|||
|
|
*/
|
|||
|
|
|
|||
|
|
#ifdef __cplusplus
|
|||
|
|
extern "C"
|
|||
|
|
{
|
|||
|
|
#endif
|
|||
|
|
|
|||
|
|
extern const SimpleDescriptionFormat_t zb_SimpleDesc;
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* @fn zb_SystemReset
|
|||
|
|
*
|
|||
|
|
* @brief The zb_SystemReset function reboots the ZigBee Stack. The
|
|||
|
|
* zb_SystemReset function can be called after a call to
|
|||
|
|
* zb_WriteConfiguration to restart Z-Stack with the updated
|
|||
|
|
* configuration.
|
|||
|
|
*
|
|||
|
|
* @param none
|
|||
|
|
*
|
|||
|
|
* @return none
|
|||
|
|
*/
|
|||
|
|
extern void zb_SystemReset ( void );
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* @fn zb_StartRequest
|
|||
|
|
*
|
|||
|
|
* @brief The zb_StartRequest function starts the ZigBee stack. When the
|
|||
|
|
* ZigBee stack starts, the device reads configuration parameters
|
|||
|
|
* from Nonvolatile memory and the device joins its network. The
|
|||
|
|
* ZigBee stack calls the zb_StartConrifm callback function when
|
|||
|
|
* the startup process completes.
|
|||
|
|
*
|
|||
|
|
* @param none
|
|||
|
|
*
|
|||
|
|
* @return none
|
|||
|
|
*/
|
|||
|
|
extern void zb_StartRequest ( void );
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* @fn zb_PermitJoiningRequest
|
|||
|
|
*
|
|||
|
|
* @brief The zb_PermitJoiningRequest function is used to control the
|
|||
|
|
* joining permissions and thus allow or disallow new devices from
|
|||
|
|
* joining the network.
|
|||
|
|
*
|
|||
|
|
* @param destination - The destination parameter indicates the address
|
|||
|
|
* of the device for which the joining permissions
|
|||
|
|
* should be set. This is usually the local device
|
|||
|
|
* address or the special broadcast address that denotes
|
|||
|
|
* all routers and coordinator ( 0xFFFC ). This way
|
|||
|
|
* the joining permissions of a single device or the
|
|||
|
|
* whole network can be controlled.
|
|||
|
|
* timeout - Indicates the amount of time in seconds for which
|
|||
|
|
* the joining permissions should be turned on.
|
|||
|
|
* If timeout is set to 0x00, the device will turn off the
|
|||
|
|
* joining permissions indefinitely. If it is set to 0xFF,
|
|||
|
|
* the joining permissions will be turned on indefinitely.
|
|||
|
|
*
|
|||
|
|
*
|
|||
|
|
* @return ZB_SUCCESS or a failure code
|
|||
|
|
*
|
|||
|
|
*/
|
|||
|
|
extern uint8 zb_PermitJoiningRequest ( uint16 destination, uint8 timeout );
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* @fn zb_BindDevice
|
|||
|
|
*
|
|||
|
|
* @brief The zb_BindDevice function establishes or removes a <EFBFBD>binding<EFBFBD>
|
|||
|
|
* between two devices. Once bound, an application can send
|
|||
|
|
* messages to a device by referencing the commandId for the
|
|||
|
|
* binding.
|
|||
|
|
*
|
|||
|
|
* @param create - TRUE to create a binding, FALSE to remove a binding
|
|||
|
|
* commandId - The identifier of the binding
|
|||
|
|
* pDestination - The 64-bit IEEE address of the device to bind to
|
|||
|
|
*
|
|||
|
|
* @return ZB_SUCCESS if the bind process started sucessfully, else
|
|||
|
|
* en error code is returned. If the return value is ZB_SUCCESS
|
|||
|
|
* then the status of the bind operation is returned in the
|
|||
|
|
* zb_BindConfirm callback.
|
|||
|
|
*/
|
|||
|
|
extern void zb_BindDevice ( uint8 create, uint16 commandId, uint8 *pDestination );
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* @fn zb_AllowBind
|
|||
|
|
*
|
|||
|
|
* @brief The zb_AllowBind function puts the device into the
|
|||
|
|
* Allow Binding Mode for a given period of time. A peer device
|
|||
|
|
* can establish a binding to a device in the Allow Binding Mode
|
|||
|
|
* by calling zb_BindDevice with a destination address of NULL
|
|||
|
|
*
|
|||
|
|
* @param timeout - The number of seconds to remain in the allow binding
|
|||
|
|
* mode. Valid values range from 1 through 65.
|
|||
|
|
*
|
|||
|
|
* @return ZB_SUCCESS if the device entered the allow bind mode, else
|
|||
|
|
* an error code.
|
|||
|
|
*/
|
|||
|
|
extern void zb_AllowBind ( uint8 timeout );
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* @fn zb_SendDataRequest
|
|||
|
|
*
|
|||
|
|
* @brief The zb_SendDataRequest function initiates transmission of data
|
|||
|
|
* to a peer device
|
|||
|
|
*
|
|||
|
|
* @param destination - The destination of the data. The destination can
|
|||
|
|
* be one of the following:
|
|||
|
|
* - 16-Bit short address of device [0-0xfffD]
|
|||
|
|
* - ZB_BROADCAST_ADDR sends the data to all devices
|
|||
|
|
* in the network.
|
|||
|
|
* - ZB_BINDING_ADDR sends the data to a previously
|
|||
|
|
* bound device.
|
|||
|
|
*
|
|||
|
|
* commandId - The command ID to send with the message. If the
|
|||
|
|
* ZB_BINDING_ADDR destination is used, this parameter
|
|||
|
|
* also indicates the binding to use.
|
|||
|
|
*
|
|||
|
|
* len - The size of the pData buffer in bytes
|
|||
|
|
* handle - A handle used to identify the send data request.
|
|||
|
|
* ack - TRUE if requesting acknowledgement from the destination.
|
|||
|
|
* radius - The max number of routers the data can travel through
|
|||
|
|
* before the data is dropped.
|
|||
|
|
*
|
|||
|
|
* @return none
|
|||
|
|
*/
|
|||
|
|
extern void zb_SendDataRequest ( uint16 destination, uint16 commandId, uint8 len,
|
|||
|
|
uint8 *pData, uint8 handle, uint8 ack, uint8 radius );
|
|||
|
|
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* @fn zb_ReadConfiguration
|
|||
|
|
*
|
|||
|
|
* @brief The zb_ReadConfiguration function is used to get a
|
|||
|
|
* Configuration Protperty from Nonvolatile memory.
|
|||
|
|
*
|
|||
|
|
* @param configId - The identifier for the configuration property
|
|||
|
|
* len - The size of the pValue buffer in bytes
|
|||
|
|
* pValue - A buffer to hold the configuration property
|
|||
|
|
*
|
|||
|
|
* @return none
|
|||
|
|
*/
|
|||
|
|
extern uint8 zb_ReadConfiguration( uint8 configId, uint8 len, void *pValue );
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* @fn zb_WriteConfiguration
|
|||
|
|
*
|
|||
|
|
* @brief The zb_WriteConfiguration function is used to write a
|
|||
|
|
* Configuration Property to nonvolatile memory.
|
|||
|
|
*
|
|||
|
|
* @param configId - The identifier for the configuration property
|
|||
|
|
* len - The size of the pValue buffer in bytes
|
|||
|
|
* pValue - A buffer containing the new value of the
|
|||
|
|
* configuration property
|
|||
|
|
*
|
|||
|
|
* @return none
|
|||
|
|
*/
|
|||
|
|
extern uint8 zb_WriteConfiguration( uint8 configId, uint8 len, void *pValue );
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* @fn zb_GetDeviceInfo
|
|||
|
|
*
|
|||
|
|
* @brief The zb_GetDeviceInfo function retrieves a Device Information
|
|||
|
|
* Property.
|
|||
|
|
*
|
|||
|
|
* @param param - The identifier for the device information
|
|||
|
|
* pValue - A buffer to hold the device information
|
|||
|
|
*
|
|||
|
|
* @return none
|
|||
|
|
*/
|
|||
|
|
extern void zb_GetDeviceInfo ( uint8 param, void *pValue );
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* @fn zb_FindDeviceRequest
|
|||
|
|
*
|
|||
|
|
* @brief The zb_FindDeviceRequest function is used to determine the
|
|||
|
|
* short address for a device in the network. The device initiating
|
|||
|
|
* a call to zb_FindDeviceRequest and the device being discovered
|
|||
|
|
* must both be a member of the same network. When the search is
|
|||
|
|
* complete, the zv_FindDeviceConfirm callback function is called.
|
|||
|
|
*
|
|||
|
|
* @param searchType - The type of search to perform. Can be one of following:
|
|||
|
|
* ZB_IEEE_SEARCH - Search for 16-bit addr given IEEE addr.
|
|||
|
|
* searchKey - Value to search on.
|
|||
|
|
*
|
|||
|
|
* @return none
|
|||
|
|
*/
|
|||
|
|
extern void zb_FindDeviceRequest( uint8 searchType, void *searchKey );
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* @fn zb_HandleOsalEvent
|
|||
|
|
*
|
|||
|
|
* @brief The zb_HandleOsalEvent function is called by the operating
|
|||
|
|
* system when a task event is set
|
|||
|
|
*
|
|||
|
|
* @param event - Bitmask containing the events that have been set
|
|||
|
|
*
|
|||
|
|
* @return none
|
|||
|
|
*/
|
|||
|
|
extern void zb_HandleOsalEvent( uint16 event );
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* @fn zb_StartConfirm
|
|||
|
|
*
|
|||
|
|
* @brief The zb_StartConfirm callback is called by the ZigBee stack
|
|||
|
|
* after a start request operation completes
|
|||
|
|
*
|
|||
|
|
* @param status - The status of the start operation. Status of
|
|||
|
|
* ZB_SUCCESS indicates the start operation completed
|
|||
|
|
* successfully. Else the status is an error code.
|
|||
|
|
*
|
|||
|
|
* @return none
|
|||
|
|
*/
|
|||
|
|
extern void zb_StartConfirm( uint8 status );
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* @fn zb_SendDataConfirm
|
|||
|
|
*
|
|||
|
|
* @brief The zb_SendDataConfirm callback function is called by the
|
|||
|
|
* ZigBee after a send data operation completes
|
|||
|
|
*
|
|||
|
|
* @param handle - The handle identifying the data transmission.
|
|||
|
|
* status - The status of the operation.
|
|||
|
|
*
|
|||
|
|
* @return none
|
|||
|
|
*/
|
|||
|
|
extern void zb_SendDataConfirm( uint8 handle, uint8 status );
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* @fn zb_BindConfirm
|
|||
|
|
*
|
|||
|
|
* @brief The zb_BindConfirm callback is called by the ZigBee stack
|
|||
|
|
* after a bind operation completes.
|
|||
|
|
*
|
|||
|
|
* @param commandId - The command ID of the binding being confirmed.
|
|||
|
|
* status - The status of the bind operation.
|
|||
|
|
* allowBind - TRUE if the bind operation was initiated by a call
|
|||
|
|
* to zb_AllowBindRespones. FALSE if the operation
|
|||
|
|
* was initiated by a call to ZB_BindDevice
|
|||
|
|
*
|
|||
|
|
* @return none
|
|||
|
|
*/
|
|||
|
|
extern void zb_BindConfirm( uint16 commandId, uint8 status );
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* @fn zb_FindDeviceConfirm
|
|||
|
|
*
|
|||
|
|
* @brief The zb_FindDeviceConfirm callback function is called by the
|
|||
|
|
* ZigBee stack when a find device operation completes.
|
|||
|
|
*
|
|||
|
|
* @param searchType - The type of search that was performed.
|
|||
|
|
* searchKey - Value that the search was executed on.
|
|||
|
|
* result - The result of the search.
|
|||
|
|
*
|
|||
|
|
* @return none
|
|||
|
|
*/
|
|||
|
|
extern void zb_FindDeviceConfirm( uint8 searchType, uint8 *searchKey, uint8 *result );
|
|||
|
|
|
|||
|
|
/******************************************************************************
|
|||
|
|
* @fn zb_ReceiveDataIndication
|
|||
|
|
*
|
|||
|
|
* @brief The zb_ReceiveDataIndication callback function is called
|
|||
|
|
* asynchronously by the ZigBee stack to notify the application
|
|||
|
|
* when data is received from a peer device.
|
|||
|
|
*
|
|||
|
|
* @param source - The short address of the peer device that sent the data
|
|||
|
|
* command - The commandId associated with the data
|
|||
|
|
* len - The number of bytes in the pData parameter
|
|||
|
|
* pData - The data sent by the peer device
|
|||
|
|
*
|
|||
|
|
* @return none
|
|||
|
|
*/
|
|||
|
|
extern void zb_ReceiveDataIndication( uint16 source, uint16 command, uint16 len, uint8 *pData );
|
|||
|
|
|
|||
|
|
extern void zb_AllowBindConfirm( uint16 source );
|
|||
|
|
|
|||
|
|
extern void zb_HandleKeys( uint8 shift, uint8 keys );
|
|||
|
|
|
|||
|
|
|
|||
|
|
/* External declarations required by SAPI */
|
|||
|
|
extern UINT16 SAPI_ProcessEvent( byte task_id, UINT16 events );
|
|||
|
|
extern void SAPI_Init( byte task_id );
|
|||
|
|
extern void osalAddTasks( void );
|
|||
|
|
|
|||
|
|
#ifdef __cplusplus
|
|||
|
|
}
|
|||
|
|
#endif
|
|||
|
|
|
|||
|
|
#endif // SAPI_H
|