Implementation of Zigbee cli function calls in Shell

[JorgenM]

Hello Support,

For my Zigbee Coordinator development I use nrf Connect SDK 1.9.1 (for now), and VS, I like using Kconfig GUI as much as possible. 

I'm trying to find some reference or documentation that shows the BDB START (as example) shell commands and what it actually calls.
The shell bdb api document doesn't actually describe what it calls from what I can find when searching on "bdb start".
https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/libraries/zigbee/shell.html#bdb-start

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?

Same applies to ZDO commands.
As example since I know how this is implemented in Shell cmd: zdo mgmt_lqi
If I search in ZDO API ref docs for "mgmt_lqi" nothing shows up. 
https://developer.nordicsemi.com/nRF_Connect_SDK/doc/zboss/3.9.0.1/group__zdo__api.html

If I search for "mgmt_lqi" in VS  in my coordinator application folder nothing shows up.

Where does "mgmt_lqi" exist?

Perhaps there a document how this works or video tutorial what I have to do to implement?
I see reference to a bunch of call functions in API documentation that would be useful, but how do I implement them using shell CLI commands?

Cheers,
Jorgen

[Marte Myrvold]

Hi Jorgen,

I'm trying to find some reference or documentation that shows the BDB START (as example) shell commands and what it actually calls.

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(). 

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?

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.

Where does "mgmt_lqi" exist?

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

[Marte Myrvold]

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