Feature : Shell

Shell on Zephyr with STM32 NUCLEO-G0B1RE

In this program, you are going to learn

What configurations needs to be added to enable shell?

How to do pre-build and post-build checks ?

How to execute commands on Zephyr shell?

How to add our own commands to execute in shell?

Topics in this section,

Step 4.1: Adding Configurations in prj.conf

Step 4.2: Do Pre-build checks

Step 4.2.1: Check configurations for shell added or not

Step 4.2.2: Location of toolchain

Step 4.3: Build the Application

Step 4.4: Do Post-build checks

Step 4.4.1: Static post build checks

Step 4.4.1.1: Location of the final target image

Step 4.4.2: Runtime post build checks

Step 4.4.2.1: Load and Run the image

Step 4.4.2.2: Confirm if the prompt is displayed

Step 4.5: Commands in Zephyr shell

Step 4.5.1: Commands to print kernel and thread related information

Step 4.5.2: Commands to print device related information

Step 4.5.3: Commands to print interrupt information

Step 4.5.4: Commands to print how many HW entity like clocks,timers are present

Step 4.5.5: Commands to print Overall RAM and SRAM usage

Step 4.5.6: Commands to print information about flash space

Step 4.5.7: Commands to print information about network interfaces

Step 4.5.8: Commands to print information about wifi interfaces

Step 4.6: Adding our own command in Zephyr shell

Step 4.6.1: Adding main.c

Step 4.6.2: Explanation of APIs used in main.c

Step 4.6.3: Building the application

Step 4.6.4: Executing our own command in zephyr shell

Adding Configurations in prj.conf

Add the following configurations in prj.conf to enable the shell on Zephyr build.

(.venv) test:zephyr$ pwd
$HOME/zephyrproject/zephyr
(.venv) test:zephyr$ vi samples/hello_world/prj.conf

prj.conf

CONFIG_SHELL=y
CONFIG_SHELL_BACKEND_SERIAL=y
CONFIG_SHELL_HISTORY=y
CONFIG_SHELL_CMDS_RESIZE=y

Do Pre-build checks

In this section we will see how to do pre-build checks.

Check the configurations for shell are added or not

Check whether the configurations required to enable shell for zephyr is added or not in prj.conf

prj.conf

CONFIG_SHELL=y
CONFIG_SHELL_BACKEND_SERIAL=y
CONFIG_SHELL_HISTORY=y
CONFIG_SHELL_CMDS_RESIZE=y

Check the location of toolchain

Check for the location of location in zephyr-sdk-0.16.4 directory

(.venv) test:zephyr$ ls -l $HOME/zephyr-sdk-0.16.4/aarch64-zephyr-elf/aarch64-zephyr-elf/bin/
total 17000
-rwxr-xr-x 2 test test 1357336 Nov 15 16:40 ar
-rwxr-xr-x 2 test test 2500544 Nov 15 16:40 as
-rwxr-xr-x 4 test test 2019136 Nov 15 16:40 ld
-rwxr-xr-x 4 test test 2019136 Nov 15 16:40 ld.bfd
-rwxr-xr-x 2 test test 1346128 Nov 15 16:40 nm
-rwxr-xr-x 2 test test 1467888 Nov 15 16:40 objcopy
-rwxr-xr-x 2 test test 2876656 Nov 15 16:40 objdump
-rwxr-xr-x 2 test test 1357368 Nov 15 16:40 ranlib
-rwxr-xr-x 2 test test  977144 Nov 15 16:40 readelf
-rwxr-xr-x 2 test test 1467888 Nov 15 16:40 strip

Build the Application

run west build command to build the application.

(.venv) test:zephyr$ pwd
$HOME/zephyrproject/zephyr


(.venv) test:zephyr$ west build -b nucleo_g0b1re samples/hello_world/
-- west build: generating a build system
Loading Zephyr default modules (Zephyr base).
-- Application: /home/test/single_thread_zephyr_build/zephyrproject/zephyr/samples/hello_world
-- CMake version: 3.24.2
-- Found Python3: /home/test/single_thread_zephyr_build/zephyrproject/.venv/bin/python3 (found suitable version "3.10.7", minimum required is "3.8") found components: Interpreter
-- Cache files will be written to: /home/test/.cache/zephyr
-- Zephyr version: 3.5.99 (/home/test/single_thread_zephyr_build/zephyrproject/zephyr)
-- Found west (found suitable version "1.2.0", minimum required is "0.14.0")
-- Board: nucleo_g0b1re
-- ZEPHYR_TOOLCHAIN_VARIANT not set, trying to locate Zephyr SDK
-- Found host-tools: zephyr 0.16.4 (/home/test/double_thread_zephyr_build/zephyr-sdk-0.16.4)
-- Found toolchain: zephyr 0.16.4 (/home/test/double_thread_zephyr_build/zephyr-sdk-0.16.4)
-- Found Dtc: /home/test/double_thread_zephyr_build/zephyr-sdk-0.16.4/sysroots/x86_64-pokysdk-linux/usr/bin/dtc (found suitable version "1.6.0", minimum required is "1.4.6")
-- Found BOARD.dts: /home/test/single_thread_zephyr_build/zephyrproject/zephyr/boards/arm/nucleo_g0b1re/nucleo_g0b1re.dts
-- Generated zephyr.dts: /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/zephyr.dts
-- Generated devicetree_generated.h: /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/include/generated/devicetree_generated.h
-- Including generated dts.cmake file: /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/dts.cmake
/home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/zephyr.dts:625.10-633.5: Warning (simple_bus_reg): /soc/clocks: missing or empty reg/ranges property
Parsing /home/test/single_thread_zephyr_build/zephyrproject/zephyr/Kconfig
Loaded configuration /home/test/single_thread_zephyr_build/zephyrproject/zephyr/boards/arm/nucleo_g0b1re/nucleo_g0b1re_defconfig
Merged configuration /home/test/single_thread_zephyr_build/zephyrproject/zephyr/samples/hello_world/prj.conf
Configuration saved to /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/.config
Kconfig header saved to /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/include/generated/autoconf.h
-- Found GnuLd: /home/test/double_thread_zephyr_build/zephyr-sdk-0.16.4/arm-zephyr-eabi/bin/../lib/gcc/arm-zephyr-eabi/12.2.0/../../../../arm-zephyr-eabi/bin/ld.bfd (found version "2.38")
-- The C compiler identification is GNU 12.2.0
-- The CXX compiler identification is GNU 12.2.0
-- The ASM compiler identification is GNU
-- Found assembler: /home/test/double_thread_zephyr_build/zephyr-sdk-0.16.4/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc
-- Using ccache: /usr/bin/ccache
-- Configuring done
-- Generating done
-- Build files have been written to: /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build
-- west build: building application
[1/147] Preparing syscall dependency handling

[3/147] Generating include/generated/version.h

-- Zephyr version: 3.5.99 (/home/test/single_thread_zephyr_build/zephyrproject/zephyr), build: zephyr-v3.5.0-4239-gcbc9439bc0ff

[146/147] Linking C executable zephyr/zephyr.elf

Memory region         Used Size  Region Size  %age Used
FLASH:               39202 B       512 KB      7.48%
RAM:                  9376 B       144 KB      6.36%
IDT_LIST:                0 GB        2 KB      0.00%

Generating files from /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/zephyr.elf for board: nucleo_g0b1re
[147/147] cd /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr && /home/test/s...ies.py --elf-file=/home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/zephyr.elf

Do Post-build checks

In this section we will see how to do post-build checks

Static Post-build checks

Here we will see how to do static post build checks

Check the location of the final target image

Lets check for the location of the final application target image to make sure the build is completed successfully without any errors.

(.venv) test:zephyr$ ls -l build/zep build/zephyr/
-rwxrwxr-x 1 test test   39190 Jan 24 18:38 zephyr.bin
-rw-rw-r-- 1 test test   23193 Jan 24 18:38 zephyr.dts
-rw-rw-r-- 1 test test    3011 Jan 24 18:38 zephyr.dts.d
-rw-rw-r-- 1 test test   97435 Jan 24 18:38 zephyr.dts.pre
-rwxrwxr-x 1 test test 1023460 Jan 24 18:38 zephyr.elf
-rw-rw-r-- 1 test test  399931 Jan 24 18:38 zephyr_final.map
-rw-rw-r-- 1 test test  110346 Jan 24 18:38 zephyr.hex
-rw-rw-r-- 1 test test  399931 Jan 24 18:38 zephyr.map
-rwxrwxr-x 1 test test 1024056 Jan 24 18:38 zephyr_pre0.elf
-rw-rw-r-- 1 test test  400481 Jan 24 18:38 zephyr_pre0.map
-rw-rw-r-- 1 test test    4675 Jan 24 18:38 zephyr.stat

Runtime Post-build checks

Here we will see how to do runtime post-build checks

Flash the image

Run minicom in the normal terminal

$ sudo minicom -D /dev/serial/by-id/usb-STMicroelectronics_STM32_STLink_0669FF30304B4E3043024711-if02 -b 115200

The console will display like this

Welcome to minicom 2.8

OPTIONS: I18n
Port /dev/serial/by-id/usb-STMicroelectronics_STM32_STLink_0669FF30304B4E3043024711-if02, 17:35:21

Press CTRL-A Z for help on special keys

Flash the image using the west command in virtual environment.

(.venv) test:zephyr$ west flash
-- west flash: rebuilding
[1/1] cd /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr && /home/test/singl...ies.py --elf-file=/home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/zephyr.elf
-- west flash: using runner stm32cubeprogrammer
      -------------------------------------------------------------------
                        STM32CubeProgrammer v2.15.0
      -------------------------------------------------------------------

ST-LINK SN  : 0669FF30304B4E3043024711
ST-LINK FW  : V2J37M27
Board       : NUCLEO-G0B1RE
Voltage     : 3.24V
SWD freq    : 4000 KHz
Connect mode: Under Reset
Reset mode  : Hardware reset
Device ID   : 0x467
Revision ID : Rev Z
Device name : STM32G0B0xx/B1xx/C1xx
Flash size  : 512 KBytes
Device type : MCU
Device CPU  : Cortex-M0+
BL Version  : 0x92



Memory Programming ...
Opening and parsing file: zephyr.hex
  File          : zephyr.hex
  Size          : 38.28 KB
  Address       : 0x08000000


Erasing memory corresponding to segment 0:
Erasing internal memory sectors [0 19]
Download in Progress:
[==================================================] 100%

File download complete
Time elapsed during download operation: 00:00:01.127

RUNNING Program ...
  Address:      : 0x8000000
Application is running, Please Hold on...
Start operation achieved successfully

now the output will be displayed in the minicom console.

Welcome to minicom 2.8

OPTIONS: I18n
Port /dev/serial/by-id/usb-STMicroelectronics_STM32_STLink_0669FF30304B4E3043024711-if02, 18:36:40

Press CTRL-A Z for help on special keys

uart:~$

Confirm if the prompt is displayed or not

We can confirm the application is successfully loaded without any errors if the prompt is displayed on the virtual environment.

uart:~$

Commands in Zephyr shell

In this section, we will see about zephyr shell commands in detail.

Commands to print kernel and thread related information

“cycles” subcommand is used to give information about the kernel cycles.

uart:~$ kernel cycles
cycles: 541874435 hw cycles

“stacks” subcommand is used to list the thread stack usage.

uart:~$ kernel stacks
0x20000430 sysworkq                         (real size 1024):   unused  816     usage  208 / 1024 (20 %)
0x20000100 shell_uart                       (real size 2048):   unused  872     usage 1176 / 2048 (57 %)
0x200002a0 idle                             (real size  256):   unused  168     usage   88 /  256 (34 %)
0x200011a0 IRQ 00                           (real size 2048):   unused 1652     usage  396 / 2048 (19 %)

“threads” subcommand is used to list kernel threads along with various information like priority, state and stack size.

uart:~$ kernel threads
Scheduler: 1529 since last call
Threads:
 0x20000430 sysworkq
        options: 0x0, priority: -1 timeout: 0
        state: pending, entry: 0x8005681
        stack size 1024, unused 816, usage 208 / 1024 (20 %)

*0x20000100 shell_uart
        options: 0x0, priority: 14 timeout: 0
        state: queued, entry: 0x8001d81
        stack size 2048, unused 872, usage 1176 / 2048 (57 %)

 0x200002a0 idle
        options: 0x1, priority: 15 timeout: 0
        state: , entry: 0x800782f
        stack size 256, unused 168, usage 88 / 256 (34 %)

Commands to print device related information

“list” subcommand is used to list the configured devices.

uart:~$ device list
devices:
- rcc40021000 (READY)
- reset-controller (READY)
- interrupt-controller40021800 (READY)
- gpio50001400 (READY)
- gpio50001000 (READY)
- gpio50000c00 (READY)
- gpio50000800 (READY)
- gpio50000400 (READY)
- gpio50000000 (READY)
- serial40004400 (READY)
- serial40013800 (READY)

Commands to print interrupt information

Commands to print how many HW entity like clocks,timers are present

Commands to print Overall RAM and SRAM usage

Commands to print information about flash space

Commands to print information about network interfaces

Commands to print information about wifi interfaces

Adding our own command in zephyr shell

In this section we will see how to see our own command in zephyr shell.

Adding main.c

Add the following instructions in main.c

(.venv) test:zephyr$ pwd
$HOME/zephyrproject/zephyr
(.venv) test:zephyr$ vi samples/hello_world/src/main.c

main.c

#include <zephyr/kernel.h>
#include <zephyr/shell/shell.h>

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

    shell_print(shell, "Hello, World!");
    return 0;
}

SHELL_CMD_REGISTER(hello, NULL, "Prints 'Hello, World!'", hello_cmd_handler);

Explanation of APIs in main.c

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

        shell_print(shell, "Hello, World!");
        return 0;
}

This defines a function named hello_cmd_handler, which will be the handler for the custom shell command.
The function does not use the argc and argv parameters, so “ARG_UNUSED(argc)” and “ARG_UNUSED(argv)” are used to avoid compiler warnings about unused parameters.
“shell_print” is used to print the “Hello, World!” message to the shell.

SHELL_CMD_REGISTER(hello, NULL, "Prints 'Hello, World!'", hello_cmd_handler);

This line registers the hello command with the Zephyr shell.
The SHELL_CMD_REGISTER macro takes four parameters:
- hello: The name of the command. Users will type this command in the shell.
- NULL: The subcommands. In this case, there are no subcommands, so it’s set to NULL.
- “Prints ‘Hello, World!’”: A description of the command, which will be displayed when users type help in the shell.
- hello_cmd_handler: The function that will handle the command.

Building the application

run west build to build the application.

(.venv) test:zephyr$ west build -b nucleo_g0b1re samples/hello_world/


-- west build: generating a build system
Loading Zephyr default modules (Zephyr base).
-- Application: /home/test/single_thread_zephyr_build/zephyrproject/zephyr/samples/hello_world
-- CMake version: 3.24.2
-- Found Python3: /home/test/single_thread_zephyr_build/zephyrproject/.venv/bin/python3 (found suitable version "3.10.7", minimum required is "3.8") found components: Interpreter
-- Cache files will be written to: /home/test/.cache/zephyr
-- Zephyr version: 3.5.99 (/home/test/single_thread_zephyr_build/zephyrproject/zephyr)
-- Found west (found suitable version "1.2.0", minimum required is "0.14.0")
-- Board: nucleo_g0b1re
-- ZEPHYR_TOOLCHAIN_VARIANT not set, trying to locate Zephyr SDK
-- Found host-tools: zephyr 0.16.4 (/home/test/double_thread_zephyr_build/zephyr-sdk-0.16.4)
-- Found toolchain: zephyr 0.16.4 (/home/test/double_thread_zephyr_build/zephyr-sdk-0.16.4)
-- Found Dtc: /home/test/double_thread_zephyr_build/zephyr-sdk-0.16.4/sysroots/x86_64-pokysdk-linux/usr/bin/dtc (found suitable version "1.6.0", minimum required is "1.4.6")
-- Found BOARD.dts: /home/test/single_thread_zephyr_build/zephyrproject/zephyr/boards/arm/nucleo_g0b1re/nucleo_g0b1re.dts
-- Generated zephyr.dts: /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/zephyr.dts
-- Generated devicetree_generated.h: /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/include/generated/devicetree_generated.h
-- Including generated dts.cmake file: /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/dts.cmake
/home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/zephyr.dts:625.10-633.5: Warning (simple_bus_reg): /soc/clocks: missing or empty reg/ranges property
Parsing /home/test/single_thread_zephyr_build/zephyrproject/zephyr/Kconfig
Loaded configuration /home/test/single_thread_zephyr_build/zephyrproject/zephyr/boards/arm/nucleo_g0b1re/nucleo_g0b1re_defconfig
Merged configuration /home/test/single_thread_zephyr_build/zephyrproject/zephyr/samples/hello_world/prj.conf
Configuration saved to /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/.config
Kconfig header saved to /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/include/generated/autoconf.h
-- Found GnuLd: /home/test/double_thread_zephyr_build/zephyr-sdk-0.16.4/arm-zephyr-eabi/bin/../lib/gcc/arm-zephyr-eabi/12.2.0/../../../../arm-zephyr-eabi/bin/ld.bfd (found version "2.38")
-- The C compiler identification is GNU 12.2.0
-- The CXX compiler identification is GNU 12.2.0
-- The ASM compiler identification is GNU
-- Found assembler: /home/test/double_thread_zephyr_build/zephyr-sdk-0.16.4/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc
-- Using ccache: /usr/bin/ccache
-- Configuring done
-- Generating done
-- Build files have been written to: /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build
-- west build: building application
[1/147] Preparing syscall dependency handling

[3/147] Generating include/generated/version.h
-- Zephyr version: 3.5.99 (/home/test/single_thread_zephyr_build/zephyrproject/zephyr), build: zephyr-v3.5.0-4239-gcbc9439bc0ff
[146/147] Linking C executable zephyr/zephyr.elf
Memory region         Used Size  Region Size  %age Used
           FLASH:       39190 B       512 KB      7.47%
             RAM:        9376 B       144 KB      6.36%
        IDT_LIST:          0 GB         2 KB      0.00%
Generating files from /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/zephyr.elf for board: nucleo_g0b1re
[147/147] cd /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr && /home/test/singl...orities.py --elf-file=/home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/zephyr.elf

Executing our own command in zephyr shell

run “minicom” command in the normal terminal

$ sudo minicom -D /dev/serial/by-id/usb-STMicroelectronics_STM32_STLink_0669FF30304B4E3043024711-if02 -b 115200

run “west flash” command in the virtual terminal

(.venv) test:zephyr$ west flash
-- west flash: rebuilding
[1/1] cd /home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr && /home/test/single_th...orities.py --elf-file=/home/test/single_thread_zephyr_build/zephyrproject/zephyr/build/zephyr/zephyr.elf
-- west flash: using runner stm32cubeprogrammer
      -------------------------------------------------------------------
                        STM32CubeProgrammer v2.15.0
      -------------------------------------------------------------------

ST-LINK SN  : 0669FF30304B4E3043024711
ST-LINK FW  : V2J37M27
Board       : NUCLEO-G0B1RE
Voltage     : 3.24V
SWD freq    : 4000 KHz
Connect mode: Under Reset
Reset mode  : Hardware reset
Device ID   : 0x467
Revision ID : Rev Z
Device name : STM32G0B0xx/B1xx/C1xx
Flash size  : 512 KBytes
Device type : MCU
Device CPU  : Cortex-M0+
BL Version  : 0x92



Memory Programming ...
Opening and parsing file: zephyr.hex
  File          : zephyr.hex
  Size          : 38.27 KB
  Address       : 0x08000000


Erasing memory corresponding to segment 0:
Erasing internal memory sectors [0 19]
Download in Progress:
[==================================================] 100%

File download complete
Time elapsed during download operation: 00:00:01.129

RUNNING Program ...
  Address:      : 0x8000000
Application is running, Please Hold on...
Start operation achieved successfully

now the output is displayed on the minicom console.

Welcome to minicom 2.8

OPTIONS: I18n
Port /dev/serial/by-id/usb-STMicroelectronics_STM32_STLink_0669FF30304B4E3043024711-if02, 18:36:40

Press CTRL-A Z for help on special keys

Booting Zephyr

uart:~$

run “hello” on the minicom console to execute our own command.

uart:~$ hello
Hello, World!