MicroEJ Developer
Get Started



Platforms are built for MicroEJ SDK evaluation version and will not run on MicroEJ SDK commercial version. Contact MicroEJ to get the commercial version of the platforms.


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

The Platform sources V1.7.0 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:
9 March 2021
+
..
    Copyright 2019-2021 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.

.. |BOARD_NAME| replace:: ESP-WROVER-KIT V4.1
.. |BOARD_REVISION| replace:: 4.1
.. |PLATFORM_VER| replace:: 1.6.2
.. |RCP| replace:: MICROEJ SDK
.. |PLATFORM| replace:: MicroEJ Platform
.. |PLATFORMS| replace:: MicroEJ Platforms
.. |SIM| replace:: MicroEJ Simulator
.. |ARCH| replace:: MicroEJ Architecture
.. |CIDE| replace:: MICROEJ SDK
.. |RTOS| replace:: FreeRTOS RTOS
.. |MANUFACTURER| replace:: Espressif

.. _中文版: ./docs/zn_CH/README_CN.rst
.. _README MicroEJ BSP: ./ESP32-WROVER-Xtensa-FreeRTOS-bsp/Projects/microej/README.rst
.. _RELEASE NOTES: ./RELEASE_NOTES.rst
.. _CHANGELOG: ./CHANGELOG.rst

==========================================
|PLATFORM| for |MANUFACTURER| |BOARD_NAME|
==========================================

`中文版`_

This project is used to build a |PLATFORM| for the |BOARD_NAME|
development board.

.. image:: ./images/esp-wrover-kit-v4.1-front.jpg

Clone the repository with ``git clone --recursive https://github.com/MicroEJ/Platform-Espressif-ESP-WROVER-KIT-V4.1``.

Related Files
=============

This directory also contains:

* `CHANGELOG`_ to track the changes in the MicroEJ
  |BOARD_NAME| Platform
* `RELEASE NOTES`_ to list:

  - the supported hardware,
  - the known issues and the limitations,
  - the development environment,
  - the list of the dependencies and their versions.

* `README MicroEJ BSP`_ recommended for users familiar with the
  |MANUFACTURER| IDF and advanced usage on how to customize the build
  process.

Board Technical Specifications
==============================

.. list-table::

   * - Name
     - |BOARD_NAME|
   * - Revision
     - |BOARD_REVISION|
   * - MCU part number
     - ESP32-WROVER-B
   * - MCU revision
     - N/A
   * - MCU architecture
     - Xtensa LX6
   * - MCU max clock frequency
     - 240 MHz
   * - Internal flash size
     - 540 KB
   * - Internal RAM size
     - 520 KB
   * - External flash size
     - 4 MB
   * - External RAM size
     - 8 MB 
   * - Power supply
     - USB, External 5V

Here is a list of |BOARD_NAME| useful documentation links:

- Board documentation available `here <https://docs.espressif.com/projects/esp-idf/en/v3.3.4/hw-reference/modules-and-boards.html#esp-wrover-kit-v4-1>`__
- |MANUFACTURER| board Getting Started available `here <https://docs.espressif.com/projects/esp-idf/en/v3.3.4/get-started/get-started-wrover-kit.html>`__
- Board schematics available `here <https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_V4_1.pdf>`__
- MCU Technical Reference Manual available `here <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`__
- MCU Datasheet available `here <https://espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`__
- MCU Errata available `here <https://espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf>`__

Platform Specifications
=======================

The Architecture version is ``7.14.0``.

This Platform provides the following Foundation Libraries:

.. list-table::
   :header-rows: 1

   * - Foundation Library
     - Version
   * - BLUETOOTH
     - 2.0
   * - BON
     - 1.4
   * - DEVICE
     - 1.1
   * - ECOM
     - 1.1
   * - ECOM-COMM
     - 1.1
   * - ECOM-NETWORK
     - 2.0
   * - ECOM-WIFI
     - 2.1
   * - EDC
     - 1.3
   * - ESP_IDF
     - 1.0
   * - FS
     - 2.0
   * - HAL
     - 1.0
   * - KF
     - 1.5
   * - MICROUI
     - 2.4
   * - NET
     - 1.1
   * - SECURITY
     - 1.3
   * - SNI
     - 1.4.0
   * - SSL
     - 2.2
   * - TRACE
     - 1.1

The |PLATFORM| is derived into:

- a Mono-Sandbox Platform (default)
- a Multi-Sandbox Platform

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

- PC with Windows 10 or Linux (tested with Ubuntu LTS 20.04)
- Internet connection to `MicroEJ Central Repository <https://developer.microej.com/central-repository/>`_
- |RCP| Dist. ``20.12`` or higher, available `here <https://developer.microej.com/get-started/>`_
- |BOARD_NAME| board

BSP Setup
=========

Install the |MANUFACTURER| toolchain as described `here
<https://docs.espressif.com/projects/esp-idf/en/v3.3.4/get-started/index.html#setup-toolchain>`__.

Windows Toolchain
-----------------

- C/C++ toolchain name:
  esp32_win32_msys2_environment_and_toolchain_idf3-20200714
- C/C++ toolchain version: 20200714
- C/C++ toolchain download link:
  https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain_idf3-20200714.zip

Please refer to the |MANUFACTURER| documentation available `here
<https://docs.espressif.com/projects/esp-idf/en/v3.3.4/get-started/windows-setup.html>`__
for more details.

Linux Toolchain
---------------

- C/C++ toolchain name: xtensa-esp32-elf-linux
- C/C++ toolchain version: 1.22.0-96-g2852398-5.2.0
- C/C++ toolchain download link for 64-bit Linux:
  https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-96-g2852398-5.2.0.tar.gz
- C/C++ toolchain download link for 32-bit Linux:
  https://dl.espressif.com/dl/xtensa-esp32-elf-linux32-1.22.0-96-g2852398-5.2.0.tar.gz

Please refer to the |MANUFACTURER| documentation available `here
<https://docs.espressif.com/projects/esp-idf/en/v3.3.4/get-started/linux-setup.html>`__
for more details.

BSP Compilation
---------------

The Platform provides a pre-compiled Mono-Sandbox Application.
Validate the BSP installation by compiling the BSP to build a MicroEJ
Firmware.

To build the ``ESP32-WROVER-Xtensa-FreeRTOS-bsp`` project, open a
terminal and enter the following command lines:

**On Windows:**

.. code-block:: sh

      $ cd "xxx/ESP32-WROVER-Xtensa-FreeRTOS-bsp/Projects/microej/scripts"
      $ build.bat 

**On Linux / macOS:**

.. code-block:: sh

      $ cd "xxx/ESP32-WROVER-Xtensa-FreeRTOS-bsp/Projects/microej/scripts"
      $ build.sh 

The BSP project build is launched. Please wait for the final message:

.. code-block::

      To flash all build output, run 'make flash' or:

The build script expects the toolchain to be installed at a known
path.  If you installed it elsewhere, see `README MicroEJ BSP`_ for
how to customize its path.


Please refer to the |MANUFACTURER| documentation available `here
<https://docs.espressif.com/projects/esp-idf/en/v3.3.4/get-started/linux-setup.html>`__.

Please refer to `README MicroEJ BSP`_ for more details on how to
customize the build scripts.

Board Setup
===========

Please refer to the |MANUFACTURER| documentation available `here
<https://docs.espressif.com/projects/esp-idf/en/v3.3.4/get-started/get-started-wrover-kit.html>`__
for more details.

Power Supply
------------

The board can be powered by USB cable or external 5V power supply.

Please refer to the Espressif documentation available `here
<https://docs.espressif.com/projects/esp-idf/en/v3.3.4/get-started/get-started-wrover-kit.html>`__
for more details.

Programming
-----------

The |BOARD_NAME| board can be flashed using |MANUFACTURER|
bootloader. Please Follow the steps below:

- Connect the USB connector of the board to your computer
- Take a look at the new COM port available
- Edit the
  ``ESP32-WROVER-Xtensa-FreeRTOS-bsp-bsp/Projects/microej/scripts/run.xxx``
  script (where ``xxx`` is ``bat`` for Windows and ``sh`` for Linux /
  macOS). Update the ``ESPPORT`` variable to put the newly COM port
  discovered previously and uncomment the associated line if not
  already done.
- Open a terminal and enter the following command lines:

**On Windows:**

.. code-block:: sh

      $ cd "xxx/ESP32-WROVER-Xtensa-FreeRTOS-bsp/Projects/microej/scripts"
      $ run.bat 

**On Linux / macOS:**

.. code-block:: sh

      $ cd "xxx/ESP32-WROVER-Xtensa-FreeRTOS-bsp/Projects/microej/scripts"
      $ run.sh 

The firmware is launched. Please wait for the final message:

.. code-block::

      Leaving...
      Hard resetting via RTS pin...

|MANUFACTURER| build and flash documentation are also available `here
<https://docs.espressif.com/projects/esp-idf/en/v3.3.4/get-started/index.html#build-and-flash>`__
for more details.

Logs Output
-----------

MicroEJ platform uses the virtual UART from the |BOARD_NAME|
USB port.  A COM port is automatically mounted when the board is
plugged to a computer using USB cable.  All board logs are available
through this COM port.

The COM port uses the following parameters:

.. list-table::
   :widths: 3 2

   * - Baudrate
     - 115200
   * - Data bits bits
     - 8
   * - Parity bits
     - None
   * - Stop bits
     - 1
   * - Flow control
     - None

If flashed, the pre-compiled application outputs ``Hello World`` on
the UART.

When running a Testsuite, logs must be redirected to a secondary UART
port.  Please refer to `Testsuite Configuration`_ for a detailed
explanation.

Please refer to the |MANUFACTURER| documentation available `here
<https://docs.espressif.com/projects/esp-idf/en/v3.3.4/get-started/establish-serial-connection.html>`__
for more details.

Debugging
---------

A JTAG interface is also directly available through the USB interface.

Please refer to the `README MicroEJ BSP`_ section debugging for more
details.

Platform Setup
==============

Platform Import
---------------

Import the projects in |RCP| Workspace:

- ``File`` > ``Import`` > ``Existing Projects into Workspace`` >
  ``Next``
- Point ``Select root directory`` to where the project was cloned.
- Click ``Finish``

Inside |RCP|, the selected example is imported as several projects
prefixed by the given name:

- ``ESP32-WROVER-Xtensa-FreeRTOS-configuration``: Contains the
  platform configuration description. Some modules are described in a
  specific sub-folder / with some optional configuration files
  (``.properties`` and / or ``.xml``).

- ``ESP32-WROVER-Xtensa-FreeRTOS-bsp``: Contains a ready-to-use BSP
  software project for the |BOARD_NAME| board, including a
  |CIDE| project, an implementation of MicroEJ core engine (and
  extensions) port on |RTOS| and the |BOARD_NAME| board
  support package.

- ``ESP32-WROVER-Xtensa-FreeRTOS-fp``: Contains the board description
  and images for the |SIM|. This project is updated once the platform
  is built.

- ``ESP32WROVER-Platform-GNUv52b96_xtensa-esp32-psram-{version}``:
  Contains the |RCP| Platform project which is empty by default until
  the Platform is built.

By default, the Platform is configured as a Mono-Sandbox Evaluation
Platform.  If the Platform is configured as Multi-Sandbox, use the
``build_no_ota_no_systemview`` script (Please refer to the `RELEASE
NOTES`_ limitations section for more details).

Platform Build
--------------

To build the Platform, please follow the steps below:

- Right-click on ``ESP32-WROVER-Xtensa-FreeRTOS-configuration``
  project in your |RCP| workspace.
- Click on ``Build Module``

The build starts.  This step may take several minutes.  The first
time, the Platform build requires to download modules that are
available on the MicroEJ Central Repository.  You can see the progress
of the build steps in the MicroEJ console.

Please wait for the final message:

.. code-block::

                          BUILD SUCCESSFUL

At the end of the execution the |PLATFORM| is fully built for the
|BOARD_NAME| board and is ready to be linked into the |CIDE|
project.


The Platform project should be refreshed with no error in the |RCP|
``ESP32WROVER-Platform-GNUv52b96_xtensa-esp32-psram-{version}``.

Please refer to
https://docs.microej.com/en/latest/ApplicationDeveloperGuide/standaloneApplication.html
for more information on how to build a MicroEJ Standalone Application.

An evaluation license is needed for building an application. Please refer to
https://docs.microej.com/en/latest/overview/licenses.html#evaluation-license
for information on how to acquire and activate a license.

Testsuite Configuration
=======================

To run a Testsuite on the |BOARD_NAME| board the standard output must
be redirected to a dedicated UART.  The property
``microej.testsuite.properties.debug.traces.uart`` must be set in the
``config.properties`` of the Testsuite.

This property redirects the UART onto a different GPIO port. Connect a
FTDI USB wire to the pin D0 of the JP4 connector and ground.

.. image:: ./images/testsuite_plug_uart_wrover.JPG

In ``config.properties``, the property ``target.platform.dir`` must be
set to the absolute path to the platform.  For example
``C:/Platform-Espressif-ESP-WROVER-KIT-V4.1/ESP32-WROVER-Xtensa-FreeRTOS-platform/source``.

Testsuite FS
------------

A ``config.properties`` and ``microej-testsuite-common.properties``
are provided in
``ESP32-WROVER-Xtensa-FreeRTOS-configuration/testsuites/fs/``.

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

esp-idf/make/project.mk: No such file or directory
--------------------------------------------------

.. code-block::

   Makefile:11: Platform-Espressif-ESP-WROVER-KIT-V4.1/ESP32-WROVER-Xtensa-FreeRTOS-bsp/Projects/microej/../../Drivers/esp-idf/make/project.mk: No such file or directory
   make: *** No rule to make target 'P0065_ESP32-WROVER-Platform/ESP32-WROVER-Xtensa-FreeRTOS-bsp/Projects/microej/../../Drivers/esp-idf/make/project.mk'.  Stop.
   cp: cannot stat 'build/microej.elf': No such file or directory

Ensure you have cloned the repository and all its submodules.  Use the following command to synchronize the submodules:

.. code-block:: sh

   git submodule update --init --recursive

Unable to flash on Linux through VirtualBox
-------------------------------------------

Press the "boot" button on the board while flashing.

Files not found during the build
--------------------------------

Errors about files not found during the build may be caused by long
path.  Please refer to the known issues and limitations in the
`RELEASE NOTES`_ for a workaround.

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:
27 November 2020
+
..
    Copyright 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.

.. |RI_NAME| replace:: STM32F7508-DK demo platform
.. |RI_VER| replace:: v1.2.0

========================================
 Readme: MicroEJ STM32F7508-DK Platform
========================================

This project is used to build the MicroEJ demo platform for the
STM32F7508-DK development board.
It is recommended to read this tutorial before using the platform: https://docs.microej.com/en/latest/Tutorials/tutorialUnderstandMicroEJFirmwareBuild.html

Configurations
==============

The |RI_NAME| |RI_VER| is declined into:

- a Mono-Sandbox platform usable with GCC toolchain (UID: M5QNX),
- a Multi-Sandbox platform usable with GCC toolchain (UID: R0OUY),
- a Mono-Sandbox platform usable with IAR toolchain (UID: KUVW3),
- a Multi-Sandbox  platform usable with IAR toolchain (UID: R5S8K).

Those declinations are themselves declined into:

- an evaluation platform (eval):

  - based on MicroEJ evaluation architecture
  - requires a SDK evaluation license from https://license.microej.com/.
  - When limitation is reached, the MicroEJ runtime will terminate. Exit code
    is described in the MicroEJ Device Developer's Guide provided with your SDK.

- a development platform (dev):

  - based on MicroEJ production architecture
  - requires a SDK USB dongle license.
  - Development (production) platforms do not implement any limitations. If used properly, the
    platform runs indefinitely or within the limits of the development board.

Mono-Sandbox Platform
---------------------

The Mono-Sandbox  platform is designed to give optimum performances and
resources for a single application firmware.
It embeds a specific MicroEJ runtime for this purpose.

Multi-Sandbox Platform
----------------------

The Multi-Sandbox platform is designed for multiple application firmware.
It embeds a specific MicroEJ runtime for this purpose.

Getting Started
===============

The STM32F7508-DK `SDK Getting Started`_ explains how to start the SDK using the
MicroEJ reference implementation platform with the STM32F7508-DK.

.. _SDK Getting Started: https://developer.microej.com/evaluate-microej-gui-features/get-started-ui-development-on-stm32f7508-dk-platform/

.. _output-stream:

Platform Output Stream
======================

The platform uses the virtual UART from the USB port *USB ST-LINK*.

The COM port uses the following parameters:

- Baudrate: 115200
- Data bits bits: 8
- Parity bits: None
- Stop bits: 1
- Flow control: None

Other files to read
===================

This directory also contains

* `CHANGELOG <./CHANGELOG.rst>`_ to track the changes in the MicroEJ
  STM32F7508-DK demo platform
* `RELEASE NOTES <./RELEASE_NOTES.rst>`_ to list:

  - the supported hardware,
  - the known issues and the limitations,
  - the development environment,
  - the list of the dependencies and their versions.

STM32F7508-DK Platform (MonoSandbox, IAR, 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-MoIF-KUVW3
Last updated:
27 November 2020
+
..
    Copyright 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.

.. |RI_NAME| replace:: STM32F7508-DK demo platform
.. |RI_VER| replace:: v1.2.0

========================================
 Readme: MicroEJ STM32F7508-DK Platform
========================================

This project is used to build the MicroEJ demo platform for the
STM32F7508-DK development board.
It is recommended to read this tutorial before using the platform: https://docs.microej.com/en/latest/Tutorials/tutorialUnderstandMicroEJFirmwareBuild.html

Configurations
==============

The |RI_NAME| |RI_VER| is declined into:

- a Mono-Sandbox platform usable with GCC toolchain (UID: M5QNX),
- a Multi-Sandbox platform usable with GCC toolchain (UID: R0OUY),
- a Mono-Sandbox platform usable with IAR toolchain (UID: KUVW3),
- a Multi-Sandbox  platform usable with IAR toolchain (UID: R5S8K).

Those declinations are themselves declined into:

- an evaluation platform (eval):

  - based on MicroEJ evaluation architecture
  - requires a SDK evaluation license from https://license.microej.com/.
  - When limitation is reached, the MicroEJ runtime will terminate. Exit code
    is described in the MicroEJ Device Developer's Guide provided with your SDK.

- a development platform (dev):

  - based on MicroEJ production architecture
  - requires a SDK USB dongle license.
  - Development (production) platforms do not implement any limitations. If used properly, the
    platform runs indefinitely or within the limits of the development board.

Mono-Sandbox Platform
---------------------

The Mono-Sandbox  platform is designed to give optimum performances and
resources for a single application firmware.
It embeds a specific MicroEJ runtime for this purpose.

Multi-Sandbox Platform
----------------------

The Multi-Sandbox platform is designed for multiple application firmware.
It embeds a specific MicroEJ runtime for this purpose.

Getting Started
===============

The STM32F7508-DK `SDK Getting Started`_ explains how to start the SDK using the
MicroEJ reference implementation platform with the STM32F7508-DK.

.. _SDK Getting Started: https://developer.microej.com/evaluate-microej-gui-features/get-started-ui-development-on-stm32f7508-dk-platform/

.. _output-stream:

Platform Output Stream
======================

The platform uses the virtual UART from the USB port *USB ST-LINK*.

The COM port uses the following parameters:

- Baudrate: 115200
- Data bits bits: 8
- Parity bits: None
- Stop bits: 1
- Flow control: None

Other files to read
===================

This directory also contains

* `CHANGELOG <./CHANGELOG.rst>`_ to track the changes in the MicroEJ
  STM32F7508-DK demo platform
* `RELEASE NOTES <./RELEASE_NOTES.rst>`_ to list:

  - the supported hardware,
  - the known issues and the limitations,
  - the development environment,
  - the list of the dependencies and their versions.

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
+

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
+

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.