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.

Note

If you own a legacy Platform, you can either create your Platform again from scratch, or follow the Former Platform Migration chapter.

Architecture Selection

The first step is to select a MicroEJ Architecture compatible with your device instructions set and C compiler.

MicroEJ Corp. provides MicroEJ Evaluation Architectures for most common instructions sets and compilers at https://repository.microej.com/modules/com/microej/architecture.

Please refer to the chapter Architectures MCU / Compiler for the details of ABI and compiler options.

If the requested MicroEJ Architecture is not available for evaluation or to get a MicroEJ Production Architecture, please contact your MicroEJ sales representative or our support team.

Platform Configuration

The next step is to create a MicroEJ Platform configuration project:

  • Select File > New > Project… > General > Project,

  • Enter a Project name. The name is arbitrary and can be changed later. The usual convention is [PLATFORM_NAME]-configuration,

  • Click on Finish button. A new empty project is created,

  • Install the latest 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

    Note

    The version of installed Platform Configuration Additions is indicated in the CHANGELOG file.

  • Edit the Module Description File module.ivy to declare the MicroEJ Architecture dependency:

    <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>
    

Pack Import

MicroEJ Pack provides additional features on top of the MicroEJ Architecture such as Graphical User Interface or Networking.

Note

MicroEJ Packs are optional. You can skip this section if you intend to integrate MicroEJ runtime only with custom libraries.

To declare a MicroEJ Pack dependency, edit the Module Description File module.ivy as follows:

  <dependencies>
    <!-- MicroEJ Architecture Specific 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>

Warning

MicroEJ Architecture Specific Packs and Legacy MicroEJ Generic Packs provide Platform modules that are not installed by default. See Platform Module Configuration section for more details.

Platform Build

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

  • Right-click on the Platform 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-[TOOLCHAIN]-0.1.0'.
      [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-[TOOLCHAIN]-0.1.0' > '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 have changed (i.e, name, version). When the same Platform is built again, the Platform project should be automatically refreshed after few seconds. In case of any doubt, right-click on the Platform project and select Refresh to get the new content.

Platform Module Configuration

A Platform module is the minimal unit that can extend a MicroEJ Architecture with additional features such as:

Platform modules provided by MicroEJ Generic Packs are automatically installed during the Platform build and do not require extra configuration. They are not displayed in the Platform Editor.

Platform modules provided by MicroEJ Architectures, MicroEJ Architecture Specific Packs and Legacy MicroEJ Generic Packs following list are not installed by default. They must be enabled and configured using the Platform Editor.

Before opening the Platform Editor, the Platform must have been built once to let MicroEJ Module Manager resolve and download MicroEJ Architecture and Packs locally. Then import them in MicroEJ SDK as follows:

  • Select File > Import > MicroEJ > Architectures,
  • Browse myplatform-configuration/target~/dependencies folder (contains .xpf and .xpfp files once the Platform is built),
  • Check the I agree and accept the above terms and conditions… box to accept the license,
  • Click on Finish button. This may take some time.

Once imported, double-click on the default.platform file to open the Platform Editor.

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

Platform modules are organized into groups. When a group is selected, by default, all its modules are selected. To view all the modules making up a group, click on the Expand All 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 selected Platform modules will be installed in the Platform.

MicroEJ Platform Configuration Modules Selection

MicroEJ Platform Configuration Modules Selection

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

  • A [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.

  • A bsp.xml file which provides additional information about the BSP implementation of Low Level APIs.

    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.

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

  • Optional module specific files and folders

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

Note

It is possible to quickly rebuild the Platform from the Platform Editor if only Platform module configuration has changed. Click on the Build Platform link on the Platform configuration Overview tab.

Platform Customization

The configuration project (the project which contains the .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.

Platform build can also be customized by updating the configuration.xml file beside the .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.

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 requires 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 the Platform options, which can be set in the 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 the Application options, which can be set 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) at the location specified 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 include the BSP.
deploy.dir.microejapp Absolute path to the directory where to deploy the MicroEJ Application file (microejapp.o). An empty value means no deployment.
deploy.dir.microejlib Absolute path to the directory where to deploy the MicroEJ Platform runtime file (microejruntime.a) to this absolute directory. An empty value means no deployment.
deploy.dir.microejinc Absolute path to the directory where to deploy the MicroEJ Platform header files (*.h) to this absolute directory. An empty value means no deployment.
deploy.dir.microejscript Absolute path to the directory that contains the BSP build script file (build.bat or build.sh). An empty value means no build script execution.

Note

It is also possible to configure the BSP root directory by setting the build option toolchain.dir, instead of the application option deploy.bsp.root.dir. This allows 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 used to invoke the third-party C toolchain (compiler and linker) to produce the final executable file (application.out).

The build script must comply with 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 a file named 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.

Note

The final executable file must be an ELF executable file. On Unix, the command file(1) can be use to check the format of a file. For example:

~$ file application.out
ELF 32-bit LSB executable

Run Script File

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

The BSP run script is used to invoke a third-party tool to upload and start the executable file on device.

The run script must comply with 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.
  • The executable file is passed as first script parameter if there is one, otherwise it is the application.out file located in the directory from where the script has been executed.
  • 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