Using Foundation Libraries APIs (Standalone)

This project gathers all the basic examples of the foundation libraries.

EXAMPLE for MISC

Supported MicroEJ Version: 4.1

Supported MicroEJ Edition: SDK

Last updated:23 October 2018

+

<!--
Markdown
Copyright 2016-2018 IS2T. All rights reserved.
For demonstration purpose only.
IS2T PROPRIETARY. Use is subject to license terms.
-->
# Overview
This project gathers some basic examples of the foundation libraries. Those examples are developed as standalone applications and as such can be run by following the associated instructions (see **README.md** file of each example).
Note that to run them on board:
* If you are using MicroEJ SDK:
* You need a supported board (see http://developer.microej.com/index.php?resource=JPF for a list of supported boards using MicroEJ SDK evaluation version)
* And the associated platform binary (.jpf) file or source archive (retrieve it from the previous link and import it into MicroEJ SDK)
* If you are using MicroEJ Studio:
* You need to convert them from standalone applications to sandboxed applications.
* Follow the [How-To convert a standalone app into a sandboxed app](https://github.com/MicroEJ/How-To/tree/master/StandaloneToSandboxed) guide.
# Details
## Core
### EDC
EDC contains the minimal standard runtime environment for embedded devices.
**Available Examples**:
* [com.microej.example.foundation.edc.helloworld](com.microej.example.foundation.edc.helloworld): Prints Hello World on the standard output stream.
### BON
BON focuses on devices with non-volatile and volatile memories. This library allows to fully control memory usage and start-up sequences on devices with limited memory resources.
**Available Examples**:
* [com.microej.example.foundation.bon.immortals](com.microej.example.foundation.bon.immortals): Shows how to manipulate the immortals.
* [com.microej.example.foundation.bon.immutables](com.microej.example.foundation.bon.immutables): Shows how to manipulate the immutables.
## Communication with other hardware
### ECOM
ECOM libraries provide a standard communication over UART.
**Available Examples**:
* [com.microej.example.foundation.ecom.hotplug](com.microej.example.foundation.ecom.hotplug): Shows how to listen on plug/unplug of dynamic ComConnections and shows their properties.
* [com.microej.example.foundation.ecom.writer](com.microej.example.foundation.ecom.writer): Shows how to write some bytes to a CommConnection.
* [com.microej.example.foundation.ecom.reader](com.microej.example.foundation.ecom.reader): Shows how to read some bytes from a CommConnection.
### HAL
HAL libraries present an abstraction of the communication with the hardware.
**Available Examples**:
* [com.microej.example.foundation.hal.gpio](com.microej.example.foundation.hal.gpio): Shows how to use gpio.
## Design a user interface
### MicroUI
MicroUI provides the minimal cornerstone for quick construction of advanced, portable and user-friendly applications for a wide and heterogeneous range of devices with just-what-is-needed resources.
**Available Examples**:
* [com.microej.example.foundation.microui.antialiased](com.microej.example.foundation.microui.antialiased): Shows how to use anti-aliased shapes.
* [com.microej.example.foundation.microui.font](com.microej.example.foundation.microui.font): Shows how to create and use a font.
* [com.microej.example.foundation.microui.gradient](com.microej.example.foundation.microui.gradient): This example shows how to draw a gradient on a display.
* [com.microej.example.foundation.microui.helloworld](com.microej.example.foundation.microui.helloworld): Shows how to print a string on a display.
* [com.microej.example.foundation.microui.image](com.microej.example.foundation.microui.image): Shows how to create and use images.
* [com.microej.example.foundation.microui.input](com.microej.example.foundation.microui.input): Shows how to listen the MicroUI input events.
* [com.microej.example.foundation.microui.led](com.microej.example.foundation.microui.led): Shows how to use the LEDs.
* [com.microej.example.foundation.microui.movableimage](com.microej.example.foundation.microui.movableimage): Shows how to create and use a movable image.
* [com.microej.example.foundation.microui.mvc](com.microej.example.foundation.microui.mvc): Shows how to create and use a MVC design pattern.
* [com.microej.example.foundation.microui.out](com.microej.example.foundation.microui.out): Shows how to redirect the standard SystemOut to the display.
* [com.microej.example.foundation.microui.transform](com.microej.example.foundation.microui.transform): Shows how to use MicroUI transform.
## Communication with the world
### NET
NET is a lightweight Java library dedicated to networking applications. It supports stream (TCP/IP) and datagram (UDP) socket connection APIs.
**Available Examples**:
* [com.microej.example.foundation.net.echo](com.microej.example.foundation.net.echo): Shows a simple echo server.
* [com.microej.example.foundation.net.helloworld](com.microej.example.foundation.net.helloworld): Shows a simple helloworld using NET.
## Data storage
### FS
FS is a library to access multiple storage devices (in and out data streams) through a simple file system API.
**Available Examples**:
* [com.microej.example.foundation.fs.helloworld](com.microej.example.foundation.fs.helloworld): Creates a list of folders, adds some files and deletes them all.

How to add a native call to manage a LED

This example describes how to add a native call to a monolithic application running on a mono-sandbox platform.

HOWTO for MISC

Supported MicroEJ Version: 4.1

Supported MicroEJ Edition: Studio & SDK

Last updated:23 October 2018

+

# Overview
This document describes how to add a native call to a monolithic application running on a mono-sandbox platform.
Important notice,
In order to ease the reader's understanding, the project from this HowTo is released in the final, working state one should obtain when following the instructions below.
# Requirements
## Hardware Requirements
The native code provided has been created for the STMicroelectronics STM32F746G-DISCO development board available from [st.com](https://www.st.com/en/evaluation-tools/32f746gdiscovery.html).
It can be ported to any hardware with a **LED**.
## Software Requirements
- MicroEJ SDK 4.1.5 or later available from [microej.com](http://developer.microej.com/getting-started-sdk.html)
- A MicroEJ platform reference implementation available from [developer.microej.com](https://developer.microej.com/index.php?resource=JPF)
### STM32F746G-DISCO Platform Reference Implementation requirements
- MicroEJ platform reference implementation STM32F746-DISCO Platform available from [developer.microej.com](http://developer.microej.com/getting-started-sdk-stm.html)
- Keil MDK-ARM version 5.25 available from [keil.com](http://www2.keil.com/mdk5)
## Prerequisite Knowledge
This tutorial is built upon an understanding of the MicroEJ SDK, MicroEJ architectures, MicroEJ Platforms and MicroEJ applications as well as at least one native BSP compiler and IDE.
The user of this tutorial should be able to create a "Hello World" application in Java, build the application, build the BSP and flash the firmware image onto the targeted board.
Other development boards, reference platforms and compilers can be used, however the instructions in this tutorial are specifically written for these items and will not apply without changes to other environments.
# Setup the workspace
Import the example projects into the MicroEJ SDK:
- Click on **File** -> **Import**
- Select **General** -> **Existing Project into Workspace**
- **Browse** to root directory
- Check **Search for nested projects** checkbox
- Select all the projects
- Click on **Finish**
* ![Import context](screenshots/ImportProjects.png)
## Projects Overview
- `SNI-LED` contains this README
- `HelloWorld` is a standalone application
- `NativeAPIs` is a project that defines the native functions to manage the LED
# Add a Native Function in the Platform to Control a LED
Modify the platform to add the capability to call a native C function from Java.
1. Configure modules
1. Open the [XXX]-configuration/[XXX].platform` file
2. Go to **Content** tab.
3. Check **Java to C interface**->**SNI API** module
* ![Check SNI](screenshots/CheckSNI.png)
2. Build the platform
1. Go to **Overview** tab
2. Click on **Build Platform** in the **Overview**->**Build section**
3. Once the platform is built, the [Platform-name]-[version]` project is created in the workspace
* ![Build Platform](screenshots/BuildPlatform.png)
3. Add a native call to the HelloWorld Java application
1. Native function definition
- The project `NativeAPIs` is used to define the native functions
- [com.microej.Led](java/NativeAPIs/src/main/java/com/microej/Led.java) defines the native function to manage the LED
- `Led.initNative()` is called at start-up to initialize the LED
`private static native void initNative();`
- `Led.switchLed(boolean on)` is called to set the state of the LED
- `public static void switchLed(boolean on);` provides the APIs to the java code.
- `private static native void switchLedNative(boolean on);`
- Optional, but recommended: To use the simulator a Mock should be created. An example of a mock usage is provided in [Example-Standalone-Java-C-Interface](https://github.com/MicroEJ/Example-Standalone-Java-C-Interface/tree/master/CallingCFromJava#adding-a-mock-of-the-native-function-to-the-jpf)
2. Call the native function in the HelloWorld application
- The project `HelloWorld` depends on `NativeAPIs`
- [com.microej.feature.HelloWorld](java/HelloWorld/src/main/java/com/microej/feature/HelloWorld.java) uses `LED` to toggle the LED
4. Build the HelloWorld Java application
1. Right-click on the HelloWorld project
2. Select **Run-As**->**Run Configuration**
3. Right-click on **MicroEJ Application**
4. Select **New**
5. In **Execution** tab
1. Set your platform that was built in step 3
2. Check **Execute on device**
3. Set **Settings** to **Build and deploy**
6. **Run** will generated a `microejapp.o` in the platform BSP folder
* ![Execute on device](screenshots/RunAsDevice.png)
5. Add the native LED C implementation to the BSP in the third party C IDE
- [LEDs.c](native/src-led/LEDs.c) provides the implementation of the native C function defined in `NativeAPIs`
- This implementation is done for the STM32F746-DISCO board, to add it to Keil IDE follow these steps:
1. Open the Keil project in the platform [XXX]-bsp/ project
2. Right-click on the `MicroEJ/Core` folder
3. Select **Add Existing Files to Group 'MicroEJ/Core'**
1. Browse to the file [LEDs.c](native/src-led/LEDs.c) in the native repository
2. Click **Add**
3. Click **Close**
4. Build the project by pressing **F7**
5. Flash the firmware on the board pressing **F8**
6. Verify the Green LED LD1 is blinking on for one second and off for one second
# Going Further
1. Learn more about Java/C communication with this example: [Example-Standalone-Java-C-Interface](https://github.com/MicroEJ/Example-Standalone-Java-C-Interface)
2. Adapt this HelloWorld to run into a Multi Sandbox kernel [Single-App-to-Multi-App-Platform](../Single-App-to-Multi-App-Platform/).
<!--
- Copyright 2018 IS2T. All rights reserved.
- For demonstration purpose only.
- IS2T PROPRIETARY. Use is subject to license terms.
-->

How to add a Security Manager to a multi-sandbox platform

This example describes how to add a security manager to a multi-sandboxed platform.

HOWTO for MISC

Supported MicroEJ Version: 4.1

Supported MicroEJ Edition: Studio & SDK

Last updated:23 October 2018

+

# Overview
This document describes how to add a security manager to a multi-sandboxed platform.
The security manager will allow access to a kernel LED native function to one feature and forbid access to a second feature.
1. Check the permission before the native call.
2. Add security manager to the kernel.
Important notice,
In order to ease the reader's understanding, the project from this HowTo is released in the final, working state one should obtain when following the instructions below.
# Requirements
This tutorial is built upon the [Single-App-to-Multi-App-Platform](../Single-App-to-Multi-App-Platform) platform.
This platform must:
- Implement LEDs native function in the kernel
- Load at least two features
# Setup the workspace
Import the example projects into the MicroEJ SDK:
- Click on **File** -> **Import**
- Select **General** -> **Existing Project into Workspace**
- **Browse** to root directory
- Check **Search for nested projects** checkbox
- Select all the projects
- Click on **Finish**
* ![Import context](screenshots/ImportProjects.png)
## Projects Overview
- `Multi-App-Security-Manager` contains this README
- `HelloWorld` is a feature named "Hello" application using the LED
- `HelloWorld2` is the same feature as `HelloWorld` with a different [kf name](java\HelloWorld2\src\main\resources\kf\Hello.kf) "Hello2"
- `NativeAPIs` is a project that defines the native functions to manage the LED
- `Kernel` is the kernel entry point and function to load the features
# Check the Permission
1. Create an [LedPermission](NativeAPIs\src\main\java\com\microej\LedPermission.java) class that extends `java.security.BasicPermission`
2. In [Led](NativeAPIs\src\main\java\com\microej\Led.java), check the permission before calling `switchLedNative(boolean on);`
```
/**
* Switch the led state.
*
* @param on
* <code>true</code> to switch on the led.
* @throws SecurityException
* when the SecurityManager does not give {@link LedPermission}.
*/
public static void switchLed(boolean on) throws SecurityException {
SecurityManager securityManager = System.getSecurityManager();
// SecurityManager may be null if the Kernel has not yet set it.
if (securityManager != null) {
securityManager.checkPermission(LedPermission.INSTANCE);
}
switchLedNative(on);
}
```
# Set the Security Manager
A simple security manager which does not check permissions when called in Kernel mode and performs the checks otherwise.
## Create a Security Manager
1. Create [com.microej.kernel.security.KernelSecurityManager](java\Kernel\src\main\java\com\microej\kernel\security\KernelSecurityManager.java) that extends `java.lang.SecurityManager`.
2. Create an interface [com.microej.kernel.security.FeaturePermissionChecker](java\Kernel\src\main\java\com\microej\kernel\security\KernelSecurityManager.java) that defines `public void checkPermission(Permission p, Feature f) throws SecurityException;`
3. In [com.microej.kernel.security.KernelSecurityManager](java\Kernel\src\main\java\com\microej\kernel\security\KernelSecurityManager.java) overrides `public void checkPermission(Permission permission)` to delegate the check.
```
@Override
public void checkPermission(Permission permission) {
if(!Kernel.isInKernelMode()){
// We are not called in kernel mode, so perform the security checks.
Feature feature = (Feature)Kernel.getContextOwner();
Kernel.enter();
FeaturePermissionChecker checker = permissionsMap.get(permission.getClass());
if(checker != null){
checker.checkPermission(permission, feature);
} else {
noCheckerFound(permission, feature);
}
} else {
// We are called in kernel mode, so allow the operation always.
kernelPermission(permission);
}
}
```
## Create the Checkers
1. Create [com.microej.kernel.security.LedPermissionChecker](java\Kernel\src\main\java\com\microej\kernel\security\LedPermissionChecker.java) that implements `com.microej.kernel.security.FeaturePermissionChecker`.
- The permission will only be granted to the features with the name "Hello"
```
@Override
public void checkPermission(Permission p, Feature f) throws SecurityException {
String name = f.getName();
if (name == null || !name.equals("Hello")) {
throw new SecurityException();
}
}
```
## Instantiate the Security Manager
Modify the Kernel entry point [com.microej.kernel.SimpleKernel.main(String[])](java\Kernel\src\main\java\com\microej\kernel\SimpleKernel.java) to instantiate the SecurityManager.
```
KernelSecurityManager securityManager = new KernelSecurityManager();
securityManager.setFeaturePermissionChecker(LedPermission.class, new LedPermissionChecker());
System.setSecurityManager(securityManager);
```
# Build & Run
## Rebuild the kernel with the security manager implementation
1. In the MicroEJ SDK, generate the microejapp.o file
1. Right-click on the `Kernel` project
2. Select **Run-As**->**Run Configuration**
3. Right-click on **MicroEJ Application**
4. Select **New**
5. In **Execution** tab
1. Set your platform
2. Check **Execute on device**
3. Set **Settings** to **Build and deploy**
6. **Run**
7. In the BSP folder the `microejapp.o` file is generated
2. Use a third party C IDE to build the BSP and flash your board
## Build the features
1. In the MicroEJ SDK, generate `application_1.fo`
1. Right-click on the HelloWorld project
2. Select **Run-As**->**Run Configuration**
3. Right-click on **MicroEJ Application**
4. Select **New**
5. In **Execution** tab
1. Set your platform
2. Check **Execute on device**
3. Set **Settings** to **Build Dynamic Feature**
* ![Build Dynamic Feature](screenshots/RunAsFeature.png)
6. In **Configuration** tab
1. Select **Feature**->**Dynamic Download**
2. Set the **Output name** to `application_1`
3. Set the **Kernel** to the object file generated by the third party IDE
* ![Feature Configuration](screenshots/RunAsFeatureConfiguration.png)
* If using Keil adding the debug information is required cf **Additional Info** at the bottom of this readme
7. **Run**
8. In the output folder (by default generated at the root of `HelloWorld` project) an `application_1.fo` file is generated
2. Generate `application_2.fo`
- Follow the same steps as *1.* with `HelloWorld2` and using the name `application_2.fo`
3. Copy the `application_1.fo` and `application_2.fo` feature files to a `tmp/` folder at the root of the microSD card.
4. Insert the SD card into the board
5. Reset the board
6. The firmware should run the 2 features
- `HelloWorld` should make the LED blink
- A `SecurityException` should be raised in `HelloWorld2`
# Going Further
## Other Permissions
- Other `FeaturePermissionChecker` can be added to the `KernelSecurityManager` for other type of Permission.
- java.net.SocketPermission
- java.io.FilePermission
- ...
# Additional Info
## Adding Debug Info for Keil
Keil strips the debug info from the binary file, a tool is provided in the platform to add them. To generate the object file with the info, follow this steps:
1. **Run -> Run configuration**
2. Create a new MicroEJ Tool configuration
3. In **Execution** tab
1. Select your platform
2. Select the tool **Soar debug infos post-linker**
4. In **Configuration** tab
1. Set the **SOAR object** file to the .o file generated in the `{kernel project output folder}/soar/`
2. Set the **executable file** to the `.axf` object file generated by Keil
5. Run
6. Update the Hello World launch configuration to use the generated file `standalone.axf.soarDebugInfos` for the kernel
<!--
- Copyright 2018 IS2T. All rights reserved.
- For demonstration purpose only.
- IS2T PROPRIETARY. Use is subject to license terms.
-->

https://github.com/MicroEJ/How-To/tree/master/Mock-Get-Started

How to add a mock to your project

This project explain how to create a mock for SNI and SP functions on the simulator.

HOWTO for MISC

Supported MicroEJ Version: 4.1

Supported MicroEJ Edition: Studio & SDK

Last updated:23 October 2018

+

# Overview
This project explain how to create a mock for SNI and SP functions on the simulator.
# Usage
## How to add a mock to your project
For this example a native function will be used: `public static native int foo();`
This function will be in `MyClass` at `my.package`
* Add a native method to your Java application. This native method will have two implementations:
* One in C code in the platform BSP project (this part is not covered in this document)
* One in Java (J2SE) in a new Java project for the simulator
### Implement the J2SE mock
* Create a new Java project `Mock`
* Open `File` > `New` > `EasyAnt project`
* Choose `com.is2t.easyant.skeleton#microej-mock;+` as skeleton
* Fulfill the form
* Click on `Finish`
* Create a class with the **same name, same package** as your SNI (e.g. `my.package.MyClass`)
* Implement the SNI function as public with the **same signature** (as `public`, without the `native` keyword) (e.g. `public native int foo()`)
### Export the mock
* Build the Mock project with EasyAnt (**right click on the project** > `build with EasyAnt`).
* A `.rip` file is created in the `target~/artifacts` folder in the Mock project.
* From the `.rip` unzip the content of `content` folder into the `dropins` folder of your platform configuration project (e.g. [Platform-Name]-configuration/dropins).
* **Build you platform**.
* Run your Java application on the simulator.
## Create a Mock with a UI
A mock can show a separate UI to ease input/output.
An example is provided
* An application using native function [Mock-Get-Started-MyApp](Mock-Get-Started-MyApp\)
* A mock opening a UI [Mock-Get-Started-MyMock](Mock-Get-Started-MyMock\)
# Requirements
* MicroEJ SDK 4.1.4 or later
* A MicroEJ 4.1 Platform Reference Implementation imported into the MicroEJ repository.
* An activated Evaluation or Production license.
* A working Java application that runs on the above platform simulator
# Dependencies
_All dependencies are retrieved transitively by Ivy resolver_.
# Source
N/A
# Restrictions
None.
<!--
Markdown
Copyright 2017-2018 IS2T. All rights reserved.
For demonstration purpose only.
IS2T PROPRIETARY. Use is subject to license terms.
-->

How to convert a mono-sandbox platform to a multi-sandbox platform

This example describes how to go from a monolithic application running on a mono-sandbox platform, to a multi-sandbox platform running multiple APPs securely protected by their own sandbox.

HOWTO for MISC

Supported MicroEJ Version: 4.1

Supported MicroEJ Edition: Studio & SDK

Last updated:10 August 2018

+

# Overview
This document describes how to go from a monolithic application running on a mono-sandbox platform, to a multi-sandbox platform running multiple APPs securely protected by their own sandbox. This HowTo uses an "Hello World" and turns it into a sandboxed APP.
1. Add a native (C) call to blink an LED in the application
2. Run a Multi Sandbox kernel
3. Adapt the hello world to run as be feature (i.e an APP)
Important notice,
In order to ease the reader's understanding, the project from this HowTo is released in the final, working state one should obtain when following the instructions below.
# Requirements
## Hardware Requirements
The native code provided has been created for the STMicroelectronics STM32F746G-DISCO development board available from [st.com](https://www.st.com/en/evaluation-tools/32f746gdiscovery.html).
It can be ported to any hardware with a **LED** and a **File System**.
## Software Requirements
- MicroEJ SDK 4.1.5 or later available from [microej.com](http://developer.microej.com/getting-started-sdk.html)
- A MicroEJ platform reference implementation available from [developer.microej.com](https://developer.microej.com/index.php?resource=JPF)
### STM32F746G-DISCO Platform Reference Implementation requirements
- MicroEJ platform reference implementation STM32F746-DISCO Platform available from [developer.microej.com](http://developer.microej.com/getting-started-sdk-stm.html)
- Keil MDK-ARM version 5.25 available from [keil.com](http://www2.keil.com/mdk5)
## Prerequisite Knowledge
This tutorial is built upon an understanding of the MicroEJ SDK, MicroEJ architectures, MicroEJ Platforms and MicroEJ applications as well as at least one native BSP compiler and IDE.
The user of this tutorial should be able to create a "Hello World" application in Java, build the application, build the BSP and flash the firmware image onto the targeted board.
Other development boards, reference platforms and compilers can be used, however the instructions in this tutorial are specifically written for these items and will not apply without changes to other environments.
# Setup the workspace
Import the example projects into the MicroEJ SDK:
- Click on **File** -> **Import**
- Select **General** -> **Existing Project into Workspace**
- **Browse** to root directory
- Check **Search for nested projects** checkbox
- Select all the projects
- Click on **Finish**
* ![Import context](screenshots/ImportProjects.png)
## Projects Overview
- `Single-App-to-Multi-App-Platform` contains this README
- `HelloWorld` is a standalone application that will be used as a feature
- `NativeAPIs` is a project that defines the native functions to manage the LED
- `Kernel` is the kernel entry point and function to load a feature
# Add a Native Function in the Platform to Control a LED
If you followed the How-To [SNI-LED](../SNI-LED/README.md), this part has already been done, go to **Run a Multi-App Kernel**.
Modify the platform to add the capability to call a native C function from Java.
1. Configure modules
1. Open the [XXX]-configuration/[XXX].platform` file
2. Go to **Content** tab.
3. Check **Java to C interface**->**SNI API** module
* ![Check SNI](screenshots/CheckSNI.png)
2. Build the platform
1. Go to **Overview** tab
2. Click on **Build Platform** in the **Overview**->**Build section**
3. Once the platform is built, the [Platform-name]-[version]` project is created in the workspace
* ![Build Platform](screenshots/BuildPlatform.png)
3. Add a native call to the HelloWorld Java application
1. Native function definition
- The project `NativeAPIs` is used to define the native functions
- [com.microej.Led](java/NativeAPIs/src/main/java/com/microej/Led.java) defines the native function to manage the LED
- `Led.initNative()` is called at start-up to initialize the LED
`private static native void initNative();`
- `Led.switchLed(boolean on)` is called to set the state of the LED
- `public static void switchLed(boolean on);` provides the APIs to the java code.
- `private static native void switchLedNative(boolean on);`
- Optional, but recommended: To use the simulator a Mock should be created. An example of a mock usage is provided in [Example-Standalone-Java-C-Interface](https://github.com/MicroEJ/Example-Standalone-Java-C-Interface/tree/master/CallingCFromJava#adding-a-mock-of-the-native-function-to-the-jpf)
2. Call the native function in the HelloWorld application
- The project `HelloWorld` depends on `NativeAPIs`
- [com.microej.feature.HelloWorld](java/HelloWorld/src/main/java/com/microej/feature/HelloWorld.java) uses `LED` to toggle the LED
4. Build the HelloWorld Java application
1. Right-click on the HelloWorld project
2. Select **Run-As**->**Run Configuration**
3. Right-click on **MicroEJ Application**
4. Select **New**
5. In **Execution** tab
1. Set your platform that was built in step 3
2. Check **Execute on device**
3. Set **Settings** to **Build and deploy**
6. **Run** will generated a `microejapp.o` in the platform BSP folder
* ![Execute on device](screenshots/RunAsDevice.png)
5. Add the native LED C implementation to the BSP in the third party C IDE
- [LEDs.c](native/src-led/LEDs.c) provides the implementation of the native C function defined in `NativeAPIs`
- This implementation is done for the STM32F746-DISCO board, to add it to Keil IDE follow these steps:
1. Open the Keil project in the platform [XXX]-bsp/ project
2. Right-click on the `MicroEJ/Core` folder
3. Select **Add Existing Files to Group 'MicroEJ/Core'**
1. Browse to the file [LEDs.c](native/src-led/LEDs.c) in the native repository
2. Click **Add**
3. Click **Close**
4. Build the project by pressing **F7**
5. Flash the firmware on the board pressing **F8**
6. Verify the Green LED LD1 is blinking on for one second and off for one second
# Run a Multi-App Kernel
This section will adapt the existing MicroEJ platform project to run a Kernel with KF support.
## Adapt the Platform to Support KF
1. Configure the platform modules
1. Open the [XXX]-configuration/[XXX].platform` file
2. Go to **Content** tab.
3. Check **Multi Applications** module
* ![Check MultiApp](screenshots/CheckMultiApp.png)
2. Build the platform
1. Go to **Overview** tab
2. Click on **Build Platform** in the **Overview**->**Build section**
3. Once the platform is built, the [Platform-name]-[version]` project is created in the workspace
* ![Build Platform](screenshots/BuildPlatform.png)
3. Implement KF low level C APIs in the BSP project
- `LLKERNEL_impl.h` has been added to the MicroEJ headers directory, this file is used for the RAM buffer where the APPs are dynamically linked
- [LLKERNEL_SDRAM.c](native/src-kf/LLKERNEL_SDRAM.c) is an implementation using the on-board SDRAM
- Add the implementation to your BSP project using the third party C IDE
1. Using the Keil IDE, right-click on the `MicroEJ/KF` folder
2. Select **Add Existing Files to Group 'MicroEJ/KF'**
1. Browse to the file [LLKERNEL_SDRAM.c](native/src-kf/LLKERNEL_SDRAM.c) in the native repository
2. Click **Add**
3. Click **Close**
## Build the Kernel
### Create the kernel project
1. Expose the foundation APIs to the feature
- In the [module.ivy](java/Kernel/module.ivy) file, the example depends on:
- `ej.api#edc`: to provide the EDC Java APIs to the kernel
- `ej.api#bon`: to provide the BON Java APIs to the kernel
- `ej.api#kf`: to provide the KF APIs to the kernel to load a feature
- `com.microej.kernelapi#edc`: to provide the EDC APIs to the feature
- `com.microej.kernelapi#bon`: to provide the BON APIs to the feature
2. Add a way to load a feature
- An example is provided in [kernel](java/Kernel)
- [com.microej.kernel.FeatureInputStream](java/Kernel/src/main/java/com/microej/kernel/FeatureInputStream.java) is used to create an input stream to receive the feature.
- [com.microej.kernel.SimpleKernel](java/Kernel/src/main/java/com/microej/kernel/SimpleKernel.java) gets a feature input stream and loads it.
3. Add an entry point
- [SimpleKernel.java](java/Kernel/src/main/java/com/microej/kernel/SimpleKernel.java) provides a main() method to load the features.
4. Expose the native function to the feature
- Features cannot access classes and methods which are not exposed by the Kernel. To provide the feature access to the `Led` class and the `switchLed` method:
1. Add a dependency to the `NativeAPIs` library in the Kernel project
2. Create [kernel.api](java/Kernel/src/main/resources/kernel.api) file at the root of a /resources folder
- Define the types that are open to the Features
- Define the methods that are open to the Features
5. Generate the microejapp.o file
1. Right-click on the `Kernel` project
2. Select **Run-As**->**Run Configuration**
3. Right-click on **MicroEJ Application**
4. Select **New**
5. In **Execution** tab
1. Set your platform
2. Check **Execute on device**
3. Set **Settings** to **Build and deploy**
6. **Run**
7. In the BSP folder the `microejapp.o` file is generated
### Adapt the platform
- [com.microej.kernel.FeatureInputStream](java/Kernel/src/main/java/com/microej/kernel/FeatureInputStream.java) expects the native functions
- `void Java_com_microej_kernel_FeatureInputStream_init()` is called once to initialize the native stack
- `jboolean Java_com_microej_kernel_FeatureInputStream_isFeatureAvailable()` to check if a feature is available
- `jint Java_com_microej_kernel_FeatureInputStream_readIntoArray(jbyte *out, jint outOffset, jint outLen)` to read the data
- `void Java_com_microej_kernel_FeatureInputStream_closeFeature()` to close the feature stream
- An example using FatFs file system (FS) is provided in [inputStream.c](native/src-feature/inputStream.c)
- [inputStream.c](native/src-feature/inputStream.c) defines ff_convert and ff_wtoupper, those functions are required by FatFS, if your project already defines it, comment them out.
- This example will look for features in the FS /tmp/application_1.fo first, then , once the feature is loaded, increment the feature search number.
- Add the implementation to your BSP project using the third party C IDE
1. Using the Keil IDE, right-click on the `MicroEJ/Core` folder
2. Select **Add Existing Files to Group 'MicroEJ/Core'**
1. Browse to the file [inputStream.c](native/src-feature/inputStream.c)` in the native repository
2. Click **Add**
3. Click **Close**
### Build
1. Build and Run using the third party C IDE.
1. Using the Keil IDE, build the project pressing **F7**
3. Flash the firmware on the board pressing **F8**
4. Verify the Green LED LD1 is blinking on for one second and off for one second
2. The firmware output should wait for a feature
```
start
VM START
Looking for feature /tmp/application_1.fo
Hello.main()
Start kernel
[K] get inputstream...
Waiting for a feature to be available
```
# Adapt the Hello World to Run as a Feature
1. Add a dependency to ej.api#kf to `HelloWorld`
- [module.ivy](java/HelloWorld/module.ivy) contains a dependency to `<dependency org="ej.api" name="kf" rev="[1.4.0-RC0,2.0.0-RC0[" conf="provided->*" />`
2. Create a `FeatureEntryPoint` that calls back `com.microej.feature.HelloWorld.main()` on the `start()`
- [com.microej.feature.MyFeatureEntryPoint](java/HelloWorld/src/main/java/com/microej/feature/MyFeatureEntryPoint.java) does it
3. Add a [FeatureName].kf file to your features resources see [Hello.kf](java/HelloWorld/src/main/resources/kf/Hello.kf)
1. Define the feature version with `version=`
2. Define the feature name with `name=`
3. Define the feature entry point with `entryPoint=` fully qualified name of the entry point
4. Define the feature types with `types=` to the package managed by the feature
4. Add a [FeatureName].cert certificate
- This certificate will be used when adding a security manager to the kernel (not used currently)
5. Build the feature
1. Right-click on the HelloWorld project
2. Select **Run-As**->**Run Configuration**
3. Right-click on **MicroEJ Application**
4. Select **New**
5. In **Execution** tab
1. Set your platform
2. Check **Execute on device**
3. Set **Settings** to **Build Dynamic Feature**
* ![Build Dynamic Feature](screenshots/RunAsFeature.png)
6. In **Configuration** tab
1. Select **Feature**->**Dynamic Download**
2. Set the **Output name** to `application_1`
3. Set the **Kernel** to the object file generated by the third party IDE
* ![Feature Configuration](screenshots/RunAsFeatureConfiguration.png)
* If using Keil adding the debug information is required cf **Additional Info** at the bottom of this readme
7. **Run**
8. In the output folder (by default generated at the root of `HelloWorld` project) an `application_1.fo` file is generated
5. Copy the `application_1.fo` feature file to a `tmp/` folder at the root of the microSD card.
6. Insert the SD card into the board
7. Reset the board
8. The firmware should run the feature
```
start
VM START
Looking for feature /tmp/application_1.fo
Hello.main()
Start kernel
[K] get inputstream...
Waiting for a feature to be available
Application available. Loading application.
[K] load&start app
[K] app loaded
close
Looking for feature /tmp/application_2.fo
[K] get inputstream...
Waiting for a feature to be available
feature started
Hello World !
```
# Going Further
MicroEJ provides an optional layer (Wadapps) that gives more abstraction and tools to manage applications lifecycle and deployment . An example of Minimal Wadapps firmware is available here: [Example-MinimalMultiAppFirmware](https://github.com/MicroEJ/Example-MinimalMultiAppFirmware).
# Troubleshooting
## ej.kf.IncompatibleFeatureException
When loading the `.fo` file a `ej.kf.IncompatibleFeatureException` exception can be raised.
This exception occurs when the kernel has changed since the `.fo` file generation.
### Solution
1. Regenerate the `.fo` file
2. Copy the `application_1.fo` feature file to a `tmp/` folder at the root of the microSD card.
3. Insert the SD card into the board
4. Reset the board
If the error still occurs, check that the kernel used for the generation of the `.fo` file is the kernel flashed on the board.
## [M101] - Input image file has no debug information :
When building the `application_1.fo` file an error **M101** occurs
```
1 : SOAR ERROR
[M101] - Input image file has no debug information : {path to the file}.
2 : SOAR ERROR
[M0] - Internal SOAR error. Please contact MicroEJ support. (-1)
FAIL
Soar image generation aborted.
```
### Solution
If using Keil adding the debug information is required cf **Additional Info** at the bottom of this readme
# Additional Info
## Adding Debug Info for Keil
Keil strips the debug info from the binary file, a tool is provided in the platform to add them. To generate the object file with the info, follow this steps:
1. **Run -> Run configuration**
2. Create a new MicroEJ Tool configuration
3. In **Execution** tab
1. Select your platform
2. Select the tool **Soar debug infos post-linker**
4. In **Configuration** tab
1. Set the **SOAR object** file to the .o file generated in the `{kernel project output folder}/soar/`
2. Set the **executable file** to the `.axf` object file generated by Keil
5. Run
6. Update the Hello World launch configuration to use the generated file `standalone.axf.soarDebugInfos` for the kernel
<!--
- Copyright 2018 IS2T. All rights reserved.
- For demonstration purpose only.
- IS2T PROPRIETARY. Use is subject to license terms.
-->

https://github.com/MicroEJ/Example-MinimalMultiAppFirmware

Build Your First MicroEJ Firmware

# Overview
This repository provides an example of a minimal MicroEJ Multi-App Firmware that features:
* a default implementation of the Wadapps framework.
* an administration server for managing the applications lifecycle (INSTALL, START, STOP, UNINSTALL).
* the exposure of a set of default APIs for applications (`EDC` + a communication channel - `NET` or `ECOM-COMM`).
* the virtual device configuration including Applications Local Deployment and Wadapps Administration Console tools.
The minimal Multi-App Firmware is declined into two distinct projects, depending on the communication channel used by the administration server:
* `com.microej.example.firmware.minimal.comm`: communication over TCP/IP network (`NET` API).
* `com.microej.example.firmware.minimal.net`: communication over a serial link (`ECOM-COMM` API).
The minimal Multi-App Firmware is headless, meaning it does not expose nor use user interfaces (such as GUI, buttons, ...). It is an entry point for developers that want, in only few steps, build their first Multi-App Firmware and test deploying an application on it.
# Requirements
* MicroEJ SDK 4.1.1 or higher.
* A MicroEJ 4.1 Multi-App platform (binary) imported into the MicroEJ repository. Please consult (<http://developer.microej.com>) for a list available evaluation platforms.
* An activated Evaluation or Production license.
* For `NET` example, a board connected to the same sub-network than the PC.
* For `COMM` example, a board with a USB-TTL cable plugged to the PC and connected to RX/TX pins.
# Dependencies
All dependencies are retrieved from _MicroEJ Central Repository 4.1_ (<http://developer.microej.com/ivy/4.1/>) using Apache Ivy. Those dependencies include:
* A set of foundation libraries, required for any Multi-App Firmware (such as `EDC` and `KF` libraries).
* A foundation library specific to each project, depending on the administration server back-end (`NET` or `ECOM-COMM`).
* Wadapps add-on libraries (_Wadapps Application Framework_, _Storage_ back-ends, ...).
* A firmware bootstrap library, that simplifies firmware development.
* A set of APIs exposed to applications.
* A set of Resident Applications, that are linked together with the Kernel to produce the Multi-App Firmware.
* A set of Virtual Device tools, such as Local Deployment and Wadapps Administration Console.
# Usage
## Import Firmware Projects
Start MicroEJ SDK on an empty workspace and clone this Git repository (`File > Import > Git > Projects From Git`).
At the end of the process, two projects have been imported:
* `com.microej.example.firmware.minimal.net`
* `com.microej.example.firmware.minimal.comm`
In the rest of the document, the term `[backend]` has to be replaced with either `net` or `comm` depending on the chosen firmware project.
## Select and Configure the Firmware
In case of the `net` back-end, the project is already configured.
In case of the `comm` back-end, the COM port on which the administration server will be connected must be set. Please consult the documentation of the selected platform to get the list of available platform COM ports. Edit `com.microej.example.firmware.minimal.comm/build/common.properties` and update with the appropriate value:
ej.ecom.com.0.port=[PLATFORM_COM_VALUE]
## Setup a Platform
Before building the firmware, a target platform must be configured in the MicroEJ workspace.
* Go to `Window > Preferences > MicroEJ > Platforms` and put the mouse pointer over the desired platform.
* A tooltip with some information should appear. Press `F2` to show more information.
* Select the the platform _Path_ and copy it to the clipboard.
* Go to `Window > Preferences > Ant > Runtime` and select the `Properties` tab.
* Click on `Add Property...` button and set a new property named `platform-loader.target.platform.dir` with the platform path pasted from the clipboard.
There are other ways to setup the input platform for building the firmware. Please consult the _Multi-App Firmware Developer's Guide_ for more informations.
## Build the Firmware
* Right-click on the chosen firmware project and select `Build With EasyAnt`. This may take several minutes.
After successful build, the firmware artifacts are available in firmware project build folder `target~/artifacts` and contains:
* the firmware executable file (`minimal.[backend].out`).
* the corresponding virtual device (`minimal.[backend].jpf`).
* the firmware package for the MicroEJ Store (`minimal.[backend].kpk`)
## Program the Firmware on the Device
The procedure to program a firmware is platform specific. Please refer to the platform documentation for the detailed firmware flashing procedure.
To flash the firmware, open `Run Configurations` menu, then create a `MicroEJ Tool` run configuration named `Flash Firmware`.
* In `Execution` tab:
* In `Target Platform`, select the platform used to build the firmware,
* In `Settings`, select `Program with [Flasher Tool]` (e.g `ST Link` or `Segger J-Link`),
* Set `Output Folder` to firmware project folder.
* In `Configuration` tab:
* Set the application binary file to `target~/artifacts/minimal-[backend].out` file.
* Click on `Run` and wait until the flashing procedure is terminated.
# Develop and Deploy an Application
Prior to develop an application, the virtual device has to be imported:
* Go to `File > Import > MicroEJ > Platforms, Virtual Devices and Architectures`
* Browse the file `\target~\artifacts\minimal.[backend].jpf` and put the mouse pointer over the desired platform.
Note that the application development can be done in a dedicated MicroEJ Studio instance (the virtual device can be freely distributed).
To create and deploy a basic application, please refer to the _Sandboxed Application Developer's Guide_ (sections _Background Service Application_ and _Wadapps Administration Console_).
# Additional Resources
## Developer Resources
MicroEJ developer web site (<http://developer.microej.com>) is the entry point to find examples, tools and documentation.
Specifically, foundation libraries javadoc can be found at <http://developer.microej.com/javadoc/microej_4.1/foundation/>, and addon libraries (such as _Wadapps Application Framework_) javadoc can be found at <http://developer.microej.com/javadoc/microej_4.1/addons/>.
## License
Examples are subject to license agreement. See `LICENSE.txt` in firmware projects.
<!--
Markdown
Copyright 2017-2018 IS2T. All rights reserved.
Use of this source code is subject to license terms.
-->

Dependencies Discoverer

Tool to list the binary dependencies (class, interfaces, methods, fields) of a piece of code.

TOOL for MISC

Supported MicroEJ Version: 4.1

Supported MicroEJ Edition: Studio & SDK

Last updated:23 January 2018

+

# Overview
This project is a tool to list all dependencies of a Java code and to discover the missing dependencies of this Java code against MicroEJ OS.
# Usage
## Online
1. In your MicroEJ or Eclipse workspace, import this project and drop all your JARs into [classpath](classpath/) folder.
2. Right click on **DependencyDiscoverer** project.
3. Select **Run As -> Java Application**.
4. Double click on **DependencyDiscoverer**.
5. Right click on **DependencyDiscoverer** project.
6. Select Refresh
7. A **result.txt** file will be generated at the root of the project.
## Offline
1. Drop all your JARs into [classpath](classpath/) folder.
2. Get a MicroEJ offline repository (zip archive). For example repository 4.0 from [developer.microej.com/4.0/ivy](http://developer.microej.com/4.0/ivy).
3. Unzip MicroEJ repository into [againstClasspath](againstClasspath/) folder.
4. Set `OFFLINE` variable in [DependencyDiscovererOptions.java](src/com/microej/tool/dependencydiscoverer/DependencyDiscovererOptions.java) to `true`.
5. Right click on **DependencyDiscoverer** project.
6. Select **Run As -> Java Application**.
7. Double click on **DependencyDiscoverer**.
8. Right click on **DependencyDiscoverer** project.
9. Select Refresh
10. A **result.txt** file will be generated at the root of the project.
## Adding additional MicroEJ libraries.
You may have some additional MicroEJ libraries, to include them, drop them into [againstClasspath](againstClasspath) folder.
## Interpreting the results.
Open the **result.txt** file with a text editor. Each line contains a missing dependency. If the file is empty, your library is compatible with MicroEJ OS!
Each line may be :
* A **class** described as `package.of.class.Class`.
* An **inner class** described as `package.of.class.Class$InnerClassName` (InnerClassName is a number if it is an anonymous class).
* A **field** described as `package.of.class.Class.fieldName`.
* A **constructor** described as `package.of.class.Class.<init>({parameters types see under})V`.
* A **method** described as `package.of.class.Class.methodName({parameters types see under}){return type}`.
The types may be:
* **B**: byte
* **C**: char
* **D**: double
* **F**: float
* **I**: int
* **J**: long
* **L{ClassName};**: reference to a {ClassName} instance
* **S**: short
* **V**: void
* **Z**: boolean
* **[{type}**: array of {type} (type may be an array it self)
## Porting a library to MicroEJ OS
To port your library with missing dependencies to MicroEJ OS, the following steps shall be taken:
1. Contact MicroEJ support, some common libraries are available on demand.
2. Refactor your libraries to avoid those dependencies.
# Requirements
* MicroEJ Studio 4.0 or later, or MicroEJ SDK 4.0 or later, or Eclipse 4.2 or later.
* A JRE 7 or higher.
# Dependencies
None.
# Source
N/A
# Restrictions
None.

JUnit Example (Sandboxed)

# Overview
This project gathers simple sandboxed applications tested with JUnit.
# Requirements
* MicroEJ Studio or SDK 4.1 or later
# Usage
Each subfolder contains a distinct application.
# Changes
* See the change log file [CHANGELOG.md](CHANGELOG.md) located at the root of this repository.
# License
* See the license file [LICENSE.txt](LICENSE.txt) located at the root of this repository.

Examples Eclasspath

# Overview
This project gather all the examples of eclasspath. Eclasspath contains Java runtime libraries.
Note that to run them on board:
* If you are using MicroEJ SDK:
* You need a supported board (see http://developer.microej.com/index.php?resource=JPF for a list of supported boards using MicroEJ SDK evaluation version)
* And the associated platform binary .jpf file (retrieve it from the previous link and import it into MicroEJ SDK)
* If you are using MicroEJ Studio:
* You need to convert them from standalone applications to sandboxed applications.
* Follow the [How-To convert a standalone app into a sandboxed app](https://github.com/MicroEJ/How-To/tree/master/StandaloneToSandboxed) guide.
# Details
## logging
**Available Examples**:
* [com.microej.examples.eclasspath.logging](com.microej.examples.eclasspath.logging) : Writes in the logger.

Using SNI and SP Libraries API (Standalone)

This repository contains examples showing how to enable communication between programs written in C and programs written in Java using MicroEJ APIs.

EXAMPLE for MISC

Supported MicroEJ Version: 4.1

Supported MicroEJ Edition: SDK

Last updated:29 August 2017

+

[](Markdown)
[](Copyright 2016 IS2T. All rights reserved.)
[](IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.)
# Overview
Although MicroEJ lets you leverage Java in an embedded context, there are still some cases where your Java threads need to synchronize and exchange data with OS tasks written in C/C++.
This repository contains examples showing how to enable communication between programs written in C and programs written in Java using MicroEJ APIs.
## Available examples
For calling C functions from a Java class, MicroEJ provides the SNI API. The following examples illustrate how to use this API :
* [CallingCFromJava](/CallingCFromJava) provides an example of invocation of a C function from a Java method
* [CallingCFromJava](/CallingCFromJavaMock) is a helper project required in order to be able to run the Java application on simulator
The SNI library also provides APIs for tasks/threads synchronisation via function calls and callbacks.
For data exchange issues between tasks/threads, MicroEJ provides a few options:
* Shielded Plug API (suitable for sharing structured data, with built-in wait/release synchronisation APIs)
* Immortals API and SNI API (suitable for sharing access to raw data, but you need to provide your own synchronisation mechanism)
The following examples, based on the consumer/producer problem, illustrate how to use those APIs :
* [Producer Consumer with ShieldedPlug](/ProducerConsumerUsingShieldedPlug) using Shielded Plug API as the delivery mechanism
* [Producer Consumer with SNI and Immortals](/ProducerConsumerUsingQueues) using SNI and Immortals APIs to wrap the native FreeRTOS message queue API as the underlying delivery mechanism
Each example comes with a launch configuration. These launch configurations require that the target platform (common to each configuration) is built.
# Building the Java Platform (JPF)
We need to generate and build a Java Platform (JPF), i.e. the set of object files and libraries required to execute Java code on the target platform linked by an executable C program.
The following assumes that you have downloaded and imported the STM32F646-DISCO platform from [MicroEJ SDK Getting Started](http://developer.microej.com/getting-startetd-sdk.html) web page.
### Creation
* Select **File > New > Other... > MicroEJ > Platform** menu item
* Click **Browse** button next to the **Architecture** field and select **STMicroElectronics STM32F7J ARMCC**
* Check the **Create from a platform reference implementation** option
* Select **STM32F746-Disco > Standalone**
* Click **Next**
* Set the name field to "**SNI**"
* Set the version field to "**1.0.0**"
* Click **Finish**. This will lead to the generation of a few projects in our workspace :
* [STM32F746GDISCO-SNI-CM7hardfp_ARMCC5-bsp](STM32F746GDISCO-SNI-CM7hardfp_ARMCC5-bsp)
* [STM32F746GDISCO-SNI-CM7hardfp_ARMCC5-configuration](STM32F746GDISCO-SNI-CM7hardfp_ARMCC5-configuration)
* [STM32F746GDISCO-SNI-CM7hardfp_ARMCC5-fp](STM32F746GDISCO-SNI-CM7hardfp_ARMCC5-fp)
### Build
* From the **Overview** tab of the generated [full.platform](/STM32F746GDISCO-SNI-CM7hardfp_ARMCC5-configuration/full.platform) file
* Click on the **Build platform** hyperlink. This will generate the following project :
* [STM32F746GDISCO-SNI-CM7hardfp_ARMCC5-1.0.0](STM32F746GDISCO-SNI-CM7hardfp_ARMCC5-1.0.0)
## API Selection Criteria
Here are a few things to consider when choosing between Shielded Plug and an SNI and Immortals based solution
* Performance
* Generally speaking, Shielded Plug (SP for short) will copy data from/to a database block and will therefore take more processing time and memory than an SNI-based solution relying on a shared memory area with less data copying.
* SP is more suitable for asynchronous (post) processing of published data
* Data Integrity
* Given that with SP there is no buffering of data, it makes it more suitable for sampling scenarios where losing a value once in a while is not critical .
* API convenience
* SP requires that you describe your data in an xml based configuration file.
* However, the SP synchronization API is quite simple
* Using SNI and Immortals, it is easier to pass data directly to/from C native functions
In summary, for simple use cases, Shielded Plug shall suffice, but for more intensive and more constrained environments, SNI and Immortals may be a better fit.
## Additional references
### B-ON Library Specification
Among other things, the **Beyond Profile Specification** document contains detailed information on:
* sharing memory areas between Java and C/C++ using **immortal objects**
**immortal objects** : such objects are never garbage collected and keep the same physical memory location forever. This makes them useful for specifying shared memory areas between C and Java.
The document can be downloaded from [www.e-s-r.net/specifications/index.html](www.e-s-r.net/specifications/index.html)
### SNI Library Specification
The **Simple Native Interface for GreenThread Context Profile Specification** document contains detailed information on :
* how to map Java primitive types to portable C types for methods/functions parameters and return types
* naming conventions for C functions implementing Java SNI native implementations
* these have to be followed to generate valid linker configuration files
* sharing memory areas between Java and C/C++ using **immortal objects**
* controlling (as in suspend and resume) Java Thread execution from C code
The document can be downloaded from [www.e-s-r.net/specifications/index.html](www.e-s-r.net/specifications/index.html)
### Shielded Plug Library Specification
The **Shielded Plug Profile Specification** document contains detailed information on :
* the concepts underlying the Shielded Plug API
* how to map Java primitive types to portable C types for methods/functions parameters and return types
* how to create dedicated readers/writers that can translate Shielded Plug Blocks into Java Objects
* the reference API for both C and Java languages
The document can be downloaded from [www.e-s-r.net/specifications/index.html](www.e-s-r.net/specifications/index.html)
### Simulation
The **Simulation** section of the **Device Developer's Guide** document contains useful info for :
* creating Java mocks simulating native code using the same naming conventions as SNI
* using the Hardware In the Loop (HIL) engine as a replacement for the SNI/GreenThread interface used on target environments
To access the document from MicroEJ:
* Select **Help > MicroEJ Resource Center** menu item
* Select **Manual > Device Developer's Guide**
# Requirements
* MicroEJ SDK 4.0.0 or later
* Keil MicroVision v5.0 or later

Examples Custom Events for MicroUI

This project illustrate how to propagate custom events from the hardware to MicroUI.

EXAMPLE for MISC

Supported MicroEJ Version: 4.1

Supported MicroEJ Edition: SDK

Last updated:29 August 2017

+

# Overview
This example illustrates how to propagate custom events from the hardware to MicroUI. MicroUI already supports generic events like touch, button and joystick.
Hardware events (e.g. sensors movement) can be used for specific display action upon occurrence.
See the Device Developer's Guide at section **Inputs** (13.5) for more information.
# Usage
1. Create a platform with at least the UI module.
2. Before building this platform, some configuration is required. In the **xxx-configuration project** in the **microui/microui.xml** file, add the following xml element as the first eventgenerator.
<eventgenerator name="CUSTOM" class="com.microej.example.customevent.CustomEventGenerator"/>
3. Build your platform.
4. In the [/com.microej.example.customevent/src/main/c](com.microej.example.customevent/src/main/c) folder
1. Choose the file corresponding to the board/RTOS used
2. Replace the application entry point in the /xxx-bsp project by the file selected in the previous step
5. In MicroEJ, create a launch configuration for the Java application
1. Set the name to "CustomEvent_Build"
2. In the **Main** tab
1. Set the **Project** field to "com.microej.example.customevent"
2. Set the **Main type** field to "CustomEventExample"
3. In the **Execution** tab
1. In the **Target** frame, set the JPF to the one built in step #3
2. In the **Execution** frame, select the **Execute on EmbJPF** radio button
6. Run the launch configuration.
7. Compile, link and flash the xxx-bsp project.
# Requirements
- JRE 7 (or later) x86.
- MicroEJ 4.0 or later.
- Java platform with (at least) EDC-1.2, MICROUI-2.0.
# Project structure
- src/main/java
- Java sources
- src/main/c
- Entry points (main.c) examples for the given board/RTOS that generates custom events.
# Dependencies
_All dependencies are retrieved transitively by Ivy resolver_.
# Source
N/A
# Restrictions
None.

Using Foundation Libraries APIs (Standalone)

This project gathers all the basic examples of the foundation libraries.

EXAMPLE for MISC

Supported MicroEJ Version: 4.0

Supported MicroEJ Edition: SDK

Last updated:22 August 2017

+

# Overview
This project gathers some basic examples of the foundation libraries. Those examples are developed as standalone applications and as such can be run by following the associated instructions (see **README.md** file of each example).
Note that to run them on board:
* If you are using MicroEJ SDK:
* You need a supported board (see http://developer.microej.com/index.php?resource=JPF for a list of supported boards using MicroEJ SDK evaluation version)
* And the associated platform binary .jpf file (retrieve it from the previous link and import it into MicroEJ SDK)
* If you are using MicroEJ Studio:
* You need to convert them from standalone applications to sandboxed applications.
* Follow the [How-To convert a standalone app into a sandboxed app](https://github.com/MicroEJ/How-To/tree/master/StandaloneToSandboxed) guide.
# Details
## Core
### EDC
EDC contains the minimal standard runtime environment for embedded devices.
**Available Examples**:
* [com.microej.example.foundation.edc.helloworld](com.microej.example.foundation.edc.helloworld): Prints Hello World on the standard output stream.
### BON
BON focuses on devices with non-volatile and volatile memories. This library allows to fully control memory usage and start-up sequences on devices with limited memory resources.
**Available Examples**:
* [com.microej.example.foundation.bon.immortals](com.microej.example.foundation.bon.immortals): Shows how to manipulate the immortals.
* [com.microej.example.foundation.bon.immutables](com.microej.example.foundation.bon.immutables): Shows how to manipulate the immutables.
## Communicate with other hardwares
### ECOM
ECOM libraries provides a standard communication over UART.
**Available Examples**:
* [com.microej.example.foundation.ecom.hotplug](com.microej.example.foundation.ecom.hotplug): Shows how to listen on plug/unplug of dynamic ComConnections and shows their properties.
* [com.microej.example.foundation.ecom.writer](com.microej.example.foundation.ecom.writer): Shows how to write some bytes to a CommConnection.
* [com.microej.example.foundation.ecom.reader](com.microej.example.foundation.ecom.reader): Shows how to read some bytes from a CommConnection.
### HAL
HAL libraries presents an abstraction of the communication with the hardware.
**Available Examples**:
* [com.microej.example.foundation.hal.gpio](com.microej.example.foundation.hal.gpio): Shows how to use gpio.
## Design a user interface
### MicroUI
MicroUI provides the minimal cornerstone for quick construction of advanced, portable and user-friendly applications for a wide and heterogeneous range of devices with just-what-is-needed resources.
**Available Examples**:
* [com.microej.example.foundation.microui.antialiased](com.microej.example.foundation.microui.antialiased): Shows how to use anti-aliased shapes.
* [com.microej.example.foundation.microui.font](com.microej.example.foundation.microui.font): Shows how to create and use a font.
* [com.microej.example.foundation.microui.helloworld](com.microej.example.foundation.microui.helloworld): Shows how to print a string on a display.
* [com.microej.example.foundation.microui.image](com.microej.example.foundation.microui.image): Shows how to create and use images.
* [com.microej.example.foundation.microui.input](com.microej.example.foundation.microui.input): Shows how to listen the MicroUI input events.
* [com.microej.example.foundation.microui.led](com.microej.example.foundation.microui.led): Shows how to use the LEDs.
* [com.microej.example.foundation.microui.movableimage](com.microej.example.foundation.microui.movableimage): Shows how to create and use a movable image.
* [com.microej.example.foundation.microui.mvc](com.microej.example.foundation.microui.mvc): Shows how to create and use a MVC design pattern.
* [com.microej.example.foundation.microui.out](com.microej.example.foundation.microui.out): Shows how to redirect the standard SystemOut to the display.
* [com.microej.example.foundation.microui.transform](com.microej.example.foundation.microui.transform): Shows how to use MicroUI transform.
### MWT
MWT is a widget toolkit designed for a wide range of devices, including embedded devices with limited processing power.
**Available Examples**:
* [com.microej.example.foundation.mwt.helloworld](com.microej.example.foundation.mwt.helloworld): Shows a simple hello world using MWT.
* [com.microej.example.foundation.mwt.mvc](com.microej.example.foundation.mwt.mvc): Shows how to create and use a MVC design pattern.
### NLS
NLS provides tools to use localized strings.
**Available Examples**:
* [com.microej.example.foundation.nls.helloworld](com.microej.example.foundation.nls.helloworld): Shows how to print a localized string on a display.
## Communicate with the world
### NET
NET is a lightweight Java library dedicated to networking applications. It supports stream (TCP/IP) and datagram (UDP) socket connection APIs.
**Available Examples**:
* [com.microej.example.foundation.net.echo](com.microej.example.foundation.net.echo): Shows a simple echo server.
* [com.microej.example.foundation.net.helloworld](com.microej.example.foundation.net.helloworld): Shows a simple helloworld using NET.
## Store data
### FS
FS is a library to access multiple storage devices (in and out data streams) through a simple file system API.
**Available Examples**:
* [com.microej.example.foundation.fs.helloworld](com.microej.example.foundation.fs.helloworld): Creates a list of folders, adds some files and deletes them all.

JSON encoder/decoder

<!--
Markdown
Copyright 2014-2016 IS2T. All rights reserved.
IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->
# Overview
JSON in Java [package org.json]
JSON is a light-weight, language independent, data interchange format.
See http://www.JSON.org/
The files in this package implement JSON encoders/decoders in Java.
It also includes the capability to convert between JSON and XML.
This is a reference implementation. There is a large number of JSON packages
in Java. Perhaps someday the Java community will standardize on one. Until
then, choose carefully.
The package compiles on Java 1.6-1.8.
JSONObject.java: The JSONObject can parse text from a String or a JSONTokener
to produce a map-like object. The object provides methods for manipulating its
contents, and for producing a JSON compliant object serialization.
JSONArray.java: The JSONObject can parse text from a String or a JSONTokener
to produce a vector-like object. The object provides methods for manipulating
its contents, and for producing a JSON compliant array serialization.
JSONTokener.java: The JSONTokener breaks a text into a sequence of individual
tokens. It can be constructed from a String, Reader, or InputStream.
JSONException.java: The JSONException is the standard exception type thrown
by this package.
JSONString.java: The JSONString interface requires a toJSONString method,
allowing an object to provide its own serialization.
JSONStringer.java: The JSONStringer provides a convenient facility for
building JSON strings.
JSONWriter.java: The JSONWriter provides a convenient facility for building
JSON text through a writer.
XML.java: XML provides support for converting between JSON and XML.
XMLTokener.java: XMLTokener extends JSONTokener for parsing XML text.
Unit tests are maintained in a separate project. Contributing developers can test
JSON-java pull requests with the code in this project:
https://github.com/stleary/JSON-Java-unit-test
Numeric types in this package comply with ECMA-404: The JSON Data Interchange Format
(http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf) and
RFC 7159: The JavaScript Object Notation (JSON) Data Interchange Format
(https://tools.ietf.org/html/rfc7159#section-6).
This package fully supports Integer, Long, and Double Java types. Partial support
for BigInteger and BigDecimal values in JSONObject and JSONArray objects is provided
in the form of get(), opt(), and put() API methods.
# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="org.json.me" name="json" rev="1.+"/>`
# Requirements
- EDC 1.2 or later
# Dependencies
None.
# Source
N/A
# Restrictions
None.

Examples Custom Events for MicroUI

This project illustrate how to propagate custom events from the hardware to MicroUI.

EXAMPLE for MISC

Supported MicroEJ Version: 4.0

Supported MicroEJ Edition: SDK

Last updated:25 January 2017

+

# Overview
This example illustrates how to propagate custom events from the hardware to MicroUI. MicroUI already supports generic events like touch, button and joystick.
Hardware events (e.g. sensors movement) can be used for specific display action upon occurrence.
See the Device Developer's Guide at section **Inputs** (13.5) for more information.
# Usage
1. Create a platform with at least the UI module.
2. Before building this platform, some configuration is required. In the **xxx-configuration project** in the **microui/microui.xml** file, add the following xml element as the first eventgenerator.
<eventgenerator name="CUSTOM" class="com.microej.example.customevent.CustomEventGenerator"/>
3. Build your platform.
4. In the [/com.microej.example.customevent/src/main/c](com.microej.example.customevent/src/main/c) folder
1. Choose the file corresponding to the board/RTOS used
2. Replace the application entry point in the /xxx-bsp project by the file selected in the previous step
5. In MicroEJ, create a launch configuration for the Java application
1. Set the name to "CustomEvent_Build"
2. In the **Main** tab
1. Set the **Project** field to "com.microej.example.customevent"
2. Set the **Main type** field to "CustomEventExample"
3. In the **Execution** tab
1. In the **Target** frame, set the JPF to the one built in step #3
2. In the **Execution** frame, select the **Execute on EmbJPF** radio button
6. Run the launch configuration.
7. Compile, link and flash the xxx-bsp project.
# Requirements
- JRE 7 (or later) x86.
- MicroEJ 4.0 or later.
- Java platform with (at least) EDC-1.2, MICROUI-2.0.
# Project structure
- src/main/java
- Java sources
- src/main/c
- Entry points (main.c) examples for the given board/RTOS that generates custom events.
# Dependencies
_All dependencies are retrieved transitively by Ivy resolver_.
# Source
N/A
# Restrictions
None.

https://github.com/MicroEJ/Tool-Excel-to-NLS/

Excel to NLS

# Overview
Internalization is an important part of many projects so that users can select the language they want for their system. MicroEJ offers a library named NLS (National Language Support) to help developers internationalize the messages in their applications. NLS imposes the structure of the translation files, with a simple and efficient "[key]=[message]" format. Nevertheless, each company may have its own format for the translation files they share with their translators, often using Microsoft Excel.
Here, we demonstrate how an Excel file (xlsx) can be converted to files in NLS format. We use the Apache POI library to perform this transformation. You can adapt this tool to your specific file format.
Two Eclipse projects are provided:
1. [Excel-to-NLS](/Excel-to-NLS) converts an Excel file to a set of NLS files and saves them as resources of the second project.
2. [HelloWorld](/HelloWorld) takes all the generated files and uses NLS library to display the same message in several languages.
## Project Setup
Excel-to-NLS comes without the JAR files from Apache POI. You have to download them from http://poi.apache.org. You have to copy the following JAR files to the [lib](/Excel-to-NLS/lib) folder of the project:
- poi-[version].jar
- poi-ooxml-[version].jar
- poi-ooxml-schemas-[version].jar
- xmlbeans-[version].jar
Then, right-click on the project and select **Properties**. In the left menu, select **Java Build Path** and open the **Libraries** tab. Add the above JARs to the Java build path.
HelloWorld is already fully configured.
### Project structure
- Tool-Excel-to-NLS
- Excel-to-NLS
- `excel/`: folder with a example xlsx file
- `launches/`: Java launch configuration
- `lib/`: folder to place the required JAR files
- `src/main/java/`: Java sources
- HelloWorld
- `excel/`: folder with a example xlsx file
- `launches/`: MicroEJ launch configuration
- `src/main/java/`: Java sources
- `src/main/resources/`: resources
- `LICENCE.md`
- `README.md`
# Usage
## Run XLS to NLS tool
1. Execute the App class of the Excel-to-NLS project as a regular Java Application. A [Java launch configuration](/Excel-to-NLS/launches/Excel-to-NLS.launch) is provided for convenience, right-click on [launches/Excel-to-NLS.launch](/Excel-to-NLS/launches/Excel-to-NLS.launch) and select **Run as->Excel-to-NLS**. This will generate a set of NLS files and drop them in the appropriate folder of the HelloWorld project.
2. Execute the [Main](/HelloWorld/src/main/java/ej/examples/nls/Main.java) class of the HelloWorld project as a MicroEJ Application. A [MicroEJ launch configuration](/HelloWorld/launches/HelloWorld on STM32429I-DISCO SimJPF.properties) is provided with the path to the [nls.list](/HelloWorld/src/main/resources/nls.list) file properly configured. This will print the same message with all the available locales in the Eclipse console.
## Run on MicroEJ Simulator
1. Right Click on [Main.java](HelloWorld/src/main/java/ej/examples/nls/Main.java)
2. Select **Run as -> Run Configuration**
3. Select **MicroEJ Application** configuration kind
4. Click on **New launch configuration** icon
5. Go to **Execution** tab
* Select your platform
6. Go to **Configuration** tab
* Go to **Libraries -> NLS**
* Check Use NLS messages
* Set the **NLS list file** to`${project_loc:HelloWorld}/src/main/resources/HelloWorld/HelloWorld.nls.list`
7. Press **Apply**
8. Press **Run**
## Run on device
### Build
1. Right Click on [Main.java](HelloWorld/src/main/java/ej/examples/nls/Main.java)
2. Select **Run as -> Run Configuration**
3. Select **MicroEJ Application** configuration kind
4. Click on **New launch configuration** icon
5. Select **Execute on Device**
6. Select **Build & Deploy**
7. Go to **Execution** tab
* Select your platform
8. Go to **Configuration** tab
* Go to **Libraries -> NLS**
* Check Use NLS messages
* Set the **NLS list file** to`${project_loc:HelloWorld}/src/main/resources/HelloWorld/HelloWorld.nls.list`
9. Press **Apply**
10. Press **Run**
11. Copy the generated `.out` file path
### Flash
1. Use the appropriate flashing tool.
# Requirements
* MicroEJ Studio or SDK 4.0 or later
* A platform with at least:
* EDC-1.2 or higher
* NLS-2.0 or higher
## Dependencies
_All dependencies are retrieved transitively by Ivy resolver_.
# License
See the license file [LICENSE.md](LICENSE.md) located at the root of this repository.
# Changes
See the changelog file [CHANGELOG.md](CHANGELOG.md) located at the root of this repository.

Dependencies Discoverer

Tool to list the binary dependencies (class, interfaces, methods, fields) of a piece of code.

TOOL for MISC

Supported MicroEJ Version: 4.0

Supported MicroEJ Edition: Studio & SDK

Last updated:23 January 2017

+

# Overview
This project is a tool to list all dependencies of a Java code and to discover the missing dependencies of this Java code against MicroEJ OS.
# Usage
## Online
1. In your MicroEJ or Eclipse workspace, import this project and drop all your JARs into [classpath](classpath/) folder.
2. Right click on **DependencyDiscoverer** project.
3. Select **Run As -> Java Application**.
4. Double click on **DependencyDiscoverer**.
5. Right click on **DependencyDiscoverer** project.
6. Select Refresh
7. A **result.txt** file will be generated at the root of the project.
## Offline
1. Drop all your JARs into [classpath](classpath/) folder.
2. Get a MicroEJ offline repository (zip archive). For example repository 4.0 from [developer.microej.com/4.0/ivy](http://developer.microej.com/4.0/ivy).
3. Unzip MicroEJ repository into [againstClasspath](againstClasspath/) folder.
4. Set `OFFLINE` variable in [DependencyDiscovererOptions.java](src/com/microej/tool/dependencydiscoverer/DependencyDiscovererOptions.java) to `true`.
5. Right click on **DependencyDiscoverer** project.
6. Select **Run As -> Java Application**.
7. Double click on **DependencyDiscoverer**.
8. Right click on **DependencyDiscoverer** project.
9. Select Refresh
10. A **result.txt** file will be generated at the root of the project.
## Adding additional MicroEJ libraries.
You may have some additional MicroEJ libraries, to include them, drop them into [againstClasspath](againstClasspath) folder.
## Interpreting the results.
Open the **result.txt** file with a text editor. Each line contains a missing dependency. If the file is empty, your library is compatible with MicroEJ OS!
Each line may be :
* A **class** described as `package.of.class.Class`.
* An **inner class** described as `package.of.class.Class$InnerClassName` (InnerClassName is a number if it is an anonymous class).
* A **field** described as `package.of.class.Class.fieldName`.
* A **constructor** described as `package.of.class.Class.<init>({parameters types see under})V`.
* A **method** described as `package.of.class.Class.methodName({parameters types see under}){return type}`.
The types may be:
* **B**: byte
* **C**: char
* **D**: double
* **F**: float
* **I**: int
* **J**: long
* **L{ClassName};**: reference to a {ClassName} instance
* **S**: short
* **V**: void
* **Z**: boolean
* **[{type}**: array of {type} (type may be an array it self)
## Porting a library to MicroEJ OS
To port your library with missing dependencies to MicroEJ OS, the following steps shall be taken:
1. Contact MicroEJ support, some common libraries are available on demand.
2. Refactor your libraries to avoid those dependencies.
# Requirements
* MicroEJ Studio 4.0 or later, or MicroEJ SDK 4.0 or later, or Eclipse 4.2 or later.
* A JRE 7 or higher.
# Dependencies
None.
# Source
N/A
# Restrictions
None.

Examples Eclasspath

# Overview
This project gather all the examples of eclasspath. Eclasspath contains Java runtime libraries.
Note that to run them on board:
* If you are using MicroEJ SDK:
* You need a supported board (see http://developer.microej.com/index.php?resource=JPF for a list of supported boards using MicroEJ SDK evaluation version)
* And the associated platform binary .jpf file (retrieve it from the previous link and import it into MicroEJ SDK)
* If you are using MicroEJ Studio:
* You need to convert them from standalone applications to sandboxed applications.
* Follow the [How-To convert a standalone app into a sandboxed app](https://github.com/MicroEJ/How-To/tree/master/StandaloneToSandboxed) guide.
# Details
## logging
**Available Examples**:
* [com.microej.examples.eclasspath.logging](com.microej.examples.eclasspath.logging) : Writes in the logger.

The Developer Preview of the Platform Reference Implementation for the S7G2DK board.

JPF_RENESAS for MISC

Supported MicroEJ Version: 4.0

Supported MicroEJ Edition: SDK

Technical Ref.: PRI-EVAL-S7G2DK-SGT-FI7B4

Last updated:18 January 2017

+

# Copyright 2015-2016 IS2T. All rights reserved.
# IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
MicroEJ BSP example for Renesas Synergy S7G2DK (E2studio/ThreadX)
============================================================
# Delivery
Folders listing:
* platforms: contains MicroEJ Platform Architecture and Platform Library.
* platforms_examples: contains the MicroEJ Platform Examples zip file.
# Prerequisites
* Java7
* MicroEJ version 4.0 or later
* E2Studio v5.0.0.043
# How to import MicroEJ Platforms (Platform Architecture with '*.xpf' extension and MicroEJ Platform Libraries with extension '*.xpfp')
Open your MicroEJ. Click on "Window->Preferences->MicroEJ". If no MicroEJ repository is set, select a file system folder to store your MicroEJ platforms repository with the "Browse" button.
Then, go to "MicroEJ->Java Platform Architectures" and click on import.
Select "Select directory" and set the path of the "platforms" folder of the delivery. Select the UI pack and select the "I agree and accept..." checkbox. Click on the "Finish" button. Your MicroEJ platforms are now imported in your MicroEJ. You could see it in "MicroEJ->Java Platforms Architectures" view.
# How to import the MicroEJ Platform Examples
Open your MicroEJ. Click on "File->Import...->MicroEJ->Examples" and select the MicroEJ Platform Examples zip file with the Browse button.
New Items appears in the list. Select all items and click on "Finish". Your MicroEJ Platform Examples are now imported in your MicroEJ.
# Start a new MicroEJ Platform Example
Click on "File->New->MicroEJ->Java Platform" and then on "Next" button. Select your MicroEJ Platform Architecture with "Browse" button. Once selected, some examples appears in examples list.
Select "Platform->S7G2DK (ThreadX)->Full" example and click on "Next". Then, enter your example informations and click on "Finish" button. Projects has been added in your MicroEJ workspace:
* [my-example]-bsp
* [my-example]-configuration
* [my-example]-fp
* [my-example]-microuiGeneratorExtension
# How to create your MicroEJ Platform associated to the MicroEJ Platform Example for the Renesas Synergy S7G2DK (E2Studio/ThreadX)
Prerequisites:
* import the MicroEJ Platforms and MicroEJ Platform Libraries
* import the MicroEJ Platform Examples
* start a new MicroEJ Platform Example
Open the "[my-example]-configuration" project and click on the "full.platform" file. A new tab is now opened in your MicroEJ. Then, click on the "Build Platform" in the "Build" category. Your platform is building. Once finished, a new platform project appears in your MicroEJ workspace ([my-example]-1.0.0). You could now launch Java application on this platform.

JSON encoder/decoder

<!--
Markdown
Copyright 2014-2016 IS2T. All rights reserved.
IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->
# Overview
JSON in Java [package org.json]
JSON is a light-weight, language independent, data interchange format.
See http://www.JSON.org/
The files in this package implement JSON encoders/decoders in Java.
It also includes the capability to convert between JSON and XML.
This is a reference implementation. There is a large number of JSON packages
in Java. Perhaps someday the Java community will standardize on one. Until
then, choose carefully.
The package compiles on Java 1.6-1.8.
JSONObject.java: The JSONObject can parse text from a String or a JSONTokener
to produce a map-like object. The object provides methods for manipulating its
contents, and for producing a JSON compliant object serialization.
JSONArray.java: The JSONObject can parse text from a String or a JSONTokener
to produce a vector-like object. The object provides methods for manipulating
its contents, and for producing a JSON compliant array serialization.
JSONTokener.java: The JSONTokener breaks a text into a sequence of individual
tokens. It can be constructed from a String, Reader, or InputStream.
JSONException.java: The JSONException is the standard exception type thrown
by this package.
JSONString.java: The JSONString interface requires a toJSONString method,
allowing an object to provide its own serialization.
JSONStringer.java: The JSONStringer provides a convenient facility for
building JSON strings.
JSONWriter.java: The JSONWriter provides a convenient facility for building
JSON text through a writer.
XML.java: XML provides support for converting between JSON and XML.
XMLTokener.java: XMLTokener extends JSONTokener for parsing XML text.
Unit tests are maintained in a separate project. Contributing developers can test
JSON-java pull requests with the code in this project:
https://github.com/stleary/JSON-Java-unit-test
Numeric types in this package comply with ECMA-404: The JSON Data Interchange Format
(http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf) and
RFC 7159: The JavaScript Object Notation (JSON) Data Interchange Format
(https://tools.ietf.org/html/rfc7159#section-6).
This package fully supports Integer, Long, and Double Java types. Partial support
for BigInteger and BigDecimal values in JSONObject and JSONArray objects is provided
in the form of get(), opt(), and put() API methods.
# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="org.json.me" name="json" rev="1.+"/>`
# Requirements
- EDC 1.2 or later
# Dependencies
None.
# Source
N/A
# Restrictions
None.

Using SNI and SP Libraries API (Standalone)

This repository contains examples showing how to enable communication between programs written in C and programs written in Java.

EXAMPLE for MISC

Supported MicroEJ Version: 4.0

Supported MicroEJ Edition: SDK

Last updated:12 August 2016

+

[](Markdown)
[](Copyright 2016 IS2T. All rights reserved.)
[](IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.)
# Overview
Although MicroEJ lets you leverage Java in an embedded context, there are still some cases where your Java threads need to synchronize and exchange data with OS tasks written in C/C++.
This repository contains examples showing how to enable communication between programs written in C and programs written in Java using MicroEJ APIs.
## Available examples
For tasks/threads synchronisation via function calls and callbacks, MicroEJ provides the SNI API.
For data exchange issues between tasks/threads, MicroEJ provides a few options:
* Shielded Plug API (suitable for sharing structured data, with built-in wait/release synchronisation APIs)
* Immortals API and SNI API (suitable for sharing access to raw data, but you need to provide your own synchronisation mechanism)
The following examples, most of them based on the consumer/producer problem, illustrate how to use those APIs :
* [Making synchronous C functions calls from Java](/CallingCFromJava) using SNI
* [Producer Consumer with ShieldedPlug](/ProducerConsumerUsingShieldedPlug) using Shielded Plug API as the delivery mechanism
* [Producer Consumer with SNI and Immortals](/ProducerConsumerUsingQueues) using SNI and Immortals APIs to wrap the native FreeRTOS message queue API as the delivery mechanism
Each example comes with a launch configuration. These launch configurations require that the target platform (common to each configuration) is built.
To build the platform :
* Open the [full.platform]([/STM32F746GDISCO-SNI_SP-CM7_ARMCC-FreeRTOS-configuration/full.platform]) file
* Click on the **Build Platform** hyperlink in the **Build** frame
## API Selection Criteria
Here are a few things to consider when choosing between Shielded Plug and an SNI and Immortals based solution
* Performance
* Generally speaking, Shielded Plug (SP for short) will copy data from/to a database block and will therefore take more processing time and memory than an SNI-based solution relying on a shared memory area with less data copying.
* SP is more suitable for asynchronous (post) processing of published data
* Data Integrity
* Given that with SP there is no buffering of data, it makes it more suitable for sampling scenarios where losing a value once in a while is not critical .
* API convenience
* SP requires that you describe your data in an xml based configuration file.
* However, the SP synchronization API is quite simple
* Using SNI and Immortals, it is easier to pass data directly to/from C native functions
In summary, for simple use cases, Shielded Plug shall suffice, but for more intensive and more constrained environments, SNI and Immortals may be a better fit.
## Additional references
Additional examples can be found at the following locations:
* Java/C Data Sharing Using SNI application note on www.microej.com.
* Synchronizing a Java thread with C task(s) application note on www.microej.com.
### B-ON Library Specification
Among other things, the **Beyond Profile Specification** document contains detailed information on:
* sharing memory areas between Java and C/C++ using **immortal objects**
**immortal objects** : such objects are never garbage collected and keep the same physical memory location forever. This makes them useful for specifying shared memory areas between C and Java.
To access the document from MicroEJ:
* Select **Help > MicroEJ Resource Center** menu item
* Select **Library Specification > BON 1.2**
### SNI Library Specification
The **Simple Native Interface for GreenThread Context Profile Specification** document contains detailed information on :
* how to map Java primitive types to portable C types for methods/functions parameters and return types
* naming conventions for C functions implementing Java SNI native implementations
* these have to be followed to generate valid linker configuration files
* sharing memory areas between Java and C/C++ using **immortal objects**
* controlling (as in suspend and resume) Java Thread execution from C code
To access the document from MicroEJ:
* Select **Help > MicroEJ Resource Center** menu item
* Select **Library Specification > SNI_GT 1.2**
### Shielded Plug Library Specification
The **Shielded Plug Profile Specification** document contains detailed information on :
* the concepts underlying the Shielded Plug API
* how to map Java primitive types to portable C types for methods/functions parameters and return types
* how to create dedicated readers/writers that can translate Shielded Plug Blocks into Java Objects
* the reference API for both C and Java languages
To access the document from MicroEJ:
* Select **Help > MicroEJ Resource Center** menu item
* Select **Library Specification > SP 1.0**
### Simulation
The **Simulation** section of the **platform architecture manual** document contains useful info for :
* creating Java mocks simulating native code using the same naming conventions as SNI
* using the Hardware In the Loop (HIL) engine as a replacement for the SNI/GreenThread interface used on target environments
To access the document from MicroEJ:
* Select **Help > MicroEJ Resource Center** menu item
* Select **Manual > Platform Architecture - User Manual**
# Requirements
* MicroEJ SDK 4.0.0 or later
* Keil MicroVision v5.0 or later

Excel to NLS

# Overview
Internalization is an important part of many projets so that users can select the language they want for their system. MicroEJ offers a library named NLS (National Language Support) to help developers to internationalize the messages in their applications. NLS imposes the structure of the translation files, with a simple and efficient "[key]=[message]" format. Nevertheless, each company may be have their own format for the translation files they share with their translators, often using Microsoft Excel.
Here, we demonstrate how an Excel file (xlsx) can be converted to files that respect the NLS format. We use the Apache POI library to make this transformation. You can adapt this tool to your specific file format.
Two Eclipse projets are provided:
1. Excel-to-NLS converts an Excel file to a set of NLS files and drops the result in the second project.
2. HelloWorld takes all the generated files and uses NLS to display the same message in several languages.
## Project Setup
Excel-to-NLS comes without the JAR files from Apache POI. You have to download them from http://poi.apache.org. You have to copy the following JAR files to the `lib` folder of the project:
- poi-[version].jar
- poi-ooxml-[version].jar
- poi-ooxml-schemas-[version].jar
- xmlbeans-[version].jar
Then, right-click on the project and select Properties. In the left menu, select Java Build Path and open the Libraries tab. Add the above JARs to the Java build path.
HelloWorld is already fully configured.
### Requirements
MicroEJ 3.1.0 or above must be installed on your computer.
### Project structure
- Tool-Excel-to-NLS
- Excel-to-NLS
- `excel/`: folder with a example xlsx file
- `launches/`: Java launch configuration
- `lib/`: folder to place the dependency JAR files
- `src/main/java/`: Java sources
- HelloWorld
- `excel/`: folder with a example xlsx file
- `launches/`: MicroEJ launch configuration
- `src/main/java/`: Java sources
- `src/main/resources/`: resources
- `LICENCE.md`
- `README.md`
## Usage
First, execute the App class of the Excel-to-NLS project. A Java launch configuration is provided for convenience, right-click on launchs/Excel-to-NLS.launch and select Run as->Excel-to-NLS. This will generate a set of NLS files and drop them in the appropriate folder of the HelloWorld project.
Second, execute the Main class of the HelloWorld project. A MicroEJ launch configuration is provided with the path to the NLS.list properly configured. This will print the same message with all the available locales in the Eclipse console.
## License
See the license file `LICENSE.md` located at the root of this repository.

Components Hello World

# Overview
This project illustrates the _ej.components_ library.
It contains a service implementation and two bundles: the service publisher and the service user.
## Project Setup
First of all, you have to download the repository by using the Download button or by cloning the repository.
After having retrieved the repository content, open your MicroEJ and then import Existing project into workspace by selecting either the ZIP file or the root directory.
### Requirements
- JRE 7 (or later) x86
- MicroEJ 3.1 or later
- A Java platform to test with at least: EDC 1.2 & EJ.COMPONENTS 2.0 & LOGGING-LIGHTWEIGHT 2.0.
### Project structure
- `helloService`
- `[â€¦]/Hello.java`: the interface defining the service.
- `helloPublisher`
- `[â€¦]/HelloPrint.java`: an implementation of the service.
- `[â€¦]/HelloPublisherBundle.java`: the bundle publishing the service implementation.
- `helloUser`
- `[â€¦]/SayHelloToEveryone.java`: an application that uses the service.
- `[â€¦]/HelloUserBundle.java`: the bundle retrieving the service.
- `helloWorld`: the startup (main) of the example.
- `src/main/java`: Java sources.
- `src/main/resources`: the properties and bundles list.
- `launches`: the MicroEJ launches.
## Usage
To launch the application, right-click on the `helloWorld` project,
select `Run as`, `MicroEJ Application` and choose `Hello World Components (Sim)`.
Another launcher is available to execute on the target board.
## Changes
2015/06/15: Initial version.
## License
See the license file `LICENSE.md` located at the root of this repository.