{"id":10250,"date":"2024-03-18T21:17:00","date_gmt":"2024-03-18T20:17:00","guid":{"rendered":"https:\/\/playembedded.org\/?p=10250"},"modified":"2025-01-13T10:28:28","modified_gmt":"2025-01-13T09:28:28","slug":"cli-chibios-shell","status":"publish","type":"post","link":"https:\/\/playembedded.org\/blog\/cli-chibios-shell\/","title":{"rendered":"Build your Command Line Interface: a Guide to ChibiOS\/Shell"},"content":{"rendered":"

Introduction<\/h2>\n\n\n\n

In this article, we explore the ChibiOS\/Shell, a fully configurable Command Line Interface (CLI) provided by ChibiOS. This tool allows users to interact with the operating system, execute tasks, and access system features through available serial drivers, utilizing either USB or UART connections.<\/p>\n\n\n\n

Embedded systems face a unique challenge because they are closed systems operating on an integrated chip without the interactive interfaces like a mouse or keyboard found on PCs. Programming on these microcontrollers typically creates a system that responds to specific events by generating outputs. These events usually come from external hardware and result in actions on other hardware components. For example, consider a smart miniature greenhouse with a temperature sensor. Positioned to receive sunlight, the greenhouse includes a small window operated by a servo. When the microcontroller reads the temperature sensor and detects that the temperature has exceeded a predetermined threshold, it opens the window to cool down the environment.<\/p>\n\n\n

\n
\"\"
Smart greenhouse control system with temperature-triggered window mechanism.<\/figcaption><\/figure>\n<\/div>\n\n\n

The system described operates in a closed loop, meaning we cannot directly influence its programmed behavior. Now, imagine if the microcontroller could accept commands with parameters through one of its serial ports. Upon receiving these commands, it would perform specific internal operations and provide feedback via the serial output. For instance, it might allow for the adjustment of the temperature threshold that triggers the window to open. Alternatively, it could enable manual control over the window, allowing it to be opened or closed on command.<\/p>\n\n\n

\n
\"\"
Enhanced smart greenhouse system with Shell integration for command input and control.<\/figcaption><\/figure>\n<\/div>\n\n\n

Furthermore, this command line can be used to display sensor data upon request, transforming it into a powerful tool. This capability is precisely what the Shell offers. At its core, a Shell is a Command Line Interface that operates on one of the microcontroller’s COM ports. It is engineered to accept commands and return responses. A command consists of a sequence of human-readable characters, potentially accompanied by optional parameters. Consider the command below, followed by two parameters:<\/p>\n\n\n\n

set threshold 35<\/pre>\n\n\n\n
In this example, the command is set<\/code>, with threshold<\/code> and 35<\/code> serving as the parameters. When a command is executed, it is linked to a specific function that receives these parameters as arguments. The action taken by the function then depends on how it is programmed by the user.<\/p>\n\n\n\n
Reflecting on our smart greenhouse scenario, such a command could adjust the temperature level that triggers the greenhouse door to open. The command might carry out verifications before setting a global variable, and if the command is processed successfully, the response might be:<\/p>\n\n\n\n
set threshold OK<\/pre>\n\n\n\n
This capability illustrates how commands can dynamically interact with the system’s settings, enabling users to tailor the system’s behavior according to specific needs or conditions.<\/p>\n\n\n\n
Setting up and running the Shell<\/h2>\n\n\n\n
The best way to really get to know what the Shell can do is by starting a test project that uses it. This gives us a hands-on chance to see how it works. A good starting point is using  The simplest project ever with ChibiOS<\/a>, chosen for an evaluation kit we like. From there we can expand the project using one of the many demo based on ChibiOS\/Shell that ChibiOS offers.<\/p>\n\n\n\n
This method helps us get familiar with the Shell quickly and shows us how we can adjust it for our own projects. By doing this, we can learn about the Shell’s capabilities and how to make the most of them in our embedded systems.<\/p>\n\n\n\n
Preliminary information<\/h3>\n\n\n\n
The best reference about how to use the Shell is the demo USB-CDC demo available under [ChibiOS Root]\\testhal\\STM32\\multi\\USB_CDC<\/em>. This demo shows the application of the Shell using the Serial Driver over USB. The SoUSB is a Complex Device Driver that programs a microcontroller native USB peripheral into into a virtual COM port, which the PC can recognize as such. However, doing so requires to deal with USB descriptors and some other complexities related to the USB standard: diving into this while still trying to understand the Shell’s workings might be overly complex because it involves managing several advanced features at once.<\/p>\n\n\n\n
Luckily, the Shell is modeled around an abstract interface called BaseSequentialStream<\/code>. The underlying principle of adopting an interface such as BaseSequentialStream<\/code> is that it acts as a contract between the application layer and the driver, defining four common methods: write<\/code>, read<\/code>, put<\/code>, and get<\/code>. Both SerialDriver and SerialDriver over USB adhere to this contract, extending it, which enables their use in any context requiring a BaseSequentialStream<\/code>. Now, as the Shell relies on these four common methods, it can be interoperable with both drivers.<\/p>\n\n\n
\n
\"\"
Diagram illustrating the Shell interaction with UART and USB-specific implementations of BaseSequentialStream, highlighting the common API and device-specific extensions.<\/figcaption><\/figure>\n<\/div>\n\n\n
For those looking for more details,  Appendic A<\/a> of the article about the chprintf<\/code> in the article is a good reference. But right now, we are focusing on running the Shell with a Serial Driver to make our first steps with this library easier. If you are not familiar with the Serial Driver, it might be helpful to check out ChibiOS\/HAL’s Serial Driver Explained<\/a>.<\/p>\n\n\n\n
In the example I will show next, I am using the SDP-K1 evaluation kit, specifically the Serial Driver 5. This driver is selected because UART5 on this evaluation kit can be directly connected to the PC through the Debugger. Thus, when we connect our kit to the PC, we immediately gain access to a COM port that is linked to UART5 on the microcontroller, making it ready to use right away.<\/p>\n\n\n
\n
\"\"
The debugger COM port bridge of the SDP-K1<\/figcaption><\/figure>\n<\/div>\n\n\n
Integrating the Shell in our project<\/h3>\n\n\n\n
The Shell is an optional library that must be explicitly integrated into your project to be utilized. This process typically involves adding specific files and configuring the makefile, which aids in minimizing the compiled code size by including only what is necessary. This strategy ensures that if the Shell is not needed, the codebase remains streamlined without unnecessary additions.<\/p>\n\n\n\n
To activate the Shell, we need to incorporate certain dependencies into our makefile under “Project, target, sources and paths<\/code>“. There are primarily three groups of dependencies to be added:<\/p>\n\n\n\n