Running and usage

The Emul8 framework provides an API which allows the user to create, assemble and run software models of the hardware to be emulated.

The models are mostly written in C# (although other mono runtime languages can also be used).

Using the framework - including assembling new platforms - does not, however, require the knowledge of programming languages, as assembling and manipulating platforms and emulating them can be done through emulation scripts and configuration files, as described in the Emulation files section.


For experienced users, the possibility to write models in C# is a good means to implement things beyond the scope of emulation scripts (which can do what the API provides). However, the scripts are the preferred way to achieve most goals.

Running Emul8

To run Emul8, use the script, with the optional file parameter and following options:


Run in plain mode (do not output colours).


Run in Debug mode (more debug information, but slower). Remember to use -d first.

-e command

Execute the given command on startup. This option cannot be used together with the file parameter.

-P port

Instead of opening a Monitor window, listen on a specified port for commands.


Disable XWT GUI support (requires -P). This is useful when running Emul8 on machines that does not provide X11 server.


Do not show a monitor window on startup.


Do not show log messages in a console.


Display usage & help information.

file is an optional argument - path to a script that should be loaded on startup.


The monitor (CLI) exposes the Emul8 API in the form of objects and methods which can be used like a scripting language. There are also some special helper commands.

After running the CLI (see Running Emul8) you will see the git branch and version denotation of the build you are using, copyright and prompt:

Emul8 Framework, version X.X.X.X (branchname-xxxxxxxxxxxxxxxxxxxxx)


The (monitor) part denotes the Context you are in.

The <TAB> key provides auto-completion - you can use it whenever you are unsure what to type. Hitting <TAB> on an empty terminal will just list all available commands and objects at that moment.

If you want to manipulate a machine/peripheral or object, write <object_name> and press <TAB> to see all available options.

Typing any command with incorrect parameters will print a help string, so do not be afraid to experiment.

Issuing help will print all available helper commands with a short description. You can get further help for any command using help <command_name>.

Some more commonly used commands also have short, usually single-letter, aliases.

Apart from typing commands interactively, you can also execute them from a script - see the include command and the Emulation files section.


The monitor is contextual with regard to machines, i.e. if you want to manipulate any peripheral which is part of a given machine, you have to enter its context, which is always shown in the prompt. The initial context after turning on the CLI is always (monitor).

Changing the context can be done using the mach set <machine_name> command first.

mach add <machine-name> lets you create a new machine, but note that its context is not entered automatically.

mach create is a shortcut which lets you create a machine with an automatically assigned name and enter its context automatically.

You can use mach to list all available machines.

Once in the context of a given machine, you can access its peripherals. All peripherals are stored in a tree-like structure, with the root being a system bus, available in the machine’s context under the name sysbus. To access them from the Monitor, you can provide their whole path, e.g. sysbus.gpioPortA.led. The Monitor simplifies access to peripherals with tab completion. You may try it by typing sysbus. and pressing <TAB>.

Since it is tiresome to type fully qualified peripheral names every time, a using helper command has been implemented - you will probably find yourself typing using sysbus quite often.

Command descriptions


allow private fields and properties manipulation.

short: privs

shows available analyzers for peripheral.

creates a platform.

short: c

executes a command or the content of a variable.

prints this help message or info about specified command.

short: ?, h


loads a monitor script, python code or a plugin class.

short: i

logs messages.

sets the output file for logger.

short: logF


sets logging level for backends.

Level Name

list and manipulate machines available in the environment.

mach set <name>
Enable the given machine.
mach add <name>
Create a new machine with the given name.
mach rem <name>
Remove a machine.
mach create
Create a new machine with a generic name and switch to it.
mach clear
Clear the current selection.
sets a macro.

sets the way numbers are displayed.


  • Hexadecimal
  • Decimal
  • Both

allows modification of internal ‘PATH’ variable.

path set <PATH>
Set PATH to the given value.
path add <PATH>
Append the given value to PATH.
path reset
Reset PATH to it’s default value.

pauses the emulation.

short: p


prints list of registered and named peripherals.

short: peri


executes the provided python command.

short: py


quits the emulator.

short: q

verifies the existence of a variable.
executes a command or the content of a macro.
sets a variable.

opens a peripheral backend analyzer.

short: sa


starts the emulation.

short: s

start <PATH>
just like include <PATH>, but also start the emulation.

treat given arguments as a single string.

short: str


expose a prefix to avoid typing full object names.

using -
Clear all previous using calls

Example: using sysbus.gpioPortA

controls the verbosity of the Monitor.
shows version information.