MicroEJ Developer
Get Started



Demo Widget

This demo illustrates the Widget library based on MicroUI 3 and MWT 3.
EXAMPLE for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
21 October 2020
+
# Overview

This repository provides a demo illustrating the widgets and containers
available in the widget library: `ej.library.ui#widget-3.0.0`.

---  
_Copyright 2020 MicroEJ Corp. All rights reserved._  
_Use of this source code is governed by a BSD-style license that can be found with this software._  

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: 5.x
Supported MicroEJ Edition: SDK
Last updated:
21 October 2020
+
.. Copyright 2016-2020 MicroEJ Corp. All rights reserved.
.. Use of this source code is governed by a BSD-style license that can be found with this software.

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.

Requirements
============

These examples have been tested on :

- MicroEJ SDK 5.1
- BSP specific toolchain (Keil MicroVision (™) v5)
- With a ST STM32F746G-DISCO board platform that contains :

  - EDC-1.2

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
- `CallingCFromJavaMock <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 STM32F746G-DISCO platform from `MicroEJ SDK Getting Started <http://developer.microej.com/getting-started-sdk-stm-5.html>`__ web page.

Creation
--------

-  Select **File > New > Other… > MicroEJ > Platform** menu item

   -  Click **Browse** button next to the **Architecture** field and select
      **ARM Cortex-M7 ARMCC**
   -  Check the **Create from a platform reference implementation** option

      -  Select **STM32F746G-Disco > MultiApp FreeRTOS**

   -  Click **Next**

      -  Set the name field to “**JavaCInterface**”
      -  Set the version field to “**1.0.0**”

   -  Click **Finish**. This will lead to the generation of a few projects in
      our workspace :

      -  `STM32F746GDISCO-JavaCInterface-CM7hardfp_ARMCC5-bsp
         <STM32F746GDISCO-JavaCInterface-CM7hardfp_ARMCC5-bsp>`__
      -  `STM32F746GDISCO-JavaCInterface-CM7hardfp_ARMCC5-configuration
         <STM32F746GDISCO-JavaCInterface-CM7hardfp_ARMCC5-configuration>`__
      -  `STM32F746GDISCO-JavaCInterface-CM7hardfp_ARMCC5-fp
         <STM32F746GDISCO-JavaCInterface-CM7hardfp_ARMCC5-fp>`__

Build
-----

-  From the **Overview** tab of the generated `STM32F746GDISCO.platform
   <STM32F746GDISCO-JavaCInterface-CM7hardfp_ARMCC5-configuration/STM32F746GDISCO.platform>`__
   file

   -  Click on the **Build platform** hyperlink. This will generate the
      following project :

      -  `STM32F746GDISCO-JavaCInterface-CM7hardfp_ARMCC5-1.0.0
         <STM32F746GDISCO-JavaCInterface-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 <http://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 <http://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 <http://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**

STM32F7508-DK Platform (MonoSandbox, GCC, FreeRTOS)

The MonoSandbox Platform for the STM32F7508-DK board.
JPF_ST for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Technical Ref.: PRI-EVAL-STM32F7506-DK-MoGF-M5QNX
Last updated:
16 October 2020
+
<!--
	Copyright 2020 IS2T. All rights reserved.
	For demonstration purpose only
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Build MicroEJ Platform Reference Implementation for STM32F7508-DK

## Introduction

This document describes how to build the MicroEJ Platform Reference Implementation for STM32F7508-DK and how to launch a MicroEJ application on this platform.
	
## Prerequisites

 * Java7 or higher
 * MicroEJ SDK 4.1 or later
 * GCC STM32Cube 1.3.0
 
## Projects Description

This platform source files are split into multiple projects:
	
`stm32f7508-[name]-CM7hardfp_GCC48-configuration` :
> Contains the platform reference implementation configuration description. Some modules are described in a specific sub-folder /<module> with some optional configuration files (<module>.properties and / or <module>.xml).
	
`stm32f7508-[name]-CM7hardfp_GCC48-bsp` :
> Contains a ready-to-use BSP software project for the STM32F7508-DK board, including a GCC STM32Cube project, an implementation of MicroEJ core engine (and extensions) port on FreeRTOS OS and the STM32F7508-DK board support package.
		
`stm32f7508-[name]-CM7hardfp_GCC48-[version]` :
> This project is created once the platform is built. It contains the platform for STM32F7508-DK board, ready to be linked into the GCC STM32Cube project.
		
`stm32f7508-[name]-CM7hardfp_GCC48-fp` :
> This front panel project is updated once the platform is built. It contains the board description and images for the MicroEJ simulator.
				
## Platform Reference Implementation Build

First step is to build a platform reference implementation for the STM32F7508-DK board from platform architecture ARM Cortex-M7. 
		
Build may be less or more complex, depending on the set	of foundation libraries that will be provided by the platform. Typical build steps are:
 * platform instantiation,
 * modules selection (native stacks, MicroEJ foundation libraries etc.),
 * GCC STM32Cube project generation. 
		
Procedure:
 * Open the file `stm32f7508-[name]-CM7hardfp_GCC48-configuration/stm32f7508.platform`. 
 * Launch the platform build clicking on the link `Build Platform` in the `Overview > Build` section.
 * Once the platform is built, the `stm32f7508-[name]-CM7hardfp_GCC48-[version]` project is created in the workspace.
		
## MicroEJ Application Build 
	
Second step is to write and generate a MicroEJ application on top of the newly created platform. This platform has built-in MicroEJ examples. Some additional MicroEJ examples are available on <http://developer.microej.com>
		
Procedure:
 * Click on `File > New > MicroEJ Standalone Example Project`
 * Select `stm32f7508-[name]-CM7hardfp_GCC48` platform
 * Select one of the available example
 * Click on `Next`
 * Click on `Finish`
 * In the Package Explorer, right-click on `[example]` project
 * Select `Run As > MicroEJ Application` to run the application on the MicroEJ simulator
 * Click on menu `Run > Run Configurations...`
 * The launcher is automatically selected on left menu, if not, select it
 * Open `Execution` tab
 * Select `Execute on Device`
 * Click on `Run`
 * Once MicroEJ launch is executed, the generated object file is available in `[workspace]/.microej/CM7hardfp_GCC48/application/microejapp.o`.
		
## Final Application build
	
Last step is to open the STM32F7508-DK board support project for GCC STM32Cube, compile it and link it with the MicroEJ application, and program the final application binary on the board.

Procedure:
 * In GCC STM32Cube, import the `stm32f7508-[name]-CM7hardfp_GCC48-bsp/.project` and it will import automatically the `stm32f7508-[name]-CM7hardfp_GCC48-bsp/projects/microej/SW4STM32/.project`
 * In GCC STM32Cube, press `Build`. The C application is compiled and linked with platform libraries and MicroEJ application.
 * In GCC STM32Cube, run `boot_release` to download the binary corresponding to internal Flash, then run `app_release` to download the binary corresponding to exrernal Flash.
 * Once application is loaded, it starts. MicroEJ application `System.out` print stream is redirected to C `printf`, which is connected to CN14 USB connector (baudrate=115200,stopbits=1,parity=none,databits=8)

Dependency Discoverer

Tool to list the binary dependencies (class, interfaces, methods, fields) of a piece of code.
TOOL for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
9 October 2020
+
..
	Copyright 2016-2020 MicroEJ Corp. All rights reserved.
	This library is provided in source code for use, modification and test, subject to license terms.
	Any modification of the source code will break MicroEJ Corp. warranties on the whole library.
	
Overview
========

This project is a tool that lists, for a given Java code, all the
dependencies that are not available in MicroEJ libraries.

Usage
=====

Online
------

#. In your MicroEJ or Eclipse workspace, import this project and drop
   all your JARs into `classpath <classpath/>`__ folder.
#. Right click on **DependencyDiscoverer** project.
#. Select **Run As -> Java Application**.
#. Double click on **DependencyDiscoverer**.
#. A **result.txt** file will be generated at the root of the project.

Offline
-------

#. In your MicroEJ or Eclipse workspace, import this project and drop
   all your JARs into `classpath <classpath/>`__ folder.
#. Get a MicroEJ offline repository (zip archive). For example
   repository from
   `repository.microej.com <https://repository.microej.com/>`__.
#. Unzip MicroEJ repository into
   `againstClasspath <againstClasspath/>`__ folder.
#. Set ``OFFLINE`` field in
   `DependencyDiscovererOptions.java <src/com/microej/tool/dependencydiscoverer/DependencyDiscovererOptions.java>`__
   to ``true``.
#. Right click on **DependencyDiscoverer** project.
#. Select **Run As -> Java Application**.
#. Double click on **DependencyDiscoverer**.
#. The **result.txt** file is available 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 libraries!

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

Requirements
============

-  MicroEJ Studio 5.0 or later, or MicroEJ SDK 5.0 or later, or Eclipse
   4.7 or later.
-  A JRE 7 or higher.

Dependencies
============

None.

Source
======

N/A

Restrictions
============

None.

Protocol Buffers (protobuf)

This library contains the lite part of Google Protocol Buffer library for java.
LIBRARY for IOT
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains the lite part of Google Protocol Buffer library for java.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="com.google" name="protobuf" rev="2.6.0"/>

And add the following option into your *.proto files :
> option optimize_for = LITE_RUNTIME;

# Requirements

This library requires the following Foundation Libraries:

    BON-1.2, EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

This project was created with all the sources from protobuf-2.5.0.
We removed classes so as to only have the classes necessary for the lite version.
A few minors changes were made in the remaining classes to make it compile.
src contains these classes and the missing classes in EDC / Eclasspath

Differences between original sources and theses source of Protocol Buffer:
- ByteString.toString() has been modified to avoid String.format() (twice)
- GeneratedMessageLite.readResolve() has been commented out to avoid reflection on methods

# Restrictions

None

---  
_Copyright 2016-2019 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._

B-ON (Foundation Library API)

B-ON API define embedded nature of objects (immutable, immortal, regular), along with the deterministic boot sequence of any MicroEJ application.
LIBRARY for CORE
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains classes and interfaces stubs of B-ON API (ESR001).

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.api" name="bon" rev="1.4.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.3

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

N/A.

# Restrictions

None.
  
---
_2011-2019 ESR - Not subject to Copyright._  
_This document has been released and published by E-S-R consortium, a non-profit entity._  
_ _  
_To learn more about E-S-R consortium, please visit http://www.e-s-r.net/._  
_The matter contained in this document is not subject to copyright; you are free to use it for any purpose, for more information see E-S-R consortium policies_  

Device

This library contains interfaces for getting device information.
LIBRARY for CORE
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2014-2017 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview
This library contains interfaces for getting device information.

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.api" name="device" rev="1.+"/>`

# Requirements
  - EDC-1.2 or higher
 
# Dependencies
None.

# Source
N/A

# Restrictions
None.

ECOM (Foundation Library API)

The Embedded Communication framework API.
LIBRARY for COMM
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2014-2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview
This library contains classes and interfaces stubs of Embedded Communications API (ESR008).

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.api" name="ecom" rev="1.+"/>`

# Requirements
  - EDC-1.2 or higher
 
# Dependencies
None.

# Source
N/A

# Restrictions
None.

ECOM-COMM (Foundation Library API)

The Embedded UART/Serial Communication API.
LIBRARY for COMM
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2014-2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview
This library contains classes and interfaces stubs of Embedded Communications API (ESR008).

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.api" name="ecom-comm" rev="1.+"/>`

# Requirements
  - EDC-1.2 or higher
  - ECOM-1.1 or higher
 
# Dependencies
None.

# Source
N/A

# Restrictions
None.

EDC (Foundation Library API)

The Embedded Device Core API.
LIBRARY for CORE
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains classes and interfaces stubs of Embedded Device Configuration API (ESR021).

# Usage

Add the following line to your `module.ivy`:
	
    @MMM_DEPENDENCY_DECLARATION@
	
# Requirements

None.

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

N/A.

# Restrictions

None.
  
  
---    
_Copyright 2012-2016 MicroEJ Corp. All rights reserved._  
_MicroEJ Corp. PROPRIETARY. Use is subject to license terms._  

FS (Foundation Library API)

The File System API.
LIBRARY for FILEDATA
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2014-2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview
This library contains classes and interfaces stubs of File System API (ESR025).

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.api" name="fs" rev="2.+"/>`

# Requirements
  - EDC-1.2 or higher
 
# Dependencies
None.

# Source
N/A

# Restrictions
None.

HAL (Foundation Library API)

The Hardware Abstraction Layer API.
LIBRARY for IO
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2015-2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview
This library contains classes and interfaces stubs of Hardware Abstraction Layer API (ESR028).

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.api" name="hal" rev="1.+"/>`

# Requirements
  - EDC-1.2 or higher

# Dependencies
None.

# Source
N/A

# Restrictions
None.

KF (Foundation Library API)

The Kernel & Feature API.
LIBRARY for STORE
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2012-2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview
This library contains classes and interfaces stubs of Kernel & Features API (ESR020).

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.api" name="kf" rev="1.+"/>`

# Requirements
  - EDC-1.2 or higher

# Dependencies
None.

# Source
N/A

# Restrictions
None.

MicroUI (Foundation Library API)

The MicroEJ User Interface and User eXperience API.
LIBRARY for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2015-2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview
This library contains classes and interfaces stubs of Micro User Interface API (ESR002).

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.api" name="microui" rev="2.+"/>`

# Requirements
  - EDC-1.2 or higher
  - BON-1.2 or higher

# Dependencies
None.

# Source
N/A

# Restrictions
None.

MWT

This library contains all that is necessary to create an HMI with widgets.
LIBRARY for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains all that is necessary to create an HMI with widgets.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.ui" name="mwt" rev="2.3.1"/>
	
# Requirements

This library requires the following Foundation Libraries:

    BON-1.2, EDC-1.2, MICROUI-2.0

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.


# Source

N/A

# Restrictions

None.

---  
_Copyright 2018-2019 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._  

NET (Foundation Library API)

The Network API.
LIBRARY for NETSEC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2012-2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview
This library contains classes and interfaces stubs of NET API (ESR024).

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.api" name="net" rev="1.+"/>`

# Requirements
  - EDC-1.2 or higher

# Dependencies
None.

# Source
N/A

# Restrictions
None.

SNI (Foundation Library API)

The Safe Native Interface API.
LIBRARY for CORE
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2012-2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview
This library contains classes and interfaces stubs of Simple Native Interface API (ESR012).

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.api" name="sni" rev="1.+"/>`

# Requirements
  - EDC-1.0 or higher
  - BON-1.2 or higher
 
# Dependencies
None.

# Source
N/A

# Restrictions
None.

SP (Foundation Library API)

The Shielded Plug API.
LIBRARY for CORE
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2015-2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview
This library contains classes and interfaces stubs of Shielded Plug API (ESR014).

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.api" name="sp" rev="2.+"/>`

# Requirements
  - EDC-1.2 or higher
  - BON-1.2 or higher

# Dependencies
None.

# Source
N/A

# Restrictions
None.

SSL (Foundation Library API)

The Secure Socket Layer API.
LIBRARY for NETSEC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2014-2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview
This library contains classes and interfaces stubs of SSL API (ESR029).

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.api" name="ssl" rev="2.+"/>`

# Requirements
  - EDC-1.2 or higher
  - NET-1.0 or higher

# Dependencies
None.

# Source
N/A

# Restrictions
None.

Eclasspath Bitset

java.util.BitSet implementation.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains the implementation of java.util.BitSet.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.eclasspath" name="bitset" rev="1.1.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

  - Open JDK 8u20

# Restrictions

  - Removed ByteBuffer and LongBuffer wrapping.
  - Removed serialization support.
  - Removed IntStream support.
  
---    
_Markdown_  
_Copyright 2016-2019 MicroEJ Corp. - EDC compliance and optimizations._  
_DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER._  
_ _  
_This code is free software; you can redistribute it and/or modify it_  
_under the terms of the GNU General Public License version 2 only, as_  
_published by the Free Software Foundation._  
_ _  
_This code is distributed in the hope that it will be useful, but WITHOUT_  
_ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or_  
_FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License_  
_version 2 for more details (a copy is included in the LICENSE file that_  
_accompanied this code)._  
_ _  
_You should have received a copy of the GNU General Public License version_  
_2 along with this work; if not, write to the Free Software Foundation,_  
_Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA._  
_ _  
_Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA_  
_or visit www.oracle.com if you need additional information or have any_  
_questions._  

Eclasspath ByteBuffer

ByteBuffer (and all its derived types such as CharBuffer, LongBuffer...) implementations.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains implementation of ByteBuffer and all its derived types such as CharBuffer, LongBuffer, ...

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.eclasspath" name="bytebuffer" rev="1.1.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    BON-1.2, EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

  - Open JDK 8u20

# Restrictions

  - Remove java.util.Spliterator references.
  - Remove MappedByteBuffer.
  - Remove direct allocation.
  
    
---    
_Markdown_  
_Copyright 2016-2019 MicroEJ Corp. - EDC compliance and optimizations._  
_DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER._  
_ _  
_This code is free software; you can redistribute it and/or modify it_  
_under the terms of the GNU General Public License version 2 only, as_  
_published by the Free Software Foundation._  
_ _  
_This code is distributed in the hope that it will be useful, but WITHOUT_  
_ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or_  
_FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License_  
_version 2 for more details (a copy is included in the LICENSE file that_  
_accompanied this code)._  
_ _  
_You should have received a copy of the GNU General Public License version_  
_2 along with this work; if not, write to the Free Software Foundation,_  
_Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA._  
_ _  
_Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA_  
_or visit www.oracle.com if you need additional information or have any_  
_questions._  

Eclasspath Collections

List, Set, Queue and Map abstract classes and interfaces.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains implementations of collections.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.eclasspath" name="collections" rev="1.3.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

  - Open JDK 7u65

# Restrictions

  - Removed Arrays.copyOf
  - Remove java.util.Spliterator references.
  - Remove serialization support.
  - Removed cloning operations and dynamically typesafe collection wrappers
  - Remove the package private constructor only used by LinkedHashSet.
  
---    
_Markdown_  
_Copyright 2014-2019 MicroEJ Corp. - EDC compliance and optimizations._  
_DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER._  
_ _  
_This code is free software; you can redistribute it and/or modify it_  
_under the terms of the GNU General Public License version 2 only, as_  
_published by the Free Software Foundation._  
_ _  
_This code is distributed in the hope that it will be useful, but WITHOUT_  
_ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or_  
_FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License_  
_version 2 for more details (a copy is included in the LICENSE file that_  
_accompanied this code)._  
_ _  
_You should have received a copy of the GNU General Public License version_  
_2 along with this work; if not, write to the Free Software Foundation,_  
_Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA._  
_ _  
_Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA_  
_or visit www.oracle.com if you need additional information or have any_  
_questions._  

Eclasspath Executor

java.util.concurrent interfaces.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains all interfaces for the implementation of the java.util.concurrent.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.eclasspath" name="executor" rev="1.1.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

  - Open JDK 7u65

# Restrictions

None.

---    
_Markdown_  
_Copyright 2014-2019 MicroEJ Corp. - EDC compliance and optimizations._  
_DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER._  
_ _  
_This code is free software; you can redistribute it and/or modify it_  
_under the terms of the GNU General Public License version 2 only, as_  
_published by the Free Software Foundation._  
_ _  
_This code is distributed in the hope that it will be useful, but WITHOUT_  
_ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or_  
_FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License_  
_version 2 for more details (a copy is included in the LICENSE file that_  
_accompanied this code)._  
_ _  
_You should have received a copy of the GNU General Public License version_  
_2 along with this work; if not, write to the Free Software Foundation,_  
_Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA._  
_ _  
_Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA_  
_or visit www.oracle.com if you need additional information or have any_  
_questions._  

Eclasspath HTTPClient

HTTP client implementation.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains the implementation of an HTTP client.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.eclasspath" name="httpclient" rev="1.3.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2, NET-1.0-API-1.0
    
# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source
  - Open JDK 8u20

# Restrictions
  - Removed java.text.DateFormat dependency APIs
  - Removed java.net.Proxy dependency and proxy tunneling connection
  - Removed traffic capture
  - Removed response caching
  - Removed authentication management
  - Removed restricted headers support
  - Removed cookie management
  - Removed keep-alive management
  - Removed cache request management
  - Removed internal MeteredStream and ProgressSource support


---  
_Markdown_
_Copyright 2015-2019 MicroEJ Corp. - EDC compliance and optimizations._
_DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER._
_ _
_This code is free software; you can redistribute it and/or modify it_
_under the terms of the GNU General Public License version 2 only, as_
_published by the Free Software Foundation._
_ _
_This code is distributed in the hope that it will be useful, but WITHOUT_
_ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or_
_FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License_
_version 2 for more details (a copy is included in the LICENSE file that_
_accompanied this code)._
_ _
_You should have received a copy of the GNU General Public License version_
_2 along with this work; if not, write to the Free Software Foundation,_
_Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA._
_ _
_Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA_
_or visit www.oracle.com if you need additional information or have any_
_questions._

Eclasspath HTTPSClient

HTTPS client implementation.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains the implementation of an HTTPS client.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.eclasspath" name="httpsclient" rev="1.2.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2, NET-1.1, SSL-2.0

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

  - Open JDK 8u20

# Restrictions

  - Removed java.net.Proxy dependency and proxy tunneling connection
  - Removed response caching
  - Removed cache request management
  - Removed certificates and keys management
  - Removed server identity checking out of SSLSocket
  - Removed javax.net.ssl.HostnameVerifier dependency
  

---  
_Markdown_
_Copyright 2015-2019 MicroEJ Corp. - EDC compliance and optimizations._
_DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER._
_ _
_This code is free software; you can redistribute it and/or modify it_
_under the terms of the GNU General Public License version 2 only, as_
_published by the Free Software Foundation._
_ _
_This code is distributed in the hope that it will be useful, but WITHOUT_
_ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or_
_FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License_
_version 2 for more details (a copy is included in the LICENSE file that_
_accompanied this code)._
_ _
_You should have received a copy of the GNU General Public License version_
_2 along with this work; if not, write to the Free Software Foundation,_
_Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA._
_ _
_Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA_
_or visit www.oracle.com if you need additional information or have any_
_questions._

Eclasspath Logging

Loggers framework and implemenation.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains an implementation of logging library.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.eclasspath" name="logging" rev="1.1.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

  - Open JDK 8u20

# Restrictions

None.


---  
_Markdown_
_Copyright 2017-2019 MicroEJ Corp. All rights reserved.._
_This library is provided in source code for use, modification and test, subject to license terms._
_Any modification of the source code will break IS2T warranties on the whole library._  

Eclasspath Properties

java.util.Properties implementation.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains the implementation of java.util.Properties.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.eclasspath" name="properties" rev="1.1.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

  - Open JDK 8u20

# Restrictions

  - Removed printf formatting.
  
  
---    
_Markdown_  
_Copyright 2015-2019 MicroEJ Corp. - EDC compliance and optimizations._  
_DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER._  
_ _  
_This code is free software; you can redistribute it and/or modify it_  
_under the terms of the GNU General Public License version 2 only, as_  
_published by the Free Software Foundation._  
_ _  
_This code is distributed in the hope that it will be useful, but WITHOUT_  
_ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or_  
_FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License_  
_version 2 for more details (a copy is included in the LICENSE file that_  
_accompanied this code)._  
_ _  
_You should have received a copy of the GNU General Public License version_  
_2 along with this work; if not, write to the Free Software Foundation,_  
_Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA._  
_ _  
_Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA_  
_or visit www.oracle.com if you need additional information or have any_  
_questions._  

Eclasspath StringTokenizer

java.util.StringTokenizer implementation.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains the implementation of java.util.StringTokenizer.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.eclasspath" name="stringtokenizer" rev="1.1.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

  - Open JDK 8u20

# Restrictions

  - Removed code point support
  
---  
_Markdown_
_Copyright 2014-2019 MicroEJ Corp. - EDC compliance and optimizations._
_DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER._
_ _
_This code is free software; you can redistribute it and/or modify it_
_under the terms of the GNU General Public License version 2 only, as_
_published by the Free Software Foundation._
_ _
_This code is distributed in the hope that it will be useful, but WITHOUT_
_ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or_
_FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License_
_version 2 for more details (a copy is included in the LICENSE file that_
_accompanied this code)._
_ _
_You should have received a copy of the GNU General Public License version_
_2 along with this work; if not, write to the Free Software Foundation,_
_Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA._
_ _
_Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA_
_or visit www.oracle.com if you need additional information or have any_
_questions._

Eclasspath URI

java.net.URI implementation.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains the implementation of java.net.URI.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.eclasspath" name="uri" rev="1.1.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

  - Open JDK 8u20

# Restrictions

  - Removed serialization support
  - Removed java.net.URI.toAsciiString to avoid Normalizer dependency
  - Removed java.net.URI.toURL to avoid URL dependency
  
---    
_Markdown_  
_Copyright 2014-2019 MicroEJ Corp. - EDC compliance and optimizations._  
_DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER._  
_ _  
_This code is free software; you can redistribute it and/or modify it_  
_under the terms of the GNU General Public License version 2 only, as_  
_published by the Free Software Foundation._  
_ _  
_This code is distributed in the hope that it will be useful, but WITHOUT_  
_ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or_  
_FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License_  
_version 2 for more details (a copy is included in the LICENSE file that_  
_accompanied this code)._  
_ _  
_You should have received a copy of the GNU General Public License version_  
_2 along with this work; if not, write to the Free Software Foundation,_  
_Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA._  
_ _  
_Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA_  
_or visit www.oracle.com if you need additional information or have any_  
_questions._  

Eclasspath URL

java.net.URL implementation.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains the implementation of java.net.URL.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.eclasspath" name="url" rev="1.1.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

  - Open JDK 8u20

# Restrictions

  - Removed serialization support
  - Removed java.net.URI dependency
  - Removed java.text.DateFormat dependency APIs
  - Removed dependency to Internet (two URLs with two host names targeting the same IP address are not equals)
  - Removed guess Content-Type methods (java.net.URLConnection.guessContentTypeFromStream, java.net.URLConnection.guessContentTypeFromName)
  - Removed java.net.URLConnection.getPermission
  - Removed java.net.URLConnection ifModifiedSince support
  
---  
_Markdown_
_Copyright 2016-2019 MicroEJ Corp. - EDC compliance and optimizations._
_DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER._
_ _
_This code is free software; you can redistribute it and/or modify it_
_under the terms of the GNU General Public License version 2 only, as_
_published by the Free Software Foundation._
_ _
_This code is distributed in the hope that it will be useful, but WITHOUT_
_ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or_
_FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License_
_version 2 for more details (a copy is included in the LICENSE file that_
_accompanied this code)._
_ _
_You should have received a copy of the GNU General Public License version_
_2 along with this work; if not, write to the Free Software Foundation,_
_Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA._
_ _
_Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA_
_or visit www.oracle.com if you need additional information or have any_
_questions._

Eclasspath URLUtil

URLEncoder and URLDecode implementation.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains the implementation of URLEncoder and URLDecoder.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.eclasspath" name="urlutil" rev="1.1.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

  - Open JDK 8u20

# Restrictions

  - Approximation of Character.isLetter with : Character.isLowerCase or Character.isUpperCase.
  - No support for surrogate pairs.

---    
_Markdown_  
_Copyright 2014-2019 MicroEJ Corp. - EDC compliance and optimizations._  
_DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER._  
_ _  
_This code is free software; you can redistribute it and/or modify it_  
_under the terms of the GNU General Public License version 2 only, as_  
_published by the Free Software Foundation._  
_ _  
_This code is distributed in the hope that it will be useful, but WITHOUT_  
_ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or_  
_FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License_  
_version 2 for more details (a copy is included in the LICENSE file that_  
_accompanied this code)._  
_ _  
_You should have received a copy of the GNU General Public License version_  
_2 along with this work; if not, write to the Free Software Foundation,_  
_Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA._  
_ _  
_Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA_  
_or visit www.oracle.com if you need additional information or have any_  
_questions._  

MQTT Client

MQTT v3 Client for MicroEJ (Paho based).
LIBRARY for IOT
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

Paho MicroEJ client for MQTT:
  - This is a fork of Paho: https://eclipse.org/paho/clients/java/ from commit 496f94a58a41557ba2401d4ba94bc099a75ba8ef (just after version 1.0.2).
  - Implements MQTT 3.1.1

# Setup

In addition of adding the library in your buildpath, you have to configure your launch.

## Dependency injection

The library requires some implementations. It comes with default implementations but you can precise yours. 
To precise your own implementation you have to create a system property with the required interface as the key and the corresponding implementation as the value.
To define a system property see the section 6.1 of the MicroEJ Platform Architecture Reference Manual.
	
The library requires an implementation for the following interfaces:
  - org.eclipse.paho.client.mqttv3.MqttClientPersistence
  - org.eclipse.paho.client.mqttv3.internal.NetworkModuleFactory
  - org.eclipse.paho.client.mqttv3.internal.MessageCatalog
  - org.eclipse.paho.client.mqttv3.logging.InternalLoggerFactory
  - org.eclipse.paho.client.mqttv3.util.SystemProperties

For information about this interfaces see the corresponding javadoc.

example: org.eclipse.paho.client.mqttv3.MqttClientPersistence=org.eclipse.paho.client.mqttv3.persist.MemoryPersistence

The default implementations are defined in the `dependencyinjection.properties` file in the package `org.eclipse.paho.client.mqttv3.internal.dependencyinjection` of `mqttv3-microej-version.jar`.
	
In your launch, in the `Main` tab:
- add the chosen implementations in the `Required types` part.
- add the file containing the default implementations in the `Resources` part.

## Threads

Paho requires 4 threads to run. You have to adapt the value `Number of threads` of your launch to take this in account. You can modify this value by going in the `Configuration` tab in the `Target > Memory` section.

## UTF-8

Paho requires UTF-8 encoding to run. In the `Configuration` tab in the `EDC` section check `Embed UTF-8 encoding`.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="org.eclipse.paho" name="mqttv3-microej" rev="1.5.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    BON-1.3, EDC-1.2, NET-1.1

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

N/A

# Restrictions

None.

---
_Copyright 2016-2019 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._  

MQTT SSL Client

SSL Add-on for Paho Client for MQTT v3.
LIBRARY for IOT
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

Paho MicroEJ client for MQTT:

  - This is a fork of Paho: https://eclipse.org/paho/clients/java/ from commit 496f94a58a41557ba2401d4ba94bc099a75ba8ef (just after version 1.0.2).
  - Implements MQTT 3.1.1

# Setup

In addition of adding the library in your buildpath, you have to configure your launch.

## Dependency injection

The library requires some implementations. It comes with default implementations but you can precise yours. 
To precise your own implementation you have to create a system property with the required interface as the key and the corresponding implementation as the value.
To define a system property see the section 6.1 of the MicroEJ Platform Architecture Reference Manual.
	
The library requires an implementation for the following interfaces:

  - org.eclipse.paho.client.mqttv3.MqttClientPersistence
  - org.eclipse.paho.client.mqttv3.internal.NetworkModuleFactory
  - org.eclipse.paho.client.mqttv3.internal.MessageCatalog
  - org.eclipse.paho.client.mqttv3.logging.InternalLoggerFactory
  - org.eclipse.paho.client.mqttv3.util.SystemProperties

For information about this interfaces see the corresponding javadoc.

example: org.eclipse.paho.client.mqttv3.MqttClientPersistence=org.eclipse.paho.client.mqttv3.persist.MemoryPersistence

The default implementations are defined in the `dependencyinjection.properties` file in the package `org.eclipse.paho.client.mqttv3.internal.dependencyinjection` of `mqttv3-microej-version.jar`.
	
In your launch, in the `Main` tab:

- add the chosen implementations in the `Required types` part.
- add the file containing the default implementations in the `Resources` part.

## Threads

Paho requires 4 threads to run. You have to adapt the value `Number of threads` of your launch to take this in account. You can modify this value by going in the `Configuration` tab in the `Target > Memory` section.

## UTF-8

Paho requires UTF-8 encoding to run. In the `Configuration` tab in the `EDC` section check `Embed UTF-8 encoding`.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="org.eclipse.paho" name="mqttv3-ssl-microej" rev="3.2.0"/>

## SSL

The path to the certificate list is defined by the System property `org.eclipse.paho.certificates` by default it is `/certificates/paho.certificates.list`
Your application must embed this file. this file is a list of path to the certificates you want to use (one certificate per line).
	
# Requirements

This library requires the following Foundation Libraries:

    BON-1.3, EDC-1.2, NET-1.1, SSL-2.0

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

N/A

# Restrictions

None.

---
_Copyright 2016-2019 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._  

JSON encoder/decoder

JSON encoder/decoder.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# 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`:
	
    <dependency org="org.json.me" name="json" rev="1.3.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by Ivy resolver_.

# Source

N/A

# Restrictions

None.

---  
_Copyright 2016-2019 MicroEJ Corp. This file has been modified by MicroEJ Corp._  

kXML 2

XML pull parser.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2014-2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->
# Overview
kXML is a small XML pull parser, specially designed for constrained environments such as Applets, Personal Java or MIDP devices. In contrast to kXML 1, kXML 2 is based on the common 
XML pull API.

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="org.kxml2" name="kxml2" rev="2.3.+"/>`
	
# Requirements
  - EDC 1.2 or later

# Dependencies
None.

# Source
N/A

# Restrictions
None.

Android Connectivity

Android Connectivity Utilities.
LIBRARY for NETSEC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains android connectivity utilities.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.iot" name="android-connectivity" rev="1.2.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    BON-1.3, EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by Ivy resolver_.

# Source

N/A

# Restrictions

None.


--- 
_Copyright 2016-2019 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._  

Connectivity

Connectivity Utilities.
LIBRARY for NETSEC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains connectivity utilities.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.iot" name="connectivity" rev="2.1.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    BON-1.3, EDC-1.2, NET-1.1

# Dependencies

_All dependencies are retrieved transitively by Ivy resolver_.

# Source

N/A

# Restrictions

None.


---    
_Copyright 2016-2019 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._  

REST Client

RESTful services client.
LIBRARY for IOT
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

ej.rest is a tiny RESTful services client. 

## Features

- GET, POST, PUT, DELETE for text, JSON, binary
- Fluent-style API to follow hyperlinks easily
- Complex path queries for JSON (simple tests on fields with operators >,=,< and full boolean expressions (&&,||,!))
- Full support for multipart/form-data

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.iot" name="restclient" rev="1.1.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    BON-1.3, EDC-1.2, NET-1.0-API-1.0

# Dependencies

_All dependencies are retrieved transitively by Ivy resolver_.

# Source

- Derived from http://beders.github.com/Resty

# Restrictions

None.

# Embedded constraints

Embedded execution environment has a limited amount of memory (RAM, Flash, etc.). Using Resty library in a such environment encourages the developer to precisely manage resources like sockets, files, etc.

Since HTTP 2.0, server defines keep-alive connections for every HTTP connection. When using Resty, developer has to take care of the number of opened sockets. In fact, many sockets can be opened at the same time and stay alive for a long time (keep-alive). To prevent having too much sockets opened, developers have to close the underlying HTTP connection of each REST call. The following code snippet shows how to correctly close such connection:

Resty allows to create access paths into a JSON object with a JSON query path. The parser of these expressions needs RAM buffers. Two different sizes can be configured:
	- The size of the buffers, through the property `ej.rest.jsonquerypath.buffersize`.
	- The expand size of the buffers, through the property `ej.rest.jsonquerypath.expandbuffersize`.

```java
Resty rest = new Resty();
try {
    // Do a REST call
    RawResource raw = this.rest.raw("http://my.url/data");
    // Close the underlying http connection
    raw.http().disconnect();
} catch (IOException e) {
    // something went horribly wrong
    e.printStackTrace();
}
```


---    
_Copyright 2016-2019 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._  

CBOR encode/decoder

Library for encoding/decoding CBOR format.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

Library for encoding/decoding CBOR format.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.iot" name="cbor" rev="1.1.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

http://github.com/jawi/jacob

# Restrictions

None.

---  
_Copyright 2016-2019 MicroEJ Corp. This file has been modified by MicroEJ Corp._  

JSON encode/decoder

Library for encoding/decoding JSON format (push parser).
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview

This library provides APIs for writing to and reading from JSON streams.
Sources have been derived from original `org.json.me` project.

Main Changes: 
  - All DOM related classes removed (JSONObject, JSONArray, JSONString)
  - JSONWriter class now allows to write base type values at root
  - JSONWriter now takes a raw OutputStream instead of a Writer
  - JSONReader class has been derived from original JSONTokener class
  - General String constants elimination
  - Enabled writing of double values (uncommented CLDC-1.0 uncompliant code)

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.libary.iot" name="json" rev="1.+"/>`
	
# Requirements
  - EDC 1.2 or later
  - UTF-8 encoding enabled

# Dependencies
None.

# Source
N/A

# Restrictions
None.

Data Pub/Sub API

The Publish-Subscribe Data API.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

MicroEJ Java library for Data Pub/Sub.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.iot.data" name="pubsub-api" rev="1.2.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2, KF-1.4

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

N/A

# Restrictions

None.


---  
_Markdown_  
_Copyright 2017-2019 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._  

Components

Component-based programming library.
LIBRARY for CORE
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

A component-based programming library.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.runtime" name="components" rev="3.3.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    BON-1.3, EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by Ivy resolver_.

# Source

N/A

# Restrictions

None.

---    
_Copyright 2015-2019 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._  

Junit

MicroEJ junit API.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

MicroEJ Java library API: junit.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.test" name="junit" rev="1.6.2"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by Ivy resolver_.

# Source

N/A

# Restrictions

None.

---  
_Copyright 2015-2019 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._  

Motion

Motion library, providing animated tasks and a set of defined motions.
LIBRARY for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2014-2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview
A motion library, providing animated tasks and a set of defined motions 
(linear, elastic, bounce, etc.), useful for HMI animations.

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.library.runtime" name="components" rev="3.+"/>`

# Requirements
  - EDC-1.2 or higher
  - BON-1.2 or higher

# Dependencies
None.

# Source
N/A

# Restrictions
None.

Widget

Widget library.
LIBRARY for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains all that is necessary to create an HMI on MWT 2:

- a dynamic style resolution (_ej.style_),
- a set of widgets (_ej.widget_),
- a set of containers (_ej.widget.container_),
- an animation framework (_ej.animation_),
- a navigation framework (_ej.widget.navigation_),
- some color utilities (_ej.color_).

# Style

The style framework is used to customize a user interface.

A style is a set of attributes to apply to an element (spacing, coloring, font, size, etc.).

The stylesheet is augmented with rules: a selector associated with a partial style. The rules are ordered from the most specific to the least one. The resolution of an element style is done by applying the rules matching the element (in order), then inheriting a part of its parents style (recursively), then completing it by the default style. 

# Widgets

The widgets are graphical elements on which a style can be applied.

The framework contains a set of predefined widgets: label, image, button, toggle, radio, check, switch, text, slider, scrollbar, progress bar.

It is also possible to create its own widgets by subclassing StyledWidget.

# Containers

The containers are graphical elements on which a style can be applied and that can contain other elements (widgets or containers). Each container defines a policy to lay out its children.

The framework contains a set of predefined layout policies: canvas, dock, grid, list, scroll, split.

It is also possible to create its own layout policies by subclassing StyledComposite.

# Animation

The animation framework provides an animator that can schedule several animations at the same framerate.

# Navigation

The navigation framework provides the capability to navigate from one page to another and going back to pages history.

The pages are composed of widgets and containers. A page is represented by a URL.

A URL resolver is responsible for creating the pages from a URL.

A pages stack manages the history of pages. It can either keep the pages in cache or create it again while going back to history.

The navigation desktop associates a URL resolver and a pages stack to navigate between the pages. It may also animate the transition between the pages.

# Color

The color utilities provide some convenient functions to manipulate the colors.

The color helper manipulates (decompose, recompose) the color components red, green, blue.

The light helper computes and modifies the level of light in a color.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.ui" name="widget" rev="2.4.2"/>
	
# Requirements

This library requires the following Foundation Libraries:

    BON-1.3, EDC-1.2, MICROUI-2.0

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

N/A

# Restrictions

None.

---    
_Copyright 2016-2019 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._  

Concurrent Executor

java.util.concurrent implementation.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains the implementation of java.util.concurrent.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.util" name="concurrent-executor" rev="1.2.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by Ivy resolver_.

# Source

N/A

# Restrictions

None.

---  
_Copyright 2015-2019 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._  

Exit

Exit utilities.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains exit utilities.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.util" name="exit" rev="1.2.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2, KF-1.4

# Dependencies

_All dependencies are retrieved transitively by Ivy resolver_.

# Source

N/A

# Restrictions

None.

---  
_Copyright 2016-2019 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._  
Maps implementations.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains the implementation of maps implementations.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.util" name="map" rev="1.1.0"/>
	
# Requirements

This library requires the following Foundation Libraries:

    EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by Ivy resolver_.


# Source

N/A

# Restrictions

None.

---  
_Copyright 2015-2019 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._  

Observable

Observer design pattern abstract classes.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2015-2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview
This library contains classes for the observer design pattern.

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.library.util" name="observable" rev="1.+"/>`
	
# Requirements
  - EDC 1.2 or later
  - KF 1.3 or later

# Dependencies
None.

# Source
N/A

# Restrictions
None.

Progress

Activity Progress Monitoring implementation.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2015-2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview
This library contains classes for monitoring the progress of an activity.

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.library.util" name="progress" rev="1.+"/>`
	
# Requirements
  - EDC 1.2 or later

# Dependencies
None.

# Source
N/A

# Restrictions
None.

Firmware BLUE OM13098 (Multi-Sandbox)

Firmware BLUE OM13098, version: 2.0.2
FIRMWARE for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio
Technical Ref.: PQ9Y4
Last updated:
20 August 2020
+
# Overview

A MicroEJ® Firmware is a binary instance of MicroEJ Operating System for a dedicated board.
MicroEJ Studio allows application developers to write Java applications, run them on a virtual (simulated) or real device, and publish them to the MicroEJ Application Store.

The MicroEJ firmware has the capabilities to locally deploy applications created with MicroEJ Studio.

Visit [http://communitystore.microej.com](http://communitystore.microej.com/) for more information (download MicroEJ Studio, virtual device, firmware and demos).

# Features
## Foundations Libraries

This firmware implements the following libraries of MicroEJ 5.0, named MICROEJ-DEVELOPER-RUNTIME-1.3:

- EDC 1.3 (java.io, java.lang, java.lang.annotation, java.lang.ref, java.lang.reflect, java.util, java.security)
- BON 1.4 (ej.bon) : all except immortals
- NET 1.1 (java.net): 3 socket max
- SSL 2.1 (javax.net.ssl): 1 secured socket max
- MicroUI 2.1 (ej.microui): support of Display, LEDs, buttons and PNG decoding
- HAL 1.0 (ej.hal)
- ECOM 1.1 (ej.ecom)
- ECOM-COMM 1.1 (ej.ecom-ecomm)

To view this API, check in Help > MicroEJ Resource Center > Javadoc > MICROEJ-DEVELOPER-RUNTIME- x.y.

## Included Add-on Java Libraries

- MWT 2.2.5 (ej.mwt)
- Wadapps Framework 1.10 (ej.kf, ej.wadapps)
- Storage 1.2 (ej.wadapps.storage)
- Components 3.2 (ej.components)
- Connectivity Manager 1.1 (android.net)
- Signature 1.0.0 (com.microej.library)

## Preinstalled MicroEJ Resident Applications

- Weather: a background application allowing to show firmware settings
- AppList: a launcher application that displays the list of available applications.
- Localserver-socket: TCP/IP server for application management through the Wadapps Administration Console or MicroEJ companion (Android smartphone app)

# Firmware API Javadoc

Javadoc can be viewed in MicroEJ Studio Resource Center view (after the corresponding virtual device is imported).

# Demos

Demo applications and getting started are available from [http://communitystore.microej.com](http://communitystore.microej.com/).

# Going further

Visit [http://developer.microej.com](http://developer.microej.com/) to get more libraries and examples.

The following add-on Java libraries are compatible with this firmware (this list is indicative and not exhaustive):

- Eclasspath elements 1.0 (e.g: streams, collections, lists, properties, queues, stringtokenizer, uri, url)
- Logging 1.0 (java.util.logging)
- Widget 2.1 (ej.widget, ej.style, ej.transition, ej.color)
- REST client 1.0 (ej.rest)
- MQTT client 1.0.2 (org.eclipse.paho.client.mqttv3)
- HTTPS client 1.0 (javax.net.ssl)
- HTTP client	1.1 (java.net)
- SNTP client 1.0 (android.net)
- XML KXML 2-2.3.0 (org.kxml2)
- XML MxParser 1.1.4c (org.xmlpull.mxp)
- JSON 1.0 (org.json.me)

# Changelog

## 2.0.2 (August 18th 2020)
- Release for OM13098

## 2.0.1 (May 26th 2020)
- Internal refactor

## 2.0.0 (February 17th 2020)
- Removed Weather appplication
- Added Forge Connect application
- Virtual Device
	- support installation of FS3 applications

## 1.7.0 (April 8th 2019)
- Local deployment over socket with metadata (description, icons…).
- Disable signatures for local deployment.
- Remove Resident Application local deployment.
- Virtual Device
	- take the same options as the firmware.
	- simulate image buffer size.
	- support sandboxed applications.

## 1.6.1 (February 12th 2019)
 - Fixed logging level
 - Fixed Weather and AppList UI

## 1.5.0 (July 25th 2018)
  - Signer API introduced

## 1.4.0 (May 16th 2018)
  - Updated to MicroEJ Developer Runtime 1.4.0
  - Introduced signed commands, administration commands signed by a trusted authority.
  - Fixed issue with Wadapps Firmware Customizer not taking into account custom Firmware

## 1.3.8 (February 20th 2018)
  - Added missing KF converters for all wrapper types, for Date and List. Fixed Map converter to allow more complex use cases.
  - Fixed Weather navigator show a white square on certain weather page transition.
  - Fixed IllegalArgumentException in thread "DesktopWeather NET Timer".

## 1.3.6 (January 20th 2018)
  - Fixed metadata FS issue created by weather 3.1.0 having an InputStream leak.
  - Switch to location v1.0.0, solves issues when the returned location has no time_zone field.

## 1.3.5 (December 29th 2017)
  - Fixed performance issues on OM13092.
  - Switched to Desktop-Weather v3.1.0, to support imperial units.
  - Fixed NTP sync on IMX6ULEVK

## 1.3.4 (November 22nd 2017)
  - Fixed an issue with the parsing of certificates in the PEM format.

## 1.3.3 (November 10th 2017)
  - Fixed an issue with the parsing of certificates in the DER format.

## 1.3.2 (November 7th 2017)
  - Fixed an issue with Weather's handling of timezones that could lead to the wrong time being displayed.

## 1.3.1 (November 3rd 2017)
  - Updated Weather to Widgets 2.3.2
  - Fixed an issue with Weather's stylesheet polluting the other applications' stylesheets, on the simulator.

## 1.3.0 (October 27th 2017)
  - Include an application list reachable from the Weather desktop.
  - Updated to MicroEJ Developer Runtime 1.3.0
  - Added command to set or get shared properties.
  - Add "run" and "show" commands to start and show applications.
  - Add commands to list activities and to show one of them.
  - Use Bootlist 2.0 to customize the boot sequence.
  - Reduced memory consumption of the connectivity manager.
  - Firmware available in the Virtual Device can be extended with new resident applications provided as WPKs.
  - Added a new execute-on-device mode that actually adds the application as a resident application.
  - Increase available BSS size for resident apps from 2048 to 4096.
  - Increase maximum number of resident apps from 5 to 10.
  - Removed automatic execution of the ShieldedPlug server in the simulator.
  - Solved issue with the startup of the simulator that could lead to a black screen and no application execution.

## 1.2.2 (September 29th 2017)
- Fixed an issue where applications with icons cannot be installed with the Android companion.

## 1.2.1 (July 8th 2017)
- Display application name and version (if available) in the list command
- Fixed an issue with Wadapps console randomly leaving a java.exe hanging consuming CPU

## 1.2.0 (June 28th 2017)
- Fixed issue with DNS not retrying in case of timeout on slow networks
- Support more than 1 parameter to uninstall command.
- Fixed issue with no appplication metadata being stored on the device.
- Fixed issue with command socket server missing the reuseadddress option.

## 1.1.3 (May 17th 2017)
Bugfixes:
  - Re-release of 1.1.2 due to a build inconsistency.

## 1.1.2 (May 17th 2017)
Bugfixes:
  - Fixed Kernel names not to be the same for YELLOW, BLUE, GREEN, PURPLE.

## 1.1.1 (May 16th 2017)

  - Fixed issue with NTP not retrying in case of failure

## 1.1.0 (May 6th 2017)

  - Increased stack blocks from 50 to 60
  - Added the debug (framerate and CPU load) APIs.
  - Weather applications fixes

## 1.0.2 (March 31th 2017)

  - Increased stack blocks from 50 to 60
  - Fixed Firmware tries to start the bootall app twice.

## 1.0.1 (March 24th 2017)

  - Initial public revision.

Platform Developer's Guide

Learn to develop your first platform.
GUIDE for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
19 August 2020

Sonar

This project presents how to run the SonarQube(TM) source code quality analyzer on a MicroEJ Java project.
TOOL for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
13 August 2020
+
# Overview
This project presents how to run the SonarQube™ source code quality analyzer on a MicroEJ Java project.
This project installs and runs a local SonarQube server and provides locally a report holding the code inspection.

SonarQube is a an open source platform for continuous inspection of code quality. SonarQube offers reports on duplicated code, coding standards, unit tests, code coverage, code complexity, potential bugs, comments and architecture.

SonarQube is available at www.sonarqube.org.

### Requirements
- JRE 7 x86 or later.
- MicroEJ 3.0 or later.
- SonarQube 5.6.7 (see Usage/Provide SonarQube 5.6.7)

### Project structure
- [lib/](lib): SonarQube server & client, HTTP ant task.
- [rules/](rules): MicroEJ coding rules.
- [scripts/](scripts): ant scripts to run SonarQube server and execute analysis.
- [LICENSE.md](LICENSE.md).
- [README.md](README.md).

### Configuration
Open the [sonarAnalysis.ant](scripts/sonarAnalysis.ant) file, edit it to match the project you want to analyze:
- `sonar.projectBaseDir`: the location to find the projects to analyse.
- `sonar.projectName`: the project's name.
- `sonar.projectOrg`: the project's organisation.
- `sonar.projectVersion`: the project's version.

## Usage
### Provide SonarQube 5.6.7
- Download [sonarqube-5.6.7.zip](https://binaries.sonarsource.com/Distribution/sonarqube/sonarqube-5.6.7.zip)
- Put it in [lib/sonar/](lib/sonar)

### Launch an analysis
- Launch MicroEJ.
- File->Import->General->Existing project into workspace: import ExampleTool-Sonar folder.
- Edit the configuration ([scripts/sonarAnalysis.ant](scripts/sonarAnalysis.ant)) as described in the configuration section.
- Right-click on [scripts/sonarAnalysis.ant](scripts/sonarAnalysis.ant)->Run as…->Ant build.
- The server is automatically started.
- The report can be viewed at http://localhost:9000/dashboard/ (note: adapt the path to match your project's name if required).

### Launch the server
- Right-click on scripts/sonarServer.ant->Run as…->Ant build.
- All your previous analysis are available at http://localhost:9000/.

### Execute sonar when building project
MicroEJ's build types can execute sonar when being executed. By default the functionality is turned off to enable it:
- Launch the server.
- In **Window->Preferences->Ant->Runtime**.
- Go to **Properties** tab.
- Remove `sonar.skip` property.
- Add `sonar.login` property with value `admin`.
- Add `sonar.password` property with value `admin`.

Now when a MicroEJ project is built using EasyAnt (right-click on the project -> Build with EasyAnt), the sonar server will be populated.


<!--
	Markdown

	Copyright 2015-2019 IS2T. All rights reserved.
	IS2T PROPRIETARY. Use is subject to license terms.
-->

Espressif ESP32-WROVER-KIT V4.1 Platform Reference Implementation (MonoSandbox, GCC, FreeRTOS)

The MonoSandbox Platform for Espressif ESP32-WROVER-KIT V4.1 board.
JPF_ESP for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Technical Ref.: PRI-EVAL-ESP32-WROVER-KIT-MoGF-HDAHT
Last updated:
30 June 2020
+

Hoka

An embedded HTTP server library.
LIBRARY for IOT
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
20 February 2020
+
# Overview

This addon library provides a tiny footprint yet extensible web server.

It also includes tools for REST services and for authentication.

# Usage

The technical documentation on the usage of the Hoka library is in the [User Manual](user-manual.rst).

# Requirements

This library requires the following Foundation Libraries:

    BON-1.4, EDC-1.3, NET-1.1

# Dependencies

*All dependencies are retrieved transitively by Ivy resolver*.

# Source

N.A.

# Restrictions

None.

---  
_Copyright 2017-2019 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._  

Hoka Examples

Examples of use of the Hoka HTTP Server.
EXAMPLE for IOT
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
20 February 2020
+
# Overview

This project contains examples using the Hoka HTTP Server :

- [SimpleExample](SimpleExample/README.md) : a minimal example of the Hoka webserver.
- [HttpsExample](HttpsExample/README.md) : similar to **SimpleExample** but using HTTPS.
- [RestExample](RestExample/README.md) : an example with a REST service.
- [AccessControlExample](AccessControlExample/README.md) : an example with REST services to setup a minimal application with authentication and authorization.
- [SlowNetworkExample](SlowNetworkExample/README.md) : an example to setup a webserver optimized for slow networks using compression and caching techniques.

# Usage

The examples can be run either on the simulator or on the device using following procedures.

## Run on MicroEJ Simulator

1. Right Click on the project to run
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
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

### Flash

1. Use the appropriate flashing tool.

# Requirements

This library requires the following Foundation Libraries:

    @FOUNDATION_LIBRARIES_LIST@

# Dependencies

*All dependencies are retrieved transitively by Ivy resolver*.

# Source

N.A.

# Restrictions

None.

---
_Copyright 2019 MicroEJ Corp. All rights reserved._
_Use of this source code is governed by a BSD-style license that can be found with this software._

Murata-Type1LD-EVB Platform Reference Implementation (MonoSandbox, GCC, FreeRTOS)

The MonoSandbox Platform for Murata-Type1LD-EVB board.
JPF_MURATA for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Technical Ref.: PRI-EVAL-Murata-Type1LD-EVB-MoGF-XPUWJ
Last updated:
7 January 2020
+
<!--
	Copyright 2017 IS2T. All rights reserved.
	For demonstration purpose only
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Build MicroEJ Platform Reference Implementation for Murata-Type1LD-EVB

## Introduction

This document describes how to build the MicroEJ Platform Reference Implementation for Murata-Type1LD-EVB and how to launch a MicroEJ application on this platform.
	
## Prerequisites

 * Java7 or higher
 * MicroEJ SDK 4.1 or later
 * WICED SDK 3.7.0
 
## Projects Description

This platform source files are split into multiple projects:
	
`MurataType1LD-[name]-CM3_GCC48-configuration` :
> Contains the platform reference implementation configuration description. Some modules are described in a specific sub-folder /<module> with some optional configuration files (<module>.properties and / or <module>.xml).
	
`MurataType1LD-[name]-CM3_GCC48-bsp` :
> Contains a ready-to-use BSP software project for the Murata-Type1LD-EVB board, including a WICED SDK project, an implementation of MicroEJ core engine (and extensions) port on FreeRTOS OS and the Murata-Type1LD-EVB board support package.
		
`MurataType1LD-[name]-CM3_GCC48-[version]` :
> This project is created once the platform is built. It contains the platform for Murata-Type1LD-EVB board, ready to be linked into the WICED SDK project.
		
`MurataType1LD-[name]-CM3_GCC48-fp` :
> This front panel project is updated once the platform is built. It contains the board description and images for the MicroEJ simulator.
				
## Platform Reference Implementation Build

First step is to build a platform reference implementation for the Murata-Type1LD-EVB board from platform architecture ARM Cortex-M3. 
		
Build may be less or more complex, depending on the set	of foundation libraries that will be provided by the platform. Typical build steps are:
 * platform instantiation,
 * modules selection (native stacks, MicroEJ foundation libraries etc.),
 * WICED SDK project generation. 
		
Procedure:
 * Open the file `MurataType1LD-[name]-CM3_GCC48-configuration/MurataType1LD.platform`. 
 * Launch the platform build clicking on the link `Build Platform` in the `Overview > Build` section.
 * Once the platform is built, the `MurataType1LD-[name]-CM3_GCC48-[version]` project is created in the workspace.
		
## MicroEJ Application Build 
	
Second step is to write and generate a MicroEJ application on top of the newly created platform. This platform has built-in MicroEJ examples. Some additional MicroEJ examples are available on <http://developer.microej.com>
		
Procedure:
 * Click on `File > New > MicroEJ Standalone Example Project`
 * Select `MurataType1LD-[name]-CM3_GCC48` platform
 * Select one of the available example
 * Click on `Next`
 * Click on `Finish`
 * In the Package Explorer, right-click on `[example]` project
 * Select `Run As > MicroEJ Application` to run the application on the MicroEJ simulator
 * Click on menu `Run > Run Configurations...`
 * The launcher is automatically selected on left menu, if not, select it
 * Open `Execution` tab
 * Select `Execute on Device`
 * Click on `Run`
 * Once MicroEJ launch is executed, the generated object file is available in `[workspace]/.microej/CM3_GCC48/application/microejapp.o`.
		
## Final Application build
	
Last step is to open the Murata-Type1LD-EVB board support project for WICED SDK, compile it and link it with the MicroEJ application, and program the final application binary on the board.

Procedure:

			  
			  

OM13098 Platform (Multi-App, IAR, FreeRTOS)

The Multi-App Platform for OM13098 board.
JPF_NXP for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Technical Ref.: PTF-EVAL-OM13098-MIF-U3OER
Last updated:
7 January 2020
+

STM32F746-DISCO Platform (Multi-app, Keil, FreeRTOS)

The Multi-app Platform for the STM32F746-DISCO board.
JPF_ST for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Technical Ref.: PTF-EVAL-STM32F746DISCO-MKF-846SI
Last updated:
7 January 2020
+

AWS IoT Core Example

Demonstration of MQTT Publish / Subscribe functionalities for AWS IoT Core.
EXAMPLE for IOT
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
20 December 2019
+
# Overview

Demonstration of MQTT Publish / Subscribe functionalities for AWS IoT.

It contains two projects :
- com.microej.demo.aws.iot :
	The demonstration code is located here, the entry point class is `com.microej.demo.aws.iot.Main`.
	It contains the launcher for the embedded mode (currently working on Wi-Fi boards).
- com.microej.demo.aws.iot-sim :
	Mock and launcher for the demonstration to work correctly in Simulator mode.

This example has been tested on Murata 1LD eval board with a MurataType1LD 1.0.0 MicroEJ platform.
	
# Requirements

- Install the MicroEJ SDK which can be found [here](http://developer.microej.com/getting-started-sdk.html) - section 1
- Add a platform with NET-1.1, SSL-2.1 and Wi-Fi support ECOM-WIFI-2.1

# Setup

You should already have cloned this repository in `[git.repo.dir]`.

First start the MicroEJ SDK on a new workspace `[workspace.dir]`.

Importing the Git repository in a MicroEJ SDK:

 - once started, import the Eclipse projects: `File` > `Import` > in `Projects from Git`, type and select `Existing local repository` > `Next` > `Add` > `Browse`
 and select the `[git.repo.dir]`> `Finish` > select your repo `Next` > `Import existing Eclipse projects` > import all the projects.
 - enable the Ivy Resolving in workspace `Window` > `Preferences` > `Ivy` > `Classpath Container` > check `Resolve dependencies in workspace`
 - after an Ivy Resolving, may take a while, the projects should compile (no red markers on the projects)

# Launching the AWS IoT Demo

## Getting ready with AWS IoT
- create AWS account through [AWS console](https://aws.amazon.com/console/)
- go to `IoT Core`
- go to `Secure` > `Policies`
- create a policy (it describes what your device will be able to do like subscribing and publishing)
- name it and configure it like this (copy/paste is available by clicking on `Advanced mode` of the `Add statements` section) :
	```
	{
	 "Version": "2012-10-17",
     "Statement": [
       {
         "Action": [
           "iot:Publish",
           "iot:Subscribe",
           "iot:Connect",
           "iot:Receive"
         ],
         "Effect": "Allow",
         "Resource": [
           "*"
         ]
       }
     ]
   }
   ```
- click on create
- go to `Manage`
- click on `Create`
- click on `Create a single thing`
- name your thing and click on `Next`
- choose the `One-click certificate creation (recommended)` option by clicking on `Create certificate`
- on the `Certificate created` page, download every certificates and keys
- click on the `Activate` button to enable the certificate authentication of your thing
- click on `Attach a policy`
- select the previously created policy

If you have any trouble, the AWS IoT full documentation can be found [here](https://docs.aws.amazon.com/iot/latest/developerguide/iot-console-signin.html)
 
## Getting ready with the certificates
- transform the private key like this using [OpenSSL](https://www.openssl.org/source/):
	`openssl.exe pkcs8 -inform PEM -in myprivate.pem.key -topk8 -outform DER -out myprivate.der -v1 PBE-SHA1-3DES -passout pass:awsdemo`
- add your private key and certificate in the folder
`[worspace.dir]/com.microej.demo.aws.iot/src/main/resources/certificates/device`
- add the paths to your private key and certificate in `[worspace.dir]/com.microej.demo.aws.iot/src/main/resources/aws.iot.demo.resources.list`
	```
	certificates/device/myprivate.der
	certificates/device/mycertificate.pem.crt
	```
- modify the properties file that will be used to initialize the SSL context, located at `[worspace.dir]/com.microej.demo.aws.iot/src/main/resources/certificates/aws.iot.demo.device.certificates.properties`
	```
	# the path of the device certificate
	certificate.file.name=/certificates/device/mycertificate.pem.crt
	# the path of the device private key (encoded with the previous openssl command)
	private.key.file.name=/certificates/device/myprivate.der
	# the password used in the previous openssl command (the part afer pass:) -passout pass:awsdemo
	keystore.password=awsdemo
	```
	
## Getting ready with the application configuration
- in order to find your broker host, go to your AWS IoT Console, click on `Manage` > `Things` and select your Thing previously created. Then click on `Interact` and the broker host is shown under the HTTPS section and should look like this : `{myowndomainid}.amazonaws.com`
- configure your information in `[worspace.dir]/com.microej.demo.aws.iot/src/main/java/com/microej/demo/aws/iot/Config.java` :
	- your MQTT AWS broker host and port :
		```
		public static final String AWS_BROKER_HOST = "myowndomainid.amazonaws.com";
		public static final int AWS_BROKER_PORT = 8883;
		```
	- your AWS thing id :
		```
		public static final String AWS_THING_ID = "myThing";
		```
	- your Wi-Fi credentials :
		```
		public static final String SSID = "my_wifi";
		public static final String PASSWORD = "passphrase";
		```

## Launching the demo in simulator mode
- Launch the Run Configuration `AWS IoT PubSub Demo [SIM]` to run it in our simulator
- Take a look at the console to see the traces of the running application

## Launching the demo on a Wi-Fi board
- Launch the Run Configuration `AWS IoT PubSub Demo [SIM]` to generate the binary `microejapp.o`
- Use the generated binary to flash your Wi-Fi board and use a serial console of your choice to see the traces of the running application

The traces should look like this :
```
[INFO] Device connected to the broker.
[INFO] Update listener added, we're now subscribed to the topic awsiot/demo/sample
[INFO] Sample data publishing timer task initialized.
[INFO] Message received on topic awsiot/demo/sample => MicroEJ
[INFO] Message received on topic awsiot/demo/sample => is
[INFO] Message received on topic awsiot/demo/sample => a
[INFO] Message received on topic awsiot/demo/sample => unique
[INFO] Message received on topic awsiot/demo/sample => solution
[INFO] Message received on topic awsiot/demo/sample => for
[INFO] Message received on topic awsiot/demo/sample => building
[INFO] Message received on topic awsiot/demo/sample => Internet
[INFO] Message received on topic awsiot/demo/sample => of
[INFO] Message received on topic awsiot/demo/sample => Things
[INFO] Message received on topic awsiot/demo/sample => and
[INFO] Message received on topic awsiot/demo/sample => embedded
[INFO] Message received on topic awsiot/demo/sample => software
[INFO] Message received on topic awsiot/demo/sample => and
[INFO] Message received on topic awsiot/demo/sample => can
[INFO] Message received on topic awsiot/demo/sample => now
[INFO] Message received on topic awsiot/demo/sample => communicate
[INFO] Message received on topic awsiot/demo/sample => with
[INFO] Message received on topic awsiot/demo/sample => AWS IoT
```

## AWS IoT dashboard
The AWS IoT console provides some tools to monitor the activity on the broker. 
- go in the `Monitor` section of the console to see graphs of successful connections to the broker and statistics on the messaging.
You can also subscribe on a topic through the console in order to see arriving messages from your device: 
- go to `Test`
- in the `Subscription topic` section, indicate the topic to subscribe to, here `awsiot/demo/sample`
- click on `Subscribe to topic`
- when the application is running, you should see messages displayed in the AWS IoT console

# References

- [MicroEJ Developer](https://developer.microej.com)
- [Ivy](https://ant.apache.org/ivy/)
- [AWS console](https://aws.amazon.com/console/)
- [AWS IoT documentation](https://docs.aws.amazon.com/iot/latest/developerguide/iot-console-signin.html) 
- [OpenSSL](https://www.openssl.org/source/)

---  
_Markdown_   
_Copyright 2018-2019 MicroEJ Corp. All rights reserved._   
_Use of this source code is governed by a BSD-style license that can be found with this software._   

How-to generate fonts using FontForge

This document explains how to use Fontforge to generate a MicroEJ Font.
HOWTO for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
3 December 2019
+
.. Copyright 2019 MicroEJ Corp. All rights reserved.
.. Use of this source code is governed by a BSD-style license that can be found with this software.

Overview
========

This document explains how to use Fontforge to generate a MicroEJ Font.

Requirements
============

This how-to has been tested on

-  MicroEJ Studio or SDK 5.1
-  Python (3.8.0) with Pillow module (6.2.1)
-  FontForge (FontForge-2019-08-01 64-bit)
   -  if you have a 64-bit OS, install a 64-bit font forge
-  Windows 10

Usage
=====

Install the dependencies
------------------------

1. Download and Install Python and Pillow: `how
   to <https://pillow.readthedocs.io/en/3.0.x/index.html>`__
2. Download and install FontForge:
   `website <https://fontforge.github.io>`__
3. Add ffpython, available in `[Fontforge installation directory]/bin`,
   to the system path

Usage
-----

Generate the images
~~~~~~~~~~~~~~~~~~~

Use a command line to execute fontConverter:

::

   python fontConverter fontFilePath sizeInPixel [startRange endRange [bpp [algorithm]]
                   fontFilePath: the path to the font file
                   sizeInPixel: the size in pixel to use for the output (c.f. algorithm)
                   startRange: (default = 0x21) hexadecimal value of the first unicode character to export
                   endRange: (default = 0x24F)  hexadecimal value of the last unicode character last character to export, it is recommanded to export a wide range
                   bpp: (default = 8) the bpp to use for the export
                   algorithm: (default = 0) the algorithm to use :
                           0: bodyHeight => The sizeInPixel define the height of `Xg` (the generated image height will be the biggest height required to print all the character in range)
                           1: capitalHeight => The sizeInPixel define the size of a capital `X` (the generated image height will be the biggest height required to print all the character in range)
                           2: emHeight => The sizeInPixel define the size of an em (the generated image height will be the biggest height required to print all the character in range)
                           3: bestFit => The sizeInPixel define the size of the final output (the size of the font used will be the biggest possible to fit all the characters within the sizeInPixel)

The output should looks like:

::

   Generating images
   Mapping em font size to 14px
   Resizing images to 15px
   Generating EJF
   EJF file can be found at [PATH]\NotoSerif-Regular_capitalHeight_10px.ejf

Algorithm
~~~~~~~~~

-  **bodyHeight** will use the height of ``Xg`` (the generated image
   height will be the biggest height required to print all the character
   in range). In case of increase of the characters range, the size of
   the printed characters will be the same, but the size of the EJF file
   may be different.
-  **capitalHeight** will use the height of a capital ``X`` (the
   generated image height will be the biggest height required to print
   all the character in range). In case of increase of the characters
   range, the size of the printed characters will be the same, but the
   size of the EJF file may be different.
-  **emHeight** will use the height of an em (the generated image height
   will be the biggest height required to print all the character in
   range). In case of increase of the characters range, the size of the
   printed characters will be the same, but the size of the EJF file may
   be different.
-  **bestFit** will use the height of the final output (the size of the
   font used will be the biggest possible to fit all the characters
   within the sizeInPixel). In case of increase of the characters range,
   the size of the printed characters may vary, but the size of the EJF
   file will stay the same.

Import the images into an EJF
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In MicroEJ SDK:

1. Import the MicroEJ font
2. Adapt the base line to Map your font's base line

Troubleshooting
===============

DLL load failed
---------------

When using a 64-bit Windows and a 32-bit version of FontForge,
the script fails to load some DLL. Using a 64-bit version should
fix the use. `Font forge 64-bit portable <https://sourceforge.net/projects/fontforgebuilds/files/x86_64/Portable/>`__

Wi-Fi Setup Example

This repository contains the projects to setup a Wi-Fi connection using the SoftAP mode a Wi-Fi chip.
EXAMPLE for IOT
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
3 December 2019
+
# Overview
This repository contains the projects to setup a Wi-Fi connection using the SoftAP mode a Wi-Fi chip.

# Usage
Setup ivy to resolve its dependencies in workspace: 
 1. Click on **Window -> Preferences**
 2. Go to **Ivy -> Classpath Container**
 3. Check **Resolve dependencies in Workspace**
 4. Press **Apply and Close**

Import the projects:
 * [com.microej.example.wifi.setup](com.microej.example.wifi.setup): this project provides abstraction classes to setup the Wi-Fi AP credential using a Soft AP.
 * [com.microej.example.wifi.setup.rest](com.microej.example.wifi.setup.rest): this project mounts a rest server to provide the Access Point credential to join a Wi-Fi.
 * [com.microej.example.wifi.setup.web](com.microej.example.wifi.setup.web): this project presents a HTTP page in addition of a rest server to provide the Access Point credential to join a Wi-Fi.
 
 Both `com.microej.example.wifi.setup.rest` and `com.microej.example.wifi.setup.web` contain an Entry point to execute the project.
 The full demo will be using `com.microej.example.wifi.setup.web`, how to run it is explained in the project's [README.md](com.microej.example.wifi.setup.web/README.md).
 

# Requirements
  - EDC-1.2 or higher
  - SSL-2.1 or higher
  - NET-1.0 or higher
  - ECOM-WIFI-2.1 or higher
  - ECOM-NETWORK-2.0 or higher

# Dependencies
 _All dependencies are retrieved transitively by Ivy resolver_.

# Source
N/A

# Restrictions
None.



<!--
    Markdown
    Copyright 2018 IS2T. All rights reserved.
    This library is provided in source code for use, modification and test, subject to license terms.
    Any modification of the source code will break IS2T warranties on the whole library.
-->

NLS Usage Example

This example shows how to print a localized string on a display.
EXAMPLE for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
3 December 2019
+
# Overview

This example shows how to print a localized string on a display.

- [resource/nls](src/main/resources/nls) contains the `[prefix]_language.po` files with the the translation.
   `.po` files standard can be found at [gnu.org](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html) 

- [examples.nls.list](src/main/resources/com/microej/example/nls/helloworld/examples.nls.list) describes the generated class to use to get message.

# Usage

## Run on MicroEJ Simulator

1. Right-click on the project
2. Select **Run as -> MicroEJ Application**
3. Select your platform 
4. Press **Ok**

## Run on device

### Build

1. Right-click on the project
2. Select **Run as -> Run Configuration** 
3. Click on **New**
4. Select **Execute on Device**
5. Select **Build & Deploy**
6. Go to **Execution** tab
    * Select your platform 
7. Press **Apply**
8. Press **Run**
9. Copy the generated `.out` file path

### Flash

1. Use the appropriate MicroEJ tool.

# Requirements

This example has been tested on:

* MicroEJ SDK 5.1
* With a platform that contains:
    * EDC-1.2
    * BON-1.3
    * MICROUI-2.0

## Dependencies

_All dependencies are retrieved transitively by Ivy resolver_.

# Source

N/A

# Restrictions

None.


---
_Copyright 2016-2019 MicroEJ Corp. All rights reserved._  
_Use of this source code is governed by a BSD-style license that can be found with this software._  
_MicroEJ Corp. PROPRIETARY. Use is subject to license terms._  

MicroEJ Architectures Release Notes

The release notes of MICROEJ Architectures.
GUIDE for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
3 December 2019

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: 5.x
Supported MicroEJ Edition: SDK
Last updated:
29 November 2019
+
.. Copyright 2019 MicroEJ Corp. All rights reserved.
.. Use of this source code is governed by a BSD-style license that can be found with this software.

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

.. figure:: screenshots/Primitives.png
   :alt: Primitives

   Primitives

-  `com.microej.howto.microui.drawing.PrimitivesAntiAliased
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/drawing/PrimitivesAntiAliased.java>`__

.. figure:: screenshots/PrimitivesAntiAliased.png
   :alt: PrimitivesAntiAliased

   PrimitivesAntiAliased

-  `com.microej.howto.microui.font.Text
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/font/Text.java>`__

.. figure:: screenshots/Text.png
   :alt: Text

   Text

-  `com.microej.howto.microui.font.PictosWithCustomFont
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/font/PictosWithCustomFont.java>`__

.. figure:: screenshots/PictosWithCustomFont.png
   :alt: PictosWithCustomFont

   PictosWithCustomFont

-  `com.microej.howto.microui.image.TransparentImages
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/TransparentImages.java>`__

.. figure:: screenshots/TransparentImages.png
   :alt: TransparentImages

   TransparentImages

-  `com.microej.howto.microui.image.FlippedImages
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/FlippedImages.java>`__

.. figure:: screenshots/FlippedImages.png
   :alt: FlippedImages

   FlippedImages

-  `com.microej.howto.microui.image.RotatedImages
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/RotatedImages.java>`__

.. figure:: screenshots/RotatedImages.png
   :alt: RotatedImages

   RotatedImages

-  `com.microej.howto.microui.image.ScaledImages
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/ScaledImages.java>`__

.. figure:: screenshots/ScaledImages.png
   :alt: ScaledImages

   ScaledImages

-  `com.microej.howto.microui.image.TilingWithImages
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/TilingWithImages.java>`__

.. figure:: screenshots/TilingWithImages.png
   :alt: TilingWithImages

   TilingWithImages

-  `com.microej.howto.microui.image.DeformedImages
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/DeformedImages.java>`__

.. figure:: screenshots/DeformedImages.png
   :alt: DeformedImages

   DeformedImages

-  `com.microej.howto.microui.events.InputEvents
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/events/InputEvents.java>`__

.. figure:: screenshots/InputEvents.png
   :alt: InputEvents

   InputEvents

-  `com.microej.howto.microui.animation.AnimationSampleWithFullRepaint
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/animation/AnimationSampleWithFullRepaint.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
============

This example has been tested on:

-  MicroEJ SDK 5.1
-  With a Platform that contains:

   -  EDC-1.2
   -  BON-1.2
   -  MiCROUI-2.0

Dependencies
============

*All dependencies are retrieved transitively by Ivy resolver*.

Credits
=======

+------------------+-------------------------------+------------------+
| Font             | Author                        |License           |
+------------------+-------------------------------+------------------+
| Font Awesome     | Dave Gandy                    | `SIL OFL 1.1     |
|                  | http://fontawseome.io         | license -        |
|                  |                               | http://scripts.s |
|                  |                               | il.org/OFL </Mic |
|                  |                               | roUI-Get-Started |
|                  |                               | /src/main/resour |
|                  |                               | ces/fonts/OFL.tx |
|                  |                               | t>`__            |
+------------------+-------------------------------+------------------+
| Sans             | Adobe                         | `SIL Open Font   |
|                  |                               | License.txt </Mi |
|                  |                               | croUI-Get-Starte |
|                  |                               | d/src/main/resou |
|                  |                               | rces/fonts/Adobe |
|                  |                               | -Source-SIL-Open |
|                  |                               | -Font-License.tx |
|                  |                               | t>`__            |
+------------------+-------------------------------+------------------+

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: 5.x
Supported MicroEJ Edition: SDK
Last updated:
29 November 2019
+
.. Copyright 2019 MicroEJ Corp. All rights reserved.
.. Use of this source code is governed by a BSD-style license that can be found with this software.

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 <src/main/java/
   com/microej/howto/mwt/colors/Gradient.java>`__

.. figure:: screenshots/Gradient.png
   :alt: Gradient

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

This example has been tested on:

-  MicroEJ SDK 5.1
-  With a ST STM32F746G-DISCO (480x272 display) board platform that contains:

   -  EDC-1.2
   -  BON-1.3
   -  MICROUI-2.2

Dependencies
============

*All dependencies are retrieved transitively by Ivy resolver*.

Source
======

N/A

Restrictions
============

None.

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: 5.x
Supported MicroEJ Edition: Studio
Last updated:
29 November 2019
+
.. Copyright 2019 MicroEJ Corp. All rights reserved.
.. Use of this source code is governed by a BSD-style license that can be found with this software.

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>``
5. Add the following dependency : ``<dependency org="ej.library.wadapps"
   name="framework" rev="1.11.0" />``

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 virtual device
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 virtual
      device
   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 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: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
29 November 2019
+
.. Copyright 2019 MicroEJ Corp. All rights reserved.
.. Use of this source code is governed by a BSD-style license that can be found with this software.

How to Setup a new Foundation Library
=====================================

This example describes how to setup a new Foundation Library in MicroEJ
SDK and how to distribute it through a MicroEJ Platform.

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

Software
~~~~~~~~

This example has been tested on:

-  MicroEJ SDK 5.1
-  With a MicroEJ 5 Platform Reference Implementation imported into the
   MicroEJ repository that contains:

   -  EDC-1.2
   -  BON-1.3
   -  SP-2.0

   See https://developer.microej.com/getting-started-sdk.html.

Knowledge
~~~~~~~~~

-  Basic knowledge about Java and C programming.
-  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.

.. figure:: resources/overview.png
   :alt: LLAPI

   LLAPI

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.

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 nativeFactorial(number);
       }

       public native static int nativeFactorial(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_nativeFactorial

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

    -  Set the project settings.

      -  Project Name: mylib-test
      -  Organization: com.mycompany.test
      -  Module: mylib
      -  Revision: 1.0.0

-  Open **module.ivy**

      - Add the dependency ``<dependency org="com.mycompany.api" name="mylib"
        rev="1.0.0" />``

-  Òpen file **Main.java**

   -  Source folder: **mylib-test/src**.
   -  Package: **com.mycompany**
   -  Class Name: **TestMyLib**

-  Copy and paste the following code into this class:

::

   package com.mycompany.test;

   public class Main {

      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 **nativeFactorial** 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 nativeFactorial(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 *nativeFactorial* 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-1:

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_nativeFactorial (referred from microejapp.o).

This is the normal behavior because the symbol
**Java_com_mycompany_MyLib_nativeFactorial** 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 *nativeFactorial* 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)

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
-  Generate a mock with an UI: `Mock-Get-Started <https://github.com/MicroEJ/How-To/tree/master/Mock-Get-Started>`__

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: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
29 November 2019
+
.. Copyright 2019 MicroEJ Corp. All rights reserved.
.. Use of this source code is governed by a BSD-style license that can be found with this software.

Overview
========

This document explains how to use Proguard 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
============

This how-to has been tested on:

-  MicroEJ SDK 5.1

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 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: 5.x
Supported MicroEJ Edition: Studio
Last updated:
29 November 2019
+
.. Copyright 2019 MicroEJ Corp. All rights reserved.
.. Use of this source code is governed by a BSD-style license that can be found with this software.

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 Storage 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).

    .. code:: 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.

    .. code:: 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 getIds method.
This method returns all data key’s already stored.

    .. code:: 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.

    .. code:: 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
============

This example has been tested on:

-  MicroEJ SDK 5.1
-  With a BLACK-ESP32WROVER-RQQAW board virtual device

Dependencies
============

*All dependencies are retrieved transitively by Ivy resolver*.

Source
======

N/A

Restrictions
============

None.

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: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
29 November 2019
+
.. Copyright 2019-2020 MicroEJ Corp. All rights reserved.
.. Use of this source code is governed by a BSD-style license that can be found with this software.

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 module project (https://docs.microej.com/en/latest/ApplicationDeveloperGuide/mmm.html#module-project-skeleton) using the ``microej-mock`` skeleton.

-  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 (**right click on the project** >
   ``Build Module``).
-  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
============

This example has been tested on:

-  MicroEJ SDK 5.1.0
-  With a platform that contains:

   -  EDC-1.2
   -  BON-1.3
   -  MICROUI-2.0
   -  SP-2.0

Dependencies
============

*All dependencies are retrieved transitively by MicroEJ Module Manager*.

Source
======

N/A

Restrictions
============

None.

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: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
29 November 2019
+
.. Copyright 2018-2019 MicroEJ Corp. All rights reserved.
.. Use of this source code is governed by a BSD-style license that can be found with this software.

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

     .. image:: screenshots/ImportProjects.png
       :alt: Import context

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

         .. image:: screenshots/RunAsFeature.png
            :alt: Build Dynamic Feature

   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

         .. image:: screenshots/RunAsFeatureConfiguration.png
            :alt: Feature Configuration

         -  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

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: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
29 November 2019
+
.. Copyright 2018-2019 MicroEJ Corp. All rights reserved.
.. Use of this source code is governed by a BSD-style license that can be found with this software.

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

This example has been tested on:

-  MicroEJ SDK 5.1
-  With a Platform Reference Platform that contains:

   -  EDC-1.2
   -  BON-1.2

STM32F746G-DISCO Platform Reference Implementation requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-  MicroEJ platform reference implementation STM32F746-DISCO Platform
   available from
   `developer.microej.com <http://developer.microej.com/index.php>`__
-  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**

     .. image:: screenshots/ImportProjects.png
       :alt: Import context


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

     .. image:: screenshots/CheckSNI.png
       :alt: Check SNI

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

     .. image:: screenshots/BuildPlatform.png
       :alt: Build Platform

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

     .. image:: screenshots/RunAsDevice.png
       :alt: Execute on device

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

     .. image:: screenshots/CheckMultiApp.png
       :alt: Check MultiApp

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

     .. image:: screenshots/BuildPlatform.png
       :alt: Build Platform

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's ``module.ivy``
      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**
   2. Flash the firmware on the board pressing **F8**
   3. 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**

         .. image:: screenshots/RunAsFeature.png
           :alt: Build Dynamic Feature

   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

         .. image:: screenshots/RunAsFeatureConfiguration.png
           :alt: Feature Configuration

         -  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

6. Copy the ``application_1.fo`` feature file to a ``tmp/`` folder at
   the root of the microSD card.
7. Insert the SD card into the board
8. Reset the board
9. 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

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: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
29 November 2019
+
.. Copyright 2018-2019 MicroEJ Corp. All rights reserved.
.. Use of this source code is governed by a BSD-style license that can be found with this software.

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

This example has been tested on:

-  MicroEJ SDK 5.1
-  With a Platform Reference Platform that contains:

   -  EDC-1.2
   -  BON-1.2

STM32F746G-DISCO Platform Reference Implementation requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-  MicroEJ platform reference implementation STM32F746-DISCO Platform
   available from
   `developer.microej.com <http://developer.microej.com/index.php>`__
-  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**

   .. image:: screenshots/ImportProjects.png
      :alt: Import context


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

     .. image:: screenshots/CheckSNI.png
       :alt: Check SNI

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

     .. image:: screenshots/BuildPlatform.png
       :alt: Build Platform

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

     .. image:: screenshots/RunAsDevice.png
       :alt: Execute on device


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/>`__.


Examples Eclasspath

This project gather all the examples of eclasspath.
EXAMPLE for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
28 November 2019
+
# 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.
* [com.microej.examples.eclasspath.formatter](com.microej.examples.eclasspath.formatter) :  Prints some messages using the formatter.

---  
_Markdown_   
_Copyright 2019 MicroEJ Corp. All rights reserved._   
_For demonstration purpose only._   
_MicroEJ Corp. PROPRIETARY. Use is subject to license terms._  

Using Foundation Libraries APIs (Standalone)

This project gathers all the basic examples of the foundation libraries.
EXAMPLE for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
28 November 2019
+
# 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.

---  
_Markdown_   
_Copyright 2016-2019 MicroEJ Corp. All rights reserved._   
_For demonstration purpose only._   
_MicroEJ Corp. PROPRIETARY. Use is subject to license terms._  

MicroEJ Studio & SDK 5.x Release Notes

The release notes for both MICROEJ Studio and MICROEJ SDK.
GUIDE for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
6 November 2019

Application Developer's Guide (Sandboxed)

Learn to develop your first sandboxed apps.
GUIDE for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio
Last updated:
6 November 2019

Application Developer's Guide (Standalone)

Learn to develop your first standalone apps.
GUIDE for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
6 November 2019

Firmware INDIGO STM32F746-DISCO (Multi-Sandbox)

Firmware INDIGO STM32F746-DISCO, version: 1.1.0
FIRMWARE for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio
Technical Ref.: L9EBM
Last updated:
31 October 2019
+
# Overview

A MicroEJ® Firmware is a binary instance of MicroEJ Operating System for a dedicated board.
MicroEJ Studio allows application developers to write Java applications, run them on a virtual (simulated) or real device, and publish them to the MicroEJ Application Store.

The MicroEJ firmware has the capabilities to locally deploy applications created with MicroEJ Studio.

Visit [https://communitystore.microej.com](https://communitystore.microej.com/) for more information (download MicroEJ Studio, virtual device, firmware and demos).

# Features
## Foundations Libraries

This firmware implements the following libraries of MicroEJ 5, named MICROEJ-DEVELOPER-RUNTIME-1.4:

- EDC 1.3 (java.io, java.lang, java.lang.annotation, java.lang.ref, java.lang.reflect, java.util, java.security)
- BON 1.3 (ej.bon) : all except immortals
- NET 1.1 (java.net): 3 socket max
- SSL 2.1 (javax.net.ssl): 1 secured socket max
- MicroUI 2.3.0 (ej.microui): support of Display, LEDs, buttons and PNG decoding
- HAL 1.0 (ej.hal)
- ECOM 1.1 (ej.ecom)
- ECOM-COMM 1.1 (ej.ecom-ecomm)

To view this API, check in Help > MicroEJ Resource Center > Javadoc > MICROEJ-DEVELOPER-RUNTIME- x.y. 

## Included Add-on Java Libraries

- MWT 2.2.5 (ej.mwt)
- Wadapps Framework 1.10.0 (ej.kf, ej.wadapps)
- Storage 1.2.0 (ej.wadapps.storage)
- Components 3.3.0 (ej.components)
- Connectivity Manager 1.2.0 (android.net)

## Preinstalled MicroEJ Resident Applications

- About 3.0.0: a simple application that shows firmware information.
- AppList 2.2.0: a launcher application that displays the list of available applications.
- Localserver-socket 1.9.0: TCP/IP server for application management through the Wadapps Administration Console or MicroEJ companion (Android smartphone app)
- Google Edge Plug Agent 1.2.2: a Google cloud platform IoT Core connector.
- WordClock 1.1.0: a demo application that displays a clock for the selected time zone.
- FlippingTiles 2.1.0: a demo application that displays a slideshow with smooth flipping transitions between images.

# Firmware API Javadoc

Javadoc can be viewed in MicroEJ Studio Resource Center view (after the corresponding virtual device is imported).

# Demos

Demo applications and getting started are available from [https://communitystore.microej.com](https://communitystore.microej.com/).

# Going further

Visit [https://developer.microej.com](https://developer.microej.com/) to get more libraries and examples.

The following add-on Java libraries are compatible with this firmware (this list is indicative and not exhaustive):

- Eclasspath elements 1.0 (e.g: streams, collections, lists, properties, queues, stringtokenizer, uri, url)
- Logging 1.0 (java.util.logging)
- Widget 2.1 (ej.widget, ej.style, ej.transition, ej.color)
- REST client 1.0 (ej.rest)
- MQTT client 1.0.2 (org.eclipse.paho.client.mqttv3)
- HTTPS client 1.0 (javax.net.ssl)
- HTTP client	1.1 (java.net)
- SNTP client 1.0 (android.net)
- XML KXML 2-2.3.0 (org.kxml2)
- XML MxParser 1.1.4c (org.xmlpull.mxp)
- JSON 1.0 (org.json.me)

# Changelog

## 1.1.0 (October 23th 2019)
- Autostart applications that are run from workspace.
- Automatically deploy and start applications from META-INF/wpk directory.
- Add About application.
- Remove Weather launcher application.
- Update other system applications.
- Enable SystemView on OM13098.
- Copy metadata when deploying an application (icons, name, description).
- Embed default bootlist in firmware.

## 1.0.0 (October 8th 2019)
- Initial public revision.
- Same as BLUE 1.7.0 with extra applications:
  - Google Edge Plug Agent 1.2.2
  - WordClock 1.0.1
  - FlippingTiles 2.0.2

Firmware INDIGO OM13098 (Multi-Sandbox)

Firmware INDIGO OM13098, version: 1.1.0
FIRMWARE for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio
Technical Ref.: 5H44X
Last updated:
31 October 2019
+
# Overview

A MicroEJ® Firmware is a binary instance of MicroEJ Operating System for a dedicated board.
MicroEJ Studio allows application developers to write Java applications, run them on a virtual (simulated) or real device, and publish them to the MicroEJ Application Store.

The MicroEJ firmware has the capabilities to locally deploy applications created with MicroEJ Studio.

Visit [https://communitystore.microej.com](https://communitystore.microej.com/) for more information (download MicroEJ Studio, virtual device, firmware and demos).

# Features
## Foundations Libraries

This firmware implements the following libraries of MicroEJ 5, named MICROEJ-DEVELOPER-RUNTIME-1.4:

- EDC 1.3 (java.io, java.lang, java.lang.annotation, java.lang.ref, java.lang.reflect, java.util, java.security)
- BON 1.3 (ej.bon) : all except immortals
- NET 1.1 (java.net): 3 socket max
- SSL 2.1 (javax.net.ssl): 1 secured socket max
- MicroUI 2.3.0 (ej.microui): support of Display, LEDs, buttons and PNG decoding
- HAL 1.0 (ej.hal)
- ECOM 1.1 (ej.ecom)
- ECOM-COMM 1.1 (ej.ecom-ecomm)

To view this API, check in Help > MicroEJ Resource Center > Javadoc > MICROEJ-DEVELOPER-RUNTIME- x.y. 

## Included Add-on Java Libraries

- MWT 2.2.5 (ej.mwt)
- Wadapps Framework 1.10.0 (ej.kf, ej.wadapps)
- Storage 1.2.0 (ej.wadapps.storage)
- Components 3.3.0 (ej.components)
- Connectivity Manager 1.2.0 (android.net)

## Preinstalled MicroEJ Resident Applications

- About 3.0.0: a simple application that shows firmware information.
- AppList 2.2.0: a launcher application that displays the list of available applications.
- Localserver-socket 1.9.0: TCP/IP server for application management through the Wadapps Administration Console or MicroEJ companion (Android smartphone app)
- Google Edge Plug Agent 1.2.2: a Google cloud platform IoT Core connector.
- WordClock 1.1.0: a demo application that displays a clock for the selected time zone.
- FlippingTiles 2.1.0: a demo application that displays a slideshow with smooth flipping transitions between images.

# Firmware API Javadoc

Javadoc can be viewed in MicroEJ Studio Resource Center view (after the corresponding virtual device is imported).

# Demos

Demo applications and getting started are available from [https://communitystore.microej.com](https://communitystore.microej.com/).

# Going further

Visit [https://developer.microej.com](https://developer.microej.com/) to get more libraries and examples.

The following add-on Java libraries are compatible with this firmware (this list is indicative and not exhaustive):

- Eclasspath elements 1.0 (e.g: streams, collections, lists, properties, queues, stringtokenizer, uri, url)
- Logging 1.0 (java.util.logging)
- Widget 2.1 (ej.widget, ej.style, ej.transition, ej.color)
- REST client 1.0 (ej.rest)
- MQTT client 1.0.2 (org.eclipse.paho.client.mqttv3)
- HTTPS client 1.0 (javax.net.ssl)
- HTTP client	1.1 (java.net)
- SNTP client 1.0 (android.net)
- XML KXML 2-2.3.0 (org.kxml2)
- XML MxParser 1.1.4c (org.xmlpull.mxp)
- JSON 1.0 (org.json.me)

# Changelog

## 1.1.0 (October 23th 2019)
- Autostart applications that are run from workspace.
- Automatically deploy and start applications from META-INF/wpk directory.
- Add About application.
- Remove Weather launcher application.
- Update other system applications.
- Enable SystemView on OM13098.
- Copy metadata when deploying an application (icons, name, description).
- Embed default bootlist in firmware.

## 1.0.0 (October 8th 2019)
- Initial public revision.
- Same as BLUE 1.7.0 with extra applications:
  - Google Edge Plug Agent 1.2.2
  - WordClock 1.0.1
  - FlippingTiles 2.0.2

Firmware BLACK ESP32-WROVER (Multi-Sandbox)

Firmware BLACK ESP32-WROVER, version: 1.0.1
FIRMWARE for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio
Technical Ref.: RQQAW
Last updated:
31 October 2019
+
# Overview

A MicroEJ® Firmware is a binary instance of MicroEJ Operating System for a dedicated board.
MicroEJ Studio allows application developers to write Java applications, run them on a virtual (simulated) or real device, and publish them to the MicroEJ Application Store.

The MicroEJ firmware has the capabilities to locally deploy applications created with MicroEJ Studio.

Visit [http://communitystore.microej.com](http://communitystore.microej.com/) for more information (download MicroEJ Studio, virtual device, firmware and demos).

# Features
## Foundations Libraries

This firmware implements the following libraries of MicroEJ 5, named MICROEJ-BLE-RUNTIME-1.0:

- EDC 1.3 (java.io, java.lang, java.lang.annotation, java.lang.ref, java.lang.reflect, java.util, java.security)
- BON 1.3 (ej.bon) : all except immortals
- NET 1.1 (java.net): 3 socket max
- SSL 2.1 (javax.net.ssl): 1 secured socket max
- MicroUI 2.0 (ej.microui): support of Display, LEDs, buttons and PNG decoding
- HAL 1.0 (ej.hal)
- ECOM 1.1 (ej.ecom)
- BLUETOOTH 1.0 (ej.bluetooth)

To view this API, check in Help > MicroEJ Resource Center > Javadoc > MICROEJ-DEVELOPER-RUNTIME- x.y. 

## Included Add-on Java Libraries

- MWT 2.2.5 (ej.mwt)
- Wadapps Framework 1.10.0 (ej.kf, ej.wadapps)
- Storage 1.2.0 (ej.wadapps.storage)
- Components 3.3.0 (ej.components)
- Connectivity Manager 1.2.0 (android.net)

## Preinstalled MicroEJ Resident Applications

- Launcher-Espressif: a launcher with Espressif's and MicroEJ's logos
- Localserver-socket: TCP/IP server for application management through the Wadapps Administration Console or MicroEJ companion (Android smartphone app)

# Firmware API Javadoc

Javadoc can be viewed in MicroEJ Studio Resource Center view (after the corresponding virtual device is imported).

# Demos

Demo applications and getting started are available from [http://communitystore.microej.com](http://communitystore.microej.com/).

# Going further

Visit [http://developer.microej.com](http://developer.microej.com/) to get more libraries and examples.

The following add-on Java libraries are compatible with this firmware (this list is indicative and not exhaustive):

- Eclasspath elements 1.0 (e.g: streams, collections, lists, properties, queues, stringtokenizer, uri, url)
- Logging 1.0 (java.util.logging)
- Widget 2.1 (ej.widget, ej.style, ej.transition, ej.color)
- REST client 1.0 (ej.rest)
- MQTT client 1.0.2 (org.eclipse.paho.client.mqttv3)
- HTTPS client 1.0 (javax.net.ssl)
- HTTP client	1.1 (java.net)
- SNTP client 1.0 (android.net)
- XML KXML 2-2.3.0 (org.kxml2)
- XML MxParser 1.1.4c (org.xmlpull.mxp)
- JSON 1.0 (org.json.me)

# Changelog

## 1.0.1 (September 18th 2019)
  - Fix firmware boots with a white screen on simulator.

## 1.0.0 (September 17th 2019)
 - First internal release

Using IOT Libraries APIs (Sandboxed)

This project gathers simple Sandboxed application using net libraries.
EXAMPLE for IOT
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
31 October 2019
+
# Overview

This project gathers simple sandboxed applications using net libraries.

## Requirements

* MicroEJ Studio or SDK 5.1 or later

# Usage

Each subfolder contains a distinct IOT application.

# Changes

- See the change log file [CHANGELOG.md](CHANGELOG.md) located at the root of this repository.

# License

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

---  
_Markdown_   
_Copyright 2019 MicroEJ Corp. All rights reserved._   
_Use of this source code is governed by a BSD-style license that can be found with this software._   
_MicroEJ Corp. PROPRIETARY. Use is subject to license terms._  

MicroEJ Module Manager Specification

The specification for the MicroEJ Module Manager.
GUIDE for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
31 October 2019

Spresense Weather Demo

Spresense Weather Demo displaying a User Interface with audio and GNSS use.
EXAMPLE for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
30 October 2019
+
# Overview

This application demonstrates a weather station's user interface with audio and GNSS support. 

![rain](screenshots/rain.png)
![cloud](screenshots/cloud.png)
![sun](screenshots/sun.png)

Then entry point (`main`) can be found at `com.microej.spresense.demo.SpresenseDemo`

# Usage

This demo requires a Sony Spresense platform to have been built.
We tested the project against this [platform](https://github.com/MicroEJ/Platform-Sony-Spresense), to build it , please follow the README at the root of the repository.

## Run on MicroEJ Simulator

1. Right-click on the project
2. Select **Run as -> MicroEJ Application**
3. Select **[Sim] SpresenseDemo**
4. Press **Ok**

## Run on a device

### Build

1. Right-click on the project
2. Select **Run as -> Run Configuration**
3. Select **[Emb] SpresenseDemo**
4. Press **Ok**
5. The application file (`.o`) has been generated

### Flash

1. Compile, link and flash the board following the platform's README.

### Memory configuration

The application comes with a MicroEJ launch configuration (**[Emb] SpresenseDemo**). This configuration is compatible with the default memory layout provided in the platform.

The important configuration are, in the **Configuration** tab of the launch configuration:
1. **Runtime -> Memory -> Java heap** : Set to **50 000**
2. **Runtime -> Memory -> Immortal heap** : Set to **1024**
3. **Runtime -> Thread -> Number of threads** : Set to **7**
4. **Libraries -> MicroUI -> Image Heap** : Set to **2000**

# Requirements

This example has been tested on:

* MicroEJ SDK 5.1
* With a Sony Spresense platform that contains:
    * EDC-1.2
    * BON-1.3
    * SNI-1.3
    * MICRO UI-2.3
    * AUDIO-0.9
    * GNSS-0.9

# Dependencies

_All dependencies are retrieved transitively by Ivy resolver_.

# Source

N/A

# Restrictions

None.

---
_Copyright 2019 Sony Corp. All rights reserved._  
_This Software has been designed by MicroEJ Corp and all rights have been transferred to Sony Corp._  
_Sony Corp. has granted MicroEJ the right to sub-licensed this Software under the enclosed license terms._  

Sony Spresense Platform Reference Implementation (MonoSandbox, GCC, NuttX)

The MonoSandbox Platform for Sony Spresense board.
JPF_SONY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Technical Ref.: PRI-EVAL-SONY-SPRESENSE-MoGN
Last updated:
10 July 2019
+
..
   Copyright 2019 MicroEJ Corp. All rights reserved.
   For demonstration purpose only.
   MicroEJ Corp. PROPRIETARY. Use is subject to license terms.


===============================
Sony Spresense MicroEJ Platform
===============================
Introduction
============

This is the README file of the reference implementation of the MicroEJ platform for the Spresense board (https://developer.sony.com/develop/spresense).

The Sony Spresense SDK is highly configurable. Any change from the provided configuration must be validated.
The MicroEJ Platform for the Spresense board is delivered as a “Reference Implementation”, with all source included to rebuild the platform and generate a firmware.

The development process is to first configure Sony Spresense’s SDK enabling and/or disabling the features you need and configuring the amount of shared memory you need.
Once you have configured your SDK, you can build the platform, generate a microejapp.o containing the bytecode of your Java application. Then, you need to configure the size of Java Heap used by the application and optimize the resources used by the MicroEJ depending on the RAM available.

For more documentation on how to use MicroEJ SDK, refer to https://developer.microej.com/, in particular the following documents in the resource section:

- Device developer guide
- Application developer guide

The MicroEJ platform is configured with the following features:

- MEJ32 for ARM Cortex-M4 / GCC
- HAL.
- File System on SD Card.
- GUI on LCD Display ILI9340 connected to the SPI Pins
    - Display SCK - Arduino Pin 13
    - Display SDO(MISO) - Arduino Pin 12
    - Display SDI(MOSI) - Arduino Pin 11
    - Display CS - Arduino Pin 10
    - Display D/C - Arduino Pin 9
    - Display RESET - Arduino Pin 8

Arborescence
============

-  README.rst: The file you are currently reading.
-  microej: folders containing the implementation of the low level
   API of the MicroEJ Runtime and foundations libraries. The folder is named like that because Sony Spresense's SDK has a naming convention for apps in its SDK. Since microEJ is declared as an app inside the SDK, it is necessary to follow this convention.

   - audio/: Implementation of a simple audio player application (based on the example given in the SDK) with SNI functions for an easy Java interface.
   - core/: C sources file implementation of the core of the low level APIs of MicroEJ runtime.
   - fs/: C sources implementaton of the file system low level APIs.
   - gnss/: Implementation of a simple gnss application (based on the example given in the SDK) with SNI functions for an easy Java interface.
   - microej\_async\_worker/: C source library to execute asynchronous functions.
   - microej\_list/: C source library containing a linked list implementation.
   - osal/: C source library containing an operating system abstraction layer.
   - ui/: C sources files implementation for the Low Level APIs of the MicroUI display stack for the ILI9340 display.
   - microej\_main.c: C source file containing the entry point of the application.
   - inc/: Generated folder upon building your platform. Contains generated LLAPI headers.
   - lib/: Generated folder upon building your platform. Contains microej runtime library and microejapp object file containing your Java application.
   - Makefile

-  Sony-Spresense-CM4hardfp\_GCC48-configuration: Configuration files
   of the platform. Normally, you should not need to modify any of these.

   - bsp/bsp.properties: BSP property file (determine the output of the platform build).
   - display/display.properties: Display property file.
   - dropins/: Folder containing Java foundations libraries that will be integrated into the platform.
   - frontpanel/frontpanel.properties: frontpanel properties file.
   - fs/fs.properties: File system properties file.
   - microui/microui.properties: MicroUI (GUI Library) properties file.
   - mjvm/mjvm.properties: Embedded Java Virtual Machine Properties file.
   - Spresense.platform: Platform file.
   - .project: Eclipse's project file in order to easily import the platform into MicroEJ's SDK.

-  Sony-Spresense-CM4hardfp\_GCC48-fp/: Front panel folder
    - definitions
        - Sony-Spresense-CM4hardfp\_GCC48-fp.fp: The simulated display definition.
        - widget.desc: Internal file used by the front panel. You should not touch this file.
        - resources/: Contains the image of the front panel.

- configs
    - microej-defconfig: an importable Spresense SDK configuration file running microej given as example.

-  microej.mk: Specific Makefile rules to integrate MicroEJ Platform
   into Sony Spresense's SDK.
-  Application.mk: Makefile rules to declare and build a NuttX
   application as part of Spresense's SDK.
-  Makefile/: Makefile rules to declare and build a NuttX application
   as part of Spresense's SDK.
-  LibTarget.mk/: Makefile rules to declare and build a NuttX
   application as part of Spresense's SDK.
-  CHANGELOG.rst: CHANGELOG file


Setup & Versions
================

- The Sony Spresense SDK is made to work under a shell terminal; either a native Ubuntu, a Cygwin or using Windows Subsystem Linux (WSL).

- The Sony Spresense SDK version required is **v1.3.1**.

- For Windows 10 user or higher, we strongly suggest using WSL. How to install WSL:    https://docs.microsoft.com/en-us/windows/wsl/install-win10

- gcc-arm-none-eabi **v7.3.1** is required. You can find it at https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads

- MicroEJ Architecture packs version is 7.11.0, Pack FS version is 5.0.0, Pack UI version is 12.0.0, Pack HAL version 2.0.1
    - Download MicroEJ architecture 7.11 https://repository.microej.com/architectures/com/microej/architecture/CM4/CM4hardfp_GCC48/flopi4G25/7.11.0/flopi4G25-7.11.0-eval.xpf
    - Download Pack FS 5.0 https://repository.microej.com/architectures/com/microej/architecture/generic/fs/fs-pack/5.0.0/fs-5.0.0.xpfp
    - Download Pack UI 12.0 https://repository.microej.com/architectures/com/microej/architecture/CM4/CM4hardfp_GCC48/flopi4G25-ui-pack/12.0.0/flopi4G25UI-12.0.0.xpfp
    - Download Pack HAL 2.0.1 https://repository.microej.com/architectures/com/microej/architecture/generic/hal/hal-pack/2.0.1/hal-2.0.1.xpfp
    - You can install them in your SDK by going into Windows -> Preferences -> MicroEJ -> Architectures- > Import...

- MicroEJ SDK Version 19.05 or higher. You can download it at https://developer.microej.com/packages/SDK/19.05/.


Step-by-step Installation
==========================

- Step 0: Configure your bash environment.
    - The process is described here https://developer.sony.com/develop/spresense/docs/sdk_set_up_en.htm . Note that with windows 10 It is recommanded to use Windows Subsystem Linux instead of MSYS2 (steps are the same) for a better integration of the filesystems between Linux and Windows.
    - Install development tools:
        - :code:`wget https://raw.githubusercontent.com/sonydevworld/spresense/master/install-tools.sh`
        - :code:`bash install-tools.sh`
    - Source your envinronment :code:`source ~/spresenseenv/setup`
    - When using WSL along a Windows environment you may encounter issues with :literal:`\\r\\n` end of line. Using tools such as :literal:`dos2unix` utilities and :literal:`build-essential`.

- Step 1: Execute the following line to clone Spresense's SDK, checked out on the correct version (v1.3.1)
    - :code:`$ git clone https://github.com/sonydevworld/spresense.git`
    - :code:`$ cd spresense/`
    - :code:`$ git submodule update --init --recursive`
    - :code:`$ git checkout --recurse-submodules v1.3.1`
    - Step 1.1: Add MicroEJ to Spresense SDK
        - :code:`$ git submodule add https://github.com/MicroEJ/Platform-Sony-Spresense.git MicroEJ`

-  Step 2 : Install MicroEJ SDK (version 19.05).
    - Step 2.1: Download the SDK evaluation license from http://license.microej.com/ or get a production license. Verifiy that the version of each pack correspond to the versions in "Setup and Versions".
    - Step 2.2 : Install the architecure. Go to Windows -> Preferences -> MicroEJ -> Architecture -> Import...
    - Step 2.3: File -> Import... -> General -> Existing Projects into Workspace -> Select root directory -> Point to the MicroEJ directory.
    - Step 2.4: Open the Spresense.platform file. You may configure what is included in the MicroEJ platform in the Content tab by selecting content (or not).
    - Step 2.5: In the Overview tab, click on build platform.

-  Step 3: Create a Java Application.
    - Step 3.1: In MicroEJ SDK either open an existing app or create a new
        - MicroEJ Application with a simple hello world for now

    - Step 3.2: Select the folder of your project (for example :literal:`gui-example` from the getting-started). Then create a new MicroEJ Launcher.
    - Step 3.2: In the tab Execution, check that the selected Platform is correct. Then select "Execute on Simulator". This will run the Java application in the simulator.
    - Step 3.3: In Run -> Run Configuration... -> Tab execution,  check "Execute on Device". This will build a microejapp.o that contains your application.

- Step 4: Make sure the configuration of your SDK and NuttX is correct. For the NuttX configuration use the release configuration and enable the option :literal:`CONFIG_SYSTEMTICK_HOOK=y`.  :literal:`CONFIG_LIBM` must be disabled in the nuttx configuration.
    - **This MicroEJ Platform require a LCD** driver in the Spresense SDK configuration. Without a LCD Driver compiled in the BSP, symbols may be missing.
    - Step 4.1:
        - :code:`$ cd spresense/sdk`.
        - :code:`$ tools/config.py -k release` to configure the kernel using in release mode.
        - :code:`$ tools/config.py -k -m` then select :literal:`RTOS Features -> Clocks and Timers -> System timer hook`
        - Don't forget to save your configuration !
        - Type :code:`make buildkernel` to compile NuttX.
    - Step 4.2 :
        - For the SDK configuration, add :literal:`CONFIG_MICROEJ=y` and :literal:`CONFIG_LIBM_NEWLIB=y`:
            - :code:`$ tools/config.py -m` then select :literal:`Library Routines -> Newlib Math library` and :literal:`Microej -> microej runtime`.
            - Select :literal:`MicroEJ Audio Library LLAPIs` and :literal:`MicroEJ gnss library LLAPIs` if needed
        - Configure the spresense SDK; Enable the properties you need, configure your shared memory (if any), lcd screen (if any).
        - If you want to boot directly on the Java runtime change the entry point to "microej_main". If so, make sure the board ioctl init function :code:`boardctl(BOARDIOC_INIT, 0);` is called (it should be the case by default).
        - Don't forget to save your configuration !
    - Step 4.4: Type :code:`make` to compile your firmware. You can flash it on board following the instruction on Sony Spresense's website https://developer.sony.com/develop/spresense/developer-tools/get-started-using-nuttx/set-up-the-nuttx-environment . There also useful information in the ReadMe of the repository https://github.com/sonydevworld/spresense
    - Step 5: The default configuration should be to define the entry point as "microej_main" in the .config file. You can use NSH as entry point, in which case you need to type the command :code:`microvjm` in the NSH command line. I highly recommand using the default configuration to avoid loading the NSH library for nothing and to avoid a manual command to start your application.

Tasks running
==================================================
When running MicroEJ some tasks will be added to the RTOS.
These are the threads running on top of the existing tasks / threads from NuttX & Spresense SDK :

- UI Task: priority 100, stack size 1024 bytes.
- VM Task: priority 100, stack size 4096 bytes (can be changed using Kconfig, these are the default values).
- pthread GNSS: stack size 512 bytes.
- pthread pool for the file system implementation: 4 threads with 256 bytes stack (configurable).

Some audio tasks from the SDK:
Audio player : priority 150, stack size 3*1024 bytes.
Audio renderer : priority 200, stack size 3*1024 bytes.

Memory Map
==========

Code is stored in flash,executed in RAM.

Memory zone : ram (rwx) :
ORIGIN = 0x0d000000, LENGTH = 1536K, END\_MEMORY=0xd180000

PlatformHeap, Java application Heap, Java Immortals are allocated in the bss zone.

C-heap is the stack of the :code:`Idle` thread, defined relatively to end of the
bss zone. Increasing the size of compiled code (text zone), data (data,
rodata), size of diplay, Java heap(bss) or shared memory (defined
in .config) can break your application on board if not enough memory is available.

Several symptoms may appear, depending on which memory zone is impacted
and the memory allocation you are doing, such as :

- A failure to create task resulting in hardfault in os_startup.
- Code executing stopping without any uart trace.
- Impossibility to create a pthread (or a task), with a return code of 12 corresponding to the errno ENOMEM.

If the board suddenly stops working, this is the FIRST thing you should
check.


Additional informations
==================================================

Do NOT forget to flash the bootloader
-----------------------------------------------------

The first time you flash the board you will be directed to download a zip containing a firmware.

Error on link during the first compilation
---------------------------------------------------------
- When you flash a new board do not forget to flash the bootloader (read https://developer.sony.com/develop/spresense/developer-tools/get-started-using-nuttx/nuttx-developer-guide#_flashing_bootloader).
- The linker file given in the NuttX repository may not have the correct name. This result in the following error :literal:`arm-none-eabi-ld: cannot open linker script file spresense/sdk/../nuttx/configs/cxd56evb/scripts/gnu-elf.ld: No such file or directory`. To solve this you can simply create a symlink with the expected name :
    - :code:`$ cd spresense//nuttx/configs/cxd56evb/scripts/`
    - :code:`$ ln -s ramconfig.ld gnu-elf.ld`

Explore the Spresense SDK
--------------------------------------------------------
- There are lots of examples in the SDK! To better understand how to configure your Spresense SDK, start by using the provided example.

- The Spresense SDK is highly configurable. The configuration of the SDK will have a great impact on the amount of RAM available and the functionnalities available. We recommend first configuring your SDK and then starting the integration of your Java application on board. You will have to configure the Java heap and Image heap you use depending on the size of your application and the available ram.


Be wary of your RAM usage
----------------------------------------------------------------------
If some hardfaults occurs, the board do not start or suddenly stops (without any UART trace), asserts fails, it is often due to a lack of RAM.

This probably means that your Java application uses too much resources. When you use microEJ you add areas in RAM with a fixed size in your Run Configuration... .

A wrong size given the Run Configuration... of your Java application can cause problems on-board.

This is why it is critical to use the simulator to find the minimum resources you can use for your application in RAM and also to correctly configure your Spresense SDK during your development process, if you encounter a bug as previously described the FIRST thing you need to check is how much RAM you use in the Java Heap, Image Heap in your MicroEJ Run Configuration... and how much memory you use in the SDK and-application code.


gperf3.1 error on some systems
-------------------------------------------------------------------

When installing kconfig front end for the Spresense SDK setup you may encouter this problem :

If your system has gperf 3.0.4 or earlier, you may safely skip this chapter. gperf 3.1 (released on 5th January of 2017) changed the type used as length argument in generated functions from unsigned int to size_t. This will cause your build to fail with following error message:

::

    CC     libkconfig_parser_la-yconf.lo
    In file included from yconf.c:234:0:
    hconf.gperf:141:1: error: conflicting types for 'kconf_id_lookup'
    hconf.gperf:12:31: note: previous declaration of 'kconf_id_lookup' was here
    static const struct kconf_id *kconf_id_lookup(register const char *str, register unsigned int len);

    make[3]: *** [Makefile:456: libkconfig_parser_la-yconf.lo] Error 1
    make[2]: *** [Makefile:350: all] Error 2
    make[1]: *** [Makefile:334: all-recursive] Error 1
    make: *** [Makefile:385: all-recursive] Error 1

- The procedure to fix is below:
    - :code:`$ curl -O https://gist.githubusercontent.com/KamilSzczygiel/d16a5d88075939578f7bd8fadd0907aa/raw/1928495cfb6a6141365d545a23d66203222d28c0/kconfig-frontends.patch`
    - :code:`$ patch -p1 -i kconfig-frontends.patch`
    - :code:`$ autoreconf -fi`

- To use the Audio and Gnss library in Java you must add to the configuration CONFIG_MICROEJ_AUDIOPLAYER and CONFIG_MICROEJ_GNSS respectively.

- When the MicroEJ project is modified, clean the Spresense SDK directory with make clean & make cleankernel (before flashing the board).

Note on multicore
==================

The MicroEJ runtime environment is executed in internal RAM on the main CPU of the board.
It is perfectly possible to execute code in parallel on other CPU while the MicroEJ runtime environment is running.