Zigbee Coordinator (Client) - IAS Zone Implementation

RE: Zigbee Coordinator (Client) - IAS Zone Implementation

Nik — Tue, 02 Mar 2021 12:34:41 GMT

Thank you Marjeris.

I was hoping to get a little more information regarding the max network size, and expected (recommended) size of the IAS ACE Zone Table, but oh well... I assume that's all we can get.

I think we can close this thread now, since primary objective was achieved - I gathered all necessary information and was able to implement IAS Zone Enrollment + reception and processing of async state change reports, and it seems to be stable for now.

Best reagards,

Nikita

RE: Zigbee Coordinator (Client) - IAS Zone Implementation

Marjeris Romero — Mon, 01 Mar 2021 12:44:19 GMT

Hi,

When it comes to storing the IAS ACE zone table, the stack doesn't store it in non-volatile memory - it has to be implemented in the application. This can be either implemented using Flash Data Storage (FDS) an used in the Zigbee Door Lock example or using ZBOSS's NVRAM and stored as APP_DATA.

RE: Zigbee Coordinator (Client) - IAS Zone Implementation

Marjeris Romero — Mon, 01 Mar 2021 11:42:40 GMT

Hi,

I am sorry for the late reply. Answer from one of our Zigbee developers:

"Yes, the Zone Enroll Request needs to be handled by the application (in the endpoint handler), I don't see it being handled in the stack. This is also confirmed by DSR.

Since this is nRF5 SDK, response packets can be scheduled from the callback. To send packet, first obtain the buffer to put packet into and then schedule it to be sent.
Macro ZB_ZCL_IAS_ZONE_SEND_ZONE_ENROLL_RES can be used to send a response.

As for the IAS ACE Zone Table, see zb_zcl_ias_ace_zone_table_t in the zb_zcl_ias_ace.h.

Declare array of zb_zcl_ias_ace_zone_table_t as variable and additional variable (zb_uint16_t) to store the size of the IAS ACE table. When declaring IAS ACE attribute list using ZB_ZCL_DECLARE_IAS_ACE_ATTRIB_LIST macro, you will pass pointers to both IAS ACE zone table and variable with table size to the macro. When it comes to size of the IAS ACE zone table, maximum size is 255 - each zone has its ID stored in uint8, hence the limit.

I am not yet sure about storing this table at non-volatile memory. Need to check if the stack stores it or not."

BR,

Marjeris

RE: Zigbee Coordinator (Client) - IAS Zone Implementation

Nik — Fri, 19 Feb 2021 17:29:02 GMT

Hi Marjeris,

Thank you for clarification.

[quote userid="73427" url="~/f/nordic-q-a/71253/zigbee-coordinator-client---ias-zone-implementation/295047#295047"]I am not sure if the stack will handle the 'Zone Enroll Request' command or not[/quote]

Currently, default response to 'Zone Enroll Requests' is 'Unsopported Command' (when IAS Zone cluster is declared), so yes, it has to be intercepted and handled by the APP layer and answered with either 'Success' + Enrolled ZoneID of 'Fail'. Just wanted to clarify that scheduling response packets right from the callback is the right thing and I don't have to create and manage signals for external thread for that.

I look forward to hearing from you about possibility of larger Zigbee networks (especially when TC is not on NRF52840) and expected 'IAS ACE Zone Table' size. Also, can application layer store information (like that zone table) inside persistent config sector? Or should it allocate another, different sector in flash memory for that?

Regards,

Nikita

RE: Zigbee Coordinator (Client) - IAS Zone Implementation

Marjeris Romero — Thu, 18 Feb 2021 10:27:21 GMT

Hi,

Sorry I haven't come back to you sooner. I don't know all the answers so I will need to consult with our developers.

[quote user="hw_dev"]After a ton of experiments I found that if I modify ZB_HA_DECLARE_IAS_CONTROL_INDICATING_EQUIPMENT_CLUSTER_LIST() macro by moving ZB_ZCL_CLUSTER_DESC() with ZB_ZCL_CLUSTER_ID_GROUPS and ZB_ZCL_CLUSTER_ID_SCENES above IAS_* related clusters, device starts up successfully and works properly. Don't ask how... Long term stability yet unknown[/quote]

I do see that most of our clusters in the example start with identiy, basic, groups and scene before moving to specific clusters, this is interesting, I will make an internal ticket to ask the developers about this, perhaps there is some requirement from the ZCL spec I am not aware of.

[quote user="hw_dev"]I assume I should handle 'Zone Enroll Requests' inside ep_handler, and also call ZB_ZCL_IAS_ZONE_SEND_ZONE_ENROLL_RES(buffer, addr, dst_addr_mode, dst_ep, ep, prfl_id, def_resp, cb, code, zone_id) macro, is that correct? And, by the way, can I use callback's bufid as buffer, or should I create a new one with zb_buf_get_out()? And, should I also return ZB_TRUE from ep_handler after calling that function macro to prevent default response?[/quote]

I am not sure if the stack will handle the 'Zone Enroll Request' command or not. If not, you need to probably use the ZCL packet handler callback to intercept the ZCL command as it's explain here: https://infocenter.nordicsemi.com/topic/sdk_tz_v4.1.0/using_zigbee__z_c_l.html?cp=7_3_3_4_1_8_1#process_zcl_cmd_implementing

There are multiple examples on how to intercept ZCL commands in many of our examples. After intercepting the 'Zone Enroll request' command from the server you should send a Zone enroll response ZB_ZCL_IAS_ZONE_SEND_ZONE_ENROLL_RES from the callback, so in this case I think inside coord_main_ep_handler().

See also this link for explanation on why sometimes the stack process the incomming ZCL commands or not: https://infocenter.nordicsemi.com/index.jsp?topic=%2Fsdk_tz_v4.1.0%2Fusing_zigbee__z_c_l.html&cp=7_3_3_4_1_11&anchor=zcl_cmd_parse

[quote user="hw_dev"]It is also not quite clear how to use ZB_ZCL_DECLARE_IAS_ACE_ATTRIB_LIST() which requires 'pointer to variable to store IAS ACE Zone Table attribute'.[/quote]

Yes, from the documentation I am quite sure you need to allocate this table yourself, and then give a pointer to that in the attribute declaration. They refer to this table:

Structure representation for the table: https://infocenter.nordicsemi.com/index.jsp?topic=%2Fsdk_tz_v4.1.0%2Fstructzb__zcl__ias__ace__zone__table__s.html&cp=7_3_5_1_1_4_7_0

But let me come back to you after I have discussed with the developers is there should be a preffered size or if you can allocate for as much memory as you think you will use.

[quote user="hw_dev"]So, I would like to know, what is the theoretical limit of the zigbee network if ZC is NRF52840? What if it is only a Router? Is it theoretically possible to connect, say, 2000 devices, or there is simply not enough memory to store routing table on NRF52840?[/quote]

Difficult question that we get asked a lot. There is a theoretical limit in Zigbee but there will probably not be enough memory on the nRF52840 for that. DSR have had long running load tests for several months with up to 24 devices connected, but there is no architectural limitation for a network larger than that. The practical limiting factor is on the Trust Center (typically on coordinator devices) memory as the TC must hold link keys to all connected devices. Current soft limit is set on 200.

Best regards,

Marjeris

RE: Zigbee Coordinator (Client) - IAS Zone Implementation

Nik — Sat, 13 Feb 2021 15:34:47 GMT

Hi Marjeris,

Once again, thank you for your advices.

Alright, so here are the results:

First, as you have suggested, I attempted to declare IAS Zone CIE cluster. However, device was failing to start. After a ton of experiments I found that if I modify ZB_HA_DECLARE_IAS_CONTROL_INDICATING_EQUIPMENT_CLUSTER_LIST() macro by moving ZB_ZCL_CLUSTER_DESC() with ZB_ZCL_CLUSTER_ID_GROUPS and ZB_ZCL_CLUSTER_ID_SCENES above IAS_* related clusters, device starts up successfully and works properly. Don't ask how... Long term stability yet unknown. Please let me know I am doing something wrong, my code is below.

Another major breakthrough happened when I found zigbee_logger_eprxzcl_ep_handler() function inside zigbee_logger_eprxzcl.c file, which clearly demonstrated how to work with bufid.

I assume I should handle 'Zone Enroll Requests' inside ep_handler, and also call ZB_ZCL_IAS_ZONE_SEND_ZONE_ENROLL_RES(buffer, addr, dst_addr_mode, dst_ep, ep, prfl_id, def_resp, cb, code, zone_id) macro, is that correct? And, by the way, can I use callback's bufid as buffer, or should I create a new one with zb_buf_get_out()? And, should I also return ZB_TRUE from ep_handler after calling that function macro to prevent default response?

Here is how it looks right now:

#define APP_DECLARE_IAS_CONTROL_INDICATING_EQUIPMENT_CLUSTER_LIST(cluster_list_name, basic_attr_list, identify_attr_list, ias_ace_attr_list)  \
    zb_zcl_cluster_desc_t cluster_list_name[] = { \
        ZB_ZCL_CLUSTER_DESC(ZB_ZCL_CLUSTER_ID_BASIC,    ZB_ZCL_ARRAY_SIZE(basic_attr_list, zb_zcl_attr_t), (basic_attr_list), ZB_ZCL_CLUSTER_SERVER_ROLE, ZB_ZCL_MANUF_CODE_INVALID), \
        ZB_ZCL_CLUSTER_DESC(ZB_ZCL_CLUSTER_ID_IDENTIFY, 0, NULL, ZB_ZCL_CLUSTER_CLIENT_ROLE, ZB_ZCL_MANUF_CODE_INVALID ), \
        ZB_ZCL_CLUSTER_DESC(ZB_ZCL_CLUSTER_ID_IDENTIFY, ZB_ZCL_ARRAY_SIZE(identify_attr_list, zb_zcl_attr_t), (identify_attr_list), ZB_ZCL_CLUSTER_SERVER_ROLE, ZB_ZCL_MANUF_CODE_INVALID), \
        ZB_ZCL_CLUSTER_DESC(ZB_ZCL_CLUSTER_ID_GROUPS,   0, NULL, ZB_ZCL_CLUSTER_CLIENT_ROLE, ZB_ZCL_MANUF_CODE_INVALID ), \
        ZB_ZCL_CLUSTER_DESC(ZB_ZCL_CLUSTER_ID_SCENES,   0, NULL, ZB_ZCL_CLUSTER_CLIENT_ROLE, ZB_ZCL_MANUF_CODE_INVALID ), \
        ZB_ZCL_CLUSTER_DESC(ZB_ZCL_CLUSTER_ID_IAS_ZONE, 0, NULL, ZB_ZCL_CLUSTER_CLIENT_ROLE, ZB_ZCL_MANUF_CODE_INVALID ), \
        ZB_ZCL_CLUSTER_DESC(ZB_ZCL_CLUSTER_ID_IAS_ACE, ZB_ZCL_ARRAY_SIZE(ias_ace_attr_list, zb_zcl_attr_t), (ias_ace_attr_list), ZB_ZCL_CLUSTER_SERVER_ROLE,ZB_ZCL_MANUF_CODE_INVALID), \
        ZB_ZCL_CLUSTER_DESC(ZB_ZCL_CLUSTER_ID_IAS_WD,   0, NULL, ZB_ZCL_CLUSTER_CLIENT_ROLE, ZB_ZCL_MANUF_CODE_INVALID ), \
    }

typedef struct {
    zb_zcl_basic_attrs_t basic_attr;
    zb_zcl_identify_attrs_t identify_attr;
    struct {
        zb_uint8_t zone_state;
        zb_uint16_t zone_type;
        zb_uint16_t zone_status;
        zb_uint8_t ias_ace_zone_table_len;
        zb_zcl_ias_ace_zone_table_t table[10]; // max is [ZB_ZCL_IAS_ACE_ZONE_TABLE_LENGTH] and sizeof(table) = 3825 (!)
    } ias_zone_attr;
} coord_attrs_t;

static coord_attrs_t coord;

ZB_ZCL_DECLARE_BASIC_ATTRIB_LIST(basic_attr_list, &coord.basic_attr.zcl_version, &coord.basic_attr.power_source);
ZB_ZCL_DECLARE_IDENTIFY_ATTRIB_LIST(identify_attr_list, &coord.identify_attr.identify_time);
ZB_ZCL_DECLARE_IAS_ACE_ATTRIB_LIST(ias_ace_attr_list, &coord.ias_zone_attr.ias_ace_zone_table_len, coord.ias_zone_attr.table);

ZB_HA_DECLARE_CONFIGURATION_TOOL_CLUSTER_LIST(cli_agent_clusters, basic_attr_list, identify_attr_list);
APP_DECLARE_IAS_CONTROL_INDICATING_EQUIPMENT_CLUSTER_LIST(ias_zone_cie_clusters, basic_attr_list, identify_attr_list, ias_ace_attr_list); // NK // rearranged ZB_HA_DECLARE_IAS_CONTROL_INDICATING_EQUIPMENT_CLUSTER_LIST(), otherwise hangs @ startup

ZB_HA_DECLARE_CONFIGURATION_TOOL_EP(cli_agent_ep, ZIGBEE_CLI_ENDPOINT, cli_agent_clusters);
ZB_HA_DECLARE_IAS_CONTROL_INDICATING_EQUIPMENT_EP(ias_zone_cie_ep, MAIN_ENDPOINT, ias_zone_cie_clusters);
ZBOSS_DECLARE_DEVICE_CTX_2_EP(device_ctx, cli_agent_ep, ias_zone_cie_ep);

//(...)

zb_uint8_t coord_main_ep_handler(zb_bufid_t bufid) { 
    zigbee_logger_eprxzcl_ep_handler(bufid);
    return ZB_FALSE; // continue packet processing inside default callback handler
}

 
int main () {

//(...)
    ZB_AF_REGISTER_DEVICE_CTX(&device_ctx);
    ZB_AF_SET_ENDPOINT_HANDLER(ZIGBEE_CLI_ENDPOINT, cli_agent_ep_handler);
    ZB_AF_SET_ENDPOINT_HANDLER(MAIN_ENDPOINT, coord_main_ep_handler);
//(...)
}

It is also not quite clear how to use ZB_ZCL_DECLARE_IAS_ACE_ATTRIB_LIST() which requires 'pointer to variable to store IAS ACE Zone Table attribute'. Is ZBOSS core going to allocate memory inside persistent config sector? In RAM? Do I have to allocate manually dynamically / staticaly? Allocate one value or as much as I expect to use, or max possible size?

zb_uint8_t ias_ace_zone_table_len;

// Option1
zb_zcl_ias_ace_zone_table_t *table;
ZB_ZCL_DECLARE_IAS_ACE_ATTRIB_LIST(ias_ace_attr_list, &ias_ace_zone_table_len, &table);

// Option2
zb_zcl_ias_ace_zone_table_t table;
ZB_ZCL_DECLARE_IAS_ACE_ATTRIB_LIST(ias_ace_attr_list, &ias_ace_zone_table_len, &table);

// Option3
zb_zcl_ias_ace_zone_table_t table[10];
ZB_ZCL_DECLARE_IAS_ACE_ATTRIB_LIST(ias_ace_attr_list, &ias_ace_zone_table_len, table);

// Option4
zb_zcl_ias_ace_zone_table_t table[ZB_ZCL_IAS_ACE_ZONE_TABLE_LENGTH]; // LENGTH = 255, size()= almost 4KB
ZB_ZCL_DECLARE_IAS_ACE_ATTRIB_LIST(ias_ace_attr_list, &ias_ace_zone_table_len, table);

Please advice, since all options compile and the device starts up successfully, but I cannot test actual functionality at this point.

I also found this line in the config

#define ZB_CONFIG_OVERALL_NETWORK_SIZE   200 // 2 <= x <= 200

So, I would like to know, what is the theoretical limit of the zigbee network if ZC is NRF52840? What if it is only a Router? Is it theoretically possible to connect, say, 2000 devices, or there is simply not enough memory to store routing table on NRF52840?

Regards,

Nikita

RE: Zigbee Coordinator (Client) - IAS Zone Implementation

Marjeris Romero — Thu, 11 Feb 2021 08:17:08 GMT

Hi again,

Regarding zb_zcl_ias_zone_init_client(), this function should not be called by the application. Try instead of getting started with the cluster implementation like in other Zigbee applications. Perhaps it's easier to start out with the light coordinator cluster, as it is a much strip down example with basic coordinator functionality and then add the IAS zone client cluster to it.

[quote user="hw_dev"]I think it is still worth posting a link even to heavily obsolete and non-functional example code (with related disclaimer, of course), since reading through it still help restore / understand the logic of declarations and function calls.[/quote]

I am afraid those examples are obsolete, as said there is an internal ticket for reviewing this part of the documentation and I think the references to these examples will ended being removed from the documentation. Also just so you are aware of it it's not possible for us to disclose ZBOSS source code as our licence with DSR does not allow us too share any source code.

Regarding you feedback about zboss_main_loop() current comsumption, have you seen our Sleepy End Device samples?

Did you have any other questions to help you get started with the IAS zone client on coordinator side?

Best regards,

Marjeris

RE: Zigbee Coordinator (Client) - IAS Zone Implementation

Nik — Mon, 08 Feb 2021 15:49:34 GMT

Hi Marjeris,

Thank you for detailed explanation. I believe that should help with implementation, I will post my results.

The release of the Zigbee stack from DSR to Nordic may have contained a IAS zone server example long time ago, and the comments from the documentation have slipped into our API docs.

Ah, I see. DSR might have not provided the examples in the first place and/or source code of those examples became completely obsolete as SDK evolves and there was not enough resources to keep those up to date, so it was removed to avoid confusion. That's totally understandable. However, if those example do exist (and if not, how about requesting those from DSR?), and taking into consideration that documentation is not finished and needs quite a bit of work to be done at this point, I think it is still worth posting a link even to heavily obsolete and non-functional example code (with related disclaimer, of course), since reading through it still help restore / understand the logic of declarations and function calls.

For example, it is sill not clear where+when to call zb_zcl_ias_zone_init_client() and if it is necessary to call it at all, I just found it accidentally, while reading the header file. Is it enough to call it once in the main() function? Does it has to be called before or after zboss_start() or zboss_start_no_autostart() or any other function, or it doesn't matter, or, maybe, it should be called inside zboss_signal_handler(), similar to bdb_start_top_level_commissioning(), and if so, at which signal, at which status of that signal? These are the essential answers that developer needs to know for each function in order to use it properly. And it gets much, much worse when a function has arguments.So far, my absolute favorites are zboss_signal_handler(zb_bufid_t bufid) and zcl_device_cb(zb_bufid_t bufid), where bufid just gets re-casted to multiple different structure types through zb_buf_get_tail_func(), but there is almost no error detection/handling implemented explicitly, while pointer cast is one of the most dangerous operations in C/C++.

Another example is zboss_start(). I actually do like how it is documented, brief exaplanation has everything necessary to work with this function: it states what it does, what are the prerequsites and consiquences of calling that function and even briefly mentioned the next step (i.e. calling zboss_main_loop()). Unfortunately, documentation makes impression that there is no alternative except polling zboss_main_loop()at max speed, draining the power source, even if nothig is happening, but that is a minor issue.

Fortunately, most of the time examples do allow us to extract all the necessary answers, but when there is no example, no details in documentation and no source code of the function, this is just impossible, so I hope you understand my frustration. And I hope my feedback will help Nordic Developers improve SDK documentation and examples in the future.

Best regards,

Nikita

RE: Zigbee Coordinator (Client) - IAS Zone Implementation

Marjeris Romero — Mon, 08 Feb 2021 11:09:47 GMT

Hi,

To start with the first problem, if you see the Wireshark messages you are receiving after writing to the IAS_CIE_address attribute of the IAS zone server:

[quote user=""]

0xf230 > 0x0000 | ZCL IAS Zone: Zone Status Change Notification, Seq: 81, Cmd: Zone Status Change Notification (0x00), Extended Status: 0x00

0x0000 > 0xf230 | ZCL: Default Response, Seq: 81, Cmd: Default Response (0x0b), Status: Unsupported Cluster (0xc3)

...

0xf230 > 0x0000 | ZCL IAS Zone: Zone Enroll Request, Seq: 82, Cmd: Zone Enroll Request (0x01), ZoneType: Water sensor (0x002a)

0x0000 > 0xf230 | ZCL: Default Response, Seq: 82, Cmd: Default Response (0x0b), Status: Unsupported Cluster (0xc3)

[/quote]

You see the coordinator (CLI example) responds with 'Unsupported Cluster' to the IAS zone server commands 'Zone Status Change Notification' and 'Zone Enroll Request'. I think as for all other ZCL clusters the first think you need to do is to declared the IAS zone client cluster on the coordinator side as an output cluster (see figure 8-1 in the ZCL specification 'Typical Use of the IAS clusters', server IAS zone needs to be paired with a client IAS zone, as normal cluster behaviour in Zigbee, for example light switch - light bulb example shows an example of server-client interaction). If you send a match desc request to the CLI coordinator example you will see that the only output clusters declared on endpoint 64 are 0x0000 (basic), 0x0003(identify) and 0x0004(groups), so IAS zone client need to be added here.

[quote user=""] And the second problem is that system does receive 'Zone Status Change' reports, but never reflects that in log or CLI[/quote]

Just so you are aware of it, the CLI example doesn't magically print logs from attribute reporting either. If you see in the Multisensor example you need to enable displaying the reports in CLI, using the command 'log enable info zigbee.report' to print the reports. You can see how printing of attribute logs on CLI example is handled in nrf_log_frontend.c and zigbee_cli_cmd_attr_report.c.

But back to your question, the 'Zone Status Change Notification' is actually a ZCL command generated by the IAS zone server, so it's not the same as configuring attribute reports either. I think you should treat these notifications like a normal ZCL command, for example see how the ON/OFF command is handled by the light bulb example, which intercept the command in the ZCL device callback function to power the LED light ON or OFF, see the light_bulb example zcl_device_cb() callback function. But before intercepting the command on the code it's better to be sure that the coordinator is acknowledging these commands sucessfully (since right now the coordinator is just responding with 'Unsupported Cluster') using Wireshark.

[quote user=""]I find references to non-existent files/foldes with essential information, like "The complete set of IAS Zone samples can be found in /application/ias_zone_sensor" in the "documentation" at infocenter.nordicsemi.com and in source files/header and wonder why is it removed/hidden?[/quote]

This is sadly a known and reported bug in the documentation. The release of the Zigbee stack from DSR to Nordic may have contained a IAS zone server example long time ago, and the comments from the documentation have slipped into our API docs. There is an internal ticket to see if this line in the documentation should be remove or modified. There is currently no IAS zone sensor example available on our nRF5 SDK for Zigbee & Thread.

[quote user=""]Finally, the general question is: how do you (Nordic Developers) expect us (users / 3d party developers) to figure out the sequence of variable decalarations, function calls and callbacks registrations without detaild documentation and examples? Trial-Error? I'm afraid reading headers with minimal comments like "This functions is for that." does not really help, since we still don't undestand what are the prerequisites for that function, what are the inputs/outputs, limitations, etc.[/quote]

I will forward this feedback to our developers. For declaring attributes, clusters, cluster list and endpoints I think the more detailed documentation we have at the moment is this section from our Zigbee API stack overview at the infocenter: 'Implementing a Zigbee end product with ZCL'. This section of the documentation have been getting bigger and better for each release but we may have parts that should be better covered/explained. Reading the ZCL specification is also obligatory for implementing other Zigbee clusters than the ones available in our examples.

Best regards,

Marjeris