- NXP Platform Accelerator for i.MX RT595 EVK v2.0.0
- MicroEJ SDK 6
- MicroEJ SDK 5
- VEE Port Specifications
- Requirements
- Directory structure
- Preliminary steps
- Fetch the source code
- MicroEJ IDE project setup
- Build and run applications using the MicroEJ SDK IDE
- Build and run applications on your i.MX RT595 EVK
- Run Demo Wearable VG application
- Switching to a production license
- Alternative: build and run from command line
- Requirements for building from command line
- Populate a Build Kit
- Using default evaluation license
- Needed Environment variables
- Explore available options (works on Linux)
- Compile and flash
- Compilation defaults
- Compile with just NET support enabled
- Debug
- Compile Release image
- Compile using production license
- Tutorial: Using native C functions from the high level application
- Get familiar with MicroEJ
- Troubleshooting
This project is used to build NXP Platform Accelerator for the i.MX RT595 EVK with a display panel G1120B0MIPI.
NXP Platform Accelerator a VEE (Virtual Execution Environment) and provides a hardware abstraction to develop applications in high-level programming languages such as Java.
NXP Platform Accelerator is built upon MicroEJ technology.
This release includes:
-
i.MX RT595 EVK simulator to develop VEE applications and test them on a host PC
- The simulator program has a graphic display of the EVK board and its LCD panel
-
The necessary recipes to embed the VEE architecture for GCC
-
Various Foundation Libraries to provide high level libraries to developers. Notable Foundation Libraries part of this release are:
-
MCUXpresso SDK 2.15.100 for i.MX RT595 EVK
-
FreeRTOS version 10.5.1
-
Sample applications demonstrating NXP VEE:
-
SimpleGFX: draw moving NXP coloured boxes using MicroUI
-
AnimatedMascot: draw an animated Android Vectordrawable image using MicroVG
-
-
Mock support with Java stub implementations to mimick C native functions. Thanks to this mock support, the SimpleGFX application can smoothly run on the simulator
NXP Platform Accelerator is built on MicroEJ technology.
MicroEJ SDK 6 is the latest available MicroEJ SDK. The SDK 6 uses Gradle plugin to compile and package MicroEJ modules. It allows the user to use his favourite IDE such as Android Studio or IntelliJ IDEA (see the list of supported IDE).
SDK 6 is currently limited to the build, test and simulation of Applications and Add-on Libraries (see Scope and Limitations for more information). If you need other features, such as developping a VEE Port, you have to use the SDK 5.
If you are an application developer only and do not need to make changes to the VEE Port, you can use the SDK 6. Please click on the button below to access to the SDK 6 Getting Started on the i.MX RT595 EVK.
If you want to modify the VEE Port, make changes to low level source code, please use SDK 5 and continue following this README.
The architecture version is 8.1.1.
This VEE Port provides the following Foundation Libraries:
| Foundation Library | Version |
|---|---|
| BON | 1.4 |
| DEVICE | 1.1 |
| DRAWING | 1.0 |
| EDC | 1.3 |
| KF | 1.7 |
| MICROUI | 3.5 |
| MICROVG | 1.4 |
| SNI | 1.4.0 |
| TRACE | 1.1 |
The VEE Port is derived into:
- a Mono-Sandbox VEE Port (default)
-
PC with Windows 10 or higher, or Linux (tested on Debian 11)
- Note for Mac users: this documentation does not cover Mac usage, however it is supported by the MicroEJ tools. If you are interested in Mac support, please contact MicroEJ.
-
Internet connection to MicroEJ Central Repository
-
MicroEJ SDK Distribution 23.07 or higher, available here
-
i.MX RT595 EVK board (can be ordered here) and G1120B0MIPI display panel (can be ordered here)
-
Optionally: J-Link Debugger to flash the software
nxp-vee-rt595
├───bsp
│ └── projects
│ ├── common
│ ├── microej
│ └── nxpvee-ui
├── BuildKit.readme.txt
├── CHANGELOG.md
├───Documentation
├───LICENSE.txt
├───Licenses
├── Makefile
├── Makefile.inc
├── microej
│ ├── apps
│ ├── front-panel
│ ├── imageGenerator
│ ├── MIMXRT595-evk_platform-CM4hardfp_GCC48-2.0.0
│ ├── mock
│ ├── validation
│ └── vee-port-configuration
├── README.md
├── SCR-nxpvee-mimxrt595-evk.txt
├── .vscode
└── west.yml
Following is a quick introduction to each folder:
MIMXRT595-evk_platform-CM4hardfp_GCC48-2.0.0: This folder contains the VEE runtime files. Initially, this folder is empty, but it will be populated after the building of the VEE Port.apps: This folder contains two Java demo applications namedAnimatedMascotandSimpleGFX. They are used in this Readme as examples.bsp: This folder contains the C BSP project of the VEE Port. You will find the C implementation of the libraries used in this VEE Port.vee-port-configuration: This folder contains the VEE Port configuration project. Inside it, you will find the VEE Port Configuration files.front-panel: This folder contains the Front Panel mock of the VEE Port. It allows applications to be developed and tested in a Simulator rather than on the target device.imageGenerator: This folder contains the Extended Mode of the Image Generator.mock: This folder contains the Mock where are implemented native method used bySimpleGFXapplication. If you are not familiar with native methods, please have a look at Native Interface Mechanisms documentation.validation: This folder contains the Java test suites to validate the VEE Port behavior. You will find the core validation that checks the correct runtime execution of the VEE Port. You will also find the UI validation that checks drivers and implementation of LLAPILLUI_DISPLAY_IMPL.
The MicroEJ SDK is an Eclipse-based IDE used to build the VEE Port and the high-level applications. The SDK can be used to run the i.MX RT595 EVK simulator.
The MicroEJ SDK requires Java JDK. JDK version depends on the MicroEJ SDK version.
- Install the JDK. You can download it on the Java SE 11 page
- Install MicroEJ SDK 23.07. Please refer to Download and Install – MicroEJ Documentation and Installer Repository
This release has been tested with MicroEJ SDK 23.07 and Java JDK 11.
VS Code is an IDE used to build, flash and debug embedded projects.
In this VEE Port release, VS Code is used to build the firmware that will be flashed to target. VS Code project uses the VEE Port and high level applications built by the MicroEJ SDK.
- You can download VS Code IDE here.
- Start VS Code and install the MCUXpresso for VS Code extension package.
- Install the MCUXpresso VS Code package dependencies to support the full development flow.
Using previously installed MCUXpresso Installer tool, need to install following tools that are used during compilation/debug:
- CMake, Ninja, West and ARM GNU Toolchain under MCUXpresso SDK Developer
- LinkServer under its own section
- SEGGER J-Link under its own section (if optional J-Link is used)
These tools can also be installed independently, MCUXpresso installer tool is just providing a convenient way to install them. In case of standalone installation, following versions need to be installed:
- CMake version 3.27 minimum
- ARM GNU Toolchain version 13.2.1 minimum
- LinkServer version 1.6.133 minimum
Clone the repository with the following command:
mkdir nxpvee-mimxrt595-prj
cd nxpvee-mimxrt595-prj
west init -m https://github.com/nxp-mcuxpresso/nxp-vee-imxrt595-evk .
west update
you will get
.west nxp-vee-rt595
Launch MicroEJ SDK and create a blank workspace.
Import the cloned repository as an existing project:
Then select all projects from the repository.
The package explorer view should look like this:
The VEE Port for the board is the first thing to build with the IDE. For demonstration purposes, one of the release examples uses a mockup (more details follow in the native functions description). The mockup is a dependency of the VEE Port and must therefore be built beforehand.
Right click on the mockup project and select Build Module:
Once the mockup dependency is resolved, the VEE Port can be built by using VEE Port Build instructions.
Right-click on the configuration project and select Build Module:
Building the platform will populate the initally empty MIMXRT595-evk_platform-CM4hardfp_GCC48-2.0.0 project which will be used to build VEE applications.
Under the source folder of the VEE Port, you will find the following files:
- The C header files of the native needed by the VEE Port libraries are located in the
includefolder. - The Java API of the VEE Port libraries is located in the
javaAPISfolder. - The jar files of the VEE Port libraries are located in the
javaLibsfolder. - The Simulation files are located in the
S3andmocksfolders. - The VEE core, the MicroJVM, and some tools.
Two example VEE applications are provided with this release.
Application SimpleGFX displays three moving rectangles using the MicroUI API. The coordinates of the rectangles are calculated in C native functions.
Application AnimatedMascot draws an animated Android Vectordrawable image. It uses the RT595's GCNanoLite-V as an accelerator.
To run applications in simulation mode, right-click on the apps project and select Run As -> MicroEJ Application:
The IDE will prompt which application should be built: either SimpleGFX or AnimatedMascot:
Choose the application. Then run the application in simulation mode by choosing the mode (SIM):
Here is the AnimatedMascot application running in simulation:
Now we will show you how easy it is to modify and test your Java application on the Simulator.
To do so, we will modify the background color of the AnimatedMascot application:
- Open the
AnimatedMascot.javafile located in themicroej/apps/src/main/java/com/nxp/animatedMascotfolder. - It sets the background color line 57. Replace the following line:
g.setColor(Colors.BLACK);
by
g.setColor(Colors.GREEN);
- Follow Run the applications in simulation mode instructions to launch the modified application on the Simulator.
Here is the modified AnimatedMascot application running in simulation:
Setup the i.MX RT595 EVK:
- Check that the dip switches (SW7) are set to OFF, OFF and ON (ISP0, ISP1, ISP2).
- Ensure jumpers JP18 and JP19 are closed.
- Remove jumper JP4.
- Connect the micro-USB cable to J40 to power the board.
- To use JLink probe ensure jumpers JP17 and JP19 are open, connect the board using J38.
The USB connection is used as a serial console for the SoC, as a CMSIS-DAP debugger and as a power input for the board.
MicroEJ VEE Port uses the virtual UART from the i.MX RT595 EVK USB port. A COM port is automatically mounted when the board is plugged into a computer using a USB cable. All board logs are available through this COM port.
The COM port uses the following parameters:
| Baudrate | Data bits bits | Parity bits | Stop bits | Flow control |
|---|---|---|---|---|
| 115200 | 8 | None | 1 | None |
A license is required to build an embedded application.
A MicroEJ license is required to build high-level applications and the VEE Port for target hardware.
Evaluation licenses can be obtained for free. Please follow the instructions from MicroEJ.
With an evaluation license, you can build high-level applications with no limitation in simulation mode. However, applications built with an evaluation license will run for a limited time on target hardware.
Evaluation licenses must be renewed periodically (every month).
Important note: applications built with an evaluation license will freeze after a random period of time. A production license is necessary to have a fully working application on the target.
With the MicroEJ SDK IDE, simply run the application the same way than in simulation but by choosing the mode (EMB).
The build will produce two artifacts:
- microejapp.o: the linked managed code application.
- microejruntime.a: the VEE core.
These artifacts are copied to the BSP project in the directory projects/microej/platform/lib.
Launch VS Code IDE and click on File -> Add Folder to Workspace...
Navigate to the nxp-vee-rt595 path then click Add.
From here you can compile and debug the project as any other C project.
To do so you need to configure then build the CMake project by following the steps below:
Open the Command Palette (CTRL + SHIFT + p) and run CMake: Select Configure Preset to select the build mode you wish to use.
By default, you can select debug variant.
This can also be done by using Projects section from MCUXpresso for VS code" view, and choose appropriate build as default.
Open the Command Palette (CTRL + SHIFT + p) and run CMake: Configure.
Compilation flags are located on ./bsp/projects/nxpvee-ui/armgcc/CMakePresets.json.
To enable any desired features, please edit CMakePresets.json file (and reload preset & re-configure if needed).
Open the Command Palette (CTRL + SHIFT + p) and run CMake: Build.
You can connect VS Code to the board using the Serial Link USB or using a SEGGER J-Link probe. Follow the Board Hardware User Guide for more information on how to connect the different debuggers.
Debug session can be started by pressing the F5 key.
It is also possible to build and debug the project via the MCUXpresso plugin:
Right click on the project, then:
Build Selectedto compileDebugto debug
Once the firmware is flashed, you should see the application running on the target.
Note:
It is possible to flash (without debug) via the MCUXpresso plugin by selecting Flash the Selected Target.
In case of connection issue to the target, reset the debug probe selection via the MCUXpresso plugin:
- Select the MCUXpresso plugin in the left banner
- Right-click on the project name and select
Reset Probe Selection - Start the debug again
The wearable VG demo application is a smart watch application developed by MicroEJ.
It features several watch faces and side applications such as heart rate monitoring, activity tracking, compass, and more.
The application uses MicroUI and MicroVG to exploit hardware's vector capabilities and to make a nice-looking/efficient user interface.
Download the Demo Wearable VG sources using the following command:
git clone -b 1.0.1 https://github.com/MicroEJ/Demo-Wearable-VG.git
If you don’t have Git installed, you can download the source code directly from our GitHub repository. Then you can click on Code > Download ZIP.
Import the projects in the SDK:
- Select
File > Import > General > Existing Projects into Workspace. - Point Select root directory to where you cloned the sources.
- Click on the
Finishbutton.
The application projects watchface-flower, watchface-flower-lp, watchface-sport, watch-util and watch-vg are imported in your workspace. After dependencies resolution it should compile without errors.
To run the application in simulation mode, , right-click on the watch-vg project and select Run As -> MicroEJ Application.
Then run the application in simulation mode by choosing the mode (SIM):
Here is the Demo Wearable VG application running in simulation:
To know more about how this demo works, please have a look at its Application flow.
To run the application, simply run the application the same way than in simulation but by choosing the mode (EMB).
Then follow Build the firmware for the target hardware instructions to launch the application on the board.
To switch to a production license, please contact your NXP representative.
This has only been tested on Linux.
A set of makefiles is provided to build either the whole project (VEE Port, high level application, firmware) or the final firmware from command line instead of using the MicroEJ / MCUXpresso IDE. This can be useful for continuous integration or to get a more automated environment during development.
To access the top level makefile:
cd nxp-vee-rt595
Make sure that the ARMGCC_DIR environment variable is set to the toolchain directory.
If not, you must add it:
Linux:
export ARMGCC_DIR=<PATH_TO_GCC>/arm-gnu-toolchain-13.2.Rel1-x86_64-arm-none-eabi/
Note: Need at least ARM GNU toolchain version >= 13.2.1
The build system used to generate the firmware is based on CMake.
Linux: to install CMake on a Debian based distro, run:
sudo apt install cmake
Note: Need at least cmake version >= 3.27
Linux: to install GNU Make on a Debian based distro, run:
sudo apt install make
It is necessary to export a Build Kit from the MicroEJ SDK IDE. This Build Kit is used by the makefile to build the VEE Port and the high level applications.
The Build Kit is bundled with the SDK and can be exported using the following steps:
Select File > Export > MicroEJ > Module Manager Build Kit,
Choose an empty Target directory, `i.e. ${HOME}/microej/BuildKit `
Click on the Finish button.
Please follow Install the License Key to be able to use make with an evaluation key
In order to compile correctly you will need to export
export MICROEJ_BUILDKIT_PATH_VAR=${HOME}/microej/BuildKit
export ECLIPSE_HOME_VAR=${HOME}/MicroEJ/MicroEJ-SDK-21.11/rcp/
you can also specify a partial repository, when needed (for example if you need libraries that are not yet public)
export MODULE_REPOSITORY_SETTINGS_FILE_VAR=${HOME}/microej/microej-partial-repository/ivysettings.xml
if you are using LinkServer to flash your board, append your path with the following command:
export PATH=$PATH:/usr/local/LinkServer_1.6.133/binaries/:/usr/local/LinkServer_1.6.133/
Note:
Use full path names in above environment variables, do not use special character ~ to represent your home directory.
LinkServer version 1.6.133 is depicted on the command line because this version is working fine, it may work with other versions as well but this is not tested.
make <TAB>
# will get you
clean # clean all projects
nxpvee-ui.prj # build complete UI project
nxpvee-ui-clean # clean UI project
nxpvee-ui-flash # flash board using Jlink
nxpvee-ui-flash_cmsisdap # flash board using CMSIS
nxpvee-ui-gdb # debug UI project using gdb and Jlink
nxpvee-ui-gdb_cmsisdap # debug UI project using gdb and CMSIS
nxpvee-ui-java_run # run simulation, you can override java main using MAIN=com.nxp.animatedMascot.AnimatedMascot make nxpvee-ui-java_run
nxpvee-ui-java_rebuild # rebuild java app
nxpvee-validation.prj # compile and run validation
make nxpvee-ui.prj
# flash with a J-Link probe
make nxpvee-ui-flash
# or flash with USB using CMSIS-DAP
make nxpvee-ui-flash_cmsisdap
Demo app is compiled with
- NET
- SSL by default
make nxpvee-ui.prj CMAKE_OPTS="-DENABLE_NET=1"
make nxpvee-ui-gdb
# or
make nxpvee-ui-gdb_cmsisdap
to compile release image you can
make nxpvee-ui.prj RELEASE=1
to compile using a production license, a dongle is needed
make nxpvee-ui.prj USAGE=prod
Some functions directly used by the high-level application can be implemented in C. It is called the Native Interface Mechanism.
A native method is declared in the Application but is implemented in the native world. So a native declaration requires a C and Java implementation for the Simulator. You can find an example of a native method on this page.
You can have custom natives specific to the Java application (less portable between VEE Ports but fast execution). On the other hand, you can use native methods provided by Foundation Libraries (Portable between VEE Ports but takes more time at the execution).
The SimpleGFX application uses of C native function to calculate rectangles' coordinates (mainly for demonstration's sake).
It is recommended to store all your native methods in the same public class. This public class contains methods with the same parameters as the C native functions.
The name of the C function is Java_<package_name>_<class_name>_<method_name>. Any underscore (_) character in package_name, class_name, or function_name is replaced by _1. Dots (.) are replaced by underscores _.
For these reasons, it is handy to stick to Java naming conventions and use camel case for class and method names and lowercase only package names.
For example:
package com.nxp.application;
public class MyClassNatives {
/* package */ native static int NativeFunction(int a);
};
This can be used in the application source code this way:
j = MyClassNatives.NativeFunction(i);
The native functions are implemented in C, with a name deriving from the package name and the native class name. In the previous example, we would have:
int Java_com_nxp_application_MyClassNatives_NativeFunction(int a)
{
int i;
[...]
return i;
}
When you implement a native method, it is recommended to use the type of sni.h rather than the native type. This ensures type consistency between Java and C.
You could use jint instead of int in the example above.
The sni.h file is located on nxp-vee-rt595/bsp/projects/microej/platform/inc folder.
Mockup functions are used to simulate the behavior of native functions when using the MicroEJ SDK Simulator. Mockups are detailed in the MicroEJ website.
They are implementated in a different MicroEJ SDK project (microej/mock).
The name of the file containing the mockup functions is supposed to be the same as the one where the native functions are declared in the application project (e.g. SimpleGFXNatives.java).
The file may look like this:
package com.nxp.application;
public class MyClassNatives {
static int NativeFunction(int a) {
int i;
[...]
return i;
}
};
Please note that this project mockup must be added as a dependency inside the VEE Port's module.ivy file. The module.ivy file is located in the microej/vee-port-configuration folder. You will find inside all the dependencies used by the VEE Port.
The org and name fields can be found inside the mockup's module.ivy file (respectively organisation and module):
After any modification to the mockup project, you need to rebuild the mock (right click on the mock project and select Build Module) and the platform (see Build the platform).
To discover insights about MicroEJ technology, please follow some of the entry points below. In addition, you will find useful links to our documentation and our GitHub.
You can try to run other examples on our VEE Port. Here is an exhaustive list of them so that you can go further in the MicroEJ technology:
- Understand How to Build a Firmware: It is a document that describes the components, their dependencies, and the process involved in the build of a Firmware.
- Get Started With GUI: It is a guided tutorial to get the basics concepts of our UI.
- Github resources:
- How to use foundation libraries on the Virtual Device or on board.
- Various examples of how-to's.
- Some Demo projects.
You can take a look at the MicroEJ development documentation. Below you can find some important chapters:
- Application Developer Guide: It covers concepts essential to MicroEJ Applications design.
- MicroEJ VEE Port Developer Guide: It covers the main process and configuration of a MicroEJ VEE.
- Tutorials: There are multiple tutorials to master different subjects about the MicroEJ environment (including UI development, code quality and debug, CI/CD…).
On Windows, fetching the source code may trigger the following fatal error:
error: unable to create file [...]: Filename too long.
To avoid this, git configuration needs to be updated to handle long file names:
Start Git Bash as Administrator.
Run following command:
git config --system core.longpaths true
If you get the error PermissionError: [WinError 5] Access is denied, please consider the following procedure :
rm .west
cd nxp-vee-rt595
west init -l
cd ..
west update
If you have the following error [M65] - License check failed [tampered (3)], please follow the steps on this page
I has been noticed an issue with the flash operating frequency on some i.MX RT595 EVK Rev. D. To fix this issue, please set to 50MHz the frequency line 46 of the flash_config.c file located in nxpvee-mimxrt595-evk-round-bsp\sdk\boards\evkmimxrt595\flash_config folder.
Replace:
.serialClkFreq = kFlexSpiSerialClk_60MHz,
By:
.serialClkFreq = kFlexSpiSerialClk_50MHz,