This document is intended as a user manual for Emul8, the extensible open source embedded systems emulation framework. Using Emul8, you can write, debug and test software for embedded boards (or whole systems, like a set of sensor nodes connected to a data gateway) and run it in a virtual environment on your PC, without the need to touch the physical hardware. Indeed, the hardware you are programming for may not even exist yet.

This first several chapters of this manual describe the framework from a typical user’s perspective, but several more chapters follow that will helpful to developers and power users.

If you are a developer and would like to contribute to Emul8 as such, (or just want to report a bug or propose a feature), please refer to the contribution guidelines.

Structure of this manual

This introduction is meant to describe the Emul8 framework and clarify some of the basic concepts behind it.

In the section entitled System requirements you will find the dependencies and steps necessary to set up your system and prepare your environment.

Section Build procedure describes in detail the process of compiling Emul8.

Running and usage shows how to start Emul8 in different modes and describes Emul8’s CLI, the Monitor.

Emulation files covers two different types of scripts used to prepare an emulation from scratch.

Typical workflow in Emul8 shows how to start an emulation, describing one of our demo scripts.

Time and synchronization presents a more advanced topic of execution determinism.

Writing peripheral models starts the part focused on model development, describing the process of peripheral implementation.

CPU registers generation presents the framework used to generate the interface to CPU registers.

Threads and background operations describes the mechanisms used to run code in separate threads while still preserving the execution determinism.

Synchronization dives deeper to determinism, showing how to synchronize connected machines and external devices.

Plugins and Extensions is an overview of the plugin system.

Native/managed bindings describes how to connect the Emul8 framework to system-native libraries.

Basic terms

the root directory where Emul8 is installed
the Emul8 CLI (command line interface)
the entire virtual world created by Emul8 which may include one or more machines as well as helper emulation objects
an instance of a platform, a virtual representation of a physical embedded board
any block constituting part of a machine, like a UART controller or memory chip
a real-world embedded board, whose virtual copy in Emul8 is called machine