4. Kernel Documentation

4.1. Public Documentation

The Kernel Development Guide documents how to create a MICROEJ Kernel on a MICROEJ VEE.

4.2. Kernel on Cinterion MICROEJ VEE

In terms of functionalities available, a MICROEJ kernel is very similar to a MICROEJ standalone application. However, in practice, their contents are usually very different: the kernel does not contain any business logic and rather only defines a runtime API, the interfaces between applications, and the application lifecycle management.

As such, the requirements are the same as for the Standalone Application. Note that there is a specific Foundation Library KF which allows for Feature (Sandboxed Application) management and kernel-specific functionalities.

4.3. Cinterion Demonstration Kernel

This package contains an example of a kernel that manages applications locally-deployed on the module filesystem and updated with binary patches (see bsdiff).

Its runtime API is defined by the kernel.api file in its resources (partial EDC, Device, EClasspath Properties) and its dependencies:

<dependency org="com.microej.kernelapi" name="kf" rev="2.0.3" conf="kernelapi->default"/>
<dependency org="com.microej.kernelapi" name="ecom-comm" rev="1.0.4" conf="kernelapi->default"/>
<dependency org="com.microej.pack.ecom-mobile" name="ecom-mobile-kernelapi" rev="0.1.0" conf="kernelapi->default"/>
<dependency org="com.microej.pack.gnss" name="gnss-kernelapi" rev="1.0.0" conf="kernelapi->default"/>
<dependency org="com.microej.kernelapi" name="fs" rev="1.0.0" conf="kernelapi->default">
        <exclude org="ej.api" module="fs"/>
</dependency>
<dependency org="com.cinterion.pack.cinterion" name="cinterion-kernelapi" rev="1.6.0" conf="kernelapi->default"/>

<dependency org="com.microej.kernelapi" name="basictool" rev="1.2.0" conf="kernelapi->default"/>

<dependency org="com.microej.kernelapi" name="property" rev="1.1.0" conf="kernelapi->default"/>
<dependency org="com.microej.kernelapi" name="service" rev="1.1.0" conf="kernelapi->default"/>
<dependency org="com.microej.kernelapi" name="storage" rev="1.1.0" conf="kernelapi->default"/>
<dependency org="com.microej.kernelapi" name="wadapps" rev="2.2.0" conf="kernelapi->default"/>

The complete runtime API is documented in Kernel API Javadoc HTML Pages.

4.3.1. SMS managed OTA

This kernel has OTA updates capabilities for both auto-updates and board firmware update. The update process is based on the SafeUpdater add-on library that leans on the GINA Safe Update API.

SMS are automatically parsed in search of a command to execute.

Update messages format is:

{
    "command":
        {
        "timestamp":"<timestamp>",
        "IMEI":"<IMEI>",
        "command":"update-kernel|update-firmware",
        "binary-location":"<binaryURL>"
        },
    "signature":"<signature>"
}

timestamp as a long value. IMEI is the board modem IMEI. bynaryURL is the URL to the binary to download, can be a delta in case of the firmware. signature is the hmac signature of the command JSON object :

{
    "timestamp":"<timestamp>",
    "IMEI":"<IMEI>",
    "command":"update-kernel|update-firmware",
    "binary-location":"<binaryURL>"
}

See Generate OTA SMS. for details on its generation.

Note : kernel uses monotonic time, timestamp can start at 0 but each commands timestamp must be higher than the previous one.

Note2 : The SafeUpdater only uses http for it’s download but it is possible to load an https resource in an InputStream and use it as parameter for the update methods.

4.3.1.1. Generate OTA SMS

Every command must be executed from the directory ./cinterion-demo-kernel/src/main/resources/scripts.

On Linux

  • Create a file containing the JSON command object : command.txt
  • Generate a private key with the command ./generateKey.sh or create a file key.txt in wich you will save your own private key in hexadecimal format.
  • Generate the message with the command ./createMessage.sh key.txt command.txt

The SMS to send can be found in SMSMessage.json file beetween single quotes : ‘<your message to copy>’.

Note: the hmac generation is sometimes done on command.txt before it was trimmed of it line ending. Consider launching the script two times to be sure the hmac is generated with the trimmed version.

On Windows

  • Create a file containing the JSON command object : command.txt
  • openssl rand -hex 32 > key.txt
  • openssl dgst -sha256 -mac hmac -macopt hexkey:$(cat key.txt) -out hmac.txt command.txt

Manually create the message :

{
    "command":
        <content of command.txt>,
    "signature":"<signature found in hmac.txt, after 'HMAC-SHA2-256(command.txt)= ' >"
}

4.4. Customization

4.4.1. Application management

To change the application lifecycle management, edit the Java code in the Kernel project and use the KF API.

It is also possible to use the Wadapps Application Framework.

The features (sandboxed applications) can basically be installed from any sources (serial communication, network, storage, …).

4.4.2. Runtime API

For optimized footprint, the runtime API should be designed according to the application needs:

  • To be compatible with an application, the kernel must open a set of APIs. In case the application already exists, it is possible to generate its dependencies in the kernel API format using the Dependency Discoverer Tool with --output-format=xml.
  • To decrease the kernel footprint, make the runtime API as close as possible to the natives. To reduce the application footprint, make the runtime API as close as possible to the application code.
  • For this tradeoff, consider the updates required in production. A “low-level” kernel API will reduce the times the kernel must be updated but will increase the payload required for application updates.
  • Also, note that the kernel may embed code that will never be used by applications. A “low-level” runtime API is less likely to embed such code and is easier to design.

To append the runtime API, either:

  • add a dependency to a kernel API module
  • merge a kernel API file with the one in the kernel project resources.