ZIGBEE report机制分析

sick

ZIGBEE提供了report机制（现在只学习了send， receive还没学习）

主要目的是实现attribute属性的report功能，即提供了一种服务端和客户端数据同步的机制

以EMBER的HasampleLightSoc来具体看看report的实现过程，具体步骤如下：

1、设置report参数

1. void emberAfMainInitCallback(void)
   
2. {
   
3.   EmberAfPluginReportingEntry reportingEntry;
   
4.   reportingEntry.direction = EMBER_ZCL_REPORTING_DIRECTION_REPORTED;    // 设置report方向为send     
   
5.   reportingEntry.endpoint = emberAfPrimaryEndpoint();　　　　　　　　　　  // 设置端点
   
6.   reportingEntry.clusterId = ZCL_ON_OFF_CLUSTER_ID;　　　　　　　　　　　  // 设置簇ID
   
7.   reportingEntry.attributeId = ZCL_ON_OFF_ATTRIBUTE_ID;　　　　　　　　　 // 设置属性ID
   
8.   reportingEntry.mask = CLUSTER_MASK_SERVER;　　　　　　　　　　　　　　    // 设置簇掩码（确定是服务端还是客户端）　　
   
9.   reportingEntry.manufacturerCode = EMBER_AF_NULL_MANUFACTURER_CODE;　　// 设置厂商ID
   
10.   reportingEntry.data.reported.minInterval = MIN_INTERVAL_S;　　　　　　 // 设置最小数据发送周期
    
11.   reportingEntry.data.reported.maxInterval = MAX_INTERVAL_S;　　　　　　 // 设置最大数据发送周期
    
12.   reportingEntry.data.reported.reportableChange = 0; // unused     　
    
13.   emberAfPluginReportingConfigureReportedAttribute(&reportingEntry);
    
14. }

复制代码

2、report参数解析和配置过程

1. EmberAfStatus emberAfPluginReportingConfigureReportedAttribute(const EmberAfPluginReportingEntry* newEntry)
   
2. {
   
3.   EmberAfAttributeMetadata *metadata;
   
4.   EmberAfPluginReportingEntry entry;
   
5.   EmberAfStatus status;
   
6.   uint8_t i, index = NULL_INDEX;
   
7.   bool initialize = true;
   
8. 
   
9.   // Verify that we support the attribute and that the data type matches. 根据参数寻找匹配的属性，并且返回指向改属性的地址
   
10.   metadata = emberAfLocateAttributeMetadata(newEntry->endpoint,
    
11.                                             newEntry->clusterId,
    
12.                                             newEntry->attributeId,
    
13.                                             newEntry->mask,
    
14.                                             newEntry->manufacturerCode);
    
15.   if (metadata == NULL) {
    
16.     return EMBER_ZCL_STATUS_UNSUPPORTED_ATTRIBUTE;
    
17.   }
    
18. 
    
19.   // Verify the minimum and maximum intervals make sense. 核对report周期最大值，最小值确定是否在范围内
    
20.   if (newEntry->data.reported.maxInterval != 0
    
21.       && (newEntry->data.reported.maxInterval
    
22.           < newEntry->data.reported.minInterval)) {
    
23.     return EMBER_ZCL_STATUS_INVALID_VALUE;
    
24.   }
    
25. 
    
26.   // Check the table for an entry that matches this request and also watch for
    
27.   // empty slots along the way.  If a report exists, it will be overwritten
    
28.   // with the new configuration.  Otherwise, a new entry will be created and
    
29.   // initialized.   确定reportingTable是否有和需要配置的参数一样的，如果有在后面会更新report周期等参数，如果没有添加一个新的entry
    
30.   for (i = 0; i < EMBER_AF_PLUGIN_REPORTING_TABLE_SIZE; i++) {
    
31.     emAfPluginReportingGetEntry(i, &entry);
    
32.     if (entry.direction == EMBER_ZCL_REPORTING_DIRECTION_REPORTED
    
33.         && entry.endpoint == newEntry->endpoint
    
34.         && entry.clusterId == newEntry->clusterId
    
35.         && entry.attributeId == newEntry->attributeId
    
36.         && entry.mask == newEntry->mask
    
37.         && entry.manufacturerCode == newEntry->manufacturerCode) {
    
38.       initialize = false;
    
39.       index = i;
    
40.       break;
    
41.     } else if (entry.endpoint == EMBER_AF_PLUGIN_REPORTING_UNUSED_ENDPOINT_ID
    
42.                && index == NULL_INDEX) {
    
43.       index = i;
    
44.     }
    
45.   }
    
46. 
    
47.   // If the maximum reporting interval is 0xFFFF, the device shall not issue
    
48.   // reports for the attribute and the configuration information for that
    
49.   // attribute need not be maintained.   如果maxInterval = 0xFFFF，删除该report配置
    
50.   if (newEntry->data.reported.maxInterval == 0xFFFF) {
    
51.     if (!initialize) {
    
52.       removeConfigurationAndScheduleTick(index);
    
53.     }
    
54.     return EMBER_ZCL_STATUS_SUCCESS;
    
55.   }
    
56. 
    
57.   if (index == NULL_INDEX) {
    
58.     return EMBER_ZCL_STATUS_INSUFFICIENT_SPACE;
    
59.   } else if (initialize) {
    
60.     entry.direction = EMBER_ZCL_REPORTING_DIRECTION_REPORTED;
    
61.     entry.endpoint = newEntry->endpoint;
    
62.     entry.clusterId = newEntry->clusterId;
    
63.     entry.attributeId = newEntry->attributeId;
    
64.     entry.mask = newEntry->mask;
    
65.     entry.manufacturerCode = newEntry->manufacturerCode;
    
66.     emAfPluginReportVolatileData[index].lastReportTimeMs = halCommonGetInt32uMillisecondTick();
    
67.     emAfPluginReportVolatileData[index].lastReportValue = 0;
    
68.   }
    
69. 
    
70.   // For new or updated entries, set the intervals and reportable change.
    
71.   // Updated entries will retain all other settings configured previously.   不论是新的entry还是更新旧的entry，report周期等参数需要被更新
    
72.   entry.data.reported.minInterval = newEntry->data.reported.minInterval;
    
73.   entry.data.reported.maxInterval = newEntry->data.reported.maxInterval;
    
74.   entry.data.reported.reportableChange = newEntry->data.reported.reportableChange;
    
75. 
    
76.   // Give the application a chance to review the configuration that we have
    
77.   // been building up.  If the application rejects it, we just do not save the
    
78.   // record.  If we were supposed to add a new configuration, it will not be
    
79.   // created.  If we were supposed to update an existing configuration, we will
    
80.   // keep the old one and just discard any changes.  So, in either case, life
    
81.   // continues unchanged if the application rejects the configuration.     给应用层传递配置信息，如果应用层拒绝，配置不生效，否则配置成功，开启report功能
    
82.   status = emberAfPluginReportingConfiguredCallback(&entry);
    
83.   if (status == EMBER_ZCL_STATUS_SUCCESS) {
    
84.     emAfPluginReportingSetEntry(index, &entry);
    
85.     scheduleTick();
    
86.   }
    
87.   return status;
    
88. }

复制代码

3、report参数设置完毕后，根据当前时间，设置的发送周期，来确定emberAfPluginReportingTickEventControl事件什么时候被激活，进而进行report的发送。

1. static void scheduleTick(void)
   
2. {
   
3.   uint32_t delayMs = MAX_INT32U_VALUE;
   
4.   uint8_t i;
   
5.   for (i = 0; i < EMBER_AF_PLUGIN_REPORTING_TABLE_SIZE; i++) {
   
6.     EmberAfPluginReportingEntry entry;
   
7.     emAfPluginReportingGetEntry(i, &entry);
   
8.     if (entry.endpoint != EMBER_AF_PLUGIN_REPORTING_UNUSED_ENDPOINT_ID
   
9.         && entry.direction == EMBER_ZCL_REPORTING_DIRECTION_REPORTED) {
   
10.       uint32_t minIntervalMs = (entry.data.reported.minInterval
    
11.                                 * MILLISECOND_TICKS_PER_SECOND);
    
12.       uint32_t maxIntervalMs = (entry.data.reported.maxInterval
    
13.                                 * MILLISECOND_TICKS_PER_SECOND);
    
14.       uint32_t elapsedMs = elapsedTimeInt32u(emAfPluginReportVolatileData[i].lastReportTimeMs,
    
15.                                            halCommonGetInt32uMillisecondTick());
    
16.       uint32_t remainingMs = MAX_INT32U_VALUE;
    
17.       if (emAfPluginReportVolatileData[i].reportableChange) {   // 如果attribute有变化，并且两次report时间大于minInterval，则report，否则延时等待相应时间   
    
18.         remainingMs = (minIntervalMs < elapsedMs
    
19.                        ? 0
    
20.                        : minIntervalMs - elapsedMs);
    
21.       } else if (maxIntervalMs) {                               // 如果attribute没变化，并且两次report时间大于maxInterval，则report，否则延时等待相应时间
    
22.         remainingMs = (maxIntervalMs < elapsedMs
    
23.                        ? 0
    
24.                        : maxIntervalMs - elapsedMs);
    
25.       }
    
26.       if (remainingMs < delayMs) {         // 寻找所有reportint table里面的延时时间中最短的一个，然后设置emberAfPluginReportingTickEventControl事件
    
27.         delayMs = remainingMs;
    
28.       }
    
29.     }
    
30.   }
    
31.   if (delayMs != MAX_INT32U_VALUE) {
    
32.     emberAfDebugPrintln("sched report event for: 0x%4x", delayMs);
    
33.     emberAfEventControlSetDelayMS(&emberAfPluginReportingTickEventControl,
    
34.                                   delayMs);
    
35.   } else {
    
36.     emberAfDebugPrintln("deactivate report event");
    
37.     emberEventControlSetInactive(emberAfPluginReportingTickEventControl);
    
38.   }
    
39. }

复制代码

4、当设置了emberAfPluginReportingTickEventControl事件后，emberAfPluginReportingTickEventHandler会相应的被执行

1. // EmberEventData structs used to populate the EmberEventData table
   
2. #define EMBER_AF_GENERATED_EVENTS   \
   
3.   { &emberAfIdentifyClusterServerTickCallbackControl1, emberAfIdentifyClusterServerTickCallbackWrapperFunction1 }, \
   
4.   { &emberAfPluginConcentratorUpdateEventControl, emberAfPluginConcentratorUpdateEventHandler }, \
   
5.   { &emberAfPluginEzmodeCommissioningStateEventControl, emberAfPluginEzmodeCommissioningStateEventHandler }, \
   
6.   { &emberAfPluginFormAndJoinCleanupEventControl, emberAfPluginFormAndJoinCleanupEventHandler }, \
   
7.   { &emberAfPluginIdentifyFeedbackProvideFeedbackEventControl, emberAfPluginIdentifyFeedbackProvideFeedbackEventHandler }, \
   
8.   { &emberAfPluginNetworkFindTickEventControl, emberAfPluginNetworkFindTickEventHandler }, \
   
9.   { &emberAfPluginReportingTickEventControl, emberAfPluginReportingTickEventHandler }, \     // 事件和相应处理函数关联表
   
10.   { &buttonEventControl, buttonEventHandler }, \
    
11. 
    
12. 
    
13. void emberAfPluginReportingTickEventHandler(void)
    
14. {
    
15.   EmberApsFrame *apsFrame = NULL;
    
16.   EmberAfStatus status;
    
17.   EmberAfAttributeType dataType;
    
18.   uint16_t manufacturerCode;
    
19.   uint8_t readData[READ_DATA_SIZE];
    
20.   uint8_t i, dataSize;
    
21.   bool clientToServer;
    
22.   EmberBindingTableEntry bindingEntry;
    
23.   uint8_t index, reportSize = 0, currentPayloadMaxLength = 0, smallestPayloadMaxLength;
    
24. 
    
25.   for (i = 0; i < EMBER_AF_PLUGIN_REPORTING_TABLE_SIZE; i++) {
    
26.     EmberAfPluginReportingEntry entry;
    
27.     uint32_t elapsedMs;
    
28.     emAfPluginReportingGetEntry(i, &entry);
    
29.     // We will only send reports for active reported attributes and only if a
    
30.     // reportable change has occurred and the minimum interval has elapsed or
    
31.     // if the maximum interval is set and has elapsed.    判断当前report条件是否满足（主要是时间），如果不满足继续寻找，直到找到符合的
    
32.     elapsedMs = elapsedTimeInt32u(emAfPluginReportVolatileData[i].lastReportTimeMs,
    
33.                                   halCommonGetInt32uMillisecondTick());
    
34.     if (entry.endpoint == EMBER_AF_PLUGIN_REPORTING_UNUSED_ENDPOINT_ID
    
35.         || entry.direction != EMBER_ZCL_REPORTING_DIRECTION_REPORTED
    
36.         || (elapsedMs
    
37.             < entry.data.reported.minInterval * MILLISECOND_TICKS_PER_SECOND)
    
38.         || (!emAfPluginReportVolatileData[i].reportableChange
    
39.             && (entry.data.reported.maxInterval == 0
    
40.                 || (elapsedMs
    
41.                     < (entry.data.reported.maxInterval
    
42.                        * MILLISECOND_TICKS_PER_SECOND))))) {
    
43.       continue;
    
44.     }
    
45. 
    
46.     status = emAfReadAttribute(entry.endpoint,            //读出attribute属性
    
47.                                entry.clusterId,
    
48.                                entry.attributeId,
    
49.                                entry.mask,
    
50.                                entry.manufacturerCode,
    
51.                                (uint8_t *)&readData,
    
52.                                READ_DATA_SIZE,
    
53.                                &dataType);
    
54.     if (status != EMBER_ZCL_STATUS_SUCCESS) {
    
55.       emberAfReportingPrintln("ERR: reading cluster 0x%2x attribute 0x%2x: 0x%x",
    
56.                               entry.clusterId,
    
57.                               entry.attributeId,
    
58.                               status);
    
59.       continue;
    
60.     }
    
61. 
    
62.     // find size of current report　计算reportSize = 簇ID长度+datetype长度+data长度
    
63.     dataSize = (emberAfIsThisDataTypeAStringType(dataType)
    
64.                   ? emberAfStringLength(readData) + 1
    
65.                   : emberAfGetDataSize(dataType));
    
66.     reportSize = sizeof(entry.attributeId) + sizeof(dataType) + dataSize;
    
67. 
    
68.     // If we have already started a report for a different attribute or
    
69.     // destination, or if the current entry is too big for current report, send it and create a new one.
    
70.     if (apsFrame != NULL &&
    
71.         (!(entry.endpoint == apsFrame->sourceEndpoint
    
72.             && entry.clusterId == apsFrame->clusterId
    
73.             && emberAfClusterIsClient(&entry) == clientToServer
    
74.             && entry.manufacturerCode == manufacturerCode) ||
    
75.         (appResponseLength + reportSize > smallestPayloadMaxLength))) {
    
76.       if (appResponseLength + reportSize > smallestPayloadMaxLength) {
    
77.         emberAfReportingPrintln("Reporting Entry Full - creating new report");
    
78.       }
    
79.       conditionallySendReport(apsFrame->sourceEndpoint, apsFrame->clusterId);
    
80.       apsFrame = NULL;
    
81.     }
    
82. 
    
83.     // If we haven't made the message header, make it.
    
84.     if (apsFrame == NULL) {
    
85.       apsFrame = emberAfGetCommandApsFrame();
    
86.       clientToServer = emberAfClusterIsClient(&entry);
    
87.       // The manufacturer-specfic version of the fill API only creates a
    
88.       // manufacturer-specfic command if the manufacturer code is set.  For
    
89.       // non-manufacturer-specfic reports, the manufacturer code is unset, so
    
90.       // we can get away with using this API for both cases.  填充zcl cammand，数据填充完成后，既可以开始发送
    
91.       emberAfFillExternalManufacturerSpecificBuffer((clientToServer
    
92.                                                      ? (ZCL_GLOBAL_COMMAND
    
93.                                                         | ZCL_FRAME_CONTROL_CLIENT_TO_SERVER
    
94.                                                         | EMBER_AF_DEFAULT_RESPONSE_POLICY_REQUESTS)
    
95.                                                      : (ZCL_GLOBAL_COMMAND
    
96.                                                         | ZCL_FRAME_CONTROL_SERVER_TO_CLIENT
    
97.                                                         | EMBER_AF_DEFAULT_RESPONSE_POLICY_REQUESTS)),
    
98.                                                     entry.clusterId,
    
99.                                                     entry.manufacturerCode,
    
100.                                                     ZCL_REPORT_ATTRIBUTES_COMMAND_ID,
     
101.                                                     "");
     
102.       apsFrame->sourceEndpoint = entry.endpoint;
     
103.       apsFrame->options = EMBER_AF_DEFAULT_APS_OPTIONS;
     
104.       manufacturerCode = entry.manufacturerCode;
     
105. 
     
106.       // EMAPPFWKV2-1327: Reporting plugin does not account for reporting too many attributes
     
107.       //                  in the same ZCL:ReportAttributes message
     
108. 
     
109.       // find smallest maximum payload that the destination can receive for this cluster and source endpoint
     
110.       smallestPayloadMaxLength = MAX_INT8U_VALUE;
     
111.       for (index = 0; index < EMBER_BINDING_TABLE_SIZE; index++) {
     
112.         status = (EmberAfStatus)emberGetBinding(index, &bindingEntry);
     
113.         if (status == (EmberAfStatus)EMBER_SUCCESS && bindingEntry.local == entry.endpoint && bindingEntry.clusterId == entry.clusterId) {
     
114.           currentPayloadMaxLength = emberAfMaximumApsPayloadLength(bindingEntry.type, bindingEntry.networkIndex, apsFrame);
     
115.           if (currentPayloadMaxLength < smallestPayloadMaxLength) {
     
116.             smallestPayloadMaxLength = currentPayloadMaxLength;
     
117.           }
     
118.         }
     
119.       }
     
120. 
     
121.     }
     
122. 
     
123.     // Payload is [attribute id:2] [type:1] [data:N].
     
124.     emberAfPutInt16uInResp(entry.attributeId);
     
125.     emberAfPutInt8uInResp(dataType);
     
126. 
     
127. #if (BIGENDIAN_CPU)
     
128.     if (isThisDataTypeSentLittleEndianOTA(dataType)) {
     
129.       uint8_t i;
     
130.       for (i = 0; i < dataSize; i++) {
     
131.         emberAfPutInt8uInResp(readData[dataSize - i - 1]);
     
132.       }
     
133.     } else {
     
134.       emberAfPutBlockInResp(readData, dataSize);
     
135.     }
     
136. #else
     
137.     emberAfPutBlockInResp(readData, dataSize);
     
138. #endif
     
139. 
     
140.     // Store the last reported time and value so that we can track intervals
     
141.     // and changes.  We only track changes for data types that are small enough
     
142.     // for us to compare.   记录上次report的时间和值，方便下次进行计算
     
143.     emAfPluginReportVolatileData[i].reportableChange = false;
     
144.     emAfPluginReportVolatileData[i].lastReportTimeMs = halCommonGetInt32uMillisecondTick();
     
145.     if (dataSize <= sizeof(emAfPluginReportVolatileData[i].lastReportValue)) {
     
146.       emAfPluginReportVolatileData[i].lastReportValue = 0;
     
147. #if (BIGENDIAN_CPU)
     
148.       MEMMOVE(((uint8_t *)&emAfPluginReportVolatileData[i].lastReportValue
     
149.                + sizeof(emAfPluginReportVolatileData[i].lastReportValue)
     
150.                - dataSize),
     
151.               readData,
     
152.               dataSize);
     
153. #else
     
154.       MEMMOVE(&emAfPluginReportVolatileData[i].lastReportValue, readData, dataSize);
     
155. #endif
     
156.     }
     
157.   }
     
158. 
     
159.   if (apsFrame != NULL) {      // 数据发送
     
160.     conditionallySendReport(apsFrame->sourceEndpoint, apsFrame->clusterId);
     
161.   }
     
162.   scheduleTick();              // 计算下一次report时间，并且设置相应的事件，如此就可以周而复始的report数据了
     
163. }

复制代码

总结：

使用report功能，只需要简单的如第一步配置相关的参数既可以了。

配置过程中注意几点：

1、配置的簇，属性，端点，厂家，掩码等参数一定要和现有的属性的相关信息一致，否则系统找不到需要发送的数据内容

2、report的最小周期和最大周期按照用户需求定制。

3、配置的过程，需要在用户需要的地方被正确的调用，例如我这里是在emberAfMainInitCallback处调用，则一上电便开启了report功能

只要相应的绑定表里面有内容，则就直接发送相应的数据到对应的绑定设备。