Platform Creation

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

Note

The creation of a Platform with this guide requires at least the version 5.4.0 of the SDK.

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 by following instructions described at https://github.com/MicroEJ/VEEPortQualificationTools/blob/master/framework/platform/README.rst.

    • Files within the content-sdk-5 folder must be copied to the configuration project folder.
    • Files within the content-architecture-7 must be copied to the configuration project folder only if you are using an Architecture version 7.x. If you are using an Architecture version 8.x, the files are already included and must not be copied.

    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>
    

    The name of the module dependency needed for your Platform can be found in the chapter Architectures MCU / Compiler. Check the table of your corresponding Architecture and follow the link in the Module Name column.

    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>
    

And the module for this Architecture is located in the Central Repository at https://repository.microej.com/modules/com/microej/architecture/CM4/CM4hardfp_GCC48/flopi4G25/7.14.0/.

Note

The Platform Configuration Additions allow to select the Architecture USAGE using the option com.microej.platformbuilder.architecture.usage. Edit the file module.properties to set the property to prod to use a Production Architecture and to eval to use an Evaluation Architecture.

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

The MicroEJ Platform can be built either from the SDK or from the MMM CLI. To build the MicroEJ Platform from the SDK, perform a regular Module Build:

  • Right-click on the Platform Configuration project,
  • Select Build Module.

To build the MicroEJ Platform from the MMM CLI:

  • Set the eclipse.home property to the path of your SDK, using -Declipse.home=<path> in the command line or using the Shared configuration.

    By default, the SDK’s path is one of the following directories:

    • on Windows: C:\Program Files\MicroEJ\MicroEJ-SDK-<YY.MM>\rcp
    • on Linux: /home/<user>/MicroEJ/MicroEJ-SDK-<YY.MM>/rcp
    • on macOS: /Applications/MicroEJ/MicroEJ-SDK-<YY.MM>/rcp/MicroEJ-SDK-<YY.MM>.app/Contents/Eclipse
  • From the Platform Configuration project, execute the command: mmm

In both cases, 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 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 a 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 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 the 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 in 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 has been imported.

The description and contents of an item (group or module) are displayed next to the list when an item is selected.

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 name), next to 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 the Platform module configuration has changed. Click on the Build Platform link on the Overview tab of the Platform Editor.

Platform Customization

The configuration project (the project which contains the .platform file) can contain an optional dropins folder. The full content of this folder will be copied in the Platform during the build. This feature allows to add or overwrite libraries, tools, etc. into the Platform.

The dropins folder organization should respect the 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 are organized. Then fill the dropins folder with additional features and build again the Platform to get a customized Platform.

Files in the dropins folder have priority. If one file has the same path and name as a file already installed in the Platform, the file from the dropins folder will be selected first.

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

Platform Publication

The publication of the built Platform to a module repository is disabled by default. It can be enabled by setting the skip.publish property to false in the module.properties file of the Platform configuration project .

The publication is kept disabled by default in the project sources because developers usually use the locally built platform in the workspace. However, the publication is required in a Continuous Integration environment. This can be done by leaving the skip.publish property to true in the project sources and by overwriting it in the command launched by the Continuous Integration environment, for example:

mmm publish shared -Dskip.publish=false

If the Platform is configured with Full BSP connection, the build script can be launched to validate that the BSP successfully compiles and links before the Platform is published. It can be enabled by setting the com.microej.platformbuilder.bsp.build.enabled property to true in the module.properties file of the Platform configuration project (defaults to false if not set).

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 (the Executable). 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 Executable (application.out).

Note

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

BSP connection configuration is only required in the following cases:

  • Use the SDK to produce the Executable of a Mono-Sandbox Application (recommended).
  • Use the SDK to run a MicroEJ Test Suite on device.
  • Build a the Executable of a Multi-Sandbox Application.

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 Executable is built outside the 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 Executable again.
  • Case 3: Full BSP connection

    The MicroEJ Platform includes the BSP.

    BSP connection is configured when building the 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 build the Executable 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 built outside the SDK

    Platform Options:
      [NONE]
    
    Application Options:
      [NONE]
    
  • No BSP connection, Executable built using the SDK

    Platform Options:
      [NONE]
    
    Application Options:
      deploy.dir.microejapp=[absolute_path]
      deploy.dir.microejlib=[absolute_path]
      deploy.dir.microejinc=[absolute_path]
      deploy.dir.microejscript=[absolute_path]
    
  • Partial BSP connection, Executable built outside the 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 built using the 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 built using the 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 Executable (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 macOS 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.

The build script can also be launched before the Platform publication, see Platform Publication for more details.

Note

The Executable 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 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 macOS or Linux operating systems, it is a shell script named run.sh, with execution permission enabled.
  • The Executable filename 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 (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 Standalone 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

Platform API Documentation

The Platform API documentation provides a comprehensive HTML Javadoc that combines all the Foundation Library APIs.

It can be built using the following steps:

  • Create a new module repository project.

  • Enable module repository javadoc generation (see Generate Javadoc).

  • Go to your Platform build directory and browse source/javaLibs and source/MICROJVM/javaLibs directories. You will find Foundation Libraries implementations JAR files in the following pattern: <module_name>-<major>.<minor>.jar.

    Example: EDC-1.3.jar: module_name = edc, major = 1, minor = 3.

  • For each Foundation Library your want to include,

    • Retrieve its api module in either the Central Repository, Developer Repository or your custom repository. Most of the Foundation Library APIs provided by MicroEJ are available under the ej.api organization.

      Example: EDC is on the Central Repository (https://repository.microej.com/modules/ej/api/edc/)

    • Get the latest available patch version corresponding to your <major>.<minor> version. This allows to benefit from the latest javadoc fixes and updates for the corresponding version.

      Example: ej.api#edc#1.3.5: patch``=``5

    • Declare a dependency line in the module repository.

      <dependency conf="artifacts->*"  transitive="false" org="<org>" name="<module_name>" rev="<major>.<minor>.<patch>" />
      

      Example:

      <dependency conf="artifacts->*"  transitive="false" org="ej.api" name="edc" rev="1.3.5" />
      
  • Build the module repository.

The Platform API documentation is available in <module_repository_project>/target~/artifacts/<module_repository_name>-javadoc.zip.

Default Application

As of Architecture 8.1.0, a default pre-built application (microejapp.o) is provided with the VEE Port. It simplifies the early-stage integration into a BSP project by eliminating the need to create and build an Application project within the SDK, thereby removing the requirement to obtain a valid SDK license.

The default pre-built application is available at [VEE_PORT_DIR]/defaultApp/microejapp.o. It prints a splash with Architecture Characteristics on the standard output:

MicroEJ START

,--.   ,--.,--.                    ,------.     ,--. ,--.   ,--.,------.,------.
|   `.'   |`--' ,---.,--.--. ,---. |  .---'     |  |  \  `.'  / |  .---'|  .---'
|  |'.'|  |,--.| .--'|  .--'| .-. ||  `--, ,--. |  |   \     /  |  `--, |  `--,
|  |   |  ||  |\ `--.|  |   ' '-' '|  `---.|  '-'  /    \   /   |  `---.|  `---.
`--'   `--'`--' `---'`--'    `---' `------' `-----'      `-'    `------'`------'

                                  **********
                              ********************
                            *************************
                        ******************************
                        **********+=--::::--=++**********
                      *******++:...           ..:=+*******
                    ******+:..                  ...+******
                    *****+:.                        .:+*****
                    ****+....--.                .:-:  .=****
                    ***+...:****-.             .****=...=****
                  ****-...=****+.             -****+...:****
                  ****:...-****=.             :****+...:+***
                  ****:....-++-                :++=....:+***
                    ***+........                 .......=****
                  ******=..........           .........-******
                  *******+.......++-:......:-=+:......=*******
                  *********=.......:=++++++=:.......-*********
                ************+-..................:+************
            ******   ***********+=-:......:-=++**********   ******
            *****    #***********************************    *****
              ***     #*********************************     ***
                *****   ********************************   *****
              ********  ##****************************  ********
              ****   ***  ###***********************##  ***   ****
              ***    *     ###******************###     *    ***
                **           #####************#####           **
                              ##################
                                ##############
                                    ######




                          ::::::::::::::::::::::::::::
                            ::::::::::::::::::::::

You successfully linked your first Application with the following Architecture characteristics:
- Name:                         atsauce6
- Version:                      8.1.0 (20231220-1011)
- Usage:                        Production
- Core Engine Capability:       Multi-Sandbox
- Instruction Set Architecture: x86
- Compilation Toolchain:        GNU GCC (GNUvX_X86Linux)
MicroEJ END (exit code = 0)