RE: Implementation of Zigbee cli function calls in Shell

Sigurd Hellesvik — Thu, 23 Jun 2022 11:31:08 GMT

Hi Jørgen

See the last comment of Marte:

[quote user="Marte.M"]I will be out of office for a few weeks, so if you have any more issues or questions regarding this case please create a new ticket and link to this one. Thank you![/quote]

Regards,
Sigurd Hellesvik

RE: Implementation of Zigbee cli function calls in Shell

JorgenM — Fri, 17 Jun 2022 15:29:22 GMT

Thanks Marte,

Wow, it looks to be quite complicated to add function calls but your directions and explanation will help a lot, thanks!
One can probably do an educated guess to find the shell commands and associated function calls but wanted to make sure I didn't miss something.
Thanks for the "bdb_c stop" example how to add a command. I will give this a try.

Just a general question:
Am I doing something very different from others how to implement a coordinator (using shell and cli) or is this what everyone is spending time on coding?
Seem like many of the "hooks" are missing to really utilize the Zigbee stack capabilities without a lot of custom coding?

If there is a easier/better way feel free to suggest it.

Have a great time off & Glad Midsummer,

Jorgen

RE: Implementation of Zigbee cli function calls in Shell

Marte Myrvold — Fri, 17 Jun 2022 14:25:26 GMT

Hi Jorgen,

I will be out of office for a few weeks, so if you have any more issues or questions regarding this case please create a new ticket and link to this one. Thank you!

Best regards,

Marte

RE: Implementation of Zigbee cli function calls in Shell

Marte Myrvold — Fri, 17 Jun 2022 07:57:55 GMT

Hi Jorgen,

[quote user=""]I'm trying to find some reference or documentation that shows the BDB START (as example) shell commands and what it actually calls.[/quote]

As you say, the documentation does not explicitly state what this command does or calls, so you must look in the Zigbee shell library code. The bdb commands are in zigbee_cli_cmd_bdb.c, and "bdb start" calls the function cmd_zb_start(), as you can see here: https://github.com/nrfconnect/sdk-nrf/blob/v1.9.1/subsys/zigbee/cli/zigbee_cli_cmd_bdb.c#L285. This function first check if the Zigbee stack is started or not, and if not it will set the channel and role of the device, and then start the Zigbee stack. If the stack is started the command will repoen the network (start commissioning) by calling bdb_start_top_level_commissioning().

[quote user=""]So when people (Marte suggestion in other ticket) say "use the function call" zb_bdb_close_network() as example, what is the actual bdb command?
It does not show in Nordic Coordinator example using 1.9.1 SDK in shell bdb commands.
Looks like I have to add this function?[/quote]

You are correct. There is no shell command for stopping the network, so you must implement it yourself, by either adding the command as a subcommand in zigbee_cli_cmd_bdb.c or create a new file and create the command there. The latter is probably the cleanest option since you should avoid making changes to the library files. Lucky for you I decided to do just that:

#include <string.h>
#include <shell/shell.h>
#include <zboss_api.h>
#include <zigbee/zigbee_error_handler.h>
#include <zb_nrf_platform.h>
#include "zigbee_cli.h"
#include "zigbee_cli_utils.h"


/**@brief Stop bdb top level commissioning process.
 *
 * @code
 * > bdb_c stop
 * Commissioning stopped
 * Done
 * @endcode
 * 
 * @pre Only after @ref start "bdb start".
 * 
 * Will stop cinnussioning by broadcasting a Mgmt_Permit_Joining_req with PermitDuration of 0.
 * See Base Device Behaviour specification for details.
 */

static int cmd_zb_stop(const struct shell *shell, size_t argc, char **argv)
{
	ARG_UNUSED(argc);
	ARG_UNUSED(argv);

	zb_bool_t ret = ZB_TRUE;

    if ((!zigbee_is_stack_started())) {
        zb_cli_print_error(shell, "Stack is not started",
					   ZB_FALSE);
		return -ENOEXEC;
    }

    ret = zb_bdb_close_network(NULL);
    if (ret != RET_OK)
    {
		zb_cli_print_error(shell, "Can not stop commissioning", ZB_FALSE);
	}
}


SHELL_STATIC_SUBCMD_SET_CREATE(sub_bdb_c,
	SHELL_CMD_ARG(stop, NULL, "Stop commissionning", cmd_zb_stop, 1, 0),
	SHELL_SUBCMD_SET_END /* Array terminated. */
);

SHELL_CMD_REGISTER(bdb_c, &sub_bdb_c, "Base device behaviour manipulation.", NULL);

Please note that since this is a new set of commands you cannot use "bdb command", since the bdb set of commands are already registered in zigbee_cli_cmd_bdb.c. I called it bdb_c for bdb custom, so you will have to call "bdb_c stop", but you can rename it to something else by changing sub_bdb_c and bdb_c in SHELL_STATIC_SUBCMD_SET_CREATE and SHELL_CMD_REGISTER. I put this code in a file called zigbee_cli_cmd_bdb_stop.c under network_coordinator/src, and added it to CMakeLists.txt like this:

target_sources(app PRIVATE
  src/main.c;
  src/zigbee_cli_cmd_bdb_stop.c
)

You can also add more subcommands by adding them to SHELL_STATIC_SUBCMD_SET_CREATE. For this, you can look at how it is done in the Zigbee shell library files.

[quote user=""]Where does "mgmt_lqi" exist?[/quote]

The command zdo mgmt_lqi calls the function cmd_zb_mgmt_lqi() in zigbee_cli_cmd_zdo.c: https://github.com/nrfconnect/sdk-nrf/blob/v1.9.1/subsys/zigbee/cli/zigbee_cli_cmd_zdo.c#L2193.

The implementation of the commands can be difficult to find, since for example the only place you will find exactly "zdo mgmt_lqi" is in the comment right above the function cmd_zb_mgmt_lqi(). This is because you have both root commands and subcommands. In this case, zdo is the root command, and it is a shell command in and of itself. In addition to this, you have a list of subcommands under zdo, such as active_ep, bind, mgmt_lqi etc. So you might not find the commands by searching for <root command> <sub_command> or even <root command>_<sub_command>, since the commands are not registered as such. The command "zdo mgmt_lqi" is not registered as "zdo mgmt_lqi" or even "zdo_mgmt_lqi", but as this:

SHELL_STATIC_SUBCMD_SET_CREATE(sub_zdo,
    ...
    SHELL_CMD_ARG(mgmt_lqi, NULL, MGMT_LQI_HELP, cmd_zb_mgmt_lqi, 2, 1),
    SHELL_SUBCMD_SET_END);
    
SHELL_CMD_REGISTER(zdo, &sub_zdo, "ZDO manipulation.", NULL);

And even the function that is called when you issue the command is not named zdo_mgmt_lqi, but cmd_zb_mgmt_lqi().

The Zigbee shell files are located in nrf/subsys/zigbee/cli/ in nRF Connect SDK v1.9.1 and earlier, and from v2.0.0 they are under nrf/subsys/zigbee/lib/zigbee_shell. You should be able to find which file most of the commands are in just by looking at the file names, e.g. bdb commands are in zigbee_cli_cmd_bdb.c/zigbee_shell_cmd_bdb.c, zdo commands in zigbee_cli_cmd_zdo.c/zigbee_shell_cmd_zdo.c and so forth.

I hope this clears up some of the confusion with the Zigbee shell commands!

Best regards,

Marte