Getting Started
Download
Download and install Microvium from the downloads page.
In a command prompt, run the following command to check the installation was successful:
microvium -v
The latest version of Microvium is 0.0.19.
Compile a Script
Create a new script file, script.mvm.js
:
// script.mvm.js const print = vmImport(1); vmExport(1, add); vmExport(2, sayHello); function add(a, b) { return a + b; } function sayHello() { print('Hello'); }
Here we have declared the functions add
and sayHello
and then exported them to the host firmware with IDs 1
and 2
respectively. IDs can be any integer from 0
to 32767
and do not need to be contiguous.
The print
function is imported from the host firmware and called by the script.
Note that not all JavaScript features are supported at present. See Language Features for a description of the supported features. New features are being added all the time.
To compile the script to bytecode, open a command prompt in the same directory as the script and run the following:
microvium script.mvm.js
The above command runs the top-level code in the script, including the vmExport
and vmImport
function calls. It will output a file named script.mvm-bc
, which is the bytecode image that must be downloaded to the target firmware.
The bytecode image includes the add
and sayHello
functions, as well as an index table that associates the numeric IDs with corresponding function code.

Integrate the Microvium engine
To execute functions in this image from a firmware host, the firmware must use the Microvium runtime engine. The Microvium runtime engine is a C file that must be compiled into the host firmware.

In your host firmware project folder, run the following command to unpack microvium.c
and its header files into the host firmware. (You can also run this command in a subdirectory if you prefer).
microvium --generate-lib
Any time you download a new version of the Microvium compiler, you should re-run the above command to get the latest version of the runtime library.
This does not configure your project or makefile. You need to manually add microvium/microvium.c
to your project build.
Also in the host firmware project, run the following command to interactively create a port file.
microvium --generate-port
Alternatively, you can rename the example port file (microvium_port_example.h
) to microvium_port.h
and customize it yourself according to your architecture.
Call the Script
To call the add
function from firmware code, we need to create some dummy firware code (or you can adapt this example to your real firmware). Create a file called getting-started.c
with the following contents:
The above example assumes that the bytecode
variable contains the exact bytes from the script.mvm-bc
file. To make it easier to get started with an example like this, you can get the data literal by running the microvium compiler with the optional argument --output-bytes
.
microvium script.mvm.js --output-bytes
Copy-paste the output of the above command into the variable named bytecode
in your getting-started.c
.
Now we can build this. If you’re compiling this example in GCC, you might use the following command (please adapt this to your situation and compiler):
gcc -lm getting-started.c microvium/microvium.c
Note: -lm
links the math library, which is required if your port file enables floating-point support.
A little bit more information to get you going
Exports and Imports
mvm_resolveExports
searches the bytecode’s export table for each of the IDs listed in the importIDs
array and populates the corresponding entry in the imports
array.
Similarly, resolveHostFunction
in the example code should search the host firmware for functions it wants to expose to the script code. In this example, there is only the print
function.
Garbage Collection
JavaScript is a garbage-collected language. The virtual machine will consume progressively more memory until a garbage collection (GC) cycle is triggered with mvm_runGC
. A GC cycle is also automatically triggered when the VM hits its maximum configured heap size (MVM_MAX_HEAP_SIZE
). See Memory Management for more detail.
The VM’s heap memory is allocated in chunks (256B chunks by default) from the host’s heap using malloc
.
Dynamic Typing
JavaScript is a dynamically typed language. To refer to JavaScript values with C code, use the mvm_Value
type. mvm_Value
is a reference (like a pointer) to a JavaScript value in the virtual machine’s own memory heap.
These should be considered to be weak references — the values they point to are not guaranteed to be preserved across garbage collection cycles (there are some exceptions to this, such as a mvm_Value
returned from mvm_resolveExports
).
In general, it’s best to assume that mvm_Value
variables become dangling pointers during garbage collection, unless they are imports or are wrapped in a handle. In the example, we needed to call mvm_toInt32
before calling mvm_runGC
, to get the value out of result
before it might become dangling.
To create an mvm_Value
, use one of the following:
mvm_undefined
(the undefined value in JavaScript)mvm_null
(the null value in JavaScript)mvm_newBoolean
(creates a boolean value)mvm_newNumber
(creates a number value)mvm_newInt32
(creates a number value from anint32_t
)mvm_newString
(creates a string value)
To extract the value of an mvm_Value
, use:
mvm_typeOf
mvm_isNaN
mvm_toBool
mvm_toInt32
mvm_toFloat64
mvm_toStringUtf8
An mvm_Value
can also point to a JavaScript function, as demonstrated by the imports
variable in the above example. Using mvm_typeOf
in that case will return VM_T_FUNCTION
. As in the example, JavaScript function values can be called using mvm_call
.
Scripts can also internally use JavaScript arrays and objects, but there is no way to create or access these through the Microvium API.