Skip to content

Commit f75da67

Browse files
jasonrandrewsjasonrandrews
authored
Merge pull request #3325 from odincodeshen/feature/zephyrrtos_shell
Build a Lightweight Shell on Cortex-M with Zephyr RTOS
2 parents 08d208f + 1e47690 commit f75da67

11 files changed

Lines changed: 847 additions & 0 deletions

File tree

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

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
title: Set up your environment
3+
weight: 2
4+
5+
### FIXED, DO NOT MODIFY
6+
layout: learningpathall
7+
---
8+
9+
## Set up your environment
10+
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+
13+
- MQTT over Ethernet
14+
- UART over a USB serial connection
15+
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:
21+
22+
- The Workbench for Zephyr extension installed
23+
- A Zephyr SDK toolchain imported in Workbench
24+
- A West workspace initialized
25+
26+
If you have not done this yet, complete [Build Zephyr projects with Workbench for Zephyr in VS Code learnin path](/learning-paths/embedded-and-microcontrollers/zephyr_vsworkbench/) first.
27+
28+
You also need:
29+
30+
- Docker Desktop, Docker Engine, or another Docker-compatible runtime
31+
- A USB cable for each development board
32+
33+
## Hardware requirements
34+
35+
For the MQTT shell example, use a Zephyr-supported development board with Ethernet. The instructions use the [FRDM-MCXN947](https://www.nxp.com/design/design-center/development-boards-and-designs/FRDM-MCXN947), with the Zephyr board identifier `frdm_mcxn947/mcxn947/cpu0`.
36+
37+
For the UART shell example, use a Zephyr-supported development board with a USB UART interface. The instructions use the [FRDM-MCXN947](https://www.nxp.com/design/design-center/development-boards-and-designs/FRDM-MCXN947), with the Zephyr board identifier `frdm_mcxn947/mcxn947/cpu0`.
38+
39+
To check whether another board is supported by Zephyr, refer to the [Zephyr Supported Boards list](https://docs.zephyrproject.org/latest/boards/index.html).
40+
41+
## Install UART terminal tools
42+
43+
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.
44+
45+
### Windows
46+
47+
Install [PuTTY](https://www.putty.org/index.html), which provides a lightweight serial terminal for UART communication.
48+
49+
After installation:
50+
51+
1. Connect the development board over USB.
52+
53+
2. Open **Device Manager** and locate the board's COM port under **Ports (COM & LPT)**.
54+
55+
3. Open PuTTY and configure:
56+
57+
- **Connection type**: `Serial`
58+
59+
- **Serial line**: your board's COM port (for example `COM5`)
60+
61+
- **Speed**: `115200`
62+
63+
Select **Open** to connect to the Zephyr UART shell.
64+
65+
<p style="text-align:center;">
66+
<img src="/learning-paths/embedded-and-microcontrollers/zephyr_shell/images/putty_installation.png"
67+
alt="PuTTY Installation"
68+
width="640"
69+
style="max-width:100%;height:auto;" />
70+
<br/>
71+
<em>PuTTY Serial Terminal Configuration</em>
72+
</p>
73+
74+
### macOS
75+
76+
macOS includes a built-in UART terminal utility through the `screen` command, so no additional software is required.
77+
78+
After connecting the development board over USB:
79+
80+
1. Open a terminal window.
81+
82+
2. List available serial devices:
83+
84+
```bash
85+
86+
ls /dev/tty.*
87+
88+
```
89+
90+
3. Identify the board's serial device.
91+
92+
4. Connect to the UART shell with:
93+
94+
```bash
95+
96+
screen /dev/tty.usbmodemXXXX 115200
97+
98+
```
99+
100+
Replace `/dev/tty.usbmodemXXXX` with the serial device shown on your system.
101+
102+
To exit `screen`:
103+
104+
1. Press `Ctrl + A`
105+
106+
2. Press `K`
107+
108+
3. Press `Y` to confirm
109+
110+
{{% notice Note %}}
111+
112+
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.
113+
114+
{{% /notice %}}
115+
116+
## Network requirements
117+
118+
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.
119+
120+
Make sure that:
121+
122+
- The board is connected to the same network as the host computer.
123+
- The network provides DHCP, or you configure a static IPv4 address in `prj.conf`.
124+
- The board can reach the MQTT broker on port `1883`.
125+
126+
{{% notice Note %}}
127+
The example configuration uses IPv4. If your network does not provide DHCP, use the static IPv4 settings shown in the next section.
128+
{{% /notice %}}
129+
130+
## What's next?
131+
132+
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 or the built-in macOS `screen` utility.

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

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: Overview
3+
weight: 3
4+
5+
### FIXED, DO NOT MODIFY
6+
layout: learningpathall
7+
---
8+
9+
## What is the Zephyr shell?
10+
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+
13+
Several Zephyr subsystems register shell commands automatically. Common built-in modules include:
14+
15+
| Module | Example commands |
16+
|--------|------------------|
17+
| `kernel` | `version`, `uptime`, `thread list`, `thread stacks` |
18+
| `net` | `iface`, `ping`, `dns`, `tcp` |
19+
| `device` | `list` |
20+
| `log` | `enable`, `disable`, `levels` |
21+
| `shell` | `help`, `history`, `resize` |
22+
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`.
26+
27+
In this Learning Path you will work with two transports:
28+
29+
- `CONFIG_SHELL_BACKEND_MQTT=y` routes shell commands and responses over MQTT topics. Inbound on `<device_id>/sh/rx`, outbound on `<device_id>/sh/tx`. The backend connects automatically once the board has an IPv4 address. The MQTT backend is IPv4-only.
30+
- `CONFIG_SHELL_BACKEND_SERIAL=y` routes shell commands and responses over the board's UART interface. The shell is accessible through a USB serial connection using a terminal application such as PuTTY on Windows or the built-in `screen` utility on macOS. The UART backend works on a wide range of Zephyr-supported development boards with no additional debug hardware required.
31+
32+
Multiple backends can be enabled at the same time in a single application when the board has the required peripherals and memory.
33+
34+
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.
35+
36+
## What you will do next
37+
38+
The two following sections each build a small Zephyr application that enables one of these backends:
39+
40+
- **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.
41+
- **UART shell** on the FRDM-MCXN947, using a USB serial connection with PuTTY on Windows or the built-in `screen` utility on macOS.
42+
43+
Each example is portable to any Zephyr-supported board with the right peripheral (Ethernet for MQTT, J-Link for RTT). The "Switch to a different board" section near the end of each page shows how to change the target board on an existing project.
44+
45+
For more information on the shell subsystem, see the [Zephyr Shell documentation](https://docs.zephyrproject.org/latest/services/shell/index.html).
46+
47+
## What's next?
48+
49+
In the next section, you will build the MQTT shell on the FRDM-MCXN947, run Mosquitto in Docker, and exchange shell commands with the board over MQTT topics.

0 commit comments

Comments
 (0)