Zigbee网络设备启动—主要函数说明

// Register the endpoint description with the AF
// This task doesn't have a Simple description, but we still need
// to register the endpoint.
afRegister( (endPointDesc_t *)&ZDApp_epDesc );

#if defined( ZDO_USERDESC_RESPONSE )
ZDApp_InitUserDesc();
#endif // ZDO_USERDESC_RESPONSE

// set broadcast address mask to support broadcast filtering
NLME_GetRequest(nwkCapabilityInfo, 0, &capabilities);
NLME_SetBroadcastFilter( capabilities );

// Start the device?
if ( devState != DEV_HOLD )
{
ZDOInitDevice( 0 );
}
/*如果devState=DEV_HOLD,则不会调用ZDOInitDevice()来初始化网络
不组网也不进网.LED4闪烁指示这是一个非自动启动模式,等待应
用程序来开启是网络设备*/

else
{
// Blink LED to indicate HOLD_START
HalLedBlink ( HAL_LED_4, 0, 50, 500 );
}

ZDApp_RegisterCBs();
}
****************************************
这里说明三个函数:
ZDAppCheckForHoldKey()
ZDO_Init()
ZDOInitDevice( 0 )

(1)ZDAppCheckForHoldKey()
**************************
void ZDAppCheckForHoldKey( void )
{
#if (defined HAL_KEY) && (HAL_KEY == TRUE)
//个人认为：可以直接通过读取按键来看是否需要采用HOLD_START模式
//如果发现SW_1按下(普通按键吧)/向上(Joystick up),则设置DEV_HOLD;
// Get Keypad directly to see if a HOLD_START is needed.
// Hold down the SW_BYPASS_START key (see OnBoard.h)
// while booting to avoid starting up the device.
if ( HalKeyRead () == SW_BYPASS_START) //HAL_KEY_SW_1
{
// Change the device state to HOLD on start up
devState = DEV_HOLD;
}
#endif // HAL_KEY
}
参见基本问题说明3.
*************************
(2)、ZDO_Init()
*************************
void ZDO_Init( void )
{
/*
//REFLECTOR如果定义了这个编译选项则使用“源绑定”，
In the Zigbee 2006 release,the binding mechanism is implemented in
all devices and is called source binding.绑定机制可以在所有设备中实现,
04版的只能在协调器中实现.*/
// Initialize ZD items
#if defined ( REFLECTOR )
ZDO_EDBind = NULL;
#endif

// Setup the device - type of device to create.
ZDODeviceSetup();
}
*************************
看下ZDODeviceSetup(),具体见各节点启动流程记录.
*************************
//Call set functions depending on the type of device compiled.
//根据编译选项来设置;比如simpleApp中的灯节点,预编译了ZDO_COORDINATOR和
//REFLECTOR和SOFT_START,因此会根据这些来选择开启一些函数功能.
static void ZDODeviceSetup( void )
{
#if defined( ZDO_COORDINATOR ) //编译了ZDO_COORDINATOR
NLME_CoordinatorInit();
#endif

#if defined ( REFLECTOR ) //编译了REFLECTOR
#if defined ( ZDO_COORDINATOR ) //编译了REFLECTOR且编译了ZDO_COORDINATOR
APS_ReflectorInit( APS_REFLECTOR_PUBLIC );
#else //编译了REFLECTOR且编译了路由器或终端
APS_ReflectorInit( APS_REFLECTOR_PRIVATE ); //路由器/终端
#endif
#endif

//没有编译ZDO_COORDINATOR或者编译了SOFT_START
#if !defined( ZDO_COORDINATOR ) || defined( SOFT_START )
NLME_DeviceJoiningInit();
#endif
}
*************************
(3)、ZDOInitDevice()
*************************
uint8 ZDOInitDevice( uint16 startDelay )
{
//初始化设备网络状态为ZDO_INITDEV_NEW_NETWORK_STATE:新的网络状态.
//可能意味着ZCD_NV_STARTUP_OPTION不能恢复，或没有任何网络状态恢复
uint8 networkStateNV = ZDO_INITDEV_NEW_NETWORK_STATE;
uint16 extendedDelay = 0;

devState = DEV_INIT; // Remove the Hold state

//----------------------------------
// Initialize leave control logic
//函数读取NV项目ZCD_NV_LEAVE_CTRL的值,ZDApp_LeaveCtrl指向这个值
ZDApp_LeaveCtrlInit();

// Check leave control reset settings
//设备的断开会造成DEV_HOLD状态,这里面设置的.
ZDApp_LeaveCtrlStartup( &devState, &startDelay );

// Leave may make the hold state come back
//以上两个函数设置了对设备离开时的控制,如果有延时则延时,没有则
//把设备状态设为DEV_HOLD
if ( devState == DEV_HOLD )
//ZDO_INITDEV_LEAVE_NOT_STARTED:该设备没有在网络中，下次调用才启用.
return ( ZDO_INITDEV_LEAVE_NOT_STARTED ); // Don't join - (one time).
//----------------------------------

#if defined ( NV_RESTORE )
// Get Keypad directly to see if a reset nv is needed.
// Hold down the SW_BYPASS_NV key (defined in OnBoard.h)
// while booting(引导) to skip past NV Restore.
if ( HalKeyRead() == SW_BYPASS_NV )
//SW_BYPASS_NV按键处于按下状态时,则避开网络层的NV存储
networkStateNV = ZDO_INITDEV_NEW_NETWORK_STATE; //设备网络状态为新的网络状态

else
{
// Determine if NV should be restored
//函数返回的设备网络状态要么是新的网络状态;要么是恢复的网络状态;以此
//来确定要不要读取NV里相应条目来恢复网络先前状态
networkStateNV = ZDApp_ReadNetworkRestoreState();
}

//如果设备的网络状态为恢复的网络状态
if ( networkStateNV == ZDO_INITDEV_RESTORED_NETWORK_STATE )
{
//恢复设备先前的网络状态参数
//设置devStartMode = MODE_RESUME!!!!
networkStateNV = ZDApp_RestoreNetworkState();
}
else //如果设备的网络状态为新的网络状态,在下面进行处理
{
// Wipe out(清除) the network state in NV
NLME_InitNV();
NLME_SetDefaultNV(); //设置默认NV条目
}
#endif

//如果设备的网络状态为新的网络状态
if ( networkStateNV == ZDO_INITDEV_NEW_NETWORK_STATE )
{
//根据预编译来设置设备新的网络状态参数
ZDAppDetermineDeviceType(); /*!!!!*/

// Only delay if joining network - not restoring network state
extendedDelay = (uint16)((NWK_START_DELAY + startDelay)
+ (osal_rand() & EXTENDED_JOINING_RANDOM_MASK));
}

// Initialize device security
ZDApp_SecInit( networkStateNV );

// Trigger the network start
ZDApp_NetworkInit( extendedDelay );

return ( networkStateNV );
}
*************************
看下五个函数:
ZDApp_LeaveCtrlInit()
ZDApp_ReadNetworkRestoreState()
ZDApp_RestoreNetworkState()
ZDAppDetermineDeviceType()
ZDApp_NetworkInit( extendedDelay )

(3.1)ZDApp_LeaveCtrlInit()
*************************
void ZDApp_LeaveCtrlInit( void )
{
uint8 status;

// Initialize control state
ZDApp_LeaveCtrl = ZDAPP_LEAVE_CTRL_INIT; //0

//初始化一个NV条目.这个函数检查一个NV条目的存在与否.
//如果不存在，它将被建立和初始化随着数据一起传给函数,
//这个函数必须在调用osal_nv_read() or osal_nv_write()之前被调用
status = osal_nv_item_init( ZCD_NV_LEAVE_CTRL, //用户定义的条目ID
sizeof(ZDApp_LeaveCtrl), //条目的大小
&ZDApp_LeaveCtrl ); //指向条目初始化的数据

if ( status == ZSUCCESS ) //这个NV条目存在,则把这个条目值读出来,ZDApp_LeaveCtrl指向它
{
// Read saved control
osal_nv_read( ZCD_NV_LEAVE_CTRL, //用户定义的项目ID
0, //Memory offset into item in bytes.
sizeof( uint8 ), //条目长度
&ZDApp_LeaveCtrl); //数据保存缓冲区指针
}
}
*************************
(3.2)ZDApp_ReadNetworkRestoreState()
如果预编译了NV_RESTORE并且没有手工设置避开NV存储机制,则通过这个函数来判断是否需要恢复设备原先的网络状态.
*************************
//返回要么是新的网络状态;要么是恢复的网络状态
//返回默认为恢复的状态,但如果从读取ZCD_NV_STARTUP_OPTION这个NV条目中
//读取出来的设备网络状态是ZCD_STARTOPT_DEFAULT_NETWORK_STATE，则返回
//新的网络状态ZDO_INITDEV_NEW_NETWORK_STATE
uint8 ZDApp_ReadNetworkRestoreState( void )
{ //设备的网络状态为恢复的网络状态
uint8 networkStateNV = ZDO_INITDEV_RESTORED_NETWORK_STATE;

// Look for the New Network State option. 默认的网络状态
if ( zgReadStartupOptions() & ZCD_STARTOPT_DEFAULT_NETWORK_STATE )
{
//网络状态初始化,即新的网络状态,可能意味着没有任何网络状态恢复
networkStateNV = ZDO_INITDEV_NEW_NETWORK_STATE;
}

return ( networkStateNV );
}
*************************
(3.3)ZDApp_RestoreNetworkState()
如果3.2的函数得到的networkStateNV为恢复的网络状态,则通过这个函数来读取存储在NV里的先前的网络状态.
*************************
uint8 ZDApp_RestoreNetworkState( void )
{
…………

// Initialize NWK NV items
nvStat = NLME_InitNV();

if ( nvStat != NV_OPER_FAILED )
{
if ( NLME_RestoreFromNV() )
{
// Are we a coordinator
//设备的网络状态为恢复的网络状态则恢复先前网络状态参数
//先判断如果短地址是0则设置设备逻辑类型为协调器,并设置
//devStartMode = MODE_RESUME,其它情况设置devStartMode = MODE_RESUME
ZDAppNwkAddr.addr.shortAddr = NLME_GetShortAddr();
if ( ZDAppNwkAddr.addr.shortAddr == 0 ) //如果短地址是0,即协调器
{
ZDO_Config_Node_Descriptor.LogicalType = NODETYPE_COORDINATOR; //!!!!!
}
devStartMode = MODE_RESUME; //MODE_RESUME!!!!!!!!
}
else
nvStat = NV_ITEM_UNINIT;

…………

if ( nvStat == ZSUCCESS )
return ( ZDO_INITDEV_RESTORED_NETWORK_STATE );//说明设备的网络状态已经恢复
else
return ( ZDO_INITDEV_NEW_NETWORK_STATE );
}
*************************
(3.4)ZDAppDetermineDeviceType()
如果设备的网络状态为新的网络状态(第一种情况:未编译NV_RESTORE则在ZDOInitDevice()开头初始化为ZDO_INITDEV_NEW_NETWORK_STATE;第二种情况:编译了NV_RESTORE但ZDApp_ReadNetworkRestoreState()得到的设备网络状态为ZDO_INITDEV_NEW_NETWORK_STATE,即不能恢复或无状态恢复.).这个函数仅适用于编译了SOFT_START的设备,不支持终端设备.比如对于自动启动模式的SampleApp，没有编译SOFT_START.因此本函数对其没作用.具体见各类型设备启动流程.
*************************

* @fn ZDAppDetermineDeviceType()
*
* @brief Determines the type of device to start. Right now
* this only works with the SOFT_START feature. So it doesn't
* support the end device type.
* //终端逻辑类型只能作为终端
*/
//像simpleApp这个例子中，灯节点和中心收集节点都同时预编译了
//SOFT_START和HOLD_AUTO_START;而开关节点和传感器节点都只预编译了
//HOLD_AUTO_START;
//开关节点和传感器节点无论按哪个键都是作为终端设备启动的
//而灯节点和中心收集节点可以选择作为协调器或路由器.
void ZDAppDetermineDeviceType( void )
{
/*
像simpleApp中灯节点和中心收集节点都编译了SOFT_START,
zgDeviceLogicalType在ZGlobals.h中被初始化为ZG_DEVICETYPE_SOFT.而像
开关节点和传感器节点没有编译SOFT_START,则zgDeviceLogicalType被初始化为
ZG_DEVICETYPE_ENDDEVICE.之前卡在这里很长时间,因为像灯节点和中心收集节点
编译过SOFT_START,那zgDeviceLogicalType不就等于ZG_DEVICETYPE_SOFT,最终在
这个函数里也只能执行devStartMode = MODE_JOIN这一句,这与灯节点和中心收集
节点可以通过按键来选择作为协调器或路由器不符,纠结了很久,最后才发现,在按键
选择设备的逻辑类型后,会把这个逻辑类型值写入NV条目ZCD_NV_LOGICAL_TYPE,而
ZDO全局变量zgDeviceLogicalType等于NV条目ZCD_NV_LOGICAL_TYPE的值,通过按键
选择逻辑类型会改变zgDeviceLogicalType的值.比如灯节点按K1选择设备的逻辑类型
为协调器ZG_DEVICETYPE_COORDINATOR,写入NV条目ZCD_NV_LOGICAL_TYPE存储,则此时zgDeviceLogicalType的值即为 ZG_DEVICETYPE_COORDINATOR!!!见基本问题说明5.
*/

if ( zgDeviceLogicalType == ZG_DEVICETYPE_ENDDEVICE )
return;

#if defined ( SOFT_START )//
if ( zgDeviceLogicalType == ZG_DEVICETYPE_COORDINATOR )
{
devStartMode = MODE_HARD; // Start as a coordinator
ZDO_Config_Node_Descriptor.LogicalType = NODETYPE_COORDINATOR;
}
else
{
if ( zgDeviceLogicalType == ZG_DEVICETYPE_ROUTER )
{
softStartAllowCoord = FALSE; // Don't allow coord to start
continueJoining = TRUE;
}

devStartMode = MODE_JOIN; // Assume joining
}
#endif // SOFT_START
}
*************************
(3.5)ZDApp_NetworkInit( extendedDelay )
函数设置触发事件ZDO_NETWORK_INIT.
*************************
void ZDApp_NetworkInit( uint16 delay )
{
if ( delay )
{
// Wait awhile before starting the device
osal_start_timerEx( ZDAppTaskID, ZDO_NETWORK_INIT, delay ); //需要延时
}
else
{
osal_set_event( ZDAppTaskID, ZDO_NETWORK_INIT ); //不需延时
}
}
*************************

****************************************
2、ZDO_StartDevice()
ZDApp_event_loop()对事件ZDO_NETWORK_INIT处理如下:
*************************
if ( events & ZDO_NETWORK_INIT )
{
// Initialize apps and start the network
devState = DEV_INIT;
ZDO_StartDevice( (uint8)ZDO_Config_Node_Descriptor.LogicalType, devStartMode,
DEFAULT_BEACON_ORDER, DEFAULT_SUPERFRAME_ORDER );

// Return unprocessed events
return (events ^ ZDO_NETWORK_INIT);
}
*************************
两个重要的网络状态参数：ZDO_Config_Node_Descriptor.LogicalType和devStartMode,
ZDO_Config_Node_Descriptor.LogicalType的初始化见基本问题说明6.devStartMode的初始化见4.但两个参数的值可以通过函数(3.3)ZDApp_RestoreNetworkState()[如果编译了NV_RESTORE]和函数(3.4)ZDAppDetermineDeviceType()来改变.
*************************
void ZDO_StartDevice( byte logicalType, devStartModes_t startMode, byte beaconOrder, byte superframeOrder )
{
ZStatus_t ret;

ret = ZUnsupportedMode;

#if defined(ZDO_COORDINATOR)

if ( logicalType == NODETYPE_COORDINATOR )
{
if ( startMode == MODE_HARD ) //MODE_HARD
{
devState = DEV_COORD_STARTING; //Started as Zigbee Coordinator
ret = NLME_NetworkFormationRequest( zgConfigPANID, zgDefaultChannelList,
zgDefaultStartingScanDuration, beaconOrder,
superframeOrder, false );
}
else if ( startMode == MODE_RESUME ) //MODE_RESUME 恢复
{
// Just start the coordinator
devState = DEV_COORD_STARTING;
ret = NLME_StartRouterRequest( beaconOrder, beaconOrder, false );
}
else //错误，启动模式未知
{
…………
}
}
#endif // !ZDO_COORDINATOR

if ( logicalType == NODETYPE_ROUTER || logicalType == NODETYPE_DEVICE )
{
if ( (startMode == MODE_JOIN) || (startMode == MODE_REJOIN) )
{
devState = DEV_NWK_DISC; //Discovering PAN's to join

#if defined( MANAGED_SCAN )
ZDOManagedScan_Next();
ret = NLME_NetworkDiscoveryRequest( managedScanChannelMask, BEACON_ORDER_15_MSEC );
#else
ret = NLME_NetworkDiscoveryRequest( zgDefaultChannelList, zgDefaultStartingScanDuration );
#endif
}
else if ( startMode == MODE_RESUME )//MODE_RESUME 恢复
{
if ( logicalType == NODETYPE_ROUTER )
{
…………
nwk_ScanJoiningOrphan(&scanCnf);

ret = ZSuccess;
}
else
{
devState = DEV_NWK_ORPHAN; //孤儿
ret = NLME_OrphanJoinRequest( zgDefaultChannelList,
zgDefaultStartingScanDuration );
}
}
else
{
…………
}
}
…………
}
*************************

3、协调器建网,路由器/终端入网的回调函数
(1)ZDO_NetworkFormationConfirmCB()：协调器建立网络请求的回调函数
* @brief This function reports the results of the request to
* initialize a coordinator in a network.
*
* @param Status - Result of NLME_NetworkFormationRequest()

(2)ZDO_StartRouterConfirmCB():作为路由器启动请求的回调函数
* @brief This function reports the results of the request to
* start functioning as a router in a network.
*
* @param Status - Result of NLME_StartRouterRequest()

(3)ZDO_JoinConfirmCB():路由器/终端加入网络请求的回调函数
* @brief This function allows the next hight layer to be notified
* of the results of its request to join itself or another
* device to a network.
*
* @param Status - Result of NLME_JoinRequest()

(4) ZDO_NetworkDiscoveryConfirmCB():路由器/终端发现网络请求的回调函数
* @fn ZDO_NetworkDiscoveryConfirmCB
*
* @brief This function returns a choice of PAN to join.
*
* @param ResultCount - Number of routers discovered
* @param NetworkList - Pointer to list of network descriptors

四种回调函数会分别触发ZDAppTaskID相应事件:
ZDO_NetworkFormationConfirmCB()： osal_set_event( ZDAppTaskID, ZDO_NETWORK_START );
ZDO_StartRouterConfirmCB():osal_set_event( ZDAppTaskID, ZDO_ROUTER_START );
ZDO_JoinConfirmCB():ZDApp_SendMsg( ZDAppTaskID, ZDO_NWK_JOIN_IND, sizeof (osal_event_hdr_t), (byte*)NULL );
ZDO_NetworkDiscoveryConfirmCB(): ZDApp_SendMsg( ZDAppTaskID, ZDO_NWK_DISC_CNF, sizeof (ZDO_NetworkDiscoveryCfm_t), (byte *)&msg );

参照上面ZDO_StartDevice()函数,可以看到相应功能的请求函数.
回调函数具体调用流程参见种类型设备的启动流程.

说明：
1、本文为个人学习笔记,纯属个人理解,错误不可避免,仅供参考.随时更新！
2、细节基本不管,遇到问题再作分析,程序注释为个人原始注释内容,记录有些仓促！
3、欢迎交流,转载请注明出处,谢谢！

2010.7.09 ～XF