Microshell - a lightweight pure C implementation of shell emulator dedicated for embedded bare-metal systems.

Build Status codecov

MicroShell

Lightweight pure C implementation of virtual shell, compatible with VT100 terminal. Support root tree, run-time mounting paths, global commands, and much more. Works out-of-the-box on Arduino-compatible boards. Dedicated for bare-metal embedded systems. Thanks to the asynchronous architecture it does not block operations and can be easily implemented even on small microcontrollers with relatively small resources.

Project Homepage
LIVE DEMO <- needs PC web browser (not mobile)

alt text

Features

  • names autocompletation (do You like a TAB-functionality on You favorite bash shell?)
  • no dynamic allocations (no memory leaks - no problem)
  • hardware independent (works just as well on AVR, PIC, STM32, ESP32 as it on x86 or RPI)
  • rich set of examples (available in the Arduino Library Manager)
  • pure C source code (works on rich set of compilers)
  • backspace key feature (simply works)
  • compatible vith VT100 standard (works out of the box with default putty configuration)
  • easy to extend (adding more "weird" features it has never been easier)
  • buildin commands (must-have, basic support of LS, CAT, PWD, HELP, XXD, ECHO)
  • scalable (configuration allows You to exclude unnecessary modules from building)
  • translation-ready (do You want Hindi translation? no problem!)
  • no internal buffers (support unlimited data stream lengths)
  • no static variables (possibility to use multiple independent shells in single system)
  • object oriented architecture (pointers attack!)
  • support root tree with static virtual files with callbacks (full customization)
  • extremely simple to integrate (only 1 simple interface with IO operations)
  • asynchronous architecture (static callbacks is not a problem)
  • non-blocking api (You just need to call one non-blocking function on main loop)
  • unit and functional tests (for greater certainty that nothing will break down)

Build

Build, test and run DEMO:

cmake -Bbuild .
cd build
make
make test
make coverage
./bin/demo

Usage

Define I/O interface:

// non-blocking read interface
static int ush_read(struct ush_object *self, char *ch)
{
    // should be implemented as a FIFO
    if (Serial.available() > 0) {
        *ch = Serial.read();
        return 1;
    }
    return 0;
}

// non-blocking write interface
static int ush_write(struct ush_object *self, char ch)
{
    // should be implemented as a FIFO
    return (Serial.write(ch) == 1);
}

// I/O interface descriptor
static const struct ush_io_interface ush_iface = {
    .read = ush_read,
    .write = ush_write,
};

Define shell descriptor and shell instance:

// working buffers allocations (size could be customized)
#define BUF_IN_SIZE    32
#define BUF_OUT_SIZE   32
#define PATH_MAX_SIZE  32

static char ush_in_buf[BUF_IN_SIZE];
static char ush_out_buf[BUF_OUT_SIZE];

// microshell instance handler
static struct ush_object ush;

// microshell descriptor
static const struct ush_descriptor ush_desc = {
    .io = &ush_iface,                           // I/O interface pointer
    .input_buffer = ush_in_buf,                 // working input buffer
    .input_buffer_size = sizeof(ush_in_buf),    // working input buffer size
    .output_buffer = ush_out_buf,               // working output buffer
    .output_buffer_size = sizeof(ush_out_buf),  // working output buffer size
    .path_max_length = PATH_MAX_SIZE,           // path maximum length (stack)
    .hostname = "arduino",                      // hostname (in prompt)
};

// root directory handler
static struct ush_node_object root;

Setup and run:

void setup()
{
    // initialize I/O interface
    Serial.begin(115200UL);

    // initialize microshell instance
    ush_init(&ush, &ush_desc);

    // mount root directory (root must be first)
    ush_node_mount(&ush, "/", &root, NULL, 0);

    // mount other directories here
    // ...
}

void loop()
{
    // non-blocking microshell service
    ush_service(&ush);

    // do other non-blocking stuff here
    // ...
}

Contribution

If You want to contribute this project - excellent! Fork it, make bugs, and send a PR :)
If You want to support me in developing this project - please donate!
paypal

Similar Resources

This is a repository entirely dedicated to all kind of questions ranging from basic DSA to CP. It aims to provide a solution to different questions. πŸ“š

πŸŽ‰ CP-DSA-Questions πŸŽ‰ This is a repository entirely dedicated to all kind of questions ranging from basic DSA to CP. It aims to provide a solution to

Dec 28, 2022

Repository dedicated for beginner to compete in Hacktoberfest 2021 challenge . Create HactoberFest Pull Request

Repository dedicated for beginner to compete in Hacktoberfest 2021 challenge . Create HactoberFest Pull Request

πŸ–₯️ HACKT0BERFEST-2021 πŸ’» This repo's main purpose is to help newbies πŸ‘Ά to complete the Hacktoberfest Challenge. STEPS:- 1. Create a GitHub account a

Nov 7, 2022

Embedded Flutter runtime targeting Embedded Linux with Wayland

ivi-homescreen IVI Homescreen for Wayland Strongly Typed (C++) Lightweight Clang 11 Release Stripped = 151k GCC 9.3 Release Stripped = 168k Source run

Dec 13, 2022

SAE J1939 protocol free to use for embedded systems or PC with CAN-bus

SAE J1939 protocol free to use for embedded systems or PC with CAN-bus

Open SAE J1939 SAE J1939 is a protocol for shaping the CAN-bus message in a specific way that suits industrial vehicles such as tractors, machinery, t

Dec 23, 2022

Embox is a configurable RTOS designed for resource constrained and embedded systems

Embox is a configurable RTOS designed for resource constrained and embedded systems. Embox main idea is using Linux software without Linux.

Dec 28, 2022

F Graphics Library (FGL) is a small graphics C++ portable library for LCD displays on embedded systems

F Graphics Library (FGL) Full documentation: fgl.docsforge.com (By Filipe Chagas) F Graphics Library is a C++ library that I created for use in embedd

Oct 31, 2022

Final Assignment for Embedded Real Time Operating Systems at UCSD Extension.

Final Assignment for Embedded Real Time Operating Systems at UCSD Extension. This program is for a certificate in Embedded Software Engineering at UCSD. We used FreeRTOS running on a STM32L475G Microcontroller.

Jun 26, 2022

A CANopen protocol for all systems such as embedded, PC, etc.

A CANopen protocol for all systems such as embedded, PC, etc.

Easy CANopen Easy CANopen is a protocol for shaping the CAN-bus message in a specific way that suits industrail automation. CANopen is a very difficul

Jan 4, 2023

A repo containing examples of embedded systems based on the STM32 micro-controller.

A repo containing examples of embedded systems based on the STM32 micro-controller.

STM32 Embedded Development A repo containing examples of embedded systems based on the STM32 micro-controller. I use a Nucleo-F446RE and the STM32Cube

Jan 10, 2022
Comments
  • New function ush_printf() providing a more flexible command output to console

    New function ush_printf() providing a more flexible command output to console

    Implemented new function ush_printf() to get better flexibility of command output to console. It is possible to use multiple calls as ush_printf() output is by default concatenated in the output_buffer.

  • Failed to build demo_linux

    Failed to build demo_linux

    Here's what I did After adding

    cmake_minimum_required(VERSION 3.20)    
    project(MicroShell) 
    

    To CMakeLists.txt to top cmake moaning.

    mkdir build 
    cd build
    cmake ..
    
    CMake Error at CMakeLists.txt:7 (build_ush):
      Unknown CMake command "build_ush".
    
    
    -- Configuring incomplete, errors occurred!
    See also "/home/andrewh/Source/microshell/examples/demo_linux/CMakeFiles/CMakeOutput.log".
    
    

    Please advise

  • Add support for Meson and update CMake files

    Add support for Meson and update CMake files

    I'm attempting to use microshell in my project. However, I'm using Meson. I have added preliminary support for Meson. I looked over the way ush_config.h is handled and I've moved it over as build options for both Meson and CMake.

    With the Arduino platform, I have left the ush_config.h as-is since the platform doesn't use neither Meson or CMake.

    This is a work in progress as I'm attempting to add unit testing support to it, as well as generating the POSIX demo.

    Β 

    From what I can see, the build process for microshell builds as a library, but also generates bin/demo, as well as running unit tests. Is this correct?

  • [Bug] Paste sometimes misses characters on STM32

    [Bug] Paste sometimes misses characters on STM32

    I have non blocking reads and writes set up over UART using HAL_UART_Transmit_IT and HAL_UART_Receive_IT, and when I paste into the terminal, it sometimes misses characters.

    I have adjusted buffer sizes, and various UART settings to no avail.

    Would be happy to gather some data to help troubleshoot this issue, but I am not entirely sure where to start.

Northstar-dedicated - Docker container for the Northstar dedicated server. Also includes general notes on running the dedi on Linux. WIP.

northstar-dedicated Docker image for the Northstar dedicated server. Not ready yet (it'll probably be another day or two). Versioning Tentative. Stabl

Jan 6, 2023
A C++ bare metal environment for Raspberry Pi with USB (32 and 64 bit)

A C++ bare metal environment for Raspberry Pi with USB (32 and 64 bit)

Jan 2, 2023
A bare metal SDK for the ESP32 & ESP32C3
A bare metal SDK for the ESP32 & ESP32C3

MDK (Minimal Development Kit) - a baremetal ESP32/ESP32C3 SDK An bare metal, make-based SDK for the ESP32, ESP32C3 chips. It is written from scratch u

Jan 2, 2023
Dexed FM synthesizer similar to DX7 running on a bare metal Raspberry Pi

Dexed is a FM synthesizer closely modeled on the famous DX7 by a well-known Japanese manufacturer. MiniDexed is a port to run it on a bare metal Raspberry Pi (without a Linux kernel or operating system).

Dec 27, 2022
A place to collaborate on code for the Embedded.fm book club. Currently reading "STM32 ARM Programming for Embedded Systems".

Welcome to the Book Club Code site! This is a place for the Embedded.fm book club to collaborate and learn together. Repo Structure Guide Top-level fo

Jul 21, 2022
My_Shell is a user-defined interactive shell written in C that works similar to the original shell in linux

MY_SHELL Overview My_Shell is a user-defined interactive shell written in C that works similar to the original shell and it can execeute many of the l

Nov 22, 2021
Newlib for Xuantie RISC-V CPU, a lightweight C library for embedded systems.

README for GNU development tools This directory contains various GNU compilers, assemblers, linkers, debuggers, etc., plus their support routines, d

Sep 9, 2022
Lightweight date, time & cron utilities for embedded systems

Lightweight Date, Time & Cron Platform independent Date, Time & Cron Utility library Read first: Documentation Features Written in ANSI C99 Platform i

Oct 31, 2022
Hobbyist Operating System targeting x86_64 systems. Includes userspace, Virtual File System, An InitFS (tarfs), Lua port, easy porting, a decent LibC and LibM, and a shell that supports: piping, file redirection, and more.
Hobbyist Operating System targeting x86_64 systems. Includes userspace, Virtual File System, An InitFS (tarfs), Lua port, easy porting, a decent LibC and LibM, and a shell that supports: piping, file redirection, and more.

SynnixOS Epic Hobby OS targeting x86_64 CPUs, it includes some hacked together functionality for most essential OSs although, with interactivity via Q

Oct 28, 2022
A shell for unix and linux systems

Snash A shell for unix/linux A shell for unix and linux systems. This is still a work in progress and ALOT has yet to be implemented. Snash stands for

Dec 2, 2022