Skip to content

Commit 147f4ee

Browse files
jasonrandrewsjasonrandrews
authored
Merge pull request #3400 from anupras-mohapatra-arm/embedded-and-microcontrollers
Zephyr local shell LP review
2 parents c634147 + 3fe3c19 commit 147f4ee

5 files changed

Lines changed: 171 additions & 223 deletions

File tree

‎content/learning-paths/embedded-and-microcontrollers/zephyr_shell/1_installation.md‎

Lines changed: 25 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,131 +1,66 @@
11
---
22
title: Set up the Zephyr shell development environment
3+
description: Prepare the host tools, hardware, UART terminal, and network requirements needed to build Zephyr shell examples on Arm Cortex-M.
34
weight: 2
45

56
### FIXED, DO NOT MODIFY
67
layout: learningpathall
78
---
89

9-
## Set up the Zephyr shell development environment
10+
## Before you begin
1011

11-
In this section, you will prepare your host computer and identify the hardware needed for two Zephyr shell examples. You will use the shell over two transports:
12+
In this section, you'll prepare your host computer and identify the hardware you need for two Zephyr shell examples. You'll use the shell over two transports:
1213

1314
- MQTT over Ethernet
1415
- UART over a USB serial connection
1516

16-
By the end of this section, you will know which boards to use, which host tools to install, and how the Zephyr shell fits into an embedded application.
17-
18-
## Before you begin
19-
20-
Make sure you have a working Zephyr development environment set up in Visual Studio Code using the Workbench for Zephyr extension, including:
17+
Make sure that you have a working Zephyr development environment set up in Visual Studio Code with:
2118

22-
- The Workbench for Zephyr extension installed
19+
- The Workbench for Zephyr extension installed
2320
- A Zephyr SDK toolchain imported in Workbench
2421
- A West workspace initialized
2522

26-
If you have not done this yet, complete [Build Zephyr projects with Workbench for Zephyr in VS Code](/learning-paths/embedded-and-microcontrollers/zephyr_vsworkbench/) first.
23+
Before working through this Learning Path, complete [Build Zephyr projects with Workbench for Zephyr in VS Code](/learning-paths/embedded-and-microcontrollers/zephyr_vsworkbench/).
2724

28-
The two examples in this Learning Path have different additional requirements:
25+
The two examples in this Learning Path have additional requirements:
2926

30-
- **MQTT shell example**: Docker Desktop, Docker Engine, or another Docker-compatible runtime on your host computer. The board communicates with a Mosquitto broker running in a container.
31-
- **UART shell example**: A USB cable to connect the development board to your host computer. The board exposes a shell prompt over the USB serial interface.
27+
- MQTT shell example: Docker Desktop, Docker Engine, or another Docker-compatible runtime on your host computer, if you're not installing Mosquitto on host. The board communicates with a Mosquitto broker running in a container.
28+
- UART shell example: A USB cable to connect the development board to your host computer. The board exposes a shell prompt over the USB serial interface.
3229

3330
## Hardware requirements
3431

35-
Both examples use the [FRDM-MCXN947](https://www.nxp.com/design/design-center/development-boards-and-designs/FRDM-MCXN947) as the development board (Zephyr identifier `frdm_mcxn947/mcxn947/cpu0`). The FRDM-MCXN947 includes an Ethernet port for the MQTT shell example and a USB UART interface for the UART shell example, so both examples run on the same board.
36-
37-
To check whether another board is supported by Zephyr, see the [Zephyr Supported Boards list](https://docs.zephyrproject.org/latest/boards/index.html).
38-
39-
## Install UART terminal tools
40-
41-
For the UART shell example, install a serial terminal application on your host computer. You will use the terminal application to connect to the Zephyr shell over the board's UART interface. This Learning Path supports Windows, macOS, and Linux host computers.
42-
43-
### Windows
44-
45-
Install [PuTTY](https://www.putty.org/index.html), which provides a lightweight serial terminal for UART communication.
46-
47-
After installation:
32+
Both examples use the [FRDM-MCXN947](https://www.nxp.com/design/design-center/development-boards-and-designs/FRDM-MCXN947) as the development board (Zephyr identifier `frdm_mcxn947/mcxn947/cpu0`). The FRDM-MCXN947 includes an Ethernet port for the MQTT shell example and a USB UART interface for the UART shell example. This allows both examples to run on the same board.
4833

49-
1. Connect the development board over USB.
34+
To check whether another board is supported by Zephyr, see the [Zephyr supported boards list](https://docs.zephyrproject.org/latest/boards/index.html).
5035

51-
2. Open **Device Manager** and locate the board's COM port under **Ports (COM & LPT)**.
36+
## Set up UART terminal tools
5237

53-
3. Open PuTTY and configure:
38+
For the UART shell example, you'll need a serial terminal application on your host computer. You'll use the terminal application to connect to the Zephyr shell over the board's UART interface.
5439

55-
- **Connection type**: `Serial`
56-
- **Serial line**: your board's COM port (for example `COM5`)
57-
- **Speed**: `115200`
40+
You can complete this Learning Path on Windows, macOS, and Linux host computers.
5841

59-
Select **Open** to connect to the Zephyr UART shell.
42+
### Windows
6043

61-
![PuTTY configuration window with Connection type set to Serial, Serial line set to COM5, and Speed set to 115200, ready to connect to the Zephyr UART shell#center](images/putty_installation.webp "PuTTY Serial Terminal Configuration")
44+
Install [PuTTY](https://www.putty.org/index.html), which provides a lightweight serial terminal for UART communication on Windows.
6245

6346
### macOS
6447

65-
macOS includes a built-in UART terminal utility through the `screen` command, so no additional software is required.
66-
67-
After connecting the development board over USB:
68-
69-
1. Open a terminal window.
70-
71-
2. List available serial devices:
72-
73-
```bash
74-
ls /dev/tty.*
75-
```
76-
77-
3. Connect to the UART shell with:
78-
79-
```bash
80-
screen /dev/tty.usbmodemXXXX 115200
81-
```
82-
83-
Replace `/dev/tty.usbmodemXXXX` with the serial device shown on your system.
84-
85-
To exit `screen`, press `Ctrl + A`, then `K`, then `Y` to confirm.
48+
macOS includes a built-in UART terminal utility through the `screen` command, so you don't need additional software to connect to the shell.
8649

8750
### Linux
8851

89-
Linux includes `screen` in most distributions, so no additional software is required. If `screen` is not installed, use your package manager to install it:
52+
Linux includes `screen` in most distributions, so you don't need additional software to connect to the shell. If `screen` isn't installed, use your package manager to install it:
9053

9154
```bash
9255
sudo apt install screen
9356
```
94-
95-
After connecting the development board over USB:
96-
97-
1. Open a terminal window.
98-
99-
2. List available serial devices:
100-
101-
```bash
102-
ls /dev/ttyACM* /dev/ttyUSB*
103-
```
104-
105-
3. If you see a permission error when connecting, add your user to the `dialout` group and log out and back in:
106-
107-
```bash
108-
sudo usermod -aG dialout $USER
109-
```
110-
111-
4. Connect to the UART shell with:
112-
113-
```bash
114-
screen /dev/ttyACM0 115200
115-
```
116-
117-
Replace `/dev/ttyACM0` with the device shown on your system. Boards using a CP210x or FTDI USB-UART chip typically appear as `/dev/ttyUSB0`.
118-
119-
To exit `screen`, press `Ctrl + A`, then `K`, then `Y` to confirm.
120-
12157
{{% notice Note %}}
122-
Workbench for Zephyr supports multiple debug runners depending on the connected board. The FRDM-MCXN947 board uses the onboard CMSIS-DAP / LinkServer interface for flashing and debugging, while shell access in this Learning Path uses UART over USB.
123-
58+
Workbench for Zephyr supports multiple debug runners depending on the connected board. The FRDM-MCXN947 board uses the onboard CMSIS-DAP/LinkServer interface for flashing and debugging, and UART over USB for shell access.
12459
{{% /notice %}}
12560

12661
## Network requirements for the MQTT shell example
12762

128-
For the MQTT shell example, the board needs access to an MQTT broker over Ethernet. You will run Mosquitto locally with Docker Compose and use the Mosquitto command-line tools to send and receive shell messages.
63+
For the MQTT shell example, the board needs access to an MQTT broker over Ethernet. You'll run Mosquitto locally and use the Mosquitto command-line tools to send and receive shell messages.
12964

13065
Make sure that:
13166

@@ -134,9 +69,11 @@ Make sure that:
13469
- The board can reach the MQTT broker on port `1883`.
13570

13671
{{% notice Note %}}
137-
The example configuration uses IPv4. If your network does not provide DHCP, use the static IPv4 settings shown in the next section.
72+
The example configuration uses IPv4. If your network doesn't provide DHCP, use the static IPv4 settings shown in the next section.
13873
{{% /notice %}}
13974

140-
## What's next?
75+
## What you've learned and what's next
76+
77+
You've now learned which boards to use, which host tools to install, and how the Zephyr shell fits into an embedded application.
14178

142-
In the next section, you will read a short overview of the Zephyr shell subsystem and the two transports used in this Learning Path. After that, you will build the MQTT shell and the UART shell on the FRDM-MCXN947 using a USB serial connection and a UART terminal application such as PuTTY on Windows or `screen` on macOS and Linux.
79+
In the next section, you'll learn about the Zephyr shell subsystem and the two transports used in this Learning Path.

‎content/learning-paths/embedded-and-microcontrollers/zephyr_shell/2_overview.md‎

Lines changed: 16 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
11
---
22
title: Understand the Zephyr shell subsystem and backends
3+
description: Learn how the Zephyr shell subsystem and MQTT and UART backends route interactive commands on Arm Cortex-M firmware.
34
weight: 3
45

56
### FIXED, DO NOT MODIFY
67
layout: learningpathall
78
---
89

9-
## Understand the Zephyr shell subsystem and backends
10+
## How the Zephyr shell subsystem works
1011

11-
The Zephyr shell subsystem (`CONFIG_SHELL=y`) adds an interactive command-line interface to your firmware. After the shell is enabled, you can inspect system state, run subsystem commands, and trigger application behavior at runtime without rebuilding or reflashing the application.
12+
The Zephyr shell subsystem (`CONFIG_SHELL=y`) adds an interactive command-line interface to your firmware. After you enable the shell, you can inspect system state, run subsystem commands, and trigger application behavior at runtime without rebuilding or reflashing the application.
1213

1314
Several Zephyr subsystems register shell commands automatically. Common built-in modules include:
1415

@@ -20,31 +21,28 @@ Several Zephyr subsystems register shell commands automatically. Common built-in
2021
| `log` | `enable`, `disable`, `levels` |
2122
| `shell` | `help`, `history`, `resize` |
2223

23-
## How shell backends work
24-
25-
The shell command tree is independent of the transport. The same commands can run over UART, RTT, MQTT, or another enabled backend. You select a transport by setting a single Kconfig option, with no code changes in `main.c`.
24+
For more information on the shell subsystem, see the [Zephyr shell documentation](https://docs.zephyrproject.org/latest/services/shell/index.html).
2625

27-
In this Learning Path you will work with two transports:
26+
## How shell backends work
2827

29-
**MQTT backend** (`CONFIG_SHELL_BACKEND_MQTT=y`)
28+
The shell command tree is independent of the transport. The same commands can run over UART, RTT, MQTT, or another enabled backend. You can select a transport by setting a single Kconfig option, with no code changes in `main.c`.
3029

31-
Routes shell commands and responses over MQTT topics. The board subscribes to `<device_id>/sh/rx` for inbound commands and publishes responses to `<device_id>/sh/tx`. The backend connects automatically once the board has an IPv4 address. This backend is IPv4-only.
30+
You can enable multiple backends at the same time in a single application when the board has the required peripherals and memory.
3231

33-
**UART backend** (`CONFIG_SHELL_BACKEND_SERIAL=y`)
32+
A minimal shell build with only the kernel and device modules adds roughly 10 to 15 KB to flash and a few hundred bytes to RAM on a Cortex-M target. The exact footprint depends on the modules enabled and the toolchain optimization level.
3433

35-
Routes shell commands and responses over the board's UART interface, accessible through a USB serial connection. Use PuTTY on Windows, or `screen` on macOS and Linux. This backend works on a wide range of Zephyr-supported development boards with no additional debug hardware required.
34+
In this Learning Path, you'll work with two transports:
3635

37-
Multiple backends can be enabled at the same time in a single application when the board has the required peripherals and memory.
36+
### MQTT backend
3837

39-
A minimal shell build with only the kernel and device modules adds roughly 10 to 15 KB to flash and a few hundred bytes to RAM on a Cortex-M target, though the exact footprint depends on the modules enabled and the toolchain optimization level.
38+
Enable the MQTT backend with `CONFIG_SHELL_BACKEND_MQTT=y`. The MQTT backend routes shell commands and responses over MQTT topics. The board subscribes to `<device_id>/sh/rx` for inbound commands and publishes responses to `<device_id>/sh/tx`. The backend is IPv4-only and connects automatically when the board has an IPv4 address.
4039

41-
## What you will build next
40+
### UART backend
4241

43-
The next two sections each build a small Zephyr application that enables one of these backends:
42+
Enable the UART backend with `CONFIG_SHELL_BACKEND_SERIAL=y`. The UART backend routes shell commands and responses over the board's UART interface, accessible through a USB serial connection. Use PuTTY on Windows, or `screen` on macOS and Linux. This backend works on a wide range of Zephyr-supported development boards without the need for additional debug hardware.
4443

45-
- **MQTT shell** on the NXP FRDM-MCXN947, with a local Mosquitto broker running in Docker. You will send commands and read responses with the `mosquitto_pub` and `mosquitto_sub` command-line tools.
46-
- **UART shell** on the FRDM-MCXN947, using a USB serial connection with PuTTY on Windows or `screen` on macOS and Linux.
44+
## What you've accomplished and what's next
4745

48-
Each example is portable to any Zephyr-supported board with the right peripheral — Ethernet for the MQTT backend, USB UART for the UART backend. The "Switch to a different board" section near the end of each page shows how to change the target board on an existing project.
46+
You've now learned how the Zephyr shell subsytem and shell backends work.
4947

50-
For more information on the shell subsystem, see the [Zephyr Shell documentation](https://docs.zephyrproject.org/latest/services/shell/index.html).
48+
Next, you'll build a small Zephyr application that enables the MQTT shell on the NXP FRDM-MCXN947, with a local Mosquitto broker running in Docker. You'll send commands and read responses with the `mosquitto_pub` and `mosquitto_sub` command-line tools.

0 commit comments

Comments
 (0)