lispBM: A Lisp for Microcontrollers

LispBM Gallery

Have you done something cool with LispBM? Send us a picture for our LispBM Gallery! You can view the full gallery to see all the amazing projects from our community.

Community & Contribution

LispBM is made possible by an amazing community of developers who contribute their time, expertise, and passion. You can meet our contributors to see the people behind the project.

There are lots of interesting things to code on in and around the LispBM runtime system. I would love to interact with people who are interested in high-level programming languages on microcontrollers (or elsewhere) so please do not be shy to make contact. Together we can make great stuff happen!

Get Involved

1. Are you interested in microcontrollers and programming languages?
2. Do you like both imperative and functional programming?
3. Clone the repository and join the fun!
4. Join the Discord server

Areas Where Help Is Needed

There are areas where insights and help would matter greatly. Some I can think of are:

1. Running LispBM on system simulators.
2. LispBM efficiency.
3. Code size optimization. Do more with less, while maintaining performance.
4. Documentation and testing.
5. Useful extension libraries.
6. Lisp scriptable home automation.
7. Lisp scriptable MIDI sequencers.
8. Lisp scriptable Audio synthesizers.
9. (WIP) Porting the Linux REPL to Windows.
10. Interface with Rust as a language for writing LBM extensions.
11. Partial-evaluation, supercompilation and byte-code compilation.
12. Real-time garbage collection.
13. Linter/code-preprocessor/checker tailored to LBM idiosyncrasies.
14. Quickcheck-like property based testing of programs written in LBM.
15. Additional platforms (a maintainer for the Zephyr platform support is needed).

Want to join this incredible community? Dive straight into the GitHub repository. Every contribution, no matter how small, is valued and appreciated!

Getting started with LispBM

Getting started on embedded: easy

The easiest way to get started with LispBM programming is to use VESC Tool together with the VESC EXPRESS Firmware on an esp32c3.

VESC-Tool gives you access to a very capable IDE for Lisp programming on embedded systems and the VESC Express firmware provides built-in functionality to interface with CAN, WiFi, BLE and UART as well as GPIO and display drivers.

Keep an eye on the VESC Labs website for devices that come with LispBM per default.

Getting started on embedded: easy (no vesc)

In the directory 'examples/esp32c3' there is an example setup targeting the esp32c3-devkitm-mini1 (available on Mouser or Digikey) and FreeRTOS.

This is a suitable starting point for integrating LispBM scripting into your own FreeRTOS based projects.

Precompiled Binaries

For quick testing, precompiled binaries are available: esp32c3-repl.zip

The precompiled binaries can be flashed onto the development kit with the following command:

esptool.py --chip esp32c3 --port /dev/ttyUSB0 --baud 460800 write-flash \
    0x0 bootloader.bin \
    0x8000 partition-table.bin \
    0x10000 repl.bin

Building and Flashing

To build and flash the ESP32C3 example, follow these steps:

First, process the flash partition table:

idf.py partition-table

Then build the project:

idf.py build

Flash the firmware to your ESP32C3:

idf.py flash

Finally, connect to the development kit using a serial terminal (such as minicom) or run:

idf.py monitor

You can now interact with a simple REPL on your ESP32C3.

Getting started on embedded: hard

If you want to build your own lisp environment based on LispBM on top of ChibiOS, Zephyr, FreeRTOS or bare-metal then this is quite possible!

For a simple example using FreeRTOS, look at Getting started on embedded: easy (no vesc). Another source for information on how to do LispBM and FreeRTOS, look at VESC EXPRESS. For ChibiOS integration look at the benchmark runner bench-chibi or for a more thorough integration VESC BLDC. Finally there is also the Linux REPL that one can look at for ideas.

Getting started on Linux

Start by cloning the LispBM repository. Open a terminal and issue the command:

git clone https://github.com/svenssonjoel/lispBM.git

You should now have a directory called lispBM. Go into it and into the repl subdirectory.

cd lispBM
cd repl

Now, you have multiple choices on how to build the REPL. To build the 32-bit version (which is most similar to what you will run on a microcontroller), issue the make command.

make

If the make command above fails, it is most likely because there are some missing dependencies.

Building the 32-bit version of the REPL requires 32-bit libraries. If you are on an Ubuntu platform, you get 32-bit standard libraries by installing gcc-multilib.

In addition to gcc-multilib, the REPL requires libreadline and libpng. You need to get the 32-bit versions of these libraries. On Ubuntu, you can run the following commands:

sudo apt install gcc-multilib libreadline-dev:i386 libpng-dev:i386

If you were unable to install the 32-bit dependencies with the command above, you may need to instruct the package manager that you are interested in 32-bit packages as well:

sudo dpkg --add-architecture i386

Then retry the previous step to install the dependencies.

If installing the dependencies finished successfully, make should now work and the REPL executable should be built.

Start the REPL and explore!

./repl

You should now be greeted by the LispBM REPL in a way similar to what is shown below.

Lisp REPL started! (LBM Version: 0.27.1)
Type :quit to exit.
     :info for statistics.
     :load [filename] to load lisp source.
#

Try to evaluate some expressions. Type (+ 1 2) and press enter.

Lisp REPL started! (LBM Version: 0.27.1)
Type :quit to exit.
     :info for statistics.
     :load [filename] to load lisp source.
# (+ 1 2)
> 3
# 

When you input code at the # prompt, LispBM answers on a new line starting with >.

Alternatively, the REPL can be built as a 64-bit binary. Building the 64-bit binary requires 64-bit versions of the readline and png libraries.

On Ubuntu, you get the dependencies by doing sudo apt install libreadline-dev libpng-dev. Then, to build the executable, you issue the following command:

make all64

Lastly, the REPL can be built with SDL (Simple Directmedia Layer) for graphical output. This is done by issuing the following command:

make sdl64 

Or for 32-bit:

make sdl

The REPL with SDL requires libsdl2-dev and libsdl2-image-dev libraries or the 32-bit versions (for 32-bit REPL binary) libsdl2-dev:i386 and libsdl2-image-dev:i386.

Getting started on Windows

• KERNEL32.dll, msvcrt.dll, WS2-32.dll (Windows system DLLs)
• SDL2.dll, SDL2-image.dll, libpng16-16.dll
• history5.dll, readline5.dll
• zlib1.dll (may also be required)

Documentation

• LispBM language reference.
• Graphics library reference.
• TrueType Font (TTF) library reference.
• Runtime system library reference.
• Library of dynamically loadable functionality.
• Gotchas and caveats.
• Implementation C code documents.
• LispBM Language Cheatsheet and to-pdf.sh script that can be used to build a PDF from your modified cheatsheet.
• LispBM Language Cheatsheet (PDF).
• There are video demonstrations on YouTube.

Editor support

• vesc-tool
• vscode support
• Zed
• Tree-sitter grammar

Presentations

• Chalmers FP-Talk December 2023 - a video can be found on YouTube
• Chalmers FP-Talk May 2025 presentation

Language Implementation

Texts about language development, implementation techniques, and the technical details behind LispBM.

• LispBM vs Guile 3: Quasiquotation Comparison
• Defunctionalizing a Continuation-Passing Style Evaluator
• Towards a bytecode compiler for lispBM
• Evaluation of expressions using a register machine (Edited June 23, 2020: BugFix!)
• An attempt to get a better grip on the memory usage
• Spawn and Wait: Concurrency in lispBM part 2
• Concurrency in lispBM part 1
• Quasiquotation in lispBM (Edited June 10, 2020: BugFix)
• Boolean operators with short-circuit behavior
• Turning Recursion into Iteration using an Explicit Stack
• Implementation of a lispBM REPL for the ESP32 MCU
• Implementing a lispBM REPL in Zephyr OS
• Compression and parsing of compressed source code
• Garbage collection in lispBM
• Implementing a lispBM REPL in ChibiOs
• Fundamental operations and extensions in lispBM
• Parsing of lispBM expressions
• A quick look at boxed values in lispBM
• More in-depth walkthrough of the lispBM evaluation function
• Introduction to LispBM for microcontrollers

Testing of LispBM

The table below contains test reports for the recent numbered releases of LispBM. The test reports apply to the tagged states with the same numbering on GitHub. Note that only versions X.Y.0 get a tag and a full run of all tests. Versions X.Y.Z for non-zero Z are experimental and in development, and are sporadically tested as part of development but not given a full testing log treatment. If you want to use LispBM for something serious, please use an X.Y.0 version and keep in mind that testing is never exhaustive and in no way a guarantee of correctness or suitability for any given purpose. A thorough safety and reliability analysis should be performed on the software system where LispBM is integrated as a whole.

The table of test-results is provided for traceability purposes and gives a snapshot of known problems with a given version of LispBM.

That said, we are very serious about our testing and we do want to make it possible to use LispBM as a scripting language integrated into any application. This is an ongoing effort and collaboration is most appreciated.

Please report bugs via the issues tracker on GitHub.

NOTE: The scan-build directory is empty if the scan-build tool finds no issues with the code.

NOTE: The Infer result file infer-x.y.z.txt is empty if Infer finds no issues.

We expand on our testing from time to time but currently apply the following testing methods:

• Unit tests.
• Static analysis using CLANG scan-build .
• Static analysis using Infer .
• Static analysis using cppcheck .
• Work in progress - Property based testing using Haskell QuickCheck .
• Test coverage is checked with gcov and gcovr coverage tool.

LispBM Performance Evolution

The performance of the LispBM implementation continuously evolves as we introduce new features and engage in optimization efforts. We work to enhance its efficiency for microcontrollers, such as the STM32F4 running at 168MHz.

Below, you can find performance charts illustrating LispBM’s performance on a set of benchmarks:

If you’re interested in the technical details and benchmarks, you can explore our benchmark code here

Other Lisp-based Languages for Microcontrollers

Explore a range of Lisp-like programming languages that are tailored for microcontroller development. These languages are designed to thrive in resource-constrained environments, making them ideal choices for embedded systems. Whether you’re looking for a lightweight solution or a minimalist Lisp dialect, these languages offer unique approaches to microcontroller programming.

• uLisp: A Lisp dialect specifically designed for microcontrollers. Learn more
• FemtoLisp: A minimalistic Lisp designed for resource-constrained environments. Learn more
• PicoLisp: A lightweight and minimalistic Lisp dialect for both server-side and embedded programming. Learn more

Is your favorite microcontroller Lisp missing from this list? Please send the details in an email to bo(dot)joel(dot)svensson(whirly-a)gmail(dot)com.