Z-Stack API - CC2530/CC2538

Z-Stack Application Programming Interface

Document Number: SWRA195

Скачать оригинал (eng)

Документ API для приложений, использующих базовый стек ZigBee в качестве модели интерфейса приложения для данных и плоскости управления. Сырой перевод.

 

 

 

 

 
 
 
 
 
Содержание
1. ВВЕДЕНИЕ.........................1
1.1 ЦЕЛЬ .................................. 1
1.2 ОБЛАСТЬ ПРИМЕНЕНИЯ ............................................... 1
1.3 АКРОНИМЫ ........................................... 1
2. ОБЗОР СЛОЯ .......................................... 2
2.1 BDB ............................................. 2
2.2 ZDO ......................................... 2
2.3 AF .......................................... 2
2,4 APS ........................................... 2
2,5 NWK ................................................ . 2
2.6 GREEN POWER ........................ 2
2.7 ZMAC ............................................. 2
3. ИНТЕРФЕЙС ПРОГРАММИРОВАНИЯ ПРИЛОЖЕНИЙ ............................... 3
3.1 ПОВЕДЕНИЕ БАЗОВЫХ УСТРОЙСТВ (BDB) .................................... 3
3.1.1 Обзор ............................................. 3
3.1.2 Общая конфигурация BDB и использование в сети ....................................... 3
3.1.2.1 bdb_SetIdentifyActiveEndpoint () ................................. 3
3.1.2.2 bdb_setChannelAttribute () ................................... 4
3.1.2.3 bdb_RegisterIdentifyTimeChangeCB () .............................. 4
3.1.2.4 bdb_RegisterBindNotificationCB () ................................ 4
3.1.2.5 bdb_RegisterCommissioningStatusCB () ............................ 5
3.1.2.6 bdb_setCommissioningGroupID () .................................... 5
3.1.2.7 bdb_RepAddAttrCfgRecordDefaultToList () .............. 6
3.1.2.8 bdb_RegisterForFilterNwkDesc () ............................ 6
3.1.2.9 bdb_TouchlinkSetAllowStealing () .............................. 7
3.1.2.10 bdb_RegisterTouchlinkTargetEnableCB () ..................... 7
3.1.3 Конфигурация безопасности BDB .........................7
3.1.3.1 bdb_GenerateInstallCodeCRC () ........................... 7
3.1.3.2 bdb_setJoinUsesInstallCodeKey () .............................. 8
3.1.3.3 bdb_setTCRequireKeyExchange () .......................... 8
3.1.3.4 bdb_addInstallCode () ....................................... 8
3.1.3.5 bdb_RegisterTCLinkKeyExchangeProcessCB ()..............................9
3.1.3.6 bdb_setActiveCentralizedLinkKey ().................................. 9
3.1.3.7 bdb_RegisterCBKETCLinkKeyExchangeCB ()................... 10
3.1.4 BDB Application Runtime API.................................... 10
3.1.4.1 bdb_StartCommissioning ()................................................. 10
3.1.4.2 bdb_initialize ()...............................................11
3.1.4.3 bdb_getZCLFrameCounter () ................................... 11
3.1.4.4 bdb_RepChangedAttrValue () ................................. 12
3.1.4.5 bdb_ZedAttemptRecoverNwk () ..................................... 12
3.1.4.6 bdb_GetFBInitiatorStatus () ..................................... 12
3.1.4.7 bdb_isDeviceNonFactoryNew () ................................ 13
3.1.4.8 bdb_nwkDescFree () ........................................... 13
3.1.4.9 bdb_CBKETCLinkKeyExchangeAttempt () ........................... 13
3.1.4.10 touchLinkTarget_EnableCommissioning () .............................. 14
3.1.4.11 touchLinkTarget_DisableCommissioning () ............................. 14
3.1.4.12 touchLinkTarget_GetTimer () ................................ 15
3.1.4.13 bdb_TouchlinkGetAllowStealing () .................................. 15
3.1.4.14 bdb_resetLocalAction () ................................................ 15
3.1.4.15 bdb_StopInitiatorFindingBinding () .................................... 16
3.1.5 API обратных вызовов времени выполнения приложения BDB .................................... 16
3.1.5.1 обратный вызов bdbGCB_IdentifyTimeChange_t ................................. 16
3.1.5.2 обратный вызов bdbGCB_BindNotification_t ......................................... 16
3.1.5.3 обратный вызов bdbGCB_CommissioningStatus_t ........................ 17
3.1.5.4 обратный вызов bdbGCB_CBKETCLinkKeyExchange_t ..................... 18
3.1.5.5 обратный вызов bdbGCB_TCLinkKeyExchangeProcess_t ............................ 19
3.1.5.6 обратный вызов bdbGCB_FilterNwkDesc_t ............................................ 19
3.2 ОБЪЕКТЫ УСТРОЙСТВА ZIGBEE (ZDO) ............................................... 20
3.2.1 Обзор .............................................. ............................................ 20
3.2.2 Запуск сети устройства ZDO ............................................ 20
3.2.2.1 ZDOInitDeviceEx () ....................................................... 20
3.2.2.2 ZDOInitDevice () ................................................. 21
3.2.3 Обратные вызовы сообщений ZDO ....................................... 21
3.2.3.1 ZDO_RegisterForZDOMsg () .................................. 21
3.2.3.2 ZDO_RemoveRegisteredCB () ............................... 22
3.2.4 ZDO Discovery API ............................................................ ..... 22
3.2.4.1 ZDP_NwkAddrReq () ......................................... 23
3.2.4.2 ZDP_NWKAddrRsp () ..................................... 24
3.2.4.3 ZDP_IEEEAddrReq () .................................. 25
3.2.4.4 ZDP_IEEEAddrRsp () ...................................... 26
3.2.4.5 ZDP_NodeDescReq () .............................. 27
3.2.4.6 ZDP_NodeDes............................... 27
3.2.4.7 ZDP_PowerDescReq().................................28
3.2.4.8 ZDP_PowerDescMsg().............................................. 28
3.2.4.9 ZDP_SimpleDescReq()..........................................29
3.2.4.10 ZDP_SimpleDescRsp()............................29
3.2.4.11 ZDP_ComplexDescReq()............................... 30
3.2.4.12 ZDP_ActiveEPIFReq ()...........................30
3.2.4.13 ZDP_ActiveEPIFRsp()............................. 31
3.2.4.14 ZDP_MatchDescReq()............................31
3.2.4.15 ZDP_MatchDescRsp()...............................32
3.2.4.16 ZDP_UserDescSet().............................33
3.2.4.17 ZDP_UserDescConf()................................33
3.2.4.18 ZDP_UserDescReq()........................................... 34
3.2.4.19 ZDP_UserDescRsp().................................34
3.2.4.20 ZDP_DeviceAnnce()...................................35
3.2.4.21 ZDP_ServerDiscReq()............................... 35
3.2.4.22 ZDP_ServerDiscRsp()...................................... 36
3.2.5 ZDO Binding API........................................................................ 37
3.2.5.1 ZDP_EndDeviceBindReq()...................................... 37
3.2.5.2 ZDP_EndDeviceBindRsp().......................38
3.2.5.3 ZDP_BindReq()................................. 38
3.2.5.4 ZDP_BindRsp()................................... 39
3.2.5.5 ZDP_UnbindReq ()........................................39
3.2.5.6 ZDP_UnbindRsp()............................... 40
3.2.6 ZDO Management API............................. 41
3.2.6.1 ZDP_MgmtNwkDiscReq().................................... 41
3.2.6.2 ZDP_MgmtNwkDiscRsp()................................ 42
3.2.6.3 ZDP_MgmtLqiReq().....................................43
3.2.6.4 ZDP_MgmtLqiRsp().......................................43
3.2.6.5 ZDP_MgmtRtgReq ()....................................... 44
3.2.6.6 ZDP_MgmtRtgRsp().................................44
3.2.6.7 ZDP_MgmtBindReq ()................................... 45
3.2.6.8 ZDP_MgmtBindRsp()................................45
3.2.6.9 ZDP_MgmtLeaveReq ()...................................... 46
3.2.6.10 ZDP_MgmtLeaveRsp()...................................47
3.2.6.11 ZDP_MgmtDirectJoinReq ()............................ 47
3.2.6.12 ZDP_MgmtDirectJoinRsp()................................48
3.2.6.13 ZDP_MgmtPermitJoinReq().................................48
3.2.6.14 ZDP_MgmtPermitJoinRsp().................................... 49
3.2.6.15 ZDP_MgmtNwkUpdateReq().........................49
3.2.6.16 ZDP_MgmtNwkUpdateNotify()..........................50
3.2.7 ZDO Parsing Functions............................................... 50
3.2.7.1 ZDO_ParseAddrRsp.................................... 51
3.2.7.2 ZDO_ParseNodeDescRsp..............................51
3.2.7.3 ZDO_ParsePowerDescRsp..................................... 51
3.2.7.4 ZDO_ParseSimpleDescRsp...................................... 52
3.2.7.5 ZDO_ParseEPListRsp.........................................52
3.2.7.6 ZDO_ParseBindRsp...........................................52
3.2.7.7 ZDO_ParseMgmNwkDiscRsp................................53
3.2.7.8 ZDO_ParseMgmtLqiRsp.......................................... 53
3.2.7.9 ZDO_ParseMgmtRtgRsp............................................53
3.2.7.10 ZDO_ParseMgmtBindRsp...................................54
3.2.7.11 ZDO_ParseMgmtDirectJoinRsp............................... 54
3.2.7.12 ZDO_ParseMgmtLeaveRsp.........................................54
3.2.7.13 ZDO_ParseMgmtPermitJoinRsp.......................... 55
3.2.7.14 ZDO_ParseUserDescRsp...............................55
3.2.7.15 ZDO_ParseServerDiscRsp....................................55
3.2.7.16 ZDO_ParseEndDeviceBindReq..................................56
3.2.7.17 ZDO_ParseBindUnbindReq............................... 56
3.2.7.18 ZDO_ParseUserDescConf............................... 57
3.2.7.19 ZDO_ParseDeviceAnnce...........................................57
3.2.7.20 ZDO_ParseMgmtNwkUpdateNotify............................... 57
3.2.8 ZDO Network Manager...............................................................58
3.2.8.1 NwkMgr_SetNwkManager..................................................58
3.3 APPLICATION FRAMEWORK (AF)....................................................58
3.3.1 Overview...........................................................58
3.3.1.1 Endpoint Management.........................................58
3.3.1.2 Sending Data....................................................63
3.3.1.3 Receiving Data.............................................................65
3.4 APPLICATION SUPPORT SUB-LAYER (APS)............... 65
3.4.1 Overview.....................................................................................65
3.4.2 Binding Table Management....................................... 66
3.4.2.1 Binding Record Structure – BindingEntry_t.........................66
3.4.2.2 Binding Table Maintenance..................................66
3.4.2.3 Binding Table Searching...........................................69
3.4.2.4 Binding Table Statistics.................................... 70
3.4.2.5 Binding Table Non-Volatile Storage.............................. 71
3.4.3 Group Table Management...................................................71
3.4.3.1 Group Table Structures............................................... 72
3.4.3.2 Group Table Maintenance..................................72
3.4.3.3 Group Table Searching................................. 73
3.4.3.4 Group Table Non-Volatile Storage...................75
3.4.4 Quick Address Lookup..................................76
3.4.4.1 APSME_LookupExtAddr()................................ 76
3.4.4.2 APSME_ LookupNwkAddr ().............................. 76
3.5 NETWORK LAYER (NWK).........................................77
3.5.1 Network Management...........................................77
3.5.1.1 NLME_NetworkDiscoveryRequest()........................ 77
3.5.1.2 NLME_NwkDiscReq2()..........................................78
3.5.1.3 NLME_NwkDiscTerm()............................................79
3.5.1.4 NLME_NetworkFormationRequest().....................79
3.5.1.5 NLME_StartRouterRequest()....................................... 80
3.5.1.6 NLME_JoinRequest()......................................80
3.5.1.7 NLME_ReJoinRequest()........................................81
3.5.1.8 NLME_OrphanJoinRequest()................................81
3.5.1.9 NLME_PermitJoiningRequest()............................ 82
3.5.1.10 NLME_DirectJoinRequest()......................... 82
3.5.1.11 NLME_LeaveReq()................................ 83
3.5.1.12 NLME_RemoveChild()........................ 83
3.5.1.13 NwkPollReq()....................................... 84
3.5.1.14 NLME_SetPollRate().....................................84
3.5.1.15 NLME_SetQueuedPollRate()................................. 84
3.5.1.16 NLME_SetResponseRate().......................................85
3.5.1.17 NLME_RouteDiscoveryRequest()........................85
3.5.2 Address Management....................................................... 86
3.5.2.1 Network Variables and Utility Functions.................... 86
3.5.3 Network Non-Volitile Storage...................................................... 90
3.5.3.1 NLME_UpdateNV()...................................................... 90
3.5.4 PAN ID Conflict..................................................................... 90
3.5.4.1 NLME_SendNetworkReport ()...............................91
3.5.4.2 NLME_SendNetworkUpdate().......................... 91
3.5.5 Inter-PAN Transmission........................................92
3.5.5.1 StubAPS_SetInterPanChannel()................. 92
3.5.5.2 StubAPS_SetIntraPanChannel().............................. 92
3.5.5.3 StubAPS_InterPan()......................................92
3.5.5.4 StubAPS_RegisterApp().................................93
3.6 GREEN POWER LAYER............................................ 93
3.6.1 GP_DataInd()...................................93
3.6.2 GP_DataReq()...................................................93
3.6.3 GP_DataCnf().................................................. 94
3.6.4 GP_SecReq()....................................................... 94
3.6.5 GP_SecRsp()...............................................................94
3.7 ZMAC LAYER (ZMAC).....................................................95
3.7.1 ZMacSetTransmitPower()......................................... 95
3.7.2 ZMacLqiAdjustMode()......................................... 95
 

1. Введение

1.1 Цель

Этот документ предоставляет интерфейс прикладных программистов (API) для компонентов Z-Stack ™, предоставляемых как часть Z-Stack-версии, совместимой с ZigBee-2015.

1.2 Область применения

Этот документ перечисляет реализованный API всех компонентов, предоставляемых в рамках Z-Stack-релиза, совместимого с ZigBee-2015. Детали, относящиеся к каждому интерфейсу, включая структуры данных и вызовы функций, указаны достаточно подробно, чтобы программист мог понять и использовать их во время разработки. API представлены сверху (на уровне приложения) вниз.

1.3 Сокращения

AF Application Framework
AIB APS Information Base Информационная база
API Application Programming Interface Интерфейс прикладного программирования
APS Application Support Sub-Layer Подуровень поддержки приложений
APSDE APS Date Entity
APSME APS Management Entity
ASDU APS Service Datagram Unit Сервисная датаграмма
BDB Base Device Behavior Поведение базового устройства
GP Green Power
LQI Link Quality Indicator
MAC Media Access Control
MSG Message Сообщение
NHLE Next Higher Layer Entity Следующий объект более высокого уровня
NIB Network Information Base Сетевая информационная база
NWK Network Сеть
NV Non-Volatile memory Энергонезависимая память
PAN Personal Area Network Персональная сеть
STAR Топология сети, состоящая из одного главного устройства и нескольких подчиненных устройств
ZDO ZigBee Device Object 

2. Обзор слоев

В этом разделе представлен обзор слоев, описанных в этом документе.

2.1 BDB

Уровень поведения базового устройства определяет среду, инициализацию, ввод в эксплуатацию и рабочие процедуры базового устройства, работающего в стеке ZigBee-PRO, для обеспечения взаимодействия профилей. Z-Stack BDB предоставляет структуры данных и интерфейс, которые требуются разработчику приложения для соответствия этой спецификации. Он также предоставляет общую реализацию атрибутов отчетности для приложений, которые поддерживают кластеры с отчетными атрибутами.

2.2 ZDO

Слой ZigBee Device Objects (ZDO) предоставляет функциональные возможности для управления устройством ZigBee. API ZDO предоставляет интерфейс для конечных точек приложений для управления функциями для координаторов, маршрутизаторов или конечных устройств ZigBee, который включает создание, обнаружение и присоединение к сети ZigBee; привязка конечных точек приложения; и управление безопасностью.

2.3 AF

Интерфейс Application Framework (AF) поддерживает интерфейс конечных точек (включая ZDO) с базовым стеком. Z-Stack AF предоставляет структуры данных и вспомогательные функции, которые требуются разработчику для построения описания устройства, и является мультиплексором конечной точки для входящих сообщений.

2.4 APS

API подуровня поддержки приложений (APS) предоставляет общий набор служб поддержки, которые используются как ZDO, так и объектами приложения, определенными производителем.

2.5 NWK

Сетевой уровень ZigBee (NWK) предоставляет услуги управления и передачи данных для компонентов более высокого уровня (приложения).

2.6 Green Power

Службы данных уровня Green Power, которые позволяют более высокому уровню отправлять или получать данные от заглушек Green Power.
Эти заглушки используются для взаимодействия с устройствами зеленого питания либо для ввода в эксплуатацию, либо для нормальной работы в сети.

2.7 ZMAC

Уровень ZMAC обеспечивает интерфейс между 802.15.4 MAC и уровнями ZigBee NWK.

3. Интерфейс прикладного программирования

В этом разделе представлена ​​сводная информация о наиболее часто используемых структурах данных, реализованных в Z-Stack, а также API для доступа к ключевым функциям, предоставляемым указанным уровнем.

3.1 Поведение базового устройства (BDB)

В этом разделе перечислены все вызовы функций, предоставляемые уровнем BDB, которые необходимы для реализации всех команд и ответов, определенных в поведении базового устройства (BDB), а также другие функции для обеспечения взаимодействия между различными устройствами ZigBee. Все функции API BDB классифицируются по общим функциям и функциям настройки безопасности, а также по функциям, которые могут вызываться приложением во время выполнения. Каждая категория обсуждается в следующих разделах.

3.1.1 Обзор

BDB описывает, как обычное устройство ZigBee будет входить и вести себя в сети ZigBee, обеспечивая совместимость профилей между устройствами. Более конкретно, спецификация BDB определяет следующие функциональные возможности:
  • Процедуры инициализации
  • Процедуры ввода в эксплуатацию
  • Процедуры сброса
  • Процедуры безопасности
  • Атрибуты отчетности
Все эти процедуры выполняются с использованием существующего API из других уровней, таких как ZDO, ZCL, NWK и APS.

3.1.2 Общая конфигурация и использование BDB в сети

Весь API BDB содержится в одном заголовочном файле bdb_interface.h. На основе функциональных возможностей BDB и методов, определенных в заголовочном файле, эти функции API представлены в следующих подразделах:
  • Функции, которые приложение должно использовать для настройки параметров BDB.
  • Функции, используемые приложением для настройки параметров безопасности BDB.
  • Функции, вызываемые приложениями после запуска комиссии BDB и во время выполнения приложения.
  • Функции обратного вызова, предоставляемые BDB для уведомления о событиях или выполнения пользовательского кода приложения в определенных частях процедуры ввода в эксплуатацию BDB.

3.1.2.1 bdb_SetIdentifyActiveEndpoint ()

Установите конечную точку, которая будет выполнять поиск и привязку (либо цель, либо инициатор).

Прототип

ZStatus_t bdb_SetIdentifyActiveEndpoint (uint8 activeEndpoint);

Детали параметров

activeEndpoint - активная конечная точка, с которой выполняют поиск и привязку. Если установлено 0xFF, все приложения будут предприняты попытки с конечными точками с идентификатором.

Возврат

ZStatus_t – значения состояния, определенные в ZStatus_t in ZComDef.h.

 

Ваша оценка: Нет Средняя: 5.5 (2 голосов)