You can find here documentation relating to products, for more documentary resources, refer to the bibliography.

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:
10 August 2018
+
# Overview
This document describes how to add a native call to a monolithic application running on a mono-sandbox platform.

# 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 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 the 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 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)



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

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 the 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/Core` folder
            2. Select **Add Existing Files to Group 'MicroEJ/Core'**
                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), 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 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)
        - 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.
-->

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:
10 August 2018
+
# Overview
This document describes how to add a security manager to a multi-sandboxed platform.
The security manager will provide access to a kernel LED native function to one feature and forbid the access to a second feature.

1. Check the permission before the native call.
2. Add security manager to the kernel.



# 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 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 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 a [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 not checking permissions in Kernel mode and delegating 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()){
        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 {
        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 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 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.
-->

How-to use the Storage Library

This library contains simple examples to understand how to use the main Storage library APIs.
HOWTO for FILEDATA
Supported MicroEJ Version: 4.1
Supported MicroEJ Edition: Studio
Last updated:
15 March 2018
+
<!--
	Markdown
	Copyright 2016 IS2T. All rights reserved.
	Use of this source code is governed by a BSD-style license that can be found at http://www.is2t.com/open-source-bsd-license/.
-->

# Overview
MicroEJ multisandbox firmware demos disable access to the file system in the application context. To store/retrieve information you should use a service provided by the firmware.
This service is called <code>Storage</code> and like any other services it can be retrieved by using the default `ServiceLoader` (if you want more information about Service, please read the firmware documentation).
> `Storage storage = ServiceLoaderFactory.getServiceLoader().getService(Storage.class);`

This service is based on key/value principle. The value is Java's `InputStream` and the keys are Java's `String` (with some restrictions on the allowed characters, see the javadoc). 

# Usage
## Store data
The `store` method needs an input stream and a key. During the method execution the given input stream is entirely read, closed and stored in the underlying file system (can be volatile or not depend on your firmware).

```java
String key = "MY_DATA"; //$NON-NLS-1$
try (ByteArrayInputStream bais = new ByteArrayInputStream("mydata".getBytes())) { //$NON-NLS-1$
   storage.store(key, bais);
} catch (IOException e) {
   e.printStackTrace();
}
```

## Retrieve data
Call the `load` method with the same key used to store the data, to retrieve it.

```java
try (InputStream stream = storage.load(key)) {
    // Do something with the input stream.
} catch (IOException e) {
    e.printStackTrace();
}
```

The application must close the input stream when it is no longer needed.

## List all stored data
An application can list all stored data by calling the <code>getIds</code> method. This method returns all data key's already stored.
```java		
try {
    for (String k : storage.getIds()) {
        System.out.println("Data available " + k);
    }
} catch (IOException e) {
    e.printStackTrace();
}
```

## Delete data
Call the `remove` method with the data key's to remove it.

```java
try {
    storage.remove(key);
} catch (IOException e) {
    e.printStackTrace();
}
```

## Run on MicroEJ Simulator
1. Right Click on the project
2. Select **Run as -> MicroEJ Application**
3. Select your virtual device. 
4. Press **Ok**

## Run on device
### Build
1. Right Click on the example
2. Select **Run as -> Run Configuration** 
3. Select **MicroEJ Application** configuration
4. Click on **New launch configuration** icon
5. In **Execution** tab
	1. In **Target** frame, in **Platform** field, select the relevant virtual device.
	2. In **Execution** frame
		1. Select **Execute on Device**
		2. In **Settings** field, select **Local Deployment(...)**
6. In **Configurations** tab, set the options of the deployment
7. Press **Apply**
8. Press **Run**
	
# Requirements
* MicroEJ Studio or SDK 4.1 or later
* A virtual device

# Dependencies
_All dependencies are retrieved transitively by Ivy resolver_.

# Source
N/A

# Restrictions
None.

How-to use Proguard in MicroEJ

This document explains how to use Proguard (Java obfuscation and optimization) in your application.
HOWTO for MISC
Supported MicroEJ Version: 4.1
Supported MicroEJ Edition: Studio & SDK
Last updated:
15 March 2018
+
# Overview
This document explains how to use <a href="https://www.guardsquare.com/en/proguard">Proguard</a> in your application.
ProGuard is an open source command-line tool that shrinks, optimizes and obfuscates Java code. It is able to optimize bytecode as well as detect and remove unused instructions. For example, Proguard can be used to remove all log message in binary production.
This project is based on Proguard version 5.1.

# Requirements
* MicroEJ Studio or SDK 4.1.1 or later

# Usage
## ADD THE DEPENDENCIES
1. Open the `module.ivy`.
2. Copy the following code inside `<ea:build organisation=...></ea:build>` :
```
<ea:plugin organisation="com.is2t.easyant.plugins" module="obf-proguard" revision="+"/>
```

## ADD PROGUARD RULES
1.  **File** → **New** → **File**
    * File name : **module.pro** → you must create a file with this name.
2. Copy the following code inside this file
```
    -assumenosideeffects class java.util.logging.Logger {
    public static java.util.logging.Logger getLogger(...);   
    public static Logger getLogger(...);
    public void log(...);
    public void severe(...);
    public void config(...);
    public void fine(...);
    public void finer(...);
    public void finest(...);
    public void info(...);
    public void warning(...);
    }
```
An example file is available @[module.pro](module.pro).

## BUILD EASYANT
1. Click on **Build selected EasyAnt projects**.
2. Verify **Proguard** is called during the build. Open **EasyAnt Console** and search for the following lines :  
```
obf-proguard:obfuscate:
     [move] Moving 1 file to C:\Users\mmartins\Documents\Work\SupportWorkspace\a\target~\build-env
     [copy] Copying 1 file to C:\Users\mmartins\Documents\Work\SupportWorkspace\a\target~\proguard
[proguard] ProGuard, version 5.1
 ```

## CHECKING
Bytecode is compared. You can find the **.jar** of your application in the folder **target~/artifacts**.

**Example Java**
```
public Main() {
    System.out.println("1");
	LOGGER.severe("severe call");
	System.out.println("2");
	LOGGER.config("config call");
	System.out.println("3");
}
```

**Bytecode generated**
* We can see than **severe(...) and config(...)** methods are called (L.25 & L.42).
```
14  ldc <String "1"> [1]
16  invokevirtual java.io.PrintStream.println(java.lang.String) : void [17]
19  aload_1
20  getfield com.mycompany.aA.a : java.util.logging.Logger [15]
23  ldc <String "severe call"> [6]
25  invokevirtual java.util.logging.Logger.severe(java.lang.String): void [23]
28  getstatic java.lang.System.out : java.io.PrintStream [16]
31  ldc <String "2"> [2]
33  invokevirtual java.io.PrintStream.println(java.lang.String) : void [17]
36  aload_1
37  getfield com.mycompany.aA.a : java.util.logging.Logger [15]
40  ldc <String "config cal"> [7]
42  invokevirtual java.util.logging.Logger.config(java.lang.String) : void [23]
45  getstatic java.lang.System.out : java.io.PrintStream [16]
48  ldc <String "3"> [3]
```
**Proguard**
* After Proguard processing, we can see than **severe(...) and config(...)** are removed.
```
5  ldc <String "1"> [1]
7  invokevirtual java.io.PrintStream.println(java.lang.String) : void [13]
10  getstatic java.lang.System.out : java.io.PrintStream [12]
13  ldc <String "2"> [2]
15  invokevirtual java.io.PrintStream.println(java.lang.String) : void [13]
18  getstatic java.lang.System.out : java.io.PrintStream [12]
21  ldc <String "3"> [3]
23  invokevirtual java.io.PrintStream.println(java.lang.String) : void [13]
```

* Java code
```
public Main() {
    System.out.println("1");
	System.out.println("2");
	System.out.println("3");
}

How-to create a Foundation Library in MicroEJ

This example describes how to setup a new Foundation Library in MicroEJ SDK.
HOWTO for MISC
Supported MicroEJ Version: 4.1
Supported MicroEJ Edition: Studio & SDK
Last updated:
15 March 2018
+
<!--
	Markdown
	Copyright 2018 IS2T. All rights reserved.
	Use of this source code is governed by a BSD-style license that can be found at http://www.microej.com/open-source-bsd-license/.
-->

# How to Setup a new Foundation Library

This example describes how to setup a new Foundation Library in MicroEJ SDK.

A Foundation Library is a library that provides core runtime APIs or hardware-dependent functionality. It is often connected to underlying C low-level APIs.

## Prerequisites

1. MicroEJ SDK 4.1.4 installed.
2. A MicroEJ 4.1 Platform Reference Implementation imported into the MicroEJ repository. See https://developer.microej.com/getting-started-sdk.html.
3. An activated Evaluation or Production license.
4. Basic knowledge about Java and C programming.
5. Basic knowledge about MicroEJ (Platform build and Standalone Application launch).

## Overview

A Foundation Library is composed of
* A MicroEJ API project: contains API skeletons for compilation purpose.
* A MicroEJ Implementation project: contains the runtime code executed by the Platform and Low Level C header files.
* C code: contains the implementation of native methods linked to the C project.
* Java Mock-up project: contains the implementation of native methods for simulation.

![LLAPI](overview.png)

## Create the Foundation Library API

### Define the API Project

* Select **File > New > Other > EasyAnt > EasyAnt Project**
	* Set the project settings.
		* Project Name: mylib-api
		* Organization: com.mycompany.api
		* Module: mylib
		* Revision: 1.0.0
	* Select **com.is2t.easyant.skeletons#microej-javaapi;+** skeleton.
	* Click on **Finish**.

* Select **File > New > Class**
	* Source folder: **mylib-api/src/main/java**.
	* Package: **com.mycompany**.
	* Name: **MyLib**.

* Copy and paste the following code into this class:

```
package com.mycompany;

/**
 * My Foundation Library.
 */
public class MyLib {
	/**
	 * Computes the factorial of an integer.
	 *
	 * @param number
	 *            a positive integer
	 *
	 * @return the factorial of number.
	 */
	public static int factorial(int number) {
		throw new RuntimeException();
	}
}

```

This class defines a _factorial_ API. The method content is filled with **throw a new RuntimeException** just for successful compilation.

### Build the API Project

Right-click on **mylib-api** project and select **Build With EasyAnt**. 
After a successful build, the project build directory **target~/artifacts** contains:

* **Jar** file (mylib.jar), that will be used by an Application.
* **Rip** file (mylib.rip), that will be embedded into a Platform.

### Add the API to the Platform

* Unzip **mylib.rip** and copy all the files of the **content** directory into the **dropins** directory of the __[platform]-configuration__ project.
* Rebuild the Platform.

The API documentation is available in the MicroEJ Resource Center View (**Help > MicroEJ Resource Center > Javadoc**).

## Create the Foundation Library Implementation

### Define the Implementation Project

* Select **File > New > Other > EasyAnt > EasyAnt Project**
	* Set the project settings. 
		* Project Name: mylib-impl
		* Organization: com.mycompany.impl
		* Module: mylib
		* Revision: 1.0.0
	* Select **com.is2t.easyant.skeletons#microej-javaimpl;+** skeleton.
	* Click on **Finish**.

* Select **File > New > Class** .
	* Source folder: **mylib-impl/src/main/java**.
	* Package: **com.mycompany**
	* Name : **MyLib**

* Copy and paste the following code into this class:

```
package com.mycompany;

@SuppressWarnings({ "javadoc", "nls" })
public class MyLib {

	public static int factorial(int number) {
		if (number < 0) {
			throw new IllegalArgumentException("Factorial cannot be negative");
		}
		return factorial0(number);
	}

	public native static int factorial0(int number);
}
	
```

This class defines the _factorial_ implementation. It first checks the argument validity and then redirects to a native method for speed consideration.

### Write the C Header File

* Create a new file named **include/LLMYLIB_impl.h** into the **content** directory of the implementation project.
* Copy and paste the following code into this file:

```
#ifndef LLMYLIB_IMPL
#define LLMYLIB_IMPL

/**
 * @file
 * @brief MicroEJ factorial Low Level API
 * @author My Company
 * @version 1.0.0
 */

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#define LLMYLIB_IMPL_factorial Java_com_mycompany_MyLib_factorial0

/*
 * Returns the factorial
 */
uint32_t LLMYLIB_IMPL_factorial(uint32_t number);

#ifdef __cplusplus
}
#endif
#endif

```

This file defines the _factorial_ C prototype. The **com_mycompany_MyLib** part is the fully qualified name of the **MyLib** class created previously where all **.** are replaced by **_**.

The _#define_ statement allows to separate the Java part and the C part. 
This is called the Low Level API of the Foundation Library.
If the fully qualified name of the Java native method is updated, the C implementation code do not need to be updated.



### Build the Implementation Project

Right-click on **mylib-impl** project and select **Build With EasyAnt**.
After a successful build, the project build directory **target~/artifacts** contains:

* **Rip** file (mylib.rip), that will be embedded into a Platform.

### Add the Implementation to the Platform 

* Unzip **mylib.rip** and copy all the files of the **content** directory into the **dropins** directory of the __[platform]-configuration__ project.
* Rebuild the Platform.

## Test the Foundation Library from an Example

### Define the Application Project

* Create a new project **File > New > MicroEJ Standalone Application Project**
	* Project Name: **mylib-test**
	* Check **MYLIB-1.0** in the section **Runtime Environment > Select MicroEJ libraries**

* Select **File > New > Class**
	* Source folder: **mylib-test/src**.
	* Package: **com.mycompany**
	* Class Name: **TestMyLib**
	
* Copy and paste the following code into this class:

```
package com.mycompany;

public class TestMyLib {
	public static void main(String[] args) {
		System.out.println("(5!)=" + MyLib.factorial(5));
	}
}

```

This class defined a main entry point that prints the result of _5!_.

### Launch the Application on Simulator

* Right-click on **mylib-test** project and select **Run As > MicroEJ Application**. 

The application is started. After a few seconds, the following trace shall appear in the console view:

```
	Exception in thread "main" java.lang.UnsatisfiedLinkError: No HIL client implementor found (timeout)
        at java.lang.Throwable.fillInStackTrace(Throwable.java:79)
        at java.lang.Throwable.<init>(Throwable.java:30)
        at java.lang.Error.<init>(Error.java:10)
        at java.lang.LinkageError.<init>(LinkageError.java:10)
        at java.lang.UnsatisfiedLinkError.<init>(UnsatisfiedLinkError.java:10)
        at com.mycompany.MyLib.factorial(MyLib.java:15)
        at com.mycompany.TestMyLib.main(TestMyLib.java:5)
        at java.lang.MainThread.run(Thread.java:836)
        at java.lang.Thread.runWrapper(Thread.java:372)

```

This is the normal behavior because **factorial0** native method is currently not implemented (see below). 
The HIL engine (Hardware In the Loop) did not find a Platform Mock-up implementing the native method.

## Create the Foundation Library Mock-up

### Define the Mock-up Project

To each MicroEJ native method is associated a Java Mock-up method that implements the simulated behavior. 
A Mock-up project is a standard Java project (J2SE).

* Select **File > New > Other > EasyAnt > EasyAnt Project**
	* Set the project settings. 
		* Project Name: mylib-mock
		* Organization: com.mycompany.mock
		* Module: mylib
		* Revision: 1.0.0
	* Select **com.is2t.easyant.skeletons#microej-mock;+** skeleton.
	* Click on **Finish**.

* Select **File > New > Class**
	* Source folder: **mylib-mock/src/main/java**.
	* Package: **com.mycompany**
	* Class Name: **MyLib**
* Copy and paste the following code into this class:

```
package com.mycompany;

public class MyLib {

	public static int factorial0(int number) {
		if (number == 0) {
			return 1;
		}
		int fact = 1; // this will be the result
		for (int i = 1; i <= number; i++) {
			fact *= i;
		}
		return fact;
	}
}

```
This class defines the implementation _factorial0_ method on Simulator. 
The Mock-up method has the same prototype than the implementation one, except the **native** modifier. 
The HIL engine will link the native method to the Mock-up method.

### Build the Mock-up Project

* Right-click on the **mylib-mock** project and select **Build With EasyAnt**.

After a successful build, the project build directory **target~/artifacts** contains:

* **Rip** file (mylib.rip), that will be embedded into a Platform.

### Add the Mock-up to the Platform 

* Unzip **mylib.rip** and copy all the files of the **content** directory into the **dropins** directory of the __[platform]-configuration__ project.
* Rebuild the Platform.

### Launch the Application on Simulator

* Right-click on **mylib-test** project and select **Run As > MicroEJ Application**. 

The following trace shall appear in the console view:
 
```
		=============== [ Initialization Stage ] ===============
		=============== [ Launching on Simulator ] ===============
		(5!)=120
		=============== [ Completed Successfully ] ===============

```

## Implement Low Level API on Device

### Launch the Application on Device

* Duplicate the Simulation launcher
	* Go to **Run > Run Configuration...**
	* Select **mylib-test TestMyLib** launcher
	* Right-Click and select **Duplicate**
	* In **Execution** tab, select  **Execute on Device"**
* Click on **Run**

The file *microejapp.o* is generated to a well known location for the C project.

### Build the C Project

* Open the Platform C project into the C IDE 
* Compile and link the project

Please consult the documentation of the imported Platform for more details on the proceedings.
 
A similar linker error than the one below should appear in the C IDE console view:

```
Undefined symbol Java_com_mycompany_MyLib_factorial0 (referred from microejapp.o).
```

This is the normal behavior because the symbol **Java_com_mycompany_MyLib_factorial0** is currently not implemented in C code. 
The third-party linker did not find an object file implementing the native function.

### Write the C Implementation File

* In the C project, create a new File called **LLMYLIB_impl.c**
* Add the C file to the compilation objects by adding it to the C Project configuration
* Copy and paste the following code to the file:

```
#include "LLMYLIB_impl.h"
#include "sni.h"

/**
 * @file
 * @brief MicroEJ factorial low level API (the implementation does not support unsigned integer overflow)
 * @author My Company
 * @version 1.0.0
 */
uint32_t LLMYLIB_IMPL_factorial(uint32_t number)
{
	if (number == 0) {
		return 1;
	}
	uint32_t fact = 1; // this will be the result
	for (uint32_t i = 1; i <= number; i++) {
		fact *= i;
	}
	return fact;
}

```
This file defines a basic C implementation of the _factorial0_ function.

### Test the C Project

* Link the C Project. 
 
The link shall produce the executable file.

* Program the executable file on the device.
 
The following trace shall appear on the standard output:

```
VM START
(5!)=120
VM END (exit code = 0)
```

# Advanced Configuration

Configure MicroEJ SDK for using Implementation project sources before the Platform Implementation:

* Select **Window > Preferences > MicroEJ > Settings**
* Check **Resolve Foundation Library in workspace**

This avoids to rebuild the Foundation Library implementation and the Platform each time the implementation code changes.
	
# Further Reading

* Communication mechanisms from Java to C: [Example-Standalone-Java-C-Interface](https://github.com/MicroEJ/Example-Standalone-Java-C-Interface)
* Simulation mock specification: Section 20.3 of the Device Developer's Guide

Convert a Standalone App into a Sandboxed App

This document explains how to convert a standalone app into a sandboxed app.
HOWTO for STORE
Supported MicroEJ Version: 4.1
Supported MicroEJ Edition: Studio
Last updated:
29 August 2017
+
# Overview
This document explains how to convert a standalone app into a sandboxed app.

# Usage
## CREATE THE APPLICATION
1. Use the wizard to create a new sandboxed app
	1. **File** → **New** → **MicroEJ Sandboxed Application Project**
	
## ADD THE DEPENDENCIES
1. Open the `module.ivy` file from the **standalone project**
2. Copy all the dependencies located in `<dependencies></dependencies>`
3. Open the `module.ivy` file from the **sandboxed project**
4. Paste the copied dependencies into `<dependencies></dependencies>`

## COPY THE SOURCES AND RESOURCES
1. From the **standalone project**, copy the content of `src/main/java`
2. Paste it into `src/main/java` in the **sandboxed project**.
3. From the **standalone project** copy the content of `src/main/resources`
4. Paste it into `src/main/resources` in the **sandboxed project**.

## LINK THE PROJECT TO A SANDBOXED APP ENTRY POINT
A sandboxed app needs a specific entry point which is not the main of the standalone app.

* If you have a GUI (i.e. using a GUI library such as MicroUI):
	1. Create a new class implementing `ej.wadapps.app.Activity`.
	2. On the **onStart()**, call your project's **main**.
* If you do not have any GUI:
	1. Create a new class implementing `ej.wadapps.app.BackgroundService`.
	2. On the **onStart()**, call your project's **main**.
	
## UPDATE THE META-INF
1. Move the **system.properties** except the services declarations to the **application.properties** file
	* In your code, replace the calls to `System.getProperty()` by calls to `ServiceLoaderFactory.getServiceLoader().getService(ApplicationsManager.class).getCurrentApplication().getProperty()`
2. For each local service declared
	* create a file with the fully qualified name of the service in the folder **services**
	* write one line containing the fully qualified name of the implementation class into this file
3. Update the `MANIFEST.MF` :
	* Set the **Application-Activities** to the created activities (if you have a GU).
	* Set the **Application-BackgroundServices** to the created background services (if you do not have a GUI).

## RUN ON MICROEJ SIMULATOR
1. Right Click on the project
2. Select **Run as -> MicroEJ Application**
3. Select **BackgroundServicesStandalone** or **ActivitiesStandalone**
4. Select your platform 
5. Press **Ok**

## RUN ON A DEVICE
### LOCAL DEPLOY
1. Right Click on /src/.generated~/.java/__YourProject__/generated/YourProjectEntryPoint.java
2. Select **Run as -> Run Configurations...** 
3. Select **MicroEJ Application** configuration kind
4. Click on **New launch configuration** icon
5. In **Execution** tab
	1. In **Target** frame, in **Platform** field, select a relevant platform
	2. In **Execution** frame
		1. Select **Execute on Device**
		2. In **Settings** field, select **Build & Deploy**
6. In **Configuration** tab
	1. In **Board** frame
		1. Set **Host** field to your board IP address
7. Press **Apply**
8. Press **Run**

How-to use the Widget Library

This library contains simple examples to understand how to use the main Widgets library APIs.
HOWTO for UI
Supported MicroEJ Version: 4.1
Supported MicroEJ Edition: SDK
Last updated:
29 August 2017
+
# Overview
This library contains simple examples to understand how to use the main Widgets library APIs. It is recommended to study them in the following order :

- [com.microej.howto.mwt.colors.Gradient](Widgets-Get-Started/src/main/java/com/microej/howto/mwt/colors/Gradient.java)

![Gradient](screenshots/Gradient.png)


# Usage
For each example:
## Run on MicroEJ Simulator
1. Right Click on the example to run `.java` file
2. Select **Run as -> MicroEJ Application**
3. Select your platform 
4. Press **Ok**


## Run on device
### Build
1. Right Click on the example to build `.java` file
2. Select **Run as -> Run Configuration** 
3. Select **MicroEJ Application** configuration kind
4. Click on **New launch configuration** icon
5. In **Execution** tab
	1. In **Target** frame, in **Platform** field, select a relevant platform (but not a virtual device)
	2. In **Execution** frame
		1. Select **Execute on Device**
		2. In **Settings** field, select **Build & Deploy**
6. Press **Apply**
7. Press **Run**
8. Copy the generated `.out` file path
	
# Requirements
* MicroEJ Studio or SDK 4.0 or later
* A platform with at least:
	* EDC-1.2 or later
	* BON-1.2 or later
	* MICROUI-2.0 or later
	* MWT-2.1 or later

* Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.library.ui" name="widget" rev="2.0.0-alpha.10"/>`


# Dependencies
_All dependencies are retrieved transitively by Ivy resolver_.


# Source
N/A

# Restrictions
None.

How-to use the MicroUI Library

This library contains simple examples to understand how to use the main MicroUI library APIs.
HOWTO for UI
Supported MicroEJ Version: 4.1
Supported MicroEJ Edition: SDK
Last updated:
29 August 2017
+
<!--
	Markdown
	Copyright 2016 IS2T. All rights reserved.
	Use of this source code is governed by a BSD-style license that can be found at http://www.is2t.com/open-source-bsd-license/.
-->

# Overview
This library contains simple examples to understand how to use the main MicroUI library APIs. It is recommended to study them in the following order :


- [com.microej.howto.microui.drawing.Primitives](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/drawing/Primitives.java)

![Primitives](screenshots/Primitives.png)

- [com.microej.howto.microui.drawing.PrimitivesAntiAliased](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/drawing/PrimitivesAntiAliased.java)

![PrimitivesAntiAliased](screenshots/PrimitivesAntiAliased.png)

- [com.microej.howto.microui.font.Text](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/font/Text.java)

![Text](screenshots/Text.png)

- [com.microej.howto.microui.font.PictosWithCustomFont](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/font/PictosWithCustomFont.java)

![PictosWithCustomFont](screenshots/PictosWithCustomFont.png)

- [com.microej.howto.microui.image.TransparentImages](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/TransparentImages.java)

![TransparentImages](screenshots/TransparentImages.png)

- [com.microej.howto.microui.image.FlippedImages](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/FlippedImages.java)

![FlippedImages](screenshots/FlippedImages.png)

- [com.microej.howto.microui.image.RotatedImages](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/RotatedImages.java)

![RotatedImages](screenshots/RotatedImages.png)

- [com.microej.howto.microui.image.ScaledImages](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/ScaledImages.java)

![ScaledImages](screenshots/ScaledImages.png)

- [com.microej.howto.microui.image.TilingWithImages](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/TilingWithImages.java)

![TilingWithImages](screenshots/TilingWithImages.png)

- [com.microej.howto.microui.image.DeformedImages](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/DeformedImages.java)

![DeformedImages](screenshots/DeformedImages.png)

- [com.microej.howto.microui.events.InputEvents](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/events/InputEvents.java)

![InputEvents](screenshots/InputEvents.png)

- [com.microej.howto.microui.animation.AnimationSampleWithFullRepaint](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/animation/AnimationSampleWithFullRepaint.java)

- [com.microej.howto.microui.animation.AnimationSampleWithFlyingImage](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/animation/AnimationSampleWithFlyingImage.java)


Note that the same set of resources (images and fonts) is used across all of the examples.

# Usage
For each example:
## Run on MicroEJ Simulator
1. Right Click on the example to run `.java` file
2. Select **Run as -> MicroEJ Application**
3. Select your platform 
4. Press **Ok**


## Run on device
### Build
1. Right Click on the example to build `.java` file
2. Select **Run as -> Run Configuration** 
3. Select **MicroEJ Application** configuration kind
4. Click on **New launch configuration** icon
5. In **Execution** tab
	1. In **Target** frame, in **Platform** field, select a relevant platform (but not a virtual device)
	2. In **Execution** frame
		1. Select **Execute on Device**
		2. In **Settings** field, select **Build & Deploy**
6. Press **Apply**
7. Press **Run**
8. Copy the generated `.out` file path
	
# Requirements
* MicroEJ Studio or SDK 4.0 or later
* A platform with at least:
	* EDC-1.2 or higher
	* BON-1.2 or higher
	* MICROUI-2.0 or higher

# Dependencies
_All dependencies are retrieved transitively by Ivy resolver_.

# Credits


| <p align="center">Font</p> | <p align="center">Author</p> | <p align="center">License</p> |
| --- | :---: | --- |
| Font Awesome | Dave Gandy <br/> http://fontawseome.io  | [SIL OFL 1.1 license - http://scripts.sil.org/OFL](/MicroUI-Get-Started/src/main/resources/fonts/OFL.txt)|
| Sans | Adobe |[SIL Open Font License.txt](/MicroUI-Get-Started/src/main/resources/fonts/Adobe-Source-SIL-Open-Font-License.txt)|


# Source
N/A

# Restrictions
None.

Device Developer's Guide

Learn to develop your first platform.
GUIDE for MISC
Supported MicroEJ Version: 4.1
Supported MicroEJ Edition: SDK
Last updated:
22 August 2017

MicroEJ SDK Errata

The Errata of MicroEJ SDK versions.
GUIDE for MISC
Supported MicroEJ Version: 4.1
Supported MicroEJ Edition: SDK
Last updated:
6 July 2017

Application Developer's Guide (Sandboxed)

Learn to develop your first sandboxed apps.
GUIDE for MISC
Supported MicroEJ Version: 4.1
Supported MicroEJ Edition: Studio
Last updated:
6 July 2017

Application Developer's Guide (Standalone)

Learn to develop your first standalone apps.
GUIDE for MISC
Supported MicroEJ Version: 4.1
Supported MicroEJ Edition: SDK
Last updated:
6 July 2017

MicroEJ SDK Errata

The Errata of MicroEJ SDK versions.
GUIDE for MISC
Supported MicroEJ Version: 3.1,4.0
Supported MicroEJ Edition: SDK
Last updated:
1 February 2017

How-to use the MicroUI Library

This library contains simple examples to understand how to use the main MicroUI library APIs.
HOWTO for UI
Supported MicroEJ Version: 4.0
Supported MicroEJ Edition: Studio & SDK
Last updated:
7 October 2016
+
<!--
	Markdown
	Copyright 2016 IS2T. All rights reserved.
	Use of this source code is governed by a BSD-style license that can be found at http://www.is2t.com/open-source-bsd-license/.
-->

# Overview
This library contains simple examples to understand how to use the main MicroUI library APIs. It is recommended to study them in the following order :


- [com.microej.howto.microui.drawing.Primitives](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/drawing/Primitives.java)

![Primitives](screenshots/Primitives.png)

- [com.microej.howto.microui.drawing.PrimitivesAntiAliased](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/drawing/PrimitivesAntiAliased.java)

![PrimitivesAntiAliased](screenshots/PrimitivesAntiAliased.png)

- [com.microej.howto.microui.font.Text](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/font/Text.java)

![Text](screenshots/Text.png)

- [com.microej.howto.microui.font.PictosWithCustomFont](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/font/PictosWithCustomFont.java)

![PictosWithCustomFont](screenshots/PictosWithCustomFont.png)

- [com.microej.howto.microui.image.TransparentImages](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/TransparentImages.java)

![TransparentImages](screenshots/TransparentImages.png)

- [com.microej.howto.microui.image.FlippedImages](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/FlippedImages.java)

![FlippedImages](screenshots/FlippedImages.png)

- [com.microej.howto.microui.image.RotatedImages](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/RotatedImages.java)

![RotatedImages](screenshots/RotatedImages.png)

- [com.microej.howto.microui.image.ScaledImages](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/ScaledImages.java)

![ScaledImages](screenshots/ScaledImages.png)

- [com.microej.howto.microui.image.TilingWithImages](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/TilingWithImages.java)

![TilingWithImages](screenshots/TilingWithImages.png)

- [com.microej.howto.microui.image.DeformedImages](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/DeformedImages.java)

![DeformedImages](screenshots/DeformedImages.png)

- [com.microej.howto.microui.events.InputEvents](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/events/InputEvents.java)

![InputEvents](screenshots/InputEvents.png)

- [com.microej.howto.microui.animation.AnimationSampleWithFullRepaint](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/animation/AnimationSampleWithFullRepaint.java)

- [com.microej.howto.microui.animation.AnimationSampleWithFlyingImage](/MicroUI-Get-Started/src/main/java/com/microej/howto/microui/animation/AnimationSampleWithFlyingImage.java)


Note that the same set of resources (images and fonts) is used across all of the examples.

# Usage
For each example:
## Run on MicroEJ Simulator
1. Right Click on the example to run `.java` file
2. Select **Run as -> MicroEJ Application**
3. Select your platform 
4. Press **Ok**


## Run on device
### Build
1. Right Click on the example to build `.java` file
2. Select **Run as -> Run Configuration** 
3. Select **MicroEJ Application** configuration kind
4. Click on **New launch configuration** icon
5. In **Execution** tab
	1. In **Target** frame, in **Platform** field, select a relevant platform (but not a virtual device)
	2. In **Execution** frame
		1. Select **Execute on Device**
		2. In **Settings** field, select **Build & Deploy**
6. Press **Apply**
7. Press **Run**
8. Copy the generated `.out` file path
	
# Requirements
* MicroEJ Studio or SDK 4.0 or later
* A platform with at least:
	* EDC-1.2 or higher
	* BON-1.2 or higher
	* MICROUI-2.0 or higher

# Dependencies
_All dependencies are retrieved transitively by Ivy resolver_.

# Credits


| <p align="center">Font</p> | <p align="center">Author</p> | <p align="center">License</p> |
| --- | :---: | --- |
| Font Awesome | Dave Gandy <br/> http://fontawseome.io  | [SIL OFL 1.1 license - http://scripts.sil.org/OFL](/MicroUI-Get-Started/src/main/resources/fonts/OFL.txt)|
| Sans | Adobe |[SIL Open Font License.txt](/MicroUI-Get-Started/src/main/resources/fonts/Source - SIL Open Font License.txt)|


# Source
N/A

# Restrictions
None.

How-to use the Widget Library

This library contains simple examples to understand how to use the main Widgets library APIs.
HOWTO for UI
Supported MicroEJ Version: 4.0
Supported MicroEJ Edition: Studio & SDK
Last updated:
16 September 2016
+
<!--
	Markdown
	Copyright 2015-2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview
This library contains simple examples to understand how to use the main Widgets library APIs. It is recommended to study them in the following order :

- [com.microej.howto.mwt.colors.Gradient](/Widgets-Get-Started/src/main/java/com/microej/howto/mwt/colors/Gradient.java)

![Gradient](screenshots/Gradient.png)


# Usage
For each example:
## Run on MicroEJ Simulator
1. Right Click on the example to run `.java` file
2. Select **Run as -> MicroEJ Application**
3. Select your platform 
4. Press **Ok**


## Run on device
### Build
1. Right Click on the example to build `.java` file
2. Select **Run as -> Run Configuration** 
3. Select **MicroEJ Application** configuration kind
4. Click on **New launch configuration** icon
5. In **Execution** tab
	1. In **Target** frame, in **Platform** field, select a relevant platform (but not a virtual device)
	2. In **Execution** frame
		1. Select **Execute on Device**
		2. In **Settings** field, select **Build & Deploy**
6. Press **Apply**
7. Press **Run**
8. Copy the generated `.out` file path
	
# Requirements
* MicroEJ Studio or SDK 4.0 or later
* A platform with at least:
	* EDC-1.2 or later
	* BON-1.2 or later
	* MICROUI-2.0 or later
	* MWT-2.1 or later

* Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.library.ui" name="widget" rev="2.0.0-alpha.10"/>`


# Dependencies
_All dependencies are retrieved transitively by Ivy resolver_.


# Source
N/A

# Restrictions
None.

Application Developer's Guide (Sandboxed)

Learn to develop your first sandboxed apps.
GUIDE for MISC
Supported MicroEJ Version: 4.0
Supported MicroEJ Edition: Studio
Last updated:
26 July 2016

Application Developer's Guide (Standalone)

Learn to develop your first standalone apps.
GUIDE for MISC
Supported MicroEJ Version: 4.0
Supported MicroEJ Edition: SDK
Last updated:
26 July 2016

Convert a Standalone App into a Sandboxed App

This document explains how to convert a standalone app into a sandboxed app.
HOWTO for STORE
Supported MicroEJ Version: 4.0
Supported MicroEJ Edition: Studio
Last updated:
1 July 2016
+
# Overview
This document explains how to convert a standalone app into a sandboxed app.

# Usage
## CREATE THE APPLICATION
1. Use the wizard to create a new sandboxed app
	1. **File** → **New** → **MicroEJ Sandboxed Application Project**
	
## ADD THE DEPENDENCIES
1. Open the `module.ivy` file from the **standalone project**
2. Copy all the dependencies located in `<dependencies></dependencies>`
3. Open the `module.ivy` file from the **sandboxed project**
4. Paste the copied dependencies into `<dependencies></dependencies>`

## COPY THE SOURCES AND RESOURCES
1. From the **standalone project**, copy the content of `src/main/java`
2. Paste it into `src/main/java` in the **sandboxed project**.
3. From the **standalone project** copy the content of `src/main/resources`
4. Paste it into `src/main/resources` in the **sandboxed project**.

## LINK THE PROJECT TO A SANDBOXED APP ENTRY POINT
A sandboxed app needs a specific entry point which is not the main of the standalone app.

* If you have a GUI (i.e. using a GUI library such as MicroUI):
	1. Create a new class implementing `ej.wadapps.app.Activity`.
	2. On the **onStart()**, call your project's **main**.
* If you do not have any GUI:
	1. Create a new class implementing `ej.wadapps.app.BackgroundService`.
	2. On the **onStart()**, call your project's **main**.
	
## UPDATE THE META-INF
1. Move the **system.properties** except the services declarations to the **application.properties** file
	* In your code, replace the calls to `System.getProperty()` by calls to `ServiceLoaderFactory.getServiceLoader().getService(ApplicationsManager.class).getCurrentApplication().getProperty()`
2. For each local service declared
	* create a file with the fully qualified name of the service in the folder **services**
	* write one line containing the fully qualified name of the implementation class into this file
3. Update the `MANIFEST.MF` :
	* Set the **Application-Activities** to the created activities (if you have a GU).
	* Set the **Application-BackgroundServices** to the created background services (if you do not have a GUI).

## RUN ON MICROEJ SIMULATOR
1. Right Click on the project
2. Select **Run as -> MicroEJ Application**
3. Select **BackgroundServicesStandalone** or **ActivitiesStandalone**
4. Select your platform 
5. Press **Ok**

## RUN ON A DEVICE
### LOCAL DEPLOY
1. Right Click on /src/.generated~/.java/__YourProject__/generated/YourProjectEntryPoint.java
2. Select **Run as -> Run Configurations...** 
3. Select **MicroEJ Application** configuration kind
4. Click on **New launch configuration** icon
5. In **Execution** tab
	1. In **Target** frame, in **Platform** field, select a relevant platform
	2. In **Execution** frame
		1. Select **Execute on Device**
		2. In **Settings** field, select **Build & Deploy**
6. In **Configuration** tab
	1. In **Board** frame
		1. Set **Host** field to your board IP address
7. Press **Apply**
8. Press **Run**


# Changes
- See the change log file [CHANGELOG.md](StandaloneToSandboxed/CHANGELOG.md).

# License
- See the license file [LICENSE.md](LICENSE.md) located at the root of this repository.

Device Developer's Guide

Learn to develop your first platform.
GUIDE for MISC
Supported MicroEJ Version: 4.0
Supported MicroEJ Edition: SDK
Last updated:
30 June 2016

Product Overview

Discover the MicroEJ Product Line.
GUIDE for MISC
Supported MicroEJ Version: 4.0
Supported MicroEJ Edition: Studio & SDK
Last updated:
30 June 2016