carllocos / warduino

A dynamic WebAssembly VM for embedded systems

WARDuino

Wasm virtual machine for ESP32 / Arduino

Installation | Examples | Run Specification tests | Documentation

About

This project is released under the Mozilla Public License 2.0, and is being developed as part of an active research project at the University of Ghent's TOPL Lab.

• The WARDuino virtual machine is a WebAssembly runtime for microcontrollers, which runs both under the Arduino and ESP-IDF toolchains.
• The WARDuino virtual machine features an extensive debugger with novel techniques such as out-of-place debugging.
• The virtual machine allows developers to implement their own primitives in C++, which are callable from Wasm.
• The WARDuino project also includes a VS Code extension to use both the remote debugging and the out-of-place debugging facilities offered by the virtual machine.

Note: WARDuino is not 1.0, since this is an active research project. Expect possible bugs or performance issues.

Build and Development Instructions

Supported platforms: Linux (Ubuntu), macOS, ESP-IDF, Arduino

The project uses CMake. Quick install looks like this:

git clone --recursive [email protected]:TOPLLab/WARDuino.git
cd WARDuino
mkdir build-emu
cd build-emu
cmake .. -D BUILD_EMULATOR=ON
make

This will build the command-line tool (emulator), which has been tested on both linux and macOS.

The WARDuino VM can be compiled with both the Arduino and ESP-IDF toolchains, and has been extensively tested on different ESP8266 and ESP32 microcontrollers.

Build for ESP-IDF

warning: primitive support for IDF is under construction

Before you can compile and flash with ESP-IDF, you must install and enable the toolchain. You also need to disable the watchdog timer:

1. Go to the root folder of the WARDuino repo
2. run idf.py menuconfig
3. Under Component config → ESP System Settings disable the following options:
   • Interrupt watchdog
   • Initialize Task Watchdog Timer on startup
4. Save and quit the menu

Make sure the ESP-IDF tools are enabled, otherwise these steps will not work.

To install the WARDuino with the ESP-IDF toolchain perform the following steps starting from the project root folder:

mkdir build
cd build
cmake .. -D BUILD_ESP=ON
make flash

Or simply run idf.py flash.

Build for Arduino

First, install the arduino-cli. You will also need python3 with the pyserial pacakge.

Second, create the config file:

arduino-cli config init

If you need additional boards, such as the esp32 boards, you can add them in the generated config file. More information on how to install the esp32 boards can be found here. (note: WARDuino requires at least version 2.0.2 of the esp32 board manager when using esp32 devices)

Thirdly, make sure you install the PubSubClient and Adafruit NeoPixel library. (used for MQTT and pixel primitives)

arduino-cli lib install "PubSubClient" # for MQTT
arduino-cli lib install "Adafruit NeoPixel" # for some primitives

To build for Arduino with WIFI support you need to also install the following third-party libraries. (You might need to set enable_unsafe_install to true in your arduino config)

arduino-cli lib install FreeRTOS
arduino-cli lib install --git-url https://github.com/me-no-dev/AsyncTCP.git

If you haven't done so already, clone (or symlink) this repository to ~/Arduino/libraries to make WARDuino availible to Arduino.

After this initial installation steps you can start using WARDuino with the Arduino toolchain. You can upload the example file as follows, starting from the project root:

cd platforms/Arduino
make compile
make flash

Build for Emulator

WARDuino can also be build as a command-line tool for a desktop environment. The purpose of this CLI is to allow developers to test WARDuino applications without the need to buy a microcontroller. The CLI is also used to run the various unit and specification tests for WARDuino.

To install the CLI perform the following steps starting from the project root folder:

mkdir build-emu
cd build-emu
cmake .. -D BUILD_EMULATOR=ON
make

WebAssembly Specification tests

cd tests/latch
npm run spectest

Technical support and feedback

For a feature request or bug report, create a GitHub issue.

LICENCE

WARDuino by Robbert Gurdeep Singh, Tom Lauwaerts, Christophe Scholliers and Joel Martin is licensed under a MPL-2.0 License. This is a derivative work of kanaka/wac by Joel Martin.

If you need to cite WARDuino in your research, use:

@inproceedings{WARDuino2019,
 author = {Gurdeep Singh, Robbert and Scholliers, Christophe},
 title = {WARDuino: A Dynamic WebAssembly Virtual Machine for Programming Microcontrollers},
 booktitle = {Proceedings of the 16th ACM SIGPLAN International Conference on Managed Programming Languages and Runtimes},
 series = {MPLR 2019},
 year = {2019},
 isbn = {978-1-4503-6977-0},
 location = {Athens, Greece},
 pages = {27--36},
 numpages = {10},
 url = {http://doi.acm.org/10.1145/3357390.3361029},
 doi = {10.1145/3357390.3361029},
 acmid = {3361029},
 publisher = {ACM},
 address = {New York, NY, USA},
 keywords = {Arduino, Live Code Updates, Virtual Machine, WebAssembly},
}

warduino's Issues

instructions 0xbc until 0xbf are igned by VM

The core interpreter has an implementation for wasm instructions with opcodes between 0xbc until 0xbf yet the VM does ignore those opcodes.

Remove single use hooks causes dangling pointers

Removing single use hooks cause all hooks to be removed when the first hook to remove is the first one of the linked list

Removing a hook cause the next hook to be ignored

Removing a hook cause the next hook to be skipped when handling hook after hook

OSX signal trap 5 unit test