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

Overview

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

Issues
  • 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

    opened by andrewtholt 3
  • 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?

    opened by ijacquez 0
  • [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.

    opened by cosmikwolf 4
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

null 71 Jun 18, 2022
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)

Rene Stange 1.3k Jun 28, 2022
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

Sergey Lyubka 63 Jun 20, 2022
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).

null 575 Jun 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

Peter Griffin 10 Jan 13, 2022
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

T-Head Semiconductor Co., Ltd. 4 Jun 4, 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

Tilen Majerle 13 May 30, 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

Greeshma 1 Nov 22, 2021
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

RaidTheWeb 40 May 27, 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

Reinhold 4 Dec 21, 2021
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

Kanak 70 May 15, 2022
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

null 48 Apr 14, 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

null 148 Jun 17, 2022
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

Daniel Mårtensson 83 Jun 21, 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.

Embox 820 Jun 24, 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

Filipe Chagas 8 Dec 14, 2021
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.

Max Guerrero 2 Jun 26, 2022
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

Daniel Mårtensson 13 May 19, 2022
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

Vincent Ho 1 Jan 10, 2022