MicroEJ Platform Creation

This section describes the steps to create a new MicroEJ Platform in MicroEJ SDK, and options to connect it to an external Board Support Package (BSP) as well as a third-party C toolchain.

MicroEJ SDK must be started on a new empty workspace.

MicroEJ Architecture Import

The first step is to choose and import a MicroEJ Architecture. MicroEJ Corp. provides MicroEJ Evaluation Architectures for most common microcontroller instructions sets and compilers at https://repository.microej.com/architectures/ [1].

MicroEJ Architecture files ends with the .xpf extension, and are classified using the following naming convention:

com/microej/architecture/[ISA]/[TOOLCHAIN]/[UID]/[VERSION]/[UID]-[VERSION]-[USAGE].xpf
  • ISA: instruction set architecture (e.g. CM4 for Arm® Cortex®-M4, ESP32 for Espressif ESP32, …).
  • TOOLCHAIN: C compilation toolchain (e.g. CM4hardfp_GCC48).
  • UID: Architecture unique ID (e.g. flopi4G25).
  • VERSION: module version (e.g. 7.12.0).
  • USAGE = eval for evaluation Architectures, prod for production Architectures.

For example, MicroEJ Architecture versions for Arm® Cortex®-M4 microcontrollers compiled with GNU CC toolchain are available at https://repository.microej.com/architectures/com/microej/architecture/CM4/CM4hardfp_GCC48/flopi4G25/.

Once you downloaded a MicroEJ Architecture file, proceed with the following steps to import it in MicroEJ SDK:

  • Select File > Import > MicroEJ > Architectures.
  • Browse an .xpf file or a folder that contains one or more an .xpf files.
  • Check the I agree and accept the above terms and conditions… box to accept the license.
  • Click on Finish button.
[1]If the requested MicroEJ Architecture is not available for evaluation or to get a MicroEJ Production Architecture, please contact your MicroEJ sales representative.

MicroEJ Pack Import

The next step is to choose and import a MicroEJ Pack. MicroEJ Corp. provides MicroEJ Packs to provide additional features.

MicroEJ Packs are distributed in two packages:

MicroEJ Architecture Specific Pack

MicroEJ Architecture Specific Packs contain compiled libraries archives and are thus dependent on the MicroEJ Architecture and toolchain used in the MicroEJ Platform.

MicroEJ Architecture Specific Packs files ends with the .xpfp extension and are classified using the following naming convention:

com/microej/architecture/[ISA]/[TOOLCHAIN]/[UID]-[NAME]-pack/[VERSION]/[UID]-[NAME]-pack-[VERSION].xpfp
  • ISA: instruction set architecture (e.g. CM4 for Arm® Cortex®-M4, ESP32 for Espressif ESP32, …).
  • TOOLCHAIN: C compilation toolchain (e.g. CM4hardfp_GCC48).
  • UID: Architecture unique ID (e.g. flopi4G25).
  • NAME : pack name (e.g. ui).
  • VERSION: pack version (e.g. 13.0.4).

For example, MicroEJ Architecture Specific Pack UI versions for Arm® Cortex®-M4 microcontrollers compiled with GNU CC toolchain are available at https://repository.microej.com/modules/com/microej/architecture/CM4/CM4hardfp_GCC48/flopi4G25-ui-pack/.

MicroEJ Generic Pack

MicroEJ Generic Packs can be imported on top of any MicroEJ Architecture.

They are classified using the following naming convention:

com/microej/pack/[NAME]/[NAME]-pack/[VERSION]/
  • NAME : pack name (e.g. bluetooth).
  • VERSION: pack version (e.g. 2.1.0).

For example, MicroEJ Generic Pack Bluetooth versions are available at https://repository.microej.com/modules/com/microej/pack/bluetooth/bluetooth-pack/.

Legacy MicroEJ Generic Packs files end with the .xpfp extension and can be manually imported on older MicroEJ Platforms. They are classified using the following naming convention:

com/microej/pack/[NAME]/[NAME]/[VERSION]/
  • NAME : pack name (e.g. net).
  • VERSION: pack version (e.g. 9.2.3).

For example, the Legacy MicroEJ Generic Pack NET version 9.2.3 is available at https://repository.microej.com/modules/com/microej/pack/net/9.2.3/net-9.2.3.xpfp.

Manual Import

This section is only relevant for older MicroEJ Platforms with no Module Description File. These Platforms are built from MicroEJ Architecture Specific Packs and Legacy MicroEJ Generic Packs (packaged as .xpfp files) that must be imported manually.

Once you downloaded a MicroEJ Pack file, proceed with the following steps to import it in MicroEJ SDK:

  • Select File > Import > MicroEJ > Architectures.
  • Browse an .xpfp file or a folder that contains one or more an .xpfp files.
  • Check the I agree and accept the above terms and conditions… box to accept the license.
  • Click on Finish button.

MicroEJ Platform Configuration

The next step is to create a MicroEJ Platform configuration:

  • Select File > New > MicroEJ Platform Project….

  • The Configure Target Architecture page allows to select the MicroEJ Architecture. This can be changed later.

    • Click on Browse… button to select one of the installed MicroEJ Architecture.
    • Uncheck the Create from a platform reference implementation box.
  • Click on Next button. The Configure platform properties page contains the identification of the MicroEJ Platform to create. Most fields are mandatory, you should therefore set them. Note that their values can be modified later on.

  • Click on Finish button. A new project [device]-[name]-[toolchain] is being created containing a [name].platform file. The Platform Editor shall then open.

  • Install Platform Configuration Additions. Files within the content folder have to be copied to the configuration project folder, by following instructions described at https://github.com/MicroEJ/PlatformQualificationTools/blob/master/framework/platform/README.rst.

    You should get a MicroEJ Platform configuration project that looks like:

    MicroEJ Platform Configuration Project Skeleton

    MicroEJ Platform Configuration Project Skeleton

  • Edit the module.properties file and set the option com.microej.platformbuilder.platform.filename to the [name].platform file name.

    com.microej.platformbuilder.platform.filename=myplatform.platform
    
  • Edit the Module Description File module.ivy to declare the dependency line to the MicroEJ Architecture previously downloaded:

    <dependencies>
    
       <dependency org="com.microej.architecture.[ISA].[TOOLCHAIN]" name="[UID]" rev="[VERSION]">
         <artifact name="[UID]" m:classifier="[USAGE]" ext="xpf"/>
       </dependency>
    
    </dependencies>
    

    For example, to declare the MicroEJ Evaluation Architecture version 7.14.0 for Arm® Cortex®-M4 microcontrollers compiled with GNU CC toolchain:

    <dependencies>
    
        <dependency org="com.microej.architecture.CM4.CM4hardfp_GCC48" name="flopi4G25" rev="7.14.0">
          <artifact name="flopi4G25" m:classifier="eval" ext="xpf"/>
        </dependency>
    
    </dependencies>
    
  • Edit the Module Description File module.ivy to declare the dependency line to the MicroEJ Packs previously downloaded:

    <dependencies>
       <!-- MicroEJ Architecture Specific Pack and Legacy MicroEJ Generic Pack  -->
       <dependency org="com.microej.architecture.[ISA].[TOOLCHAIN]" name="[UID]-[NAME]-pack" rev="[VERSION]"/>
    
       <!-- MicroEJ Generic Pack  -->
       <dependency org="com.microej.pack.[NAME]" name="[NAME]-pack" rev="[VERSION]"/>
    
       <!-- Legacy MicroEJ Generic Pack -->
       <dependency org="com.microej.pack" name="[NAME]" rev="[VERSION]"/>
    
    </dependencies>
    

    For example, to declare the MicroEJ Architecture Specific Pack UI version 13.0.4 for MicroEJ Architecture flopi4G25 on Arm® Cortex®-M4 microcontrollers compiled with GNU CC toolchain:

    <dependencies>
        <!-- MicroEJ Architecture Specific Pack -->
        <dependency org="com.microej.architecture.CM4.CM4hardfp_GCC48" name="flopi4G25-ui-pack" rev="13.0.4"/>
    
    </dependencies>
    

    To declare the MicroEJ Generic Pack Bluetooth version 2.1.0:

    <dependencies>
      <!-- MicroEJ Generic Pack  -->
        <dependency org="com.microej.pack.bluetooth" name="bluetooth-pack" rev="2.1.0"/>
    
    </dependencies>
    

    And to declare the Legacy MicroEJ Generic Pack Net version 9.2.3:

    <dependencies>
      <!-- Legacy MicroEJ Generic Pack -->
      <dependency org="com.microej.pack" name="net" rev="9.2.3"/>
    
    </dependencies>
    

MicroEJ Platform Build

To build the MicroEJ Platform, perform as a regular Module Build:

  • Right-click on the Platfom Configuration project,

  • Select Build Module.

  • The build starts and the build logs are redirected to the integrated console. Once the build is terminated, you should get the following message:

    module-platform:report:
      [echo]     ============================================================================================================
      [echo]     Platform has been built in this directory 'C:\tmp\mydevice-Platform-mytoolchain-0.0.1'.
      [echo]     To import this project in your MicroEJ SDK workspace (if not already available):
      [echo]      - Select 'File' > 'Import...' > 'General' > 'Existing Projects into Workspace' > 'Next'
      [echo]      - Check 'Select root directory' and browse 'C:\tmp\mydevice-Platform-mytoolchain-0.0.1' > 'Finish'
      [echo]     ============================================================================================================
    
    BUILD SUCCESSFUL
    
    Total time: 43 seconds
    

Then , import the Platform directory to your MicroEJ SDK workspace as mentioned in the report. You should get a ready-to-use MicroEJ Platform project in the workspace available for the MicroEJ Application project to run on. You can also check the MicroEJ Platform availability in: Window > Preferences > MicroEJ > Platforms in workspace.

MicroEJ Platform Project

MicroEJ Platform Project

This step is only required the first time the Platform is built, or if the Platform properties haved changed. When the same Platform is rebuilt, right-click on the Platform project and select Refresh to get the new content.

Platform Groups / Modules Selection

From the Platform Editor, select the Content tab to access the Platform modules selection. Platform modules can be selected/deselected from the Modules frame.

Platform modules are provided by MicroEJ Architecture Specific Packs and Legacy MicroEJ Generic Packs. Platform modules are organized into groups. When a group is selected, by default, all its modules are selected. To view the modules making up a group, click on the Show/Hide modules icon on the top-right of the frame. This will let you select/deselect on a per module basis. Note that individual module selection is not recommended and that it is only available when the module have been imported.

The description and contents of an item (group or module) are displayed beside the list on item selection.

All the checked Platform modules will be installed in the Platform.

MicroEJ Platform Configuration Modules Selection

MicroEJ Platform Configuration Modules Selection

Note

It is possible to quickly rebuild the Platform from the Platform Editor when only changes have been made in the Platform Editor. Click on the Build Platform link on the Platform configuration Overview tab.

Platform Modules Customization

Each selected Platform module can be customized by creating a [module] folder named after the module beside the [name].platform definition. It may contain:

  • An optional [module].properties file named after the module name. These properties will be injected in the execution context prefixed by the module name. Some properties might be needed for the configuration of some modules. Please refer to the modules documentation for more information.
  • Optional module specific files and folders.

Modifying one of these files requires to build the Platform again.

Platform Customization

Platforms can be customized by creating a configuration.xml Ant file beside the [name].platform file. This Ant script can extend one or several of the extension points available. By default, you should not have to change the default configuration script.

Here is a template for a configuration.xml Ant file:

<?xml version="1.0" encoding="UTF-8"?>
<project name="configuration">

     <!--
             Define "project.dir" property that references the directory
             where this file is located.
     -->
     <dirname property="project.dir" file="${ant.file.configuration}"/>

</project>

Configuration project (the project which contains the [name].platform file) can contain an optional dropins folder. The contents of this folder will be copied integrally into the final Platform. This feature allows to add some additional libraries, tools etc. into the Platform.

The dropins folder organization should respect the final Platform files and folders organization. For instance, the tools are located in the sub-folder tools. Launch a Platform build without the dropins folder to see how the Platform files and folders organization is. Then fill the dropins folder with additional features and build again the Platform to obtain an advanced Platform.

The dropins folder files are kept in priority. If one file has the same path and name as another file already installed into the Platform, the dropins folder file will be kept.

Modifying one of these files requires to build the Platform again.

BSP Connection

Principle

Using a MicroEJ Platform, the user can compile a MicroEJ Application on that Platform. The result of this compilation is a microejapp.o file.

This file has to be linked with the MicroEJ Platform runtime file (microejruntime.a) and a third-party C project, called the Board Support Package (BSP) , to obtain the final binary file (MicroEJ Firmware). For more information, please consult the MicroEJ build process overview.

The BSP connection can be configured by defining 4 folders where the following files are located:

  • MicroEJ Application file (microejapp.o).
  • MicroEJ Platform runtime file (microejruntime.a, also available in the Platform lib folder).
  • MicroEJ Platform header files (*.h, also available in the Platform include folder).
  • BSP project build script file (build.bat or build.sh).

Once the MicroEJ Application file (microejapp.o) is built, the files are then copied to these locations and the build.bat or build.sh file is executed to produce the final executable file (application.out).

Note

The final build stage to produce the executable file can be done outside of MicroEJ SDK, and thus the BSP connection configuration is optional.

BSP connection configuration is only required in the following cases:

  • Use MicroEJ SDK to produce the final executable file of a Mono-Sandbox Firmware (recommended).
  • Use MicroEJ SDK to run a MicroEJ Test Suite on device.
  • Build a Multi-Sandbox Firmware.

MicroEJ provides a flexible way to configure the BSP connection to target any kind of projects, teams organizations and company build flows. To achieve this, the BSP connection can be configured either at MicroEJ Platform level or at MicroEJ Application level (or a mix of both).

The 3 most common integration cases are:

  • Case 1: No BSP connection

    The MicroEJ Platform does not know the BSP at all.

    BSP connection can be configured when building the MicroEJ Application (absolute locations).

    MicroEJ Platform with no BSP connection

    MicroEJ Platform with no BSP connection

    This case is recommended when:

    • the MicroEJ Firmware is built outside MicroEJ SDK.
    • the same MicroEJ Platform is intended to be reused on multiple BSP projects which do not share the same structure.
  • Case 2: Partial BSP connection

    The MicroEJ Platform knows how the BSP is structured.

    BSP connection is configured when building the MicroEJ Platform (relative locations within the BSP), and the BSP root location is configured when building the MicroEJ Application (absolute directory).

    MicroEJ Platform with partial BSP connection

    MicroEJ Platform with partial BSP connection

    This case is recommended when:

    • the MicroEJ Platform is used to build one MicroEJ Application on top of one BSP.
    • the Application and BSP are slightly coupled, thus making a change in the BSP just require to build the firmware again.
  • Case 3: Full BSP connection

    The MicroEJ Platform includes the BSP.

    BSP connection is configured when building MicroEJ Platform (relative locations within the BSP), as well as the BSP root location (absolute directory). No BSP connection configuration is required when building the MicroEJ Application.

    MicroEJ Platform with full BSP connection

    MicroEJ Platform with full BSP connection

    This case is recommended when:

    • the MicroEJ Platform is used to build various MicroEJ Applications.
    • the MicroEJ Platform is validated using MicroEJ test suites.
    • the MicroEJ Platform and BSP are delivered as a single standalone module (same versioning), perhaps subcontracted to a team or a company outside the application project(s).

Options

BSP connection options can be specified as Platform options or as Application options or a mix of both.

The following table describes Platform options, configured in bsp > bsp.properties file of the Platform configuration project.

MicroEJ Platform Options for BSP Connection
Option Name Description Example
microejapp.relative.dir The path relative to BSP root.dir where to deploy the MicroEJ Application file (microejapp.o). MicroEJ/lib
microejlib.relative.dir The path relative to BSP root.dir where to deploy the MicroEJ Platform runtime file (microejruntime.a). MicroEJ/lib
microejinc.relative.dir The path relative to BSP root.dir where to deploy the MicroEJ Platform header files (*.h). MicroEJ/inc
microejscript.relative.dir The path relative to BSP root.dir where to execute the BSP build script file (build.bat or build.sh). Project/MicroEJ
root.dir The 3rd-party BSP project absolute directory, to be included to the Platform. c:\\Users\\user\\mybsp on Windows systems or /home/user/bsp on Unix systems.

The following table describes Application options, configured as regular MicroEJ Application Options.

MicroEJ Application Options for BSP Connection
Option Name Description
deploy.bsp.microejapp Deploy the MicroEJ Application file (microejapp.o) to the location defined by the Platform (defaults to true when Platform option microejapp.relative.dir is set).
deploy.bsp.microejlib Deploy the MicroEJ Platform runtime file (microejruntime.a) to the location defined by the Platform (defaults to true when Platform option microejlib.relative.dir is set).
deploy.bsp.microejinc Deploy the MicroEJ Platform header files (*.h) to the location defined by the Platform (defaults to true when Platform option microejinc.relative.dir is set).
deploy.bsp.microejscript Execute the BSP build script file (build.bat or build.sh) present at the location defined by the Platform. (defaults to false and requires microejscript.relative.dir Platform option to be set).
deploy.bsp.root.dir The 3rd-party BSP project absolute directory. This option is required if at least one the 4 options described above is set to true and the Platform does not includes the BSP.
deploy.dir.microejapp Deploy the MicroEJ Application file (microejapp.o) to this absolute directory. An empty value means no deployment.
deploy.dir.microejlib Deploy the MicroEJ Platform runtime file (microejruntime.a) to this absolute directory. An empty value means no deployment.
deploy.dir.microejinc Deploy the MicroEJ Platform header files (*.h) to this absolute directory. An empty value means no deployment.
deploy.dir.microejscript Execute the BSP build script file (build.bat or build.sh) present in this absolute directory. An empty value means no deployment.

Note

It is also possible to configure the BSP root directory using the build option toolchain.dir, instead of the application option deploy.bsp.root.dir. This allow to configure a MicroEJ Firmware by specifying both the Platform (using the target.platform.dir option) and the BSP at build level, without having to modify the application options files.

For each Platform BSP connection case, here is a summary of the options to set:

  • No BSP connection, executable file built outside MicroEJ SDK

    Platform Options:
      [NONE]
    
    Application Options:
      [NONE]
    
  • No BSP connection, executable file built using MicroEJ SDK

    Platform Options:
      [NONE]
    
    Application Options:
      deploy.dir.microejapp=[absolute_path]
      deploy.dir.microejlib=[absolute_path]
      deploy.dir.microejinc=[absolute_path]
      deploy.bsp.microejscript=[absolute_path]
    
  • Partial BSP connection, executable file built outside MicroEJ SDK

    Platform Options:
      microejapp.relative.dir=[relative_path]
      microejlib.relative.dir=[relative_path]
      microejinc.relative.dir=[relative_path]
    
    Application Options:
      deploy.bsp.root.dir=[absolute_path]
    
  • Partial BSP connection, executable file built using MicroEJ SDK

    Platform Options:
      microejapp.relative.dir=[relative_path]
      microejlib.relative.dir=[relative_path]
      microejinc.relative.dir=[relative_path]
      microejscript.relative.dir=[relative_path]
    
    Application Options:
      deploy.bsp.root.dir=[absolute_path]
      deploy.bsp.microejscript=true
    
  • Full BSP connection, executable file built using MicroEJ SDK

    Platform Options:
      microejapp.relative.dir=[relative_path]
      microejlib.relative.dir=[relative_path]
      microejinc.relative.dir=[relative_path]
      microejscript.relative.dir=[relative_path]
      root.dir=[absolute_path]
    
    Application Options:
      deploy.bsp.microejscript=true
    

Build Script File

The BSP build script file is responsible to invoke the third-party C toolchain (compiler and linker) to produce the final executable file (application.out).

The build script must implement the following specification:

  • On Windows operating system, it is a Windows batch file named build.bat.
  • On Mac OS X or Linux operating systems, it is a shell script named build.sh, with execution permission enabled.
  • On error, the script must end with a non zero exit code.
  • On success
    • The executable must be copied to the file application.out in the directory from where the script has been executed.
    • The script must end with zero exit code.

Many build script templates are available for most commonly used C toolchains in the Platform Qualification Tools repository.

Run Script File

This script is required only for Platforms intended to run a MicroEJ Testsuite on device.

The BSP run script is responsible to invoke a third-party tool to upload and start the executable file (application.out) on device. The application.out file is located in the directory from where the script has been executed.

The run script must implement the following specification:

  • On Windows operating system, it is a Windows batch file named run.bat.
  • On Mac OS X or Linux operating systems, it is a shell script named run.sh, with execution permission enabled.
  • On error, the script must end with a non zero exit code.
  • On success
    • The executable file (application.out) has been uploaded and started on the device
    • The script must end with zero exit code.

The run script can optionally redirect execution traces. If it does not implement execution traces redirection, the testsuite must be configured with the following Application Options in order to take its input from a TCP/IP socket server, such as Serial to Socket Transmitter.

testsuite.trace.ip=localhost
testsuite.trace.port=5555

Low Level APIs Implementation Files

Some Platform modules require additional information about the BSP implementation of Low Level APIs.

This information must be stored in each Platform module’s configuration folder, in a file named bsp.xml.

This file must start with the node <bsp>. It can contain several lines like this one: <nativeName="A_LLAPI_NAME" nativeImplementation name="AN_IMPLEMENTATION_NAME"/> where:

  • A_LLAPI_NAME refers to a Low Level API native name. It is specific to the MicroEJ C library which provides the Low Level API.
  • AN_IMPLEMENTATION_NAME refers to the implementation name of the Low Level API. It is specific to the BSP; and more specifically, to the C file which does the link between the MicroEJ C library and the C driver.

Example:

<bsp>
    <nativeImplementation name="COMM_DRIVER" nativeName="LLCOMM_BUFFERED_CONNECTION"/>
</bsp>

These files will be converted into an internal format during the MicroEJ Platform build.