ALL
ALL
5.x
ANY
https://github.com/MicroEJ/AbstractionLayer-Core-ThreadX/tree/1.1.0
OS Abstraction Layer for ThreadX
Low Level MicroEJ Core Engine API implementation over ThreadX.
LIBRARY for CORE
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
21 July 2022
# Overview
Low Level MicroEJ Core Engine API implementation over ThreadX.
This component implements the `LLMJVM` Low Level API for MicroEJ Platforms connected to a Board Support Package based on [Azure RTOS ThreadX](https://azure.microsoft.com/en-us/services/rtos/).
See the MicroEJ documentation for a description of the `LLMJVM` functions:
- [LLMJVM: MicroEJ Core Engine](https://docs.microej.com/en/latest/PlatformDeveloperGuide/appendix/llapi.html#llmjvm-microej-core-engine)
- [MicroEJ Core Engine: Implementation](https://docs.microej.com/en/latest/PlatformDeveloperGuide/coreEngine.html#implementation)
# Usage
1. Install ``src`` and ``inc`` directories in your Board Support Package. They can be automatically downloaded using the following command lines:
```sh
svn export --force https://github.com/MicroEJ/AbstractionLayer-Core-ThreadX/trunk/inc [path_to_bsp_directory]
svn export --force https://github.com/MicroEJ/AbstractionLayer-Core-ThreadX/trunk/src [path_to_bsp_directory]
```
2. Implement the MicroEJ time functions, as described in [microej_time.h](./inc/microej_time.h).
3. The `LLMJVM_IMPL_scheduleRequest` schedule request function in [LLMJVM_ThreadX.c](./src/LLMJVM_ThreadX.c) uses a software timer. In order to correctly schedule MicroEJ threads, check the following elements in the ThreadX configuration file:
- `TX_TIMER_TICKS_PER_SECOND`: can depend on the application, if it needs a 1 ms precision then the tick rate would be 1000 Hz, the recommended value is between 100 Hz and 1000 Hz
# Requirements
None.
# Validation
This Abstraction Layer implementation can be validated in the target Board Support Package using the [MicroEJ Core Validation](https://github.com/MicroEJ/PlatformQualificationTools/tree/master/tests/core/java/microej-core-validation) Platform Qualification Tools project.
Here is a non exhaustive list of tested environments:
- Hardware
- STMicroelectronics STM32F746-DISCOVERY
- Compilers / development environments:
- IAR Embedded Workbench 8.50.6
- ThreadX / Azure RTOS versions:
- 6.1
## MISRA Compliance
The implementation is MISRA-compliant (MISRA C 2004) with the following observed deviations:
| Deviation | Category | Justification |
|:---------:|:--------:|:-------------------------------------------------------------------------------------------------------------:|
| Rule 6.3 | Advisory | A deviation from this rule is applied so as to use the bool type from `<stdbool.h>`. |
| Rule 11.3 | Advisory | A deviation from this rule is unavoidable as ThreadX's handles (timers, queues, tasks) are pointers to void. |
# Dependencies
- MicroEJ Architecture ``7.x`` or higher.
- Azure RTOS ThreadX ``6.1`` or higher.
# Source
N/A.
# Restrictions
None.
---
_Copyright 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._
https://github.com/MicroEJ/AbstractionLayer-Security-MbedTLS/tree/1.0.0
Security Abstraction Layer for mbedTLS
Low Level MicroEJ Security API implementation for MbedTLS.
EXAMPLE for NETSEC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
21 July 2022
# Overview
Low Level MicroEJ Security API implementation for MbedTLS.
This component implements the `LLSEC` Low Level API for MicroEJ platforms connected to a Board Support Package based on MbedTLS.
# Usage
Add the following line to your `module.ivy` file:
> `<dependency org="com.microej.clibrary.llimpl" name="security-mbedtls" rev="..."/>`
# Requirements
N/A
# Validation
Here is a non exhaustive list of tested environments:
- Hardware
- Espressif ESP-WROVER-KIT V4.1
- Compilers / Integrated Development Environments:
- Espressif IoT Development Framework (``esp-idf``) v3.3.4 and v4.3.2 (using GNU GCC toolchain)
- MbedTLS versions:
- MbedTLS v2.16.5 and v2.16.11
# MISRA Compliance
This Abstraction Layer implementation is MISRA-compliant (MISRA C:2012) with some noted exception.
It has been verified with Cppcheck v2.8.0. Here is the list of deviations from MISRA standard:
| Deviation | Category | Justification |
|:----------:|:--------:|:------------------------------------------------------------------ |
| Rule 8.4 | Required | The Cppcheck analysis is made only on this LL code |
| Rule 8.7 | Advisory | The Cppcheck analysis is made only on this LL code |
| Rule 8.9 | Advisory | Global variable or for code readability |
| Rule 10.8 | Required | Boundries of the value is controlled |
| Rule 11.1 | Required | Abstract data type for SNI usage |
| Rule 11.3 | Required | Cast for matching MbedTLS function signature |
| Rule 11.4 | Advisory | Abstract data type for SNI usage |
| Rule 11.5 | Advisory | Abstract data type for SNI usage |
| Rule 11.6 | Required | Abstract data type for SNI usage |
| Rule 11.8 | Required | Cast to match used generic library function ```mbedtls_free``` |
| Rule 17.8 | Advisory | Used as an output parameter |
| Rule 21.6 | Required | Used for debug purpose only |
| Rule 21.10 | Required | Type defined in library used in MbedTLS |
# Dependencies
- MicroEJ Architecture `7.x` or higher.
- MbedTLS `v2.16.5` or higher.
# Source
N/A
# Restrictions
None.
---
_Copyright 2021-2022 MicroEJ Corp. All rights reserved._
_Use of this source code is governed by a BSD-style license that can be found with this software._https://github.com/MicroEJ/Demo-Wearable/tree/1.0.1
A minimal sample of a watch application.
EXAMPLE for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
12 July 2022
# Overview
This project contains a minimal sample of a watch application.
It consists in:
- an analog watchface
- an scrollable list of applications
## Application flow
The user can go from the watchface to the application list and vice versa by pressing the physical button.
Clicking on an item of the list opens a new page with the item's information. Pressing the button goes back to the list.
## Main classes
### WatchExample class
It is the entry point of the application.
At boot, it does the following steps:
1. starts the MicroUI framework.
2. creates a desktop, a placeholder for the application widget tree.
3. creates the watchface and sets it as the root widget of the desktop.
4. shows the desktop on the display.
This class also provides convenient methods for navigating from one view to the other.
### Watchface class
This class implements a widget that displays three hands (hour, minute, second) and a full-screen background image.
### ApplicationList class
A widget that represents a scrollable list. It contains other widgets (the application items, see class `ApplicationListItem`).
### ApplicationListItem class
A widget that represents an item of the application list. It displays the icon and name of applications. Note that for purposes of performances, an image of the name is drawn rather than the text itself: drawing an image is faster than drawing a string.
# Usage
This application has been tested on the STM32L4R9 platform available here: <https://github.com/MicroEJ/Platform-STMicroelectronics-STM32L4R9-DISCO>
## Run on the Virtual Device
1. Right-click on this project
2. Select `Run As` > `MicroEJ Application`
3. Select `WatchExample (Simulator)`
4. Click `Ok`
The application runs on the Virtual Device.
## Run on the device
1. Right-click on this project
2. Select `Run As` > `MicroEJ Application`
3. Select `WatchExample (Device)`
4. Click `Ok`
Upon success:
- The MicroEJ Application file `microejapp.o` has been deployed to `${root.dir}`/`${microejapp.relative.dir}`.
- The MicroEJ Platform runtime file `microejruntime.a` has been deployed to `${root.dir}`/`${microejlib.relative.dir}`.
- The platform header files `*.h` have been deployed to `${root.dir}`/`${microejinc.relative.dir}`.
- The BSP is compiled and linked using the C toolchain.
5. Program the firmware to the target device. You may use the `run.bat` script of the platform to program the device.
Notes:
- The above properties are platform options, they are set in the `bsp/bsp.properties` file of the platform configuration project (`*-configuration)`. They provide a flexible way to configure the BSP connection to target any kind of projects, teams organizations and company build flows. More about BSP Connection: <https://docs.microej.com/en/latest/PlatformDeveloperGuide/platformCreation.html#bsp-connection>.
# Requirements
This library requires the following Foundation Libraries:
EDC-1.3, BON-1.4, MICROUI-3.0, DRAWING-1.0
# Dependencies
_All dependencies are retrieved transitively by MicroEJ Module Manager_.
# Source
N/A.
# Restrictions
None.
---
_Copyright 2022 MicroEJ Corp. All rights reserved._
_Use of this source code is governed by a BSD-style license that can be found with this software._
https://github.com/MicroEJ/ExampleJava-AWS/tree/2.0.0
Demonstration of use of the library for AWS IoT Core.
EXAMPLE for IOT
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
5 July 2022
# Overview
 
This repository contains a usage example of MICROEJ AWS IoT SDK.
It shows the following features:
- AWS Just In Time Provisioning of an IoT device
- AWS MQTT TLS Connection Configuration
- AWS MQTT Publish/Subscribe to a topic
- AWS Device Shadow management (CRUD)
MICROEJ AWS IoT SDK documentation can be found [here](https://repository.microej.com/modules/ej/library/iot/aws-iot/2.0.0/README-2.0.0.md)
# Requirements
This example requires the following:
* An AWS account. It can be created from [AWS console](https://aws.amazon.com/console/)
* MICROEJ SDK Dist `20.12` or higher. It can be downloaded from [MicroEJ Developer Portal](http://developer.microej.com/getting-started-sdk.html)
* A Platform providing the following Foundation Libraries:
* EDC-1.2
* BON-1.3
* NET-1.1
* SSL-2.1
* ECOM-WIFI-2.1
* ECOM-NETWORK-2.0
This example has been tested on the [Platform for Espressif ESP-WROVER-KIT V4.1 v2.0.0](https://github.com/MicroEJ/Platform-Espressif-ESP-WROVER-KIT-V4.1/tree/2.0.0).
# Usage
## Import project & Platform to SDK
* Clone this repository
* Start the SDK and import the Git repository into it:
* From top menu, Go to `File` > `Import...`
* Then `General` > `Existing Project into Workspace`
* Select root directory where the project was cloned
* Click `Finish` button
* Import the Platform into the SDK. See Requirements Section.
* Clone the Platform Git project
* From top menu, Go to `File` > `Import...`
* `General` > `Existing Project into Workspace`
* Select root directory where the project was cloned
* Click `Finish` button
* Build the Platform
* Right Click on the `ESP32-WROVER-Xtensa-FreeRTOS-configuration`
* Select `Build Module`
* Wait for the build to finish and import the result to the workspace. Note that the project may be already imported. If it's the case just refresh it.
## Launching the AWS IoT Demo
### Getting ready with AWS IoT
* Set up your AWS account by following [this AWS guide](https://docs.aws.amazon.com/iot/latest/developerguide/setting-up.html)
* Generate the authority and device certificates, and the provisioning template. Then, register the authority certificate in AWS IoT Core Service by following [this AWS guide](https://aws.amazon.com/blogs/iot/setting-up-just-in-time-provisioning-with-aws-iot-core/).
* **Important notes**
* In the section `Create a provisioning template`, allow the necessary actions for this example to work. You can put `[iot:*]` in the `Action:` field of the template instead of `[iot:Connect,iot:Publish]` (escape characters omitted) to allow all the actions. The full list of AWS IoT policy actions can be found [here](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policy-actions.html)
* The last part using `mosquitto_pub` to test the connection and the JIT provisioning at the first connection can be skipped as it will be covered by this example.
### Getting ready with the certificates
At this step you should have the following files:
* `rootCA.pem`: Root CA certificate in PEM format
* `deviceCert.crt`: Device X509 certificate in PEM format
* `deviceCert.key`: Device private key in PEM format.
`deviceCert.key` needs to be converted to DER format, as this is the format supported by the Platform today.
* Convert `deviceCert.key` to DER format using [OpenSSL](https://www.openssl.org/source/) by running the following command:
```powershell
openssl.exe pkcs8 -inform PEM -in deviceCert.key -topk8 -outform DER -out deviceCert.der -v1 PBE-SHA1-3DES -passout pass:awsdemo
```
* Place the 3 files into `src\main\resources\certificates\device` folder.
#### Note
If the files naming doesn't match this documentation, it can be adapted by changing `com.microej.demo.aws.iot.constants.list` and `com.microej.demo.aws.iot.resources.list` files
### Getting ready with the application configuration
* Get the AWS IoT server `hostname` (endpoint), For that go to:
* Connect to `AWS Console`
* Go to `Iot Core` Service
* From the left menu, go to `Settings`
* Copy the endpoint from the setting page. It looks something like `*.iot.eu-west-3.amazonaws.com`
* Configure the application by changing the following values in `src\main\resources\com.microej.demo.aws.iot.constants.list`
```properties
###################################################
# AWS IoT Broker Configuration
###################################################
aws.url=<AWS IoT Server Host Name>
```
### Launching the demo on Simulator
* Right click on the project and select `Run As` > `MicroEJ Application`
* Select `com.microej.demo.aws.iot.Main` class in the `Select Java Application` wizard
* Select a compatible Platform from the `Select a Platform` wizard
* Follow the instructions from the application logs to configure the WIFI network
The traces should look like this :
```java
=============== [ Initialization Stage ] ===============
Using default Platform kernel.kf
=============== [ Launching on Simulator ] ===============
com.microej.demo.aws.iot.main INFO: Starting WIFI Setup
com.microej.demo.aws.iot.main INFO: Please connect to the board SOFT Access Point WIFI network
com.microej.demo.aws.iot.wifi INFO: Scan:
com.microej.demo.aws.iot.wifi INFO: -myFirstSSid
com.microej.demo.aws.iot.wifi INFO: -mySecondSSid
com.microej.demo.aws.iot.main INFO: Loading Stored AP config
com.microej.demo.aws.iot.wifi INFO:
############ WIFI CONFIG INSTRUCTIONS ###################
Please connect to the WIFI network with SSID=AWS_IOT_SAMPLE, password=qwertyuiop, and security=WPA2
from a mobile phone or a computer.
Then, open http://192.168.56.1:80 in a browser to configure a WIFI network with internet access.
The demo will start automatically when a WIFI network is configured successfully.
#############################################################
```
* Connect to the IP address showed in the log. Note that the IP address will be different on your machine
* Select and connect to a WIFI network with internet access
* When the WIFI network is connected the demo will start as the following.
```json
com.microej.demo.aws.iot.wifi INFO: Trying Join:myFirstSSid
com.microej.demo.aws.iot.wifi INFO: successfully joined WIFI: myFirstSSid
com.microej.demo.aws.iot.wifi INFO: Updating local time from NTP server pool.ntp.org:123
com.microej.demo.aws.iot.aws INFO: Connecting to AWS IoT Core Server. JIT provisioning will be done if necessary.
com.microej.demo.aws.iot.aws INFO: Device connected to the broker.
com.microej.demo.aws.iot.aws INFO: Update listener added, we're now subscribed to the topic awsiot/demo/sample
com.microej.demo.aws.iot.aws INFO: Sample data publishing timer task initialized.
com.microej.demo.aws.iot.aws INFO: Create or Update Device Shadow by reporting the device state
com.microej.demo.aws.iot.main INFO: Storing AP config for reuse
com.microej.demo.aws.iot.wifi INFO: Soft AP Unmount
com.microej.demo.aws.iot.shadow.updatedelta INFO: Message received on topic='$aws/things/Thermostat-1/shadow/update/documents, payload='{"previous":{"state":{"reported":{"unit":"°C","temperature":16,"target-time":"2022-04-14 08:33","target":16,"state":"ready","location":{"country":"FR","city":"Nantes"},"timestamp":1654603200094,"firmware-version":"1.8.3","capabilities":{"ble":true,"ota":true,"network":"WIFI"}}},"metadata":{"reported":{"unit":{"timestamp":1649925184},"temperature":{"timestamp":1649925184},"target-time":{"timestamp":1649925184},"target":{"timestamp":1649925184},"state":{"timestamp":1654603200},"location":{"country":{"timestamp":1654603200},"city":{"timestamp":1654603200}},"timestamp":{"timestamp":1654603200},"firmware-version":{"timestamp":1654603200},"capabilities":{"ble":{"timestamp":1654603200},"ota":{"timestamp":1654603200},"network":{"timestamp":1654603200}}}},"version":20},"current":{"state":{"reported":{"unit":"°C","temperature":16,"target-time":"2022-04-14 08:33","target":16,"state":"ready","location":{"country":"FR","city":"Nantes"},"timestamp":1654604502398,"firmware-version":"1.8.3","capabilities":{"ble":true,"ota":true,"network":"WIFI"}}},"metadata":{"reported":{"unit":{"timestamp":1649925184},"temperature":{"timestamp":1649925184},"target-time":{"timestamp":1649925184},"target":{"timestamp":1649925184},"state":{"timestamp":1654604502},"location":{"country":{"timestamp":1654604502},"city":{"timestamp":1654604502}},"timestamp":{"timestamp":1654604502},"firmware-version":{"timestamp":1654604502},"capabilities":{"ble":{"timestamp":1654604502},"ota":{"timestamp":1654604502},"network":{"timestamp":1654604502}}}},"version":21},"timestamp":1654604502}'
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"MicroEJ"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"is"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"a"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"unique"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"solution"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"for"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"building"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"Internet"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"of"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"Things"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"and"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"embedded"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"software"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"and"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"can"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"now"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"communicate"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"with"}
com.microej.demo.aws.iot.topicsubscriber INFO: Message received on topic awsiot/demo/sample => {"message":"AWS IoT"}
```
### Launching the demo on a Wi-Fi board (ESP32 WROVER KIT 4.1)
* Compile & Link the application with the BSP
* From the SDK top menu, go to `Run` > `Run Configurations...`
* From the left menu, Right click on `MicroEJ Application` and select `New Configuration`
* Enter a Configuration Name. for example `AWS Demo Build`
* From the `Main` tab
* Select the demo project `aws-iot-sample`
* Enter the main class `com.microej.demo.aws.iot.Main` in the Main type field
* From the `Execution` tab
* Select a compatible MICROEJ Platform
* Select `Execute On Device` and keep the default options (Core Engine Mode: Default, Settings: Build & Deploy)
* From the `Configuration` tab
* Go to `Device` > `Deploy` and check the option `Execute the MicroEJ build script (build.bat)`
* Click `Run` button
* **Note:** that the first compilation may take some time as It will compile the ESP-IDF BSP
* Flash the demo to your ESP32 WROVER KIT 4.1 evaluation Board by
* Ensure the ESP32 Board is plugged in to your computer over USB and the COM port is mounted
* Set the COM port of the ESP32 by setting the property `ESPPORT` in the file located in the Platform project `ESP32-WROVER-Xtensa-FreeRTOS-bsp/Projects/microej/scripts/set_project_env.(bat|sh)`. You can check the template file `ESP32-WROVER-Xtensa-FreeRTOS-bsp/Projects/microej/scripts/set_local_env.(bat|sh).tpl` for an example on how to set this property.
* From the SDK top menu, go to `Run` > `Run Configurations...`
* From the left menu, Right click on `MicroEJ Tool` and select `New Configuration`
* Enter a Configuration Name. for example `AWS Demo Flash ESP32`
* From the `Execution` tab
* Select a compatible MICROEJ Platform
* Select `Deploy with the BSP run script` for the `Execution` > `Settings` field
* From the `Configuration` tab
* Select the binary file to flash. The `application.out` file was generated during the Compile & Link step into `com.microej.demo.aws.iot.Main` folder in the demo project `aws-iot-sample`
* Click `Run Button`
* Follow the instructions from the application logs to configure the WIFI network (same as for the Simulator)
# AWS IoT dashboard
The AWS IoT console provides some tools to monitor the activity on the broker.
* Go to `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
# Troubleshooting
### ERROR javax.net.ssl.SSLHandshakeException: SSL-2.1:E=-129
**-129**: Verify problem on certificate and check date/time on your device.
This SSL ERROR means that the time is not correctly set on the device.
This example automatically set the device time from an NTP server. Please ensure you're using a valid one.
It can be configured in `src/main/resources/com.microej.demo.aws.iot.properties.list` file
```properties
ntp.url=pool.ntp.org
ntp.port=123
ntp.timeout=1000
```
### Error : problem while parsing Ivy module file: Cause : Can't parse module descriptor
This is a known issue with SDK 5.5.0 please update your SDK to the latest version.
For that, please check for updates from the SDK top menu `Help` > `Check for updates`
# References
* [MicroEJ Developer Portal](https://developer.microej.com)
* [Apache 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/)
# Dependencies
_All dependencies are retrieved transitively by MicroEJ Module Manager_.
# Source
N/A.
# Restrictions
None.
---
_Markdown_
_Copyright 2018-2022 MicroEJ Corp. All rights reserved._
_Use of this source code is governed by a BSD-style license that can be found with this software._ https://github.com/MicroEJ/VEEPort-STMicroelectronics-STM32F7508-DK/tree/1.5.0
VEE Port for STMicroelectronics STM32F7508-DK Discovery kit (v1.5.0)
VEE Port for STMicroelectronics STM32F7508-DK Discovery kit.
JPF_ST for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Technical Ref.: PRI-EVAL-STM32F7508-DK
Last updated:
29 June 2022
..
Copyright 2020-2022 MicroEJ Corp. All rights reserved.
Use of this source code is governed by a BSD-style license that can be found with this software.
.. |BOARD_NAME| replace:: STM32F7508-DK
.. |PLATFORM_VER| replace:: 1.5.0
.. |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:: STMicroelectronics
.. _README MicroEJ BSP: ./stm32f7508_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/stm32f7508-dk.png
It is recommended to read this tutorial before using the platform: https://docs.microej.com/en/latest/Tutorials/tutorialUnderstandMicroEJFirmwareBuild.html
Related Files
=============
This directory also contains:
* `CHANGELOG`_ to track the changes in the MicroEJ
|BOARD_NAME| Platform
* `RELEASE NOTES`_ to list:
- the list of the dependencies and their versions.
- the known issues and the limitations,
- the development environment.
* `README MicroEJ BSP`_ recommended for users familiar with the
|MANUFACTURER| SDK and advanced usage on how to customize the build
process.
Board Technical Specifications
==============================
.. list-table::
* - Name
- |BOARD_NAME|
* - MCU part number
- STM32F750N8H6
* - MCU architecture
- Arm Cortex-M7
* - MCU max clock frequency
- 216 MHz
* - Internal flash size
- 64 KB
* - Internal RAM size
- 340 KB
* - External flash size
- 128 Mb
* - External RAM size
- 64 Mb
* - Power supply
- ST-LINK USB V\ :sub:`BUS`\ or external sources
Here is a list of |BOARD_NAME| useful documentation links:
- Board documentation available `here <https://www.st.com/en/evaluation-tools/stm32f7508-dk.html#documentation>`__
- MCU documentation available `here <https://www.st.com/en/microcontrollers-microprocessors/stm32f750n8.html#documentation>`__
Platform Specifications
=======================
The Architecture version is ``7.16.1`` for GCC compiler and ``7.16.0`` for IAR compiler.
This Platform provides the following Foundation Libraries:
.. list-table::
:header-rows: 1
* - Foundation Library
- Version
* - BON
- 1.4
* - DEVICE
- 1.0
* - DRAWING
- 1.0
* - ECOM
- 1.1
* - ECOM-COMM
- 1.1
* - ECOM-SOCKET
- 1.0
* - EDC
- 1.3
* - FS
- 2.0
* - HAL
- 1.0
* - KF
- 1.5
* - MICROUI
- 3.1
* - NET
- 1.1
* - NET-EMBEDDED-DNS-NATIVE
- 1.2
* - NLS
- 2.0
* - PUMP
- 2.0
* - RESOURCEMANAGER
- 1.0
* - SECURITY
- 1.3
* - SNI
- 1.4
* - SP
- 2.0
* - SSL
- 2.2
* - TRACE
- 1.1
* - WADAPPS
- 1.0
* - WATCHDOG
- 1.0
The |PLATFORM| is derived into:
- a Mono-Sandbox Platform (default)
- a Multi-Sandbox Platform
The |PLATFORM| can be built using two toolchains:
- GCC
- IAR
Requirements
============
- PC with Windows 10
- 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 at least one of the following C IDEs:
- The STM32CubeIDE version 1.9.0 for |BOARD_NAME|, available `here <https://www.st.com/en/development-tools/stm32cubeide.html>`__ (also requires STM32CubeProgrammer, available `here <https://www.st.com/en/development-tools/stm32cubeprog.html>`__)
- The IAR EmbeddedWorkbench version 8.50.5 for |BOARD_NAME|, available `here <https://www.iar.com/iar-embedded-workbench/>`__
STM32CubeIDE Setup
------------------
1. Install STM32CubeIDE.
2. Install STM32CubeProgrammer.
IAR Embedded Workbench Setup
----------------------------
1. Install IAR Embedded Workbench.
2. Unzip the patch found here ``/stm32f7508_freertos-bsp/sdk/Utilities/PC_Software/patch/EWARM/``.
3. Execute the self-extracting archive ``EWARM_v7_ValueLine_STM32F7x0x8_Supportv4.0.exe``.
4. Apply the extracted patch to IAR Embedded Workbench installation directory (e.g. ``C:/Program Files (x86)/IAR Systems/Embedded Workbench 8.4/``).
BSP Compilation
---------------
The Platform provides a pre-compiled Mono-Sandbox Application for each toolchain.
Validate the BSP installation by compiling the BSP to build a MicroEJ
Firmware.
**Using the provided build scripts**
To build the ``stm32f750-freertos-bsp`` project, open a
terminal:
- If you are using the GCC toolchain go to the directory ``xxx/stm32f750-freertos-bsp/projects/microej/SW4STM32``.
- If you are using the IAR toolchain go to the directory ``xxx/stm32f750-freertos-bsp/projects/microej/EWARM``.
.. note::
The build script expects the toolchain to be installed at a known
path. If you installed it elsewhere or if you are using a different IDE version from the one listed above, see `README MicroEJ BSP`_ for
how to customize its path.
Run the following commands:
**On Windows:**
.. code-block:: sh
$ build.bat
The BSP project build is launched. Please wait for the end of the build.
**Using STM32CubeIDE**
Import the projects in the workspace:
- ``File`` > ``Import`` > ``General`` > ``Existing Projects into Workspace`` >
``Next``
- Point ``Select root directory`` to ``stm32f750-freertos-bsp/projects/```
- Click ``Finish``
Build the BSP:
- Right-click on ``application (in SW4STM32)`` project in your STM32CubeIDE workspace
- Click on ``Build Project``
**Using IAR Embedded Workbench**
Import the projects in the workspace:
- ``File`` > ``Open workspace``
- Select ``application.eww` from ``stm32f7508_freertos-bsp\projects\microej\EWARM``
- Click ``Open``
Build the BSP:
- Select ``Debug`` or ``Release`` from the dropdown in the ``Workspace`` view
- Right-click on ``application`` and select ``Make``
Board Setup
===========
Please refer to the `README MicroEJ BSP`_ ``Board Configuration`` section
for more details.
Power Supply
------------
The board can be powered by a mini-USB cable.
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.
- Open a terminal.
- If you are using the GCC toolchain go to the directory ``xxx/stm32f750-freertos-bsp/projects/microej/SW4STM32``.
- If you are using the IAR toolchain go to the directory ``xxx/stm32f750-freertos-bsp/projects/microej/EWARM``.
To ensure that your board is detected by your PC, open your Windows device manager and check at your ports, you should see the STMicroelectronics STLink Virtual COM port (COMx where x is the number of the port).
**On Windows:**
.. code-block:: sh
$ run.bat
The firmware is launched.
|BOARD_NAME| build and flash documentation are also available in the `README MicroEJ BSP`_ 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.
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`` > ``General`` > ``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:
- ``stm32f7508_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``).
- ``stm32f7508_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.
- ``stm32f7508_freertos-fp``: Contains the board description
and images for the |SIM|. This project is updated once the platform
is built.
- ``STM32F7508-Platform-CM7hardfp_GCC48-{version}``:
Contains the |RCP| Platform project for the GCC toolchain which is empty by default until
the Platform is built. This platform project will be the one built by default. To build using
IAR toolchain instead, please see the note below.
- ``STM32F7508-Platform-CM7hardfp_IAR83-{version}``:
Contains the |RCP| Platform project for the IAR toolchain which is empty by default until
the Platform is built. This platform project will not be the one used by default. To build using
IAR toolchain instead, please see the note below.
By default, the Platform is configured as a Mono-Sandbox Evaluation
Platform which will allow you to run any application on the Simulator.
However, to be able to run an application on the Device you need a license, if you don't have one, follow the procedure described
`here <https://docs.microej.com/en/latest/SDKUserGuide/licenses.html>`__.
.. note::
| The default toolchain is GCC.
| If you want to switch to the IAR toolchain:
- Open ``stm32f7508_freertos-configuration/module.properties`` and follow its documentation to set the ``xpf.name``, ``xpf.toolchain.name`` and ``xpf.version`` properties.
.. note::
To build a Multi-Sandbox platform, open ``stm32f7508_freertos-configuration/STM32F7508.platform``,
go to the ``Content`` tab and check ``Multi Applications``.
Platform Build
--------------
To build the Platform, please follow the steps below:
- Right-click on ``stm32f7508_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|
``STM32F7508-Platform-CM7hardfp_GCC48-{version}``, or ``STM32F7508-Platform-CM7hardfp_IAR83-{version}``
if you changed the toolchain for IAR.
.. note::
If the platform still shows an error, proceed to a manual refresh of the MicroEJ SDK package explorer (``right click in the package explorer`` -> ``Refresh``)
Please refer to https://docs.microej.com/en/latest/PlatformDeveloperGuide/platformOverview.html#build-process
for more details about the MicroEJ platform build process
Please refer to https://docs.microej.com/en/latest/ApplicationDeveloperGuide/standaloneApplication.html
for more information on how to build a MicroEJ Standalone Application.
Testsuite Configuration
=======================
To run a Testsuite on the |BOARD_NAME| board please refer to the testsuite tutorial `here <https://docs.microej.com/en/latest/Tutorials/tutorialRunATestSuiteOnDevice.html>`__
In ``config.properties``, the property ``target.platform.dir`` must be
set to the absolute path to the platform. For example
``C:/Platform-STMicroelectronics-STM32F7508-DK/STM32F7508-Platform-CM7hardfp_GCC48-{version}/source``.
Troubleshooting
===============
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.
https://github.com/MicroEJ/VEEPort-STMicroelectronics-STM32L4R9-DISCO/tree/1.0.1
VEE Port for STMicroelectronics 32L4R9IDISCOVERY Discovery kit (v1.0.1)
VEE Port for STMicroelectronics 32L4R9IDISCOVERY Discovery kit.
JPF_ST for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Technical Ref.: PRI-EVAL-STM32L4R9-DISCO
Last updated:
22 June 2022
..
Copyright 2019-2022 MicroEJ Corp. All rights reserved.
Use of this source code is governed by a BSD-style license that can be found with this software.
.. |BOARD_NAME| replace:: STM32L4R9I-DISCO
.. |RCP| replace:: MICROEJ SDK
.. |PLATFORM| replace:: MicroEJ Platform
.. |SIM| replace:: MicroEJ Simulator
.. |CIDE| replace:: MICROEJ SDK
.. |RTOS| replace:: FreeRTOS RTOS
.. |MANUFACTURER| replace:: STMicroelectronics
.. _README MicroEJ BSP: ./STM32L4R9DISCO-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/board-front.png
Related Files
=============
This directory also contains:
* `CHANGELOG`_ to track the changes in the |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| SDK and advanced usage on how to customize the build
process.
Board Technical Specifications
==============================
.. list-table::
* - Name
- |BOARD_NAME|
* - MCU part number
- STM32L4R9AII6
* - MCU architecture
- Arm Cortex-M4
* - MCU max clock frequency
- 120 MHz
* - Internal flash size
- 2 MB
* - Internal RAM size
- 640 KB
* - External flash size
- 512 MB
* - External RAM size
- 16 MB
* - Power supply
- ST-LINK USB V\ :sub:`BUS`\ or external sources
Here is a list of |BOARD_NAME| useful documentation links:
- Board documentation available `here <https://www.st.com/en/evaluation-tools/32l4r9idiscovery.html#documentation>`__
- MCU documentation available `here <https://www.st.com/en/microcontrollers-microprocessors/stm32l4r9-s9.html#documentation>`__
Platform Specifications
=======================
The Architecture version is ``7.16.0``.
This Platform provides the following Foundation Libraries:
.. list-table::
:header-rows: 1
* - Foundation Library
- Version
* - BON
- 1.4
* - DEVICE
- 1.1
* - DRAWING
- 1.0
* - ECOM
- 1.1
* - EDC
- 1.3
* - KF
- 1.5
* - MICROUI
- 3.1
* - NLS
- 2.0
* - SNI
- 1.4
* - SP
- 2.0
* - TRACE
- 1.1
The |PLATFORM| is derived into:
- a Mono-Sandbox Platform (default)
The |PLATFORM| can be built using the following toolchains:
- IAR EmbeddedWorkbench version 8.50.6 or higher
Requirements
============
- PC with Windows 10
- 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 following softwares:
- The IAR EmbeddedWorkbench version 8.50.6, available `here <https://www.iar.com/iar-embedded-workbench/>`__
- The STM32CubeProgrammer version 2.8.0, available `here <https://www.st.com/en/development-tools/stm32cubeprog.html>`__
BSP Compilation
---------------
The Platform provides a pre-compiled Mono-Sandbox Application.
Validate the BSP installation by compiling the BSP to build a |BOARD_NAME|
Firmware.
To build the ``STM32L4R9DISCO-bsp`` project, open a
terminal and enter the following command lines:
**On Windows:**
.. code-block:: sh
$ cd "xxx/STM32L4R9DISCO-bsp/projects/microej/EWARM/scripts"
$ build.bat
The BSP project build is launched. Please wait for the end of the build.
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.
Board Setup
===========
Please refer to the |MANUFACTURER| documentation for more details.
Power Supply
------------
The board can be powered by a mini-USB cable.
Programming
-----------
The |BOARD_NAME| board can be flashed using |MANUFACTURER|
bootloader. Please Follow the steps below:
- Plug the device to your computer using a USB cable (on micro-USB port labeled ``USB STLINK``).
- Open a terminal and enter the following command lines:
**On Windows:**
.. code-block:: sh
$ cd "xxx/STM32L4R9DISCO-bsp/projects/microej/EWARM/scripts"
$ run.bat
The firmware is launched.
Logs Output
-----------
This |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.
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:
- ``STM32L4R9DISCO-configuration``: Contains the
platform configuration description. Some modules are described in a
specific sub-folder / with some optional configuration files
(``.properties`` and / or ``.xml``).
- ``STM32L4R9DISCO-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.
- ``STM32L4R9DISCO-fp``: Contains the board description
and images for the |SIM|. This project is updated once the platform
is built.
- ``STM32L4R9DISCO-Platform-CM4hardfp_IAR83-1.0.0``:
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.
Platform Build
--------------
To build the Platform, please follow the steps below:
- Right-click on ``STM32L4R9DISCO-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 |RCP| 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 used.
The Platform project should be refreshed with no error in the |RCP|
``STM32L4R9DISCO-Platform-CM4hardfp_IAR83-1.0.0``.
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 please refer to the testsuite tutorial `here <https://docs.microej.com/en/latest/Tutorials/tutorialRunATestSuiteOnDevice.html>`__.
In ``config.properties``, the property ``target.platform.dir`` must be
set to the absolute path to the platform. For example
``xxx/STM32L4R9DISCO-Platform-CM4hardfp_IAR83-1.0.0/source``.
Troubleshooting
===============
Files not found during the build
--------------------------------
Errors about files not found during the build may be caused by long path.
https://github.com/MicroEJ/VEEPort-Espressif-ESP-WROVER-KIT-V4.1/tree/2.0.0
VEE Port for Espressif ESP-WROVER-KIT V4.1 development board (v2.0.0)
VEE Port for Espressif ESP-WROVER-KIT V4.1 development board.
JPF_ESP for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Technical Ref.: PRI-EVAL-ESP32-WROVER-KIT
Last updated:
8 June 2022
..
Copyright 2019-2022 MicroEJ Corp. All rights reserved.
Use of this source code is governed by a BSD-style license that can be found with this software.
.. |BOARD_NAME| replace:: ESP-WROVER-KIT V4.1
.. |BOARD_REVISION| replace:: 4.1
.. |PLATFORM_VER| replace:: 2.0.0
.. |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 the following command:
.. code-block:: sh
git clone --recursive https://github.com/MicroEJ/Platform-Espressif-ESP-WROVER-KIT-V4.1
Do not miss the ``--recursive`` option. If you have already cloned this project without this option, run another command to get all the submodules:
.. code-block:: sh
git submodule update --init --recursive
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/v4.3.2/esp32/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/v4.3.2/esp32/hw-reference/esp32/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.16.1``.
This Platform provides the following Foundation Libraries:
.. list-table::
:header-rows: 1
* - Foundation Library
- Version
* - BLUETOOTH
- 2.1
* - BON
- 1.4
* - DEVICE
- 1.1
* - DRAWING
- 1.0
* - ECOM-NETWORK
- 2.1
* - ECOM-WIFI
- 2.3
* - ESP_IDF
- 1.1
* - FS
- 2.1
* - HAL
- 1.0
* - KF
- 1.5
* - MICROUI
- 3.1
* - NET
- 1.1
* - NLS
- 2.0
* - SECURITY
- 1.4
* - SNI
- 1.4
* - SSL
- 2.2
* - TRACE
- 1.1
* - WATCHDOG
- 1.0
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. ``21.11`` or higher, available `here <https://developer.microej.com/get-started/>`_
- |BOARD_NAME| board
BSP Setup
=========
Install the |MANUFACTURER| toolchain by following the section ``Setting up Development Environment`` described `here
<https://docs.espressif.com/projects/esp-idf/en/v4.3.2/esp32/get-started/index.html#installation-step-by-step>`__, but skip the section ``Get ESP-IDF``. The ESP-IDF is already a submodule of this repository.
Please pay attention on the limitations regarding the installation path (e.g. no white spaces, parentheses ...),
described in the above documentation.
Please refer to the |MANUFACTURER| documentation available `here <https://docs.espressif.com/projects/esp-idf/en/v4.3.2/esp32/api-guides/tools/idf-tools.html#list-of-idf-tools>`__
for more details about |MANUFACTURER| tools.
Windows Toolchain
-----------------
- C/C++ toolchain name: xtensa-esp32-elf-gcc
- C/C++ toolchain version: 8.4.0 (crosstool-NG esp-2021r2)
- C/C++ toolchain download link for 64-bit Windows: https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/xtensa-esp32-elf-gcc8_4_0-esp-2021r2-patch1-win64.zip
- C/C++ toolchain download link for 32-bit Windows: https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/xtensa-esp32-elf-gcc8_4_0-esp-2021r2-patch1-win32.zip
Please refer to the |MANUFACTURER| documentation available `here
<https://docs.espressif.com/projects/esp-idf/en/v4.3.2/esp32/get-started/windows-setup.html>`__
for more details.
Linux Toolchain
---------------
- C/C++ toolchain name: xtensa-esp32-elf-gcc
- C/C++ toolchain version: 8.4.0 (crosstool-NG esp-2021r2)
- C/C++ toolchain download link for 64-bit Linux: https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/xtensa-esp32-elf-gcc8_4_0-esp-2021r2-linux-amd64.tar.gz
- C/C++ toolchain download link for 32-bit Linux: https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2/xtensa-esp32-elf-gcc8_4_0-esp-2021r2-linux-i686.tar.gz
Please refer to the |MANUFACTURER| documentation available `here
<https://docs.espressif.com/projects/esp-idf/en/v4.3.2/esp32/get-started/linux-setup.html>`__
for more details.
BSP Compilation
---------------
Before the first build of the BSP, ensure you have cloned the repository and all its submodules
and also the patch for the MicroEJ Segger SystemView implementation is applied. This can be done
running the script **RunAtFirstBSPCompile** located in ``xxx/ESP32-WROVER-Xtensa-FreeRTOS-bsp/projects/microej/scripts``.
Please refer to the `README MicroEJ BSP`_ on further details.
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::
Project build complete. To flash, run this command:
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/v4.3.2/esp32/hw-reference/esp32/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/v4.3.2/esp32/hw-reference/esp32/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
- Create the ``ESP32-WROVER-Xtensa-FreeRTOS-bsp/projects/microej/scripts/set_local_env.xxx`` script
by copying the template ``ESP32-WROVER-Xtensa-FreeRTOS-bsp/projects/microej/scripts/set_local_env.xxx.tpl``
(where ``xxx`` is ``bat`` for Windows and ``sh`` for Linux / macOS).
- Edit in this script the the ``ESPPORT`` variable to put the newly COM port discovered previously.
- 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...
Done
|MANUFACTURER| build and flash documentation are also available `here
<https://docs.espressif.com/projects/esp-idf/en/v4.3.2/esp32/get-started/index.html#step-8-build-the-project>`__
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/v4.3.2/esp32/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-GNUv84_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-GNUv84_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.
Test Suite Configuration
========================
To run a Test Suite 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 Test Suite.
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``.
Test Suite Projects
-------------------
A ``config.properties`` and ``microej-testsuite-common.properties``
are provided in ``ESP32-WROVER-Xtensa-FreeRTOS-configuration/testsuites/*``.
Troubleshooting
===============
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.
https://repository.microej.com/modules/ej/library/iot/websocket-secure/2.0.1/
Implementation for the client side of the WebSocket protocol as described in RFC 6455.
LIBRARY for IOT
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
8 June 2022
# Overview
MicroEJ Java library: websocket-secure.
Implementation for the client side of the WebSocket protocol as described in RFC 6455.
This implementation does not support very extended Length and masked frames.
Secure version of WebSocket library, see [WebSocket README](../ej.websocket/README.md)
# Usage
Add the following line to your `module.ivy`:
<dependency org="ej.library.iot" name="websocket-secure" rev="2.0.1"/>
# Requirements
This library requires the following Foundation Libraries:
BON-1.3, EDC-1.2, NET-1.1-API-1.1, SSL-2.0
# Dependencies
_All dependencies are retrieved transitively by Ivy resolver_.
# Source
N/A
# Restrictions
None.
---
_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._ https://github.com/MicroEJ/JavaScript-Demo/tree/1.0.1
This project demonstrates the JavaScript capabilities of MicroEJ.
EXAMPLE for CORE
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
8 June 2022
.. ReStructuredText
.. Copyright 2020-2021 MicroEJ Corp. All rights reserved.
.. Use of this source code is governed by a BSD-style license that can be found with this software.
.. image:: https://shields.microej.com/endpoint?url=https://repository.microej.com/packages/badges/sdk_5.4.json
:alt: sdk_5.4 badge
:align: left
==========
Overview
==========
This repository contains MicroEJ JavaScript demonstration projects:
- `js-demo <js-demo>`_ demonstrates how to run simple JavaScript files
- `js-demo-mqtt <js-demo-mqtt>`_ demonstrates integration of Paho JS retrieved from npm, interaction with REST services and with hardware
Please refer to the ``README.md`` files of the projects for more information.
https://repository.microej.com/packages/demo/RT595_EmbeddedDevice_WearableDemo_Source_v2.3.2.zip
VEE Port for NXP i.MX RT595 Evaluation Kit (v2.3.2)
VEE Port for NXP i.MX RT595 Evaluation Kit.
JPF_NXP for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Technical Ref.: PRI-EVAL-RT595
Last updated:
3 June 2022
https://github.com/MicroEJ/VEEPort-Espressif-ESP-WROVER-KIT-V4.1/tree/1.8.4
VEE Port for Espressif ESP-WROVER-KIT V4.1 development board (v1.8.4)
VEE Port for Espressif ESP-WROVER-KIT V4.1 development board.
JPF_ESP for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Technical Ref.: PRI-EVAL-ESP32-WROVER-KIT
Last updated:
2 June 2022
..
Copyright 2019-2022 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.8.4
.. |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/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.
https://github.com/MicroEJ/VEEPort-STMicroelectronics-STM32F746G-DISCO-Zephyr/tree/0.1.1
VEE Port for STMicroelectronics 32F746GDISCOVERY Discovery kit using Zephyr (v0.1.1)
VEE Port for STMicroelectronics 32F746GDISCOVERY Discovery kit using Zephyr.
JPF_ST for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Technical Ref.: PRI-EVAL-STM32F746G-DISCO-Zephyr
Last updated:
2 June 2022
..
Copyright 2020-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:: STM32F746G discovery
.. |BOARD_REVISION| replace:: A01
.. |PLATFORM_NAME| replace:: STM32F746G Platform
.. |PLATFORM_VER| replace:: 0.1.1
.. |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:: Zephyr RTOS
.. |MANUFACTURER| replace:: STMicroelectronics
.. _README MicroEJ BSP: ./stm32f746g_zephyr-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/stm32f746g_disco.jpg
It is recommended to read this tutorial before using the platform: https://docs.microej.com/en/latest/Tutorials/tutorialUnderstandMicroEJFirmwareBuild.html.
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`_ to customize the build/flash process.
Board Technical Specifications
==============================
.. list-table::
* - Name
- |BOARD_NAME|
* - Revision
- |BOARD_REVISION|
* - MCU part number
- STM32F746NG
* - MCU revision
- N/A
* - MCU architecture
- ARM Cortex-M7
* - MCU max clock frequency
- 216 MHz
* - Internal flash size
- 1 MB
* - Internal SRAM size
- 340 KB
* - External flash size
- 16 MB
* - External SRAM size
- 16 MB
* - Power supply
- 5 different options for power supply
Here is a list of |BOARD_NAME| useful documentation links:
- Board documentation available `here <https://www.st.com/en/evaluation-tools/32f746gdiscovery.html>`__.
- Microcontroller documentation available `here <https://www.st.com/en/microcontrollers-microprocessors/stm32f746ng.html>`__.
- Zephyr board support documentation available `here <https://docs.zephyrproject.org/2.5.0/boards/arm/stm32f746g_disco/doc/index.html>`__.
Platform Specifications
=======================
The Architecture version is ``7.14.0``.
This Platform provides the following Foundation Libraries:
.. list-table::
:header-rows: 1
* - Foundation Library
- Version
* - BON
- 1.4
* - EDC
- 1.3
* - NLS
- 2.0
* - SNI
- 1.4
* - SP
- 2.0
* - TRACE
- 1.1
The |PLATFORM| is derived into:
- a Mono-Sandbox Platform (default),
- a Multi-Sandbox Platform.
Requirements
============
- PC with Windows 10 or Linux.
- Internet connection to `MicroEJ Central Repository <https://developer.microej.com/central-repository/>`_.
- |RCP| Dist. ``21.03`` or higher, available `here <https://developer.microej.com/get-started/>`_.
- |BOARD_NAME| board.
BSP Setup
=========
Install zephyr and the required third party utilities as described `here <https://docs.zephyrproject.org/2.5.0/getting_started/index.html>`_.
The relevant sections to complete are:
1. Select and Update OS,
2. Install dependencies,
3. Get Zephyr and install Python dependencies (see note below),
4. Install a Toolchain.
.. note::
Use command ``west init -m https://github.com/zephyrproject-rtos/zephyr --mr v2.5.0 zephyrproject``
instead of ``west init`` to force use of Zephyr Project v2.5.0 in section ``3. Get Zephyr and install Python dependencies``.
The zephyr SDK is only available for Ubuntu Linux distribution. It contains all necessary tools to build Zephyr project on all supported architectures.
Additionally, it includes host tools such as custom QEMU binaries, host compiler, openocd, etc.
If the SDK is available for your Linux operating system, it should be installed as described
`here <https://docs.zephyrproject.org/2.5.0/getting_started/installation_linux.html#zephyr-sdk>`_.
Otherwise, the gnu arm compilation toolchain should additionally be installed, following the first step listed
`here <https://docs.zephyrproject.org/2.5.0/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded>`_.
The environment variables ``ZEPHYR_TOOLCHAIN_VARIANT`` and ``GNUARMEMB_TOOLCHAIN_PATH`` have to be correctly defined to build a project for the target.
See `README MicroEJ BSP`_ to learn how to do so.
``openocd`` is included in zephyr's SDK, Windows and macOS users will have to set it up manually to flash and debug the software.
It can either be compiled from sources using the `patched openocd <https://github.com/zephyrproject-rtos/openocd>`_
for zephyr or it can be downloaded in `pre-built version <https://gnutoolchains.com/arm-eabi/openocd>`_.
Follow the instructions under *BSP setup* in `README MicroEJ BSP`_ for further information.
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 ``stm32f746g_zephyr-bsp`` project, open a
terminal and enter the following command lines:
.. code-block:: sh
$ cd "xxx/stm32f746g_zephyr-bsp/projects/microej/scripts"
$ build.bat
The BSP project build is launched. Please wait for the final message:
.. code-block::
build.bat script terminating.
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://www.st.com/en/evaluation-tools/32f746gdiscovery.html#documentation>`__
for more details.
Power Supply
------------
There are 5 different options for power supply:
- ST LINK/V2-1.
- USB FS connector.
- USB HS connector.
- VIN from Arduino connector.
- External 5V from connector.
Programming
-----------
Please Follow the steps below:
- Connect the USB ST-LINK connector of the board to your computer.
- Open a terminal and enter the following command lines:
.. code-block:: sh
$ cd "xxx/stm32f746g_zephyr-bsp/projects/microej/scripts"
$ run.bat
The firmware is launched. Please wait for the final message:
.. code-block::
run.bat script terminating.
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``.
Debugging
---------
An embedded ST-LINK debugger 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:
- ``stm32f746g_zephyr-configuration`` contains the
platform configuration description. Some modules are described in a
specific sub-folder / with some optional configuration files
(``.properties`` and / or ``.xml``).
- ``stm32f746g_zephyr-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.
- ``stm32f746g_zephyr-fp`` contains the board description and
images for the MicroEJ Simulator. This project is updated once
the platform is built.
- ``stm32f746g-Platform-CM7hardfp_GCC48-{version}``
contains the |RCP| Platform project which is empty by default until
the Platform is built.
Platform Build
--------------
To build the Platform, please follow the steps below:
- Right-click on ``stm32f746g_zephyr-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|
``stm32f746g-Platform-CM7hardfp_GCC48-{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
=======================
Troubleshooting
===============
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.
Zephyr project build cache issue
--------------------------------
Zephyr project build issue can occurred if OS environment variables have been updated
and an old Zephyr project build cache already exists. Please cleanup Zephyr project build
cache and relaunch a build before investigating more on the issue.https://repository.microej.com/packages/demo/RT595_VirtualDevice_WearableDemo_v2.3.2.zip
A Virtual Device Player on the Wearable Demo (for Windows, macOS, and Linux).
EXAMPLE for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
1 June 2022
https://repository.microej.com/packages/applications/demo-exs82-mqtt-virtualdevice-0.4.0.zip
Data Collection and Sharing over MQTT Demo
Discover how to collect temperature and GPS data and safely share the information to the Cloud through a MQTT server (on Cinterion LGA DevKit for the EXS82-W IoT Module).
EXAMPLE for IOT
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
1 June 2022
https://github.com/MicroEJ/AbstractionLayer-Core-Zephyr/tree/1.0.1
OS Abstraction Layer for Zephyr
MicroEJ Core Engine Abstraction Layer implementation for Zephyr OS.
LIBRARY for CORE
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
1 June 2022
# Overview
MicroEJ Core Engine Abstraction Layer implementation for Zephyr OS.
This module implements the `LLMJVM` Low Level API for MicroEJ Platforms connected to a Board Support Package based on [Zephyr OS](https://www.zephyrproject.org/).
See [these sections](https://docs.microej.com/en/latest/PlatformDeveloperGuide/appendix/llapi.html#llmjvm-microej-core-engine) of the MicroEJ documentation for a description of the `LLMJVM` functions:
- [LLMJVM: MicroEJ Core Engine](https://docs.microej.com/en/latest/PlatformDeveloperGuide/appendix/llapi.html#llmjvm-microej-core-engine)
- [MicroEJ Core Engine: Implementation](https://docs.microej.com/en/latest/PlatformDeveloperGuide/coreEngine.html#implementation)
# Usage
1. Install ``src`` and ``inc`` directories in your Board Support Package. They can be automatically downloaded using the following command lines:
```sh
svn export --force https://github.com/MicroEJ/AbstractionLayer-Core-Zephyr/trunk/inc [path_to_bsp_directory]
svn export --force https://github.com/MicroEJ/AbstractionLayer-Core-Zephyr/trunk/src [path_to_bsp_directory]
```
2. Implement the MicroEJ time functions, as described in [microej_time.h](./inc/microej_time.h).
3. The `LLMJVM_IMPL_scheduleRequest` schedule request function in [LLMJVM_ZephyrOS.c](./src/LLMJVM_ZephyrOS.c) uses a software timer. In order to correctly schedule MicroEJ threads, check the following elements in the Zephyr OS configuration file:
- `CONFIG_SYS_CLOCK_TICKS_PER_SEC`: can depend on the application, if it needs a 1 ms precision then the tick rate would be 1000 Hz, the recommended value is between 100 Hz and 1000 Hz (see [Zephyr Kernel Timing](https://docs.zephyrproject.org/2.5.0/reference/kernel/timing/clocks.html) page for more details)
# Requirements
None.
# Validation
This Abstraction Layer implementation can be validated in the target Board Support Package using the [MicroEJ Core Validation](https://github.com/MicroEJ/PlatformQualificationTools/tree/master/tests/core/java/microej-core-validation) Platform Qualification Tools project.
Here is a non exhaustive list of tested environments:
- Hardware
- STMicroelectronics 32F746GDISCOVERY Discovery kit
- Compilers / Build environments:
- arm-none-eabi-gcc v10.2.1 / cmake v3.20.0, ninja v1.10.2
- Zephyr OS v2.5.0
## MISRA Compliance
The implementation is MISRA-compliant (MISRA C 2012). It has been verified with cppcheck v2.4.1.
Here is the list of deviations:
| Deviation | Category | Action | Justification |
|:---------:|:--------:|:----------:|:---------------------------------------------------------------------------------------------------------------------------------:|
| Rule 11.3 | Advisory | Flagged | A deviation from this rule is necessary as the pointer returned by k_current_get has to be cast to an int32_t to get a task id |
| Rule 5.5 | Required | Ignored | A deviation from this rule is necessary as macros are used to map JVM symbols to LLMJVM_IMPL_ functions |
## Usage
Copy/paste source code in your platform BSP project or add the following line to your platform configuration `module.ivy`:
> `<dependency org="com.microej.clibrary.llimpl" name="mjvm-zephyros" rev="..."/>`
**_Note:_** Run the [MicroEJ Core Validation](https://github.com/MicroEJ/PlatformQualificationTools/tree/master/tests/core/java/microej-core-validation) Platform Qualification Tools project to validate code integration in your environment.
# Dependencies
- MicroEJ Architecture ``7.x`` or higher.
- Zephyr OS ``2.5.0`` or higher.
# Source
N/A.
# Restrictions
None.
---
_Copyright 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._
https://github.com/MicroEJ/AbstractionLayer-Core-MicriumOS/tree/1.1.1
OS Abstraction Layer for MicriumOS
Low Level MicroEJ Core Engine API implementation over Micrium OS.
LIBRARY for CORE
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
1 June 2022
# Overview
Low Level MicroEJ Core Engine API implementation over Micrium OS.
This component implements the `LLMJVM` Low Level API for MicroEJ platforms connected to a Board Support Package based on [Micrium OS](https://www.silabs.com/developers/micrium-os).
See the MicroEJ documentation for a description of the `LLMJVM` functions:
- [LLMJVM: MicroEJ Core Engine](https://docs.microej.com/en/latest/PlatformDeveloperGuide/appendix/llapi.html#llmjvm-microej-core-engine)
- [MicroEJ Core Engine: Implementation](https://docs.microej.com/en/latest/PlatformDeveloperGuide/coreEngine.html#implementation)
# Usage
1. Install ``src`` and ``inc`` directories in your Board Support Package. They can be automatically downloaded using the following command lines:
```sh
svn export --force https://github.com/MicroEJ/AbstractionLayer-Core-MicriumOS/trunk/inc [path_to_bsp_directory]
svn export --force https://github.com/MicroEJ/AbstractionLayer-Core-MicriumOS/trunk/src [path_to_bsp_directory]
```
2. Implement the MicroEJ time functions, as described in [microej_time.h](./inc/microej_time.h).
3. The `LLMJVM_IMPL_scheduleRequest` schedule request function in [LLMJVM_MicriumOS.c] uses a software timer. In order to correctly schedule MicroEJ threads, check the following elements in the MicriumOS configuration file:
- `OS_CFG_TICK_EN`: needs to be enabled to get access to all time-based services in Micrium OS Kernel. The `OS_ConfigureTickTask` function can be used to configure the tick task stack size and priority.
The `OS_ConfigureTickRate` function can be used to set the OS tick rate. The MicroEJ task should have a lower priority than the tick task.
- `OS_CFG_TMR_EN`: needs to be enabled to get access to all software-based timers in Micrium OS Kernel. The `OS_ConfigureTmrTask` function can be used to configure the timer task stack size and priority.
The `OSTmrCreate` function can be used to create a timer with the desired periodicity. The MicroEJ task should have a lower priority than the timer task.
# Requirements
None.
# Validation
This Abstraction Layer implementation can be validated in the target Board Support Package using the [MicroEJ Core Validation](https://github.com/MicroEJ/PlatformQualificationTools/tree/master/tests/core/java/microej-core-validation) Platform Qualification Tools project.
Here is a non exhaustive list of tested environments:
- Hardware
- Silicon Labs EFR32BG22
- Compilers / development environments:
- IAR Embedded Workbench 8.50.6
- Micrium OS versions:
- 5.9.0
## MISRA Compliance
The implementation is MISRA-compliant (MISRA C 2004) with the following observed deviations:
| Deviation | Category | Justification |
|:---------:|:--------:|:-------------------------------------------------------------------------------------------------------------:|
| Rule 11.3 | Advisory | A deviation from this rule is necessary as the OSTCBCurPtr has to be cast to an int32_t to get a task id |
| Rule 16.4 | Required | A deviation from this rule is necessary as long as the LLMJVM_IMPL_getCurrentTime declaration does not match |
# Dependencies
- MicroEJ Architecture ``7.x`` or higher.
- Micrium OS ``5.9.0`` or higher.
# Source
N/A.
# Restrictions
None.
---
_Copyright 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._
https://github.com/MicroEJ/AbstractionLayer-Core-FreeRTOS/tree/1.2.0
OS Abstraction Layer for FreeRTOS
MicroEJ Core Engine Abstraction Layer implementation for FreeRTOS.
LIBRARY for CORE
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
1 June 2022
# Overview
MicroEJ Core Engine Abstraction Layer implementation for FreeRTOS.
This module implements the `LLMJVM` Low Level API for MicroEJ Platforms connected to a Board Support Package based on [FreeRTOS](https://www.freertos.org/).
See the MicroEJ documentation for a description of the `LLMJVM` functions:
- [LLMJVM: MicroEJ Core Engine](https://docs.microej.com/en/latest/PlatformDeveloperGuide/appendix/llapi.html#llmjvm-microej-core-engine)
- [MicroEJ Core Engine: Implementation](https://docs.microej.com/en/latest/PlatformDeveloperGuide/coreEngine.html#implementation)
# Usage
1. Install ``src`` and ``inc`` directories in your Board Support Package. They can be automatically downloaded using the following command lines:
```sh
svn export --force https://github.com/MicroEJ/AbstractionLayer-Core-FreeRTOS/trunk/inc [path_to_bsp_directory]
svn export --force https://github.com/MicroEJ/AbstractionLayer-Core-FreeRTOS/trunk/src [path_to_bsp_directory]
```
2. Implement the MicroEJ time functions, as described in [microej_time.h](./inc/microej_time.h).
3. The `LLMJVM_IMPL_scheduleRequest` schedule request function in [LLMJVM_FreeRTOS.c](./src/LLMJVM_FreeRTOS.c) uses a software timer. In order to correctly schedule MicroEJ threads, check the following elements in the FreeRTOS configuration file:
- Timers are enabled with `#define configUSE_TIMERS 1`
- `configTIMER_TASK_PRIORITY` is higher than MicroEJ task priority
- `configTICK_RATE_HZ`: can depend on the application, if it needs a 1 ms precision then the tick rate would be 1000 Hz, the recommended value is between 100 Hz and 1000 Hz
# Requirements
None.
# Validation
This Abstraction Layer implementation can be validated in the target Board Support Package using the [MicroEJ Core Validation](https://github.com/MicroEJ/PlatformQualificationTools/tree/master/tests/core/java/microej-core-validation) Platform Qualification Tools project.
Here is a non exhaustive list of tested environments:
- Hardware
- STMicroelectronics STM32F7508-DK
- Espressif ESP-WROVER-KIT V4.1
- Compilers / Integrated Development Environments:
- IAR Embedded Workbench 8.50.6
- STM32CubeIDE version 1.3.0 (using GNU GCC toolchain)
- Espressif IoT Development Framework (``esp-idf``) v3.3.4 (using GNU GCC toolchain)
- FreeRTOS versions:
- FreeRTOS V10.2.0
- FreeRTOS V8.2.0
# MISRA Compliance
This Abstraction Layer implementation is MISRA-compliant (MISRA C 2004) with the following observed deviations:
| Deviation | Category | Justification |
|:---------:|:--------:|:-------------------------------------------------------------------------------------------------------------:|
| Rule 6.3 | Advisory | A deviation from this rule is applied so as to use the bool type from `<stdbool.h>`. |
| Rule 11.3 | Advisory | A deviation from this rule is unavoidable as FreeRTOS's handles (timers, queues, tasks) are pointers to void. |
# Dependencies
- MicroEJ Architecture ``7.x`` or higher.
- FreeRTOS ``8.2.0`` or higher.
# Source
N/A.
# Restrictions
None.
---
_Copyright 2020-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._
https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/com/google/flatbuffers/1.0.0
This library allows the use of FlatBuffers with MicroEJ. FlatBuffers is a serialization library designed by Google.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
1 June 2022
# Overview
[FlatBuffers](https://google.github.io/flatbuffers/) is an open-source cross-platform serialization library designed by Google.
This project makes the Java API of this library available in the MicroEJ environment and deployable into MicroEJ supported platforms.
This project contains:
- the original FlatBuffers API
- its implementation, modified to compile against EDC API and eclasspath libraries
- its Java testsuite, modified to compile against FS API and to work around some limitations
## UTF-8
If FlexBuffers are used, UTF-8 encoding has to be embedded.
If FlatBuffers are used and the `Utf8Safe` implementation of `Utf8` is used (default), UTF-8 encoding does not have to be embedded.
However, if the `Utf8Old` implementation of `Utf8` is used, UTF-8 encoding has to be embedded.
In order to use the `Utf8Old` implementation instead of the `Utf8Safe` implementation,
the following code must be executed before loading the FlatBuffers: `Utf8.setDefault(new Utf8Old());`
See [MicroEJ Docs](https://docs.microej.com/en/latest/ApplicationDeveloperGuide/applicationOptions.html?highlight=utf#option-checkbox-embed-utf-8-encoding)
for more information on how to embed UTF-8 encoding.
## Schema Compiler
If an application uses `.fbs` files to describe the data structure, these files must be converted to Java code.
This is done by using the [FlatBuffers schema compiler](https://google.github.io/flatbuffers/flatbuffers_guide_using_schema_compiler.html).
The code generated by this compiler is compatible with MicroEJ except in a specific case: if a `struct` or a `table` uses a field of type `string` as `key`.
The suggested workaround is to use another field as `key`.
## Testsuite
The library implementation can be tested by running the `FlatBuffers Testsuite` launcher.
This launcher is configured to embed UTF-8 encoding and to specify a sufficient Java heap size.
It can be run on simulator or on device, on any platform with FS (`1.2` or compatible).
# Usage
Add the following line to your `module.ivy`:
<dependency org="com.google" name="flatbuffers" rev="1.0.0"/>
# Requirements
This library requires the following Foundation Libraries:
BON-1.4, EDC-1.3
# Dependencies
_All dependencies are retrieved transitively by MicroEJ Module Manager_.
# Source
N/A.
# Restrictions
None.
---
_Copyright 2022 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._
https://repository.microej.com/modules/ej/library/iot/aws-iot/2.0.0/
AWS IoT Java SDK is a set of Java APIs enabling MicroEJ developers to securely access and interact with AWS IoT platform from an embedded device.
LIBRARY for IOT
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
1 June 2022
# Overview
AWS IoT Java SDK is a set of Java APIs enabling MicroEJ developers to securely access and interact with
[AWS IoT platform](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) from an embedded device.
It can be used to create embedded applications that runs on MicroEJ VEE.
It provides the following functionalities:
- AWS MQTT connection over TLS
- AWS MQTT Topics Pub/Sub
- AWS Device Shadow management (CRUD)
# Usage
Add the following line to your `module.ivy`:
<dependency org="ej.library.iot" name="aws-iot" rev="2.0.0"/>
# Requirements
This library requires the following Foundation Libraries to be provided by the MicroEJ VEE:
BON-1.4, EDC-1.3, NET-1.1, SECURITY-1.3, SSL-2.2, TRACE-1.1
# Dependencies
All dependencies are retrieved transitively by MicroEJ Module Manager.
# Source
N/A
## Code Memory Consumption
AWS IoT Java SDK code memory consumption is approximately ``3.1KB``
It has been measured using the [Memory Map Analyzer](https://docs.microej.com/en/latest/ApplicationDeveloperGuide/memoryMapAnalyzer.html)
on the [WROVER 4.1 Platform](https://github.com/MicroEJ/Platform-Espressif-ESP-WROVER-KIT-V4.1) based on Xtensa LX6 Architecture version ``7.16.0``.
The original ``SOAR.map`` file can be found [here](./memoryrequirements/SOAR.map) and can be browsed using the Memory Map Analyzer in the MicroEJ SDK.
This library relies on MicroPaho (MicroEJ lightweight MQTT client implementation). MicroPaho is about ``5.5KB``.
# Documentation
## Client options & connection
The MQTT connections options are provided by the class ``AwsIotClientOptions``.
```java
// Build the client connection options using the AwsIotClientOptions.Builder
AwsIotClientOptions options = AwsIotClientOptions.Builder
.builder()
.host("<AWS IoT server URL>")
.port(8883)// AWS IoT server port
.clientID("<MQTT client id>")// MQTT client id
.thingName("<AWS IoT thing name>")
.timeout(30) //Optional, client connection timeout in seconds. default is 30
.keepAlive(60) //Optional, client connection keep alive in seconds. default is 60
.secure(socketFactory)// Optional, an SSL Socket Factory for TLS connection
.username("username") // Optional, User name to use in MQTT CONNECT
.password("changeit") // Optional, Password to use in MQTT CONNECT
.build();
// Create an instance of AwsIotClient using the connection options
AwsIotClient client = new AwsIotClient(options);
client.connect(); // connect
```
**Host**
To get your AWS IoT ``host`` address (endpoint):
- Connect to ``AWS Console``
- Go to ``Iot Core`` Service
- From the left menu, go to ``Setting``
- Copy the endpoint from the setting page.
It looks something like ``*.iot.eu-west-3.amazonaws.com``
**Port**
The MQTT server port. default is ``8883`` for a connection over TLS.
**Client ID**
MQTT client id.
>MQTT client IDs uniquely identify MQTT connections. If a new connection is established using a client ID that is already claimed for another connection, the AWS IoT message broker drops the old connection to allow the new connection. Client IDs must be unique within each AWS account and each AWS Region. This means that you don't need to enforce global uniqueness of client IDs outside of your AWS account or across Regions within your AWS account.
>Source: [AWS IoT Security Best-Practices](https://docs.aws.amazon.com/iot/latest/developerguide/security-best-practices.html)
For Test Only: ``AwsIotClientOptions#generateClientId()`` method can be used to generate a random client id.
The id will have the following format ``MicroEJ<platformTimeNanos>`` where *<platformTimeNanos>* is the current platform time in nanoseconds.
**Thing Name**
The device thing name that was used to register or provision the device in the AWS Iot platform.
**Timeout**
MQTT connection timeout value. This value, measured in seconds,
defines the maximum time interval the client will wait for the network connection to the MQTT server to be established.
The default timeout is 30 seconds.
A value of 0 disables timeout processing meaning the client will wait until the network connection is made successfully or fails.
**Keep Alive**
This value, measured in seconds, defines the maximum time interval between messages sent or received.
It enables the client to detect if the server is no longer available, without having to wait for the TCP/IP timeout.
The client will ensure that at least one message travels across the network within each keep alive period.
In the absence of a data-related message during the time period,
the client sends a very small "ping" message, which the server will acknowledge.
A value of 0 disables keep alive processing in the client.
The default value is 60 seconds
**Secure (Socket Factory)**
This options let you configure the underlying socket factory to setup a TLS connection for example.
**Username & Password**
MQTT credentials to be used in CONNECT.
## Client Disconnect
----------
Use ``AwsIotClient#disconnect()`` method on a connected client to disconnect the client. This will close the underlying connection socket.
The same client instance can be reused to connect the device again.
```java
client.disconnect();
```
## Client Close
Use ``AwsIotClient#close()`` after disconnecting the clients to clear all the registered subscribers callbacks and
stop the executor service responsible of executing the callbacks when a message is received.
```java
client.close();
```
# AWS MQTT Pub/Sub
## Publish
Message can be published using QOS 0 or 1 to a specific topic using the following APIs:
* ``publish(AwsIotMessage message)``
* ``publish(String topic, byte[] data)``
* ``publish(String topic, byte[] data, int qos)``
* ``publish(String topic, byte[] data, int qos, boolean retained)``
### Publish Example
```java
String message = "{\"message\" : \"Hello world\"}";
client.publish("foo/bar", message.getBytes());
```
## Subscribe
Topic subscriptions are managed using a callback mechanism. A callback can be registered on a topic
and will be executed when a message is received on that specific topic.
Callbacks are executed on a separated thread.
### Subscribe Example
```java
AwsIotMessageCallback callback = new AwsIotMessageCallback() {
@Override
public void onMessageReceived(AwsIotMessage message) {
// message received..
System.out.println(message.getTopic());
System.out.println(message.getQos());
System.out.println(message.isRetained());
System.out.println(new String(message.getPayload()));
}
};
// Subscribe to topic
client.subscribe("foo/bar", callback);
```
# AWS Device Shadow
The AWS IoT Device Shadow service adds shadows to AWS IoT thing objects.
Shadows can make a deviceâs state available to apps and other services whether the device is connected to AWS IoT or not.
AWS IoT thing objects can have multiple named shadows so that your IoT solution has more options for connecting your devices to other apps and services.
[Read more about Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html)
The SDK provides the following API to manage Device Shadow.
**Subscribe to shadow results before performing an action to get the result.**
You can subscribe to none, one or all the possible results ACCEPTED, REJECTED, DELTA, and DOCUMENTS.
## Classic Shadow:
* ``getShadow()``
* ``getShadow(int qos)``
* ``deleteShadow()``
* ``deleteShadow(int qos)``
* ``updateShadow(byte[] message)``
* ``updateShadow(byte[] message, int qos)``
* ``subscribeToShadow(ShadowAction action, ShadowResult result, AwsIotMessageCallback callback)``
* ``subscribeToShadow(ShadowAction action, ShadowResult result, AwsIotMessageCallback callback, int qos)``
* ``unsubscribeFromShadow(ShadowAction action, ShadowResult result)``
## Named Shadow:
* ``getShadow(String shadowName)``
* ``getShadow(String shadowName, int qos)``
* ``deleteShadow(String shadowName)``
* ``deleteShadow(String shadowName, int qos)``
* ``updateShadow(String shadowName, byte[] message)``
* ``updateShadow(String shadowName, byte[] message, int qos)``
* ``subscribeToShadow(String shadowName, ShadowAction action, ShadowResult result, AwsIotMessageCallback callback)``
* ``subscribeToShadow(String shadowName, ShadowAction action, ShadowResult result, AwsIotMessageCallback callback, int qos)``
* ``unsubscribeFromShadow(String shadowName, ShadowAction action, ShadowResult result)``
## Get Shadow Example
``` java
AwsIotMessageCallback onSuccess = new AwsIotMessageCallback() {
@Override
public void onMessageReceived(AwsIotMessage message) {
System.out.println("accepted");
System.out.println(new String(message.getPayload()));
}
}
AwsIotMessageCallback onError = new AwsIotMessageCallback() {
@Override
public void onMessageReceived(AwsIotMessage message) {
System.out.println("rejected");
System.out.println(new String(message.getPayload()));
}
}
// subscribe to get results
client.subscribeToShadow(ShadowAction.get, ShadowResult.accepted, onSuccess);
client.subscribeToShadow(ShadowAction.get, ShadowResult.rejected, onError);
// Get for the shadow data
client.getShadow();
```
## Delete Shadow Example
```java
AwsIotMessageCallback onSuccess = new AwsIotMessageCallback() {
@Override
public void onMessageReceived(AwsIotMessage message) {
System.out.println("accepted");
System.out.println(new String(message.getPayload()));
}
}
AwsIotMessageCallback onError = new AwsIotMessageCallback() {
@Override
public void onMessageReceived(AwsIotMessage message) {
System.out.println("rejected");
System.out.println(new String(message.getPayload()));
}
}
//subscribe to delete shadow events
client.subscribeToShadow(ShadowAction.delete, ShadowResult.accepted, onSuccess);
client.subscribeToShadow(ShadowAction.delete, ShadowResult.rejected, onError);
// delete shadow
client.deleteShadow()
```
## Create/Update Shadow Example
```java
String AWS_SHADOW_NAME = "shadowName";
String message = "{\"state\": {\"reported\": {\"welcome\": \"AWS updated\"}}}";
AwsIotMessageCallback onSuccess = new AwsIotMessageCallback() {
@Override
public void onMessageReceived(AwsIotMessage message) {
System.out.println("accepted");
System.out.println(new String(message.getPayload()));
}
}
AwsIotMessageCallback onError = new AwsIotMessageCallback() {
@Override
public void onMessageReceived(AwsIotMessage message) {
System.out.println("rejected");
System.out.println(new String(message.getPayload()));
}
}
AwsIotMessageCallback delta = new AwsIotMessageCallback() {
@Override
public void onMessageReceived(AwsIotMessage message) {
System.out.println("delta");
System.out.println(new String(message.getPayload()));
}
}
AwsIotMessageCallback documents = new AwsIotMessageCallback() {
@Override
public void onMessageReceived(AwsIotMessage message) {
System.out.println("documents");
System.out.println(new String(message.getPayload()));
}
}
// Subscribe update shadow results
client.subscribeToShadow(ShadowAction.update, ShadowResult.accepted, onSuccess);
client.subscribeToShadow(ShadowAction.update, ShadowResult.rejected, onError);
client.subscribeToShadow(ShadowAction.update, ShadowResult.delta, delta);
client.subscribeToShadow(ShadowAction.update, ShadowResult.documents, documents);
// Create or Update a shadow and
client.updateShadow(message.getBytes());
```
# Restrictions
The following features specified by MQTT ``3.1.1`` are not supported by this client:
* Other MQTT versions than ``3.1.1``
* Clean Session 0
* QoS 2
* Will messages
* Multiple in-flight messages
* When QoS is 1, the message acknowledgment is sent before the callback method is executed, thus the message is acknowledged even if an exception is thrown by the callback
* Within an implementation of ``AwsIotMessageCallback`` callback, it is not possible to send a new message. Only the following methods are allowed to be called:
* ``ej.aws.iot.AwsIotClient.getClientOptions()``
* ``ej.aws.iot.AwsIotClient.isConnected()``
* [AWS IoT differences from MQTT version 3.1.1 specification](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html#mqtt-differences)
* Topic filters are not supported when registering a callback during subscribe. The full topic name should be provided. [Read more about AWS Topic filters](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html#topicfilters).
---
_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._https://repository.microej.com/modules/ej/library/iot/micropaho/1.0.0/
MicroPaho - MQTT Client is MicroEJ Add-on Library for MQTT protocol communication.
LIBRARY for IOT
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
1 June 2022
# Overview
MicroPaho - MQTT Client is MicroEJ Add-on Library for MQTT protocol communication.
MicroPaho is a tiny MQTT client running on MicroEJ, inspired from Eclipse Paho Java & Embedded C implementations.
This library has been designed with the following key points in mind:
* Keep well known APIs defined by the Paho Java implementation. Most of the existing Java applications using Paho Java implementation can be migrated in few minutes with minor updates.
* Simple, efficient and tiny code inspired by the Paho Embedded C implementation:
* At least one action at a time (connect, publish, subscribe, disconnect) so that there is at most one pending acknowledgment to wait for.
* Minimum dependencies to external libraries
* Implements only features of the MQTT specification required to connect production grade MQTT servers. The most noticeable feature which is not supported by this library is QoS 2.
# Usage
Add the following line to your `module.ivy`:
<dependency org="ej.library.iot" name="micropaho" rev="1.0.0"/>
# Requirements
This library requires the following Foundation Libraries to be provided by the MicroEJ VEE:
BON-1.4, EDC-1.3, NET-1.1, TRACE-1.1
# Dependencies
All dependencies are retrieved transitively by MicroEJ Module Manager.
# Source
This software has been derived from:
- Eclipse Paho Java, commit ID ``5af7b53499e7dbe45b7227b3d41fc870089c0033``
- Eclipse Paho Embedded C, commit ID ``07bf54a3f4a93121a018edb6981facc85e566f27``
# Tests
* To Run the tests, a running docker process is required on the test host.
* Docker version >= ``20.10.8``
MicroPaho is tested at build time against a local ``Mosquitto`` server.
The project is configured to start/stop an ``eclipse-mosquitto:1.6.15`` docker container before running/terminating the tests execution.
The docker image is automatically pulled from [docker hub](https://hub.docker.com/_/eclipse-mosquitto).
MicroPaho has been successfully tested to connect [AWS IoT Core server](https://aws.amazon.com/fr/iot-core/).
# Memory Requirements
This section provides some measurements giving a good idea of the library memory requirements.
The values are given as an indication and are subject to slightly change from versions to versions.
## Code Memory Consumption
MicroPaho code memory consumption is approximately ``5.5KB``.
It has been measured using the [Memory Map Analyzer](https://docs.microej.com/en/latest/ApplicationDeveloperGuide/memoryMapAnalyzer.html)
on the [WROVER 4.1 Platform](https://github.com/MicroEJ/Platform-Espressif-ESP-WROVER-KIT-V4.1) based on Xtensa LX6 Architecture version ``7.16.0``.
The original ``SOAR.map`` file can be found [here](./memoryrequirements/SOAR.map) and can be browsed using the Memory Map Analyzer in the MicroEJ SDK.
## Heap Memory Consumption
MicroPaho heap memory consumption is approximately ``2KB``
(from the ``MqttConnectOptions`` object creation to a message received in the ``MqttCallback.messageArrived`` callback).
It has been measured to 1.9KB using the MicroEJ Simulator
on a Platform based on CM4/GCC Architecture version ``7.11.0`` and NET Pack version ``8.1.6``.
## Thread and Stack Consumption
MicroPaho requires one thread to dispatch incoming events and to regularly send the ``Keep Alive`` message
when it is enabled.
The thread requires less than ``1`` stack block of ``512`` bytes for its internal execution.
Obviously, the thread may require more than one stack block depending on the depth of
the application callback call stack.
## External Dependencies
MicroPaho depends on approximately ``25`` types and ``60`` methods.
At the time this file has been wrote, here is the list of the required types:
```
ej/bon/Constants
ej/bon/Immutables
ej/bon/Util
ej/trace/Tracer
java/io/EOFException
java/io/InputStream
java/io/OutputStream
java/lang/AssertionError
java/lang/AutoCloseable
java/lang/Class
java/lang/IllegalArgumentException
java/lang/Integer
java/lang/Object
java/lang/Runnable
java/lang/RuntimeException
java/lang/String
java/lang/StringBuilder
java/lang/Thread
java/lang/Throwable
java/net/InetSocketAddress
java/net/Socket
javax/net/SocketFactory
```
# Restrictions
The following features specified by MQTT ``3.1.1`` are not supported by this client:
* Other MQTT versions than ``3.1.1``
* Clean Session 0
* QoS 2
* Will messages
* Multiple in-flight messages
The following features specified by the Eclipse Paho Java API are not supported by this client:
* The callback method ``org.eclipse.paho.client.mqttv3.MqttCallback.messageArrive`` specification has been modified:
* when QoS is 1, the message acknowledgment is sent before the callback method is executed, thus the message is acknowledged even if an exception is thrown by the callback
* within an implementation of this callback, it is not possible to send a new message. Only the following methods are allowed to be called:
- ``org.eclipse.paho.client.mqttv3.IMqttClient.getClientId()``
- ``org.eclipse.paho.client.mqttv3.IMqttClient.getServerURI()``
- ``org.eclipse.paho.client.mqttv3.IMqttClient.isConnected()``
* The method ``org.eclipse.paho.client.mqttv3.MqttCallback.deliveryComplete(IMqttDeliveryToken)`` has been removed.
* No topic format validation in ``publish`` and ``subscribe`` methods
# Constants
* ``micropaho.server.check`` enable additional consistency checks on the data received from the MQTT server. default is `true`
* ``micropaho.thread.priority`` allow to customize the MQTT receiver thread priority. default is ``5``
* ``micropaho.debug`` enable debug mode and activate traces. default is ``false``
[see B-ON constants documentation](https://docs.microej.com/en/latest/ApplicationDeveloperGuide/classpath.html#constants)
---
_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._ https://github.com/MicroEJ/Tool-UITestAutomation/tree/2.0.0
A tool for automated GUI testing and a library for using this tool with JUnit.
TOOL for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
1 June 2022
# Overview
This repository provides an automated tool for UI testing. It is used to record scenario of events (on `Pointer` and `Button`) and replay the scenario. While replaying a scenario, this tool can also compare the screen with screenshots captured while recording scenario.
# Architecture
This module extends the classes `Pointer` and `Button` of the `FrontPanel` then the tool overrides its events and adds a recording step before sending the event to the MicroEJ Application. It can also capture a screenshot so when the user replays it, they will have a point to compare the current screen with the screen captured during the recording process. The screen capture process stores the current displayed pixels in a .raw file.
The replay process is done by replicating an event from the `Pointer` or `Button` by getting the widget by its label name and calling the event recorded.
# Usage
## Run on MicroEJ Simulator
- Add the following line to the platform-fp's `module.ivy`:
```xml
<dependency org="ej.tool.frontpanel" name="fp-test-automation-tool" rev="2.0.0"/>
```
- Update the Front Panel file(s) (`.fp` in `src/main/resources`) to record and simulate `Pointer` and `Button` events:
- Replace `ej.fp.widget.Pointer` by `ej.fp.widget.recorder.RecorderPointer`.
- Replace `ej.fp.widget.Button` by `ej.fp.widget.recorder.RecorderButton`.
- Build the platform-configuration project.
- Update the application launchers to use the new platform.
### Recording
To record a scenario press the record button (center button). All triggered events within the Display (and `RecorderButton` if used) are recorded. Click on the screenshot button (right button) to take a screenshot for comparison while recording.
All the files are stored under `$USER_HOME/.microej/frontPanelRecorder` in subfolders representing their timestamp of creation. The following files are available:
- `scenario.steps` contains all the commands recorded.
- `screenshotTIMESTAMP.raw` are screenshot images taken when recording.
- `testTIMESTAMP.report` are the reports generated after the execution of the scenario.
The `.raw` format is a raw bytes file that stores all the pixels in sequence. They are store in order `Alpha`, `Red`, `Green` and `Blue`. `Alpha` is the transparency component of each pixel, `Red` is the red component, `Green` is the green component and `Blue` is the blue component.
The `testTIMESTAMP.report` files has the results of all screenshot comparisons, it can have two results:
- Screen test number TIMESTAMP ended with success.
- Screen test number TIMESTAMP ended with with fail exiting player.
When a test fails it will stop execution of the player so it will not have the result message of any tests after the failed one.
### Playing
To play a scenario:
- Select a scenario from the `Scenario List` (below the buttons)
- Press the play button (left button) to play the selected scenario
# Requirements
- Java SE 8.
- UI Pack 13.0.0 or higher.
# Dependencies
_All dependencies are retrieved transitively by MicroEJ Module Manager_.
# Restrictions
Cannot be used on embedded devices.
# Known limitations
- The tool can, and most likely will, display incorrect test results if animations are involved, the best solution for this is to avoid animations by waiting for the animation to completely end before making any other actions while recording.
- Scroll animations in particular will cause a test to fail almost every time. To avoid the scroll animation, either wait a little before releasing the pointer after a drag or set the animation time to 0.
---
_Markdown_
_Copyright 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._https://github.com/MicroEJ/Tool-SDK-Docker
MicroEJ BuildKit Docker Image for various MICROEJ SDK versions.
TOOL for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
11 October 2021
# Docker for MicroEJ BuildKit SDK
## Overview
This is the git repository to build the MicroEJ BuildKit Docker Image
for various MicroEJ SDK versions.
## Documentation
All images referenced in this document are available in our [Docker Hub repository](https://hub.docker.com/u/microej/).
You can also build them yourself following build instruction bellow and our [Github repository](https://github.com/MicroEJ/Tool-SDK-Docker).
### MicroEJ SDK version `5.4.1` and above
For MicroEJ SDK version `5.4.1` and above, please refer to
<https://docs.microej.com/en/latest/ApplicationDeveloperGuide/mmm.html#command-line-interface>.
Start the image for interactive usage:
``` console
$ docker run --rm -it microej/sdk:5.4.1 bash
```
Build a project from a local folder:
``` console
$ docker run --rm -v PATH/TO/PROJECT:/project -w /project microej/sdk:5.4.1 mmm build
```
You can also build the image yourself from `Dockerfile`:
``` console
$ docker build -t microej/sdk:5.4.1 5.4.1
```
### MicroEJ SDK version `4.1.5` to `5.3.1`
For MicroEJ SDK version `4.1.5` to `5.3.1`, please refer to
<https://github.com/MicroEJ/Tool-CommandLineBuild>.
Start the image for interactive usage:
``` console
$ docker run --rm -it microej/sdk:4.1.5 bash
```
Build a project from a local folder:
``` console
$ docker run --rm -v PATH/TO/PROJECT:/project -w /project microej/sdk:4.1.5 build_module_local.sh ./
```
You can also build the image yourself from `Dockerfile`:
``` console
$ docker build -t microej/sdk:4.1.5 4.1.5
```
### Automated tests
A Jenkinsfile is at the root of this project to automatically test project Dockerfiles. You can launch it using Jenkins CI. \
We followed the Jenkins recommendations to write this Jenkinsfile : [Using Docker with Pipeline](https://www.jenkins.io/doc/book/pipeline/docker/). \
If you want to run it, you need to have at least one node labelled `docker`.
## F.A.Q
### How can I add my custom certificate to fetch my company dependencies using mmm ?
You can either :
#### Update existing keystore
Add your custom CA certificate to the docker image by adding these lines
to the `Dockerfile` you want to build :
``` console
USER root
COPY company.cer $JAVA_HOME/jre/lib/security
RUN \
cd $JAVA_HOME/jre/lib/security \
&& keytool -keystore cacerts -storepass changeit -noprompt -trustcacerts -importcert -alias companycert -file company.cer
```
#### Use custom keystore
Mount your keystore using -v in the docker container and use it with mmm
by adding `-Djavax.net.ssl.trustStore=keystore_path_in_container` to
your build
### How can I use my custom ivysettings to use my company maven repository ?
The recommended way to do that is to mount your ivysettings into your
docker container and use MMM-CLI with parameter `-r` to specify the
module repository settings file location.
Please refer to [MicroEJ Module Manager
documentation](https://docs.microej.com/en/latest/SDKUserGuide/mmm.html)
for more information.
## Where to get help?
- [MicroEJ Forum](https://forum.microej.com)
- [MicroEJ Documentation Center](https://docs.microej.com)
- [MicroEJ Technical Hot-line](https://www.microej.com/contact/#form_2)
---
_Markdown_
_Copyright 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._ https://github.com/MicroEJ/VEEPort-Espressif-ESP-WROVER-KIT-V4.1/tree/3ffa756213f3f63003ddf3c30a35f6e311d54ff0
VEE Port for Espressif ESP-WROVER-KIT V4.1 development board (MonoSandbox, GCC, FreeRTOS)
VEE Port for Espressif ESP-WROVER-KIT V4.1 development 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.
https://github.com/MicroEJ/Demo-Protobuf3/tree/864692476599aaa60534c3fe0df47bd25f976ccf
This example contains a demo illustrating how to use Protobuf 3 library.
EXAMPLE for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
19 February 2021
..
Copyright 2020-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.
=============================================================================================
Running the partial buffer demo and integrating partial buffer support to an existing project
=============================================================================================
Overview
========
This example shows the minimum steps required to implement a UI partial buffer in a MicroEJ application and in a MicroEJ platform.
To learn more about the partial buffer, please visit the `MicroEJ Developer Documentation <https://docs.microej.com/en/latest/PlatformDeveloperGuide/uiDisplay.html#section-display-partial-buffer>`__.
The following steps will be described:
- Running the demo application on STM32F7508-DK
- Changing your MicroEJ application to use partial buffer
- Changing your platform to support partial buffer
Requirements
------------
This example has been tested on:
- STM32F7508-DK board
- MicroEJ SDK 5.3.0
- STM32CubeIDE 1.5.0
Repository content
------------------
This repository provides:
- a fork of the STM32F7508-DK demo platform 1.2.0, which supports the partial buffer mode
- a support library, which allows to use the partial buffer support of the platform in the application
- a demo application, which uses partial buffer and shows animations
- this documentation
Running the demo application on STM32F7508-DK
=============================================
Setting up the workspace
------------------------
Importing the projects
~~~~~~~~~~~~~~~~~~~~~~
1. Open MicroEJ SDK in an empty workspace
2. Select ``File > Import...``
3. Select ``General > Existing Projects into Workspace``
4. Press ``Next >``
5. Next to the ``Select root directory`` field, press ``Browse...``
6. Navigate to the root folder of this Git repository
7. Press ``OK``
8. Press ``Finish``
Downloading the architecture and packs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Download the following architecture and packs (``.xpf`` and ``.xpfp``):
- Architecture: https://repository.microej.com/architectures/com/microej/architecture/CM7/CM7hardfp_GCC48/flopi7G26/7.14.0/
- UI pack: https://repository.microej.com/architectures/com/microej/architecture/CM7/CM7hardfp_GCC48/flopi7G26-ui-pack/13.0.3/
- FS pack: https://repository.microej.com/modules/com/microej/pack/fs/5.1.2/
- HAL pack: https://repository.microej.com/modules/com/microej/pack/hal/2.0.1/
- NET pack: https://repository.microej.com/modules/com/microej/pack/net/9.2.2/
Importing the architecture and packs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. In MicroEJ SDK, select ``File > Import...``
2. Select ``MicroEJ > Architectures``
3. Press ``Next >``
4. Next to the ``Select directory`` field, press ``Browse...``
5. Navigate to the folder containing the downloaded architecture and packs
6. Press ``OK``
7. Press ``Deselect All``
8. Check ``ARM Cortex-M7 GCC EVAL``
9. Click on ``ARM Cortex-M7 GCC EVAL``
10. Check ``I agree and accept the above terms and conditions and I want to install the copyrighted Software``
11. Click on ``HAL``
12. Check ``I agree and accept the above terms and conditions and I want to install the copyrighted Software``
13. Press ``Finish``
Activate your architecture license
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Follow the steps in `this documentation <https://docs.microej.com/en/latest/overview/licenses.html#evaluation-license>`__ in order to activate your license of the evaluation architecture.
Building the platform
~~~~~~~~~~~~~~~~~~~~~
1. In MicroEJ SDK, open the ``stm32f7508_freertos-configuration/STM32F7508.platform`` file
4. Click on ``Build Platform``
Running the demo application on simulator
-----------------------------------------
1. In MicroEJ SDK, select ``Run > Run Configurations...``
2. Under ``MicroEJ Application``, select the ``Partial Buffer Demo (SIM)`` run configuration
3. Press ``Run``
Running the demo application on device
--------------------------------------
Building the application on device
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. In MicroEJ SDK, select ``Run > Run Configurations...``
2. Under ``MicroEJ Application``, select the ``Partial Buffer Demo (EMB)`` run configuration
3. Press ``Run``
Importing the BSP project
~~~~~~~~~~~~~~~~~~~~~~~~~
1. Open STM32CubeIDE in an empty workspace
2. Select ``File > Import...``
3. Select ``General > Existing Projects into Workspace``
4. Press ``Next >``
5. Next to the ``Select root directory`` field, press ``Browse...``
6. Navigate to the ``stm32f7508_freertos-bsp/projects/microej/SW4STM32`` folder of this Git repository
7. Press ``OK``
8. Press ``Finish``
Building the BSP project
~~~~~~~~~~~~~~~~~~~~~~~~
1. In STM32CubeIDE, right-click on the ``application`` project
2. Press ``Build Project``
3. Wait for the end of the build
Flashing the application on the board
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. Plug-in your STM32F7508-DK board
2. In STM32CubeIDE, select ``Run > Run Configurations...``
3. Under ``STM32 Cortex-M C/C++ Application``, select the ``application_debug`` run configuration
4. Press ``Run``
Changing your MicroEJ application to use partial buffer
=======================================================
Setting up the render policy
----------------------------
First, add a dependency to the support library in the ``module.ivy`` file of your application:
.. code-block:: xml
<dependency org="com.microej.example.partial" name="support" rev="1.0.0"/>
In the code of your application, use the partial render policy instead of the default policy when the desktop is created:
.. code-block:: java
Desktop desktop = new Desktop() {
@Override
protected RenderPolicy createRenderPolicy() {
return new PartialRenderPolicy(this, false);
}
};
Solving rendering issues
------------------------
Using a partial buffer may lead to rendering issues.
Refer to the ``Application Limitations`` section of `this documentation <https://docs.microej.com/en/latest/PlatformDeveloperGuide/uiDisplay.html#section-display-partial-buffer>`__ in order to understand why these issues occur and how to fix them.
Updating the run configuration
------------------------------
To be able to run your application, the platform selected in the run configuration has to support partial buffer.
If you want to check that your application doesn't have rendering issues in partial buffer mode, you may run your application on the STM32F7508-DK platform provided in this demo.
If you want to run your application on your own platform, follow the next section in order to integrate the partial buffer support in your platform.
Changing your platform to support partial buffer
================================================
Running your application on simulator
-------------------------------------
Run your application launcher on your platform.
When the application will try to use the partial render policy, the execution will fail because your platform does not support partial buffer yet.
Here is the expected error message:
::
Exception in thread "UIPump" @T:java.lang.UnsatisfiedLinkError@: No HIL client implementor found (timeout)
at java.lang.Throwable.fillInStackTrace(Throwable.java:82)
at java.lang.Throwable.<init>(Throwable.java:37)
at java.lang.Error.<init>(Error.java:18)
at java.lang.LinkageError.<init>(LinkageError.java:18)
at java.lang.UnsatisfiedLinkError.<init>(UnsatisfiedLinkError.java:10)
at com.microej.example.partial.support.PartialRenderPolicy.<init>(PartialRenderPolicy.java:42)
at com.microej.demo.widget.common.PageHelper$2.createRenderPolicy(PageHelper.java:216)
at ej.mwt.Desktop.onShown(Desktop.java:217)
at ej.microui.display.Display.replaceDisplayable(Display.java:322)
at ej.microui.display.Display.executeEventOnShow(Display.java:271)
at ej.microui.display.DisplayPump.executeEvent(DisplayPump.java:81)
at ej.microui.MicroUIPump.execute(MicroUIPump.java:236)
at ej.microui.MicroUIPump.run(MicroUIPump.java:177)
at java.lang.Thread.run(Thread.java:325)
at java.lang.Thread.runWrapper(Thread.java:387
This error is due to the missing implementation of the partial buffer natives.
Indeed, the simulator engine expects to find a Java implementation emulating the behavior of the partial buffer natives.
The next section describes how to implement a mock of the partial buffer for the simulator.
Implementing the partial buffer mock for the simulator
------------------------------------------------------
The simulator is using a mock called Front Panel (``{YOUR_PLATFORM_NAME}-fp`` project) to generate a graphical representation of the target device.
The partial buffer mock needs to be integrated to the Front Panel to simulate the use of a partial buffer.
To integrate the partial buffer mock to a Front Panel project, perform the following steps:
1. Copy the ``com.microej.example.partial.support`` package from the `stm32f7508_freertos-fp <stm32f7508_freertos-fp/src/main/java/>`__ project to your Front Panel project
2. Open the ``PartialBufferNatives`` class of your Front Panel project and change the value of the ``BUFFER_HEIGHT`` constant to the desired value
3. Open the description file of your Front Panel project (``.fp`` file) and replace ``ej.fp.widget.Display`` by ``com.microej.example.partial.support.PartialDisplay``
4. Open the configuration file of your platform (``.platform`` file) and build the platform
Once done, you should be able to run your application on simulator.
Running your application on device
----------------------------------
Building the application
~~~~~~~~~~~~~~~~~~~~~~~~
Run your application launcher on your platform, and link the application with your BSP.
Since your application uses the partial render policy, the link will fail because your platform does not support partial buffer yet.
Here is the expected error message:
::
undefined reference to Java_com_microej_example_partial_support_PartialBufferNatives_setFlushLimits
undefined reference to Java_com_microej_example_partial_support_PartialBufferNatives_getBufferHeight
This error is due to the missing implementation of the partial buffer natives.
Indeed, the linker expects to find the C implementation of the partial buffer natives.
The next section describes how to implement the partial buffer in the BSP code.
Implementing the partial buffer in the BSP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section shows the process for a STM32F7508-DK target using the GCC toolchain.
Please refer to the relevant ``Build a Java Platform`` guide in the ``Getting started`` section of MicroEJ Resource Center for indications on how to adapt this process to your specific target.
The partial buffer is designed to work with the ``copy`` mode of the MicroUI Display engine.
See the `Buffer Modes <https://docs.microej.com/en/latest/PlatformDeveloperGuide/uiDisplay.html#principle>`__ section of the MicroEJ GUI documentation for more information.
This ``copy`` mode is a prerequisite to complete the following steps.
The implementation of the partial buffer is done in the ``LLUI_DISPLAY.c`` file located in the ``stm32f7508_freertos-bsp/projects/microej/ui/src/`` folder.
Step 1: Allocate memory for the back buffer and the frame buffer
################################################################
In the ``LLUI_DISPLAY.c`` file, remove the following lines:
.. code-block:: C
#define DISPLAY_MEM_SIZE 0x80000
uint8_t display_mem[DISPLAY_MEM_SIZE] __ALIGNED(DISPLAY_MEM_SIZE) __attribute__((section(".DisplayMem")));
#define BUFFER_SIZE (RK043FN48H_WIDTH * RK043FN48H_HEIGHT * (DRAWING_DMA2D_BPP / 8))
#define BACK_BUFFER ((int32_t)&display_mem[0])
#define FRAME_BUFFER (BACK_BUFFER + BUFFER_SIZE)
Add the following lines to allocate a dedicated array for the frame buffer:
.. code-block:: C
#define FRAME_BUFFER_MEM_SIZE RK043FN48H_WIDTH * RK043FN48H_HEIGHT * DRAWING_DMA2D_BPP / 8
uint8_t frame_buffer_mem[FRAME_BUFFER_MEM_SIZE] __attribute__((section(".DisplayMem")));
#define FRAME_BUFFER ((int32_t)&frame_buffer_mem[0])
Add the following lines to allocate a dedicated array for the back buffer:
.. code-block:: C
#define BACK_BUFFER_HEIGHT 136
#define BACK_BUFFER_MEM_SIZE RK043FN48H_WIDTH * BACK_BUFFER_HEIGHT * DRAWING_DMA2D_BPP / 8
uint8_t back_buffer_mem[BACK_BUFFER_MEM_SIZE] __attribute__((section(".DisplayMem")));
#define BACK_BUFFER ((int32_t)&back_buffer_mem[0])
In the ``main.c`` file, update the MPU (Memory Protection Unit) configuration:
- Add the following lines to make a reference to the back buffer:
.. code-block:: C
extern uint8_t back_buffer_mem[];
#define BACK_BUFFER ((int32_t)&back_buffer_mem[0])
- In the ``MPU_Config`` function:
- Update the size of the protected region for the back buffer:
- Change the ``MPU_InitStruct.Size = MPU_REGION_SIZE_256KB;`` line to ``MPU_InitStruct.Size = MPU_REGION_SIZE_128KB;``
- Add the following lines after the last ``HAL_MPU_ConfigRegion(&MPU_InitStruct)`` line,
to protect the memory space of the frame buffer:
.. code-block:: C
MPU_InitStruct.BaseAddress = FRAME_BUFFER;
MPU_InitStruct.Size = MPU_REGION_SIZE_256KB;
MPU_InitStruct.IsCacheable = MPU_ACCESS_NOT_CACHEABLE;
MPU_InitStruct.DisableExec = MPU_INSTRUCTION_ACCESS_DISABLE;
MPU_InitStruct.Number = MPU_REGION_NUMBER6;
HAL_MPU_ConfigRegion(&MPU_InitStruct);
Note that the ``MPU_InitStruct.Number`` must be unique for each protected memory space.
Step 2: Setup variables for the partial buffer
##############################################
In the ``LLUI_DISPLAY.c`` file:
Declare a structure that will be used to store the parameters of the flushed region:
.. code-block:: C
typedef struct {
int32_t x_offset;
int32_t y_offset;
uint32_t width;
uint32_t height;
} flush_region_t;
static flush_region_t flush_region;
Step 3: Implement the partial buffer natives
############################################
Add the partial Buffer native functions, following the strict SNI naming convention mentioned earlier.
For the ``..._setFlushLimits`` native, use the ``flush_region`` structure to save the flush parameters:
.. code-block:: C
void Java_com_microej_example_partial_support_PartialBufferNatives_setFlushLimits(jint xOffset, jint yOffset, jint width, jint height)
{
flush_region.x_offset = xOffset;
flush_region.y_offset = yOffset;
flush_region.width = width;
flush_region.height = height;
}
For the ``..._getBufferHeight`` native, return the back buffer height:
.. code-block:: C
int32_t Java_com_microej_example_partial_support_PartialBufferNatives_getBufferHeight()
{
return BACK_BUFFER_HEIGHT;
}
Step 4: Adapt the LLUI_DISPLAY_IMPL_flush function to use the partial buffer
############################################################################
In the partial buffer mode, the role of the ``LLUI_DISPLAY_IMPL_flush`` function is to copy the content of the back buffer to a specific area of the frame buffer.
First, the back buffer content needs to be fetched without exceeding its boundaries.
Thus, ``Xmax`` and ``Ymax`` will respectively be the width and the height of the area to update:
.. code-block:: C
xmax = flush_region.width - 1;
ymax = flush_region.height - 1;
Secondly, that content needs to be copied to a specific area of the frame buffer.
This area is determined thanks to the X and Y flush offsets.
Slide the frame buffer address to copy the content to the right area:
.. code-block:: C
int y_flush_offset = flush_region.y_offset;
int x_flush_offset = flush_region.x_offset;
uint8_t* dest_addr = FRAME_BUFFER_ADDRESS + ((x_flush_offset + y_flush_offset * SCREEN_WIDTH) * DISPLAY_BPP / 8);
The ``SCREEN_WIDTH`` and ``DISPLAY_BPP`` constants are depending on the configuration of the target device.
Finally, copy the back buffer to the frame buffer, it can be done with a ``memcpy`` or thanks to DMA.
In this example, the DMA2D accelerator of the STM32F7508-DK board is used:
.. code-block:: C
DRAWING_DMA2D_configure_memcpy(srcAddr, dest_addr, xmin, ymin, xmax, ymax, SCREEN_WIDTH, &dma2d_memcpy);
DRAWING_DMA2D_start_memcpy(&dma2d_memcpy);
Extra: Switching to dual back buffer mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A dual back buffer can be implemented for performances enhancement.
It is interesting to implement it when the copy from the back buffer to the frame buffer takes a long time compared the time taken by the MicroEJ application to draw in the back buffer.
The dual back buffer mode is using 2 back buffers of the same size and the frame buffer:
- Back Buffer A (BB_A)
- Back Buffer B (BB_B)
- Frame Buffer (FB)
This switch mode will run the following way:
1. App is drawing in BB_A
2. BB_A is copied to FB
3. App is drawing in BB_B
4. BB_B is copied to FB
5. App is drawing in BB_A
6. ...
This process can be parallelized, doing the back buffer to frame buffer copy in a dedicated task (DMA flush task):
+------+----------------+------------------+
| Time | Flush function | DMA flush task |
+======+================+==================+
| T1 | App -> BB_A | WAITING |
+------+----------------+------------------+
| T2 | App -> BB_B | BB_A -> FB |
+------+----------------+------------------+
| T3 | App -> BB_A | BB_B -> FB |
+------+----------------+------------------+
| T4 | App -> BB_B | BB_A -> FB |
+------+----------------+------------------+
| T5 | ... | ... |
+------+----------------+------------------+
In the following example, the dual back buffer has already been implemented
in the `dual_back_buffer.c <stm32f7508_freertos-bsp/projects/microej/ui/src/dual_back_buffer.c>`__ file.
It can be enabled by adding the ``#define DUAL_BACK_BUFFER_MODE_ENABLED`` directive in the
in the `display_configuration.h <stm32f7508_freertos-bsp/projects/microej/ui/inc/display_configuration.h>`__ file.
The following steps explain how to implement this dual back buffer.
Step 1: Allocate the memory for a second back buffer
#####################################################
In the ``LLUI_DISPLAY.c`` file:
- Allocate the memory for the second back buffer:
.. code-block:: C
uint8_t back_buffer_B_mem[BACK_BUFFER_MEM_SIZE] __attribute__((section(".DisplayMem")));
#define BACK_BUFFER_B ((int32_t)&back_buffer_B_mem[0])
In the ``main.c`` file, update the MPU (Memory Protection Unit) configuration:
- Add the following lines to make a reference to the second back buffer:
.. code-block:: C
extern uint8_t back_buffer_B_mem[];
#define BACK_BUFFER_B ((int32_t)&back_buffer_B_mem[0])
- In the ``MPU_Config`` function, update the MPU configuration,
add the following lines after the last ``HAL_MPU_ConfigRegion(&MPU_InitStruct)`` line:
.. code-block:: C
MPU_InitStruct.BaseAddress = BACK_BUFFER_B;
MPU_InitStruct.Size = MPU_REGION_SIZE_128KB;
MPU_InitStruct.IsCacheable = MPU_ACCESS_NOT_CACHEABLE;
MPU_InitStruct.DisableExec = MPU_INSTRUCTION_ACCESS_DISABLE;
MPU_InitStruct.Number = MPU_REGION_NUMBER7;
HAL_MPU_ConfigRegion(&MPU_InitStruct);
Note that the ``MPU_InitStruct.Number`` must be unique for each protected memory space.
Step 2: Declare binary semaphores to synchronize the DMA flush task with the flush function
#############################################################################################
In the ``LLUI_DISPLAY.c`` file:
- Declare binary semaphores:
.. code-block:: C
static xSemaphoreHandle task_start_copy_sem;
static xSemaphoreHandle dma2d_end_of_copy_sem;
- Initialize the semaphores in the ``LLUI_DISPLAY_IMPL_initialize`` function:
.. code-block:: C
task_start_copy_sem = xSemaphoreCreateBinary();
dma2d_end_of_copy_sem = xSemaphoreCreateBinary();
Step 3: Implement a custom callback function for the DMA2D
###########################################################
By default, when the DMA copy ends, the callback function ``LLUI_DISPLAY_flushDone``
is called to notify the MicroEJ application that the flush is done.
Once received, the application will start drawing a new frame in the back buffer.
In the dual back buffer case, it is not necessary to wait for the end of the DMA copy anymore.
Indeed, one back buffer will be copied to the frame buffer while the application will draw in the other one.
A custom callback will be used to replace the call to the ``LLUI_DISPLAY_flushDone`` callback.
This callback will be used to notify the DMA flush task that the DMA have finished its job.
In the ``LLUI_DISPLAY.c`` file:
- Add a custom callback function that unlocks the ``dma2d_end_of_copy_sem`` semaphore:
.. code-block:: C
void DMA2D_EndOfCopy(bool under_isr)
{
LLUI_DISPLAY_IMPL_binarySemaphoreGive((void*)dma2d_end_of_copy_sem, under_isr);
}
In the ``drawing_dma2d.c`` file:
- Declare the ``DMA2D_EndOfCopy`` function:
.. code-block:: C
extern void DMA2D_EndOfCopy(bool under_isr);
- In the ``DRAWING_DMA2D_configure_memcpy`` function, configure the DMA2D to call the
``DMA2D_EndOfCopy`` callback :
.. code-block:: C
g_callback_notification = &DMA2D_EndOfCopy;
Step 4: Implement the DMA flush task
####################################
In the ``LLUI_DISPLAY.c`` file:
- Declare a structure that will be used to pass the flush parameters of the flush function to the DMA flush task:
.. code-block:: C
typedef struct {
uint8_t* srcAddr;
uint8_t* dest_addr;
uint32_t xmin;
uint32_t ymin;
uint32_t xmax;
uint32_t ymax;
} flush_params_t;
static flush_params_t flush_params;
- Create a new task in the ``LLUI_DISPLAY_IMPL_initialize`` function:
.. code-block:: C
xTaskCreate(&DMA_flush_task, "DMA_flush_task",
1024, &flush_params, DMA_TASK_PRIO, NULL);
The ``DMA_TASK_PRIO`` should have less priority than the MicroJVM task (``JAVA_TASK_PRIORITY``)
defined in the `main.c <stm32f7508_freertos-bsp/projects/microej/main/src/main.c>`__ file.
- Implement the ``DMA_flush_task`` function:
.. code-block:: C
void DMA_flush_task(void * params)
{
while(1){
// wait for flush asked by the Java application
LLUI_DISPLAY_IMPL_binarySemaphoreTake((void*)task_start_copy_sem);
flush_params_t* flush_p = (flush_params_t*) params; /* get the parameters */
// The DMA2D configure waits for the end of a previous DMA2D copy before starting
DRAWING_DMA2D_configure_memcpy(flush_p->srcAddr, flush_p->dest_addr, flush_p->xmin, flush_p->ymin, flush_p->xmax, flush_p->ymax, RK043FN48H_WIDTH, &dma2d_memcpy, false);
LLUI_DISPLAY_flushDone(false); /* send the flush done event to the Java world */
DRAWING_DMA2D_start_memcpy(&dma2d_memcpy);
// wait for the end of the DMA copy
LLUI_DISPLAY_IMPL_binarySemaphoreTake((void*)dma2d_end_of_copy_sem);
}
}
Note that the ``DRAWING_DMA2D_configure_memcpy`` and ``DRAWING_DMA2D_start_memcpy`` functions have been moved from the ``LLUI_DISPLAY_IMPL_flush`` to the DMA flush task.
Step 5: Update the LLUI_DISPLAY_IMPL_flush function
###################################################
In the ``LLUI_DISPLAY.c`` file, in the ``LLUI_DISPLAY_IMPL_flush`` function:
- Delete the call to the ``DRAWING_DMA2D_configure_memcpy`` and ``DRAWING_DMA2D_start_memcpy`` functions
- Store the flush parameters in the ``flush_params`` structure:
.. code-block:: C
flush_params.srcAddr=srcAddr;
flush_params.dest_addr=dest_addr;
flush_params.xmin=xmin;
flush_params.xmax=flush_region.width -1;
flush_params.ymin=ymin;
flush_params.ymax=flush_region.height-1;
- Wake up the DMA flush task:
.. code-block:: C
xSemaphoreGive(task_start_copy_sem);
- Change the returned address to switch between the back buffer A and B:
.. code-block:: C
return srcAddr == (uint8_t*)BACK_BUFFER_A ? (uint8_t*)BACK_BUFFER_B : (uint8_t*)BACK_BUFFER_A;
Tweaking the size of the partial buffer
---------------------------------------
The goal of using a partial buffer is to reduce the memory footprint used by the display.
The following section explains how to adapt the size of the partial buffer.
In the Front Panel
~~~~~~~~~~~~~~~~~~
1. Open the ``com.microej.example.partial.support.PartialBufferNatives`` class of your Front Panel project
2. Change the value of the ``BUFFER_HEIGHT`` constant to the desired value
In the BSP
~~~~~~~~~~
The generic formula to compute the size of a pixel buffer is the following one: ``SCREEN_WIDTH * BUFFER_HEIGHT * DISPLAY_BPP / 8``
The value of ``DISPLAY_BPP`` depends on the MicroUI configuration on the target board.
Refer to the `MicroEJ documentation <https://docs.microej.com/en/latest/PlatformDeveloperGuide/uiDisplay.html#section-display-installation>`__ for more information.
For the STM32F7508-DK board, the parameters are the following ones:
- ``SCREEN_WIDTH``: 480
- ``SCREEN_HEIGHT``: 272
- ``DISPLAY_BPP``: 16
Frame buffer size computation
#############################
Since the display uses a buffer in RAM to read the pixel data to display, this buffer has to be a complete buffer.
For example, on the STM32F7508-DK board, the size of the frame buffer would be ``262120`` bytes.
Back buffer size computation
############################
A partial buffer always has the same width as the screen but a smaller height.
For example, on the STM32F7508-DK board, the size of a back buffer presenting half the screen would be ``130560`` bytes.
https://github.com/MicroEJ/Demo-PartialBuffer/tree/091c7a78b63e6d8d7ecb016423ae5148abf2f9ed
This example shows the minimum steps required to implement a UI partial buffer in a MicroEJ application and platform.
EXAMPLE for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
10 February 2021
..
Copyright 2020-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.
=============================================================================================
Running the partial buffer demo and integrating partial buffer support to an existing project
=============================================================================================
Overview
========
This example shows the minimum steps required to implement a UI partial buffer in a MicroEJ application and in a MicroEJ platform.
To learn more about the partial buffer, please visit the `MicroEJ Developer Documentation <https://docs.microej.com/en/latest/PlatformDeveloperGuide/uiDisplay.html#section-display-partial-buffer>`__.
The following steps will be described:
- Running the demo application on STM32F7508-DK
- Changing your MicroEJ application to use partial buffer
- Changing your platform to support partial buffer
Requirements
------------
This example has been tested on:
- STM32F7508-DK board
- MicroEJ SDK 5.3.0
- STM32CubeIDE 1.5.0
Repository content
------------------
This repository provides:
- a fork of the STM32F7508-DK demo platform 1.2.0, which supports the partial buffer mode
- a support library, which allows to use the partial buffer support of the platform in the application
- a demo application, which uses partial buffer and shows animations
- this documentation
Running the demo application on STM32F7508-DK
=============================================
Setting up the workspace
------------------------
Importing the projects
~~~~~~~~~~~~~~~~~~~~~~
1. Open MicroEJ SDK in an empty workspace
2. Select ``File > Import...``
3. Select ``General > Existing Projects into Workspace``
4. Press ``Next >``
5. Next to the ``Select root directory`` field, press ``Browse...``
6. Navigate to the root folder of this Git repository
7. Press ``OK``
8. Press ``Finish``
Downloading the architecture and packs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Download the following architecture and packs (``.xpf`` and ``.xpfp``):
- Architecture: https://repository.microej.com/architectures/com/microej/architecture/CM7/CM7hardfp_GCC48/flopi7G26/7.14.0/
- UI pack: https://repository.microej.com/architectures/com/microej/architecture/CM7/CM7hardfp_GCC48/flopi7G26-ui-pack/13.0.3/
- FS pack: https://repository.microej.com/modules/com/microej/pack/fs/5.1.2/
- HAL pack: https://repository.microej.com/modules/com/microej/pack/hal/2.0.1/
- NET pack: https://repository.microej.com/modules/com/microej/pack/net/9.2.2/
Importing the architecture and packs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. In MicroEJ SDK, select ``File > Import...``
2. Select ``MicroEJ > Architectures``
3. Press ``Next >``
4. Next to the ``Select directory`` field, press ``Browse...``
5. Navigate to the folder containing the downloaded architecture and packs
6. Press ``OK``
7. Press ``Deselect All``
8. Check ``ARM Cortex-M7 GCC EVAL``
9. Click on ``ARM Cortex-M7 GCC EVAL``
10. Check ``I agree and accept the above terms and conditions and I want to install the copyrighted Software``
11. Click on ``HAL``
12. Check ``I agree and accept the above terms and conditions and I want to install the copyrighted Software``
13. Press ``Finish``
Activate your architecture license
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Follow the steps in `this documentation <https://docs.microej.com/en/latest/overview/licenses.html#evaluation-license>`__ in order to activate your license of the evaluation architecture.
Building the platform
~~~~~~~~~~~~~~~~~~~~~
1. In MicroEJ SDK, open the ``stm32f7508_freertos-configuration/STM32F7508.platform`` file
4. Click on ``Build Platform``
Running the demo application on simulator
-----------------------------------------
1. In MicroEJ SDK, select ``Run > Run Configurations...``
2. Under ``MicroEJ Application``, select the ``Partial Buffer Demo (SIM)`` run configuration
3. Press ``Run``
Running the demo application on device
--------------------------------------
Building the application on device
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. In MicroEJ SDK, select ``Run > Run Configurations...``
2. Under ``MicroEJ Application``, select the ``Partial Buffer Demo (EMB)`` run configuration
3. Press ``Run``
Importing the BSP project
~~~~~~~~~~~~~~~~~~~~~~~~~
1. Open STM32CubeIDE in an empty workspace
2. Select ``File > Import...``
3. Select ``General > Existing Projects into Workspace``
4. Press ``Next >``
5. Next to the ``Select root directory`` field, press ``Browse...``
6. Navigate to the ``stm32f7508_freertos-bsp/projects/microej/SW4STM32`` folder of this Git repository
7. Press ``OK``
8. Press ``Finish``
Building the BSP project
~~~~~~~~~~~~~~~~~~~~~~~~
1. In STM32CubeIDE, right-click on the ``application`` project
2. Press ``Build Project``
3. Wait for the end of the build
Flashing the application on the board
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. Plug-in your STM32F7508-DK board
2. In STM32CubeIDE, select ``Run > Run Configurations...``
3. Under ``STM32 Cortex-M C/C++ Application``, select the ``application_debug`` run configuration
4. Press ``Run``
Changing your MicroEJ application to use partial buffer
=======================================================
Setting up the render policy
----------------------------
First, add a dependency to the support library in the ``module.ivy`` file of your application:
.. code-block:: xml
<dependency org="com.microej.example.partial" name="support" rev="1.0.0"/>
In the code of your application, use the partial render policy instead of the default policy when the desktop is created:
.. code-block:: java
Desktop desktop = new Desktop() {
@Override
protected RenderPolicy createRenderPolicy() {
return new PartialRenderPolicy(this, false);
}
};
Solving rendering issues
------------------------
Using a partial buffer may lead to rendering issues.
Refer to the ``Application Limitations`` section of `this documentation <https://docs.microej.com/en/latest/PlatformDeveloperGuide/uiDisplay.html#section-display-partial-buffer>`__ in order to understand why these issues occur and how to fix them.
Updating the run configuration
------------------------------
To be able to run your application, the platform selected in the run configuration has to support partial buffer.
If you want to check that your application doesn't have rendering issues in partial buffer mode, you may run your application on the STM32F7508-DK platform provided in this demo.
If you want to run your application on your own platform, follow the next section in order to integrate the partial buffer support in your platform.
Changing your platform to support partial buffer
================================================
Running your application on simulator
-------------------------------------
Run your application launcher on your platform.
When the application will try to use the partial render policy, the execution will fail because your platform does not support partial buffer yet.
Here is the expected error message:
::
Exception in thread "UIPump" @T:java.lang.UnsatisfiedLinkError@: No HIL client implementor found (timeout)
at java.lang.Throwable.fillInStackTrace(Throwable.java:82)
at java.lang.Throwable.<init>(Throwable.java:37)
at java.lang.Error.<init>(Error.java:18)
at java.lang.LinkageError.<init>(LinkageError.java:18)
at java.lang.UnsatisfiedLinkError.<init>(UnsatisfiedLinkError.java:10)
at com.microej.example.partial.support.PartialRenderPolicy.<init>(PartialRenderPolicy.java:42)
at com.microej.demo.widget.common.PageHelper$2.createRenderPolicy(PageHelper.java:216)
at ej.mwt.Desktop.onShown(Desktop.java:217)
at ej.microui.display.Display.replaceDisplayable(Display.java:322)
at ej.microui.display.Display.executeEventOnShow(Display.java:271)
at ej.microui.display.DisplayPump.executeEvent(DisplayPump.java:81)
at ej.microui.MicroUIPump.execute(MicroUIPump.java:236)
at ej.microui.MicroUIPump.run(MicroUIPump.java:177)
at java.lang.Thread.run(Thread.java:325)
at java.lang.Thread.runWrapper(Thread.java:387
This error is due to the missing implementation of the partial buffer natives.
Indeed, the simulator engine expects to find a Java implementation emulating the behavior of the partial buffer natives.
The next section describes how to implement a mock of the partial buffer for the simulator.
Implementing the partial buffer mock for the simulator
------------------------------------------------------
The simulator is using a mock called Front Panel (``{YOUR_PLATFORM_NAME}-fp`` project) to generate a graphical representation of the target device.
The partial buffer mock needs to be integrated to the Front Panel to simulate the use of a partial buffer.
To integrate the partial buffer mock to a Front Panel project, perform the following steps:
1. Copy the ``com.microej.example.partial.support`` package from the `stm32f7508_freertos-fp <stm32f7508_freertos-fp/src/main/java/>`__ project to your Front Panel project
2. Open the ``PartialBufferNatives`` class of your Front Panel project and change the value of the ``BUFFER_HEIGHT`` constant to the desired value
3. Open the description file of your Front Panel project (``.fp`` file) and replace ``ej.fp.widget.Display`` by ``com.microej.example.partial.support.PartialDisplay``
4. Open the configuration file of your platform (``.platform`` file) and build the platform
Once done, you should be able to run your application on simulator.
Running your application on device
----------------------------------
Building the application
~~~~~~~~~~~~~~~~~~~~~~~~
Run your application launcher on your platform, and link the application with your BSP.
Since your application uses the partial render policy, the link will fail because your platform does not support partial buffer yet.
Here is the expected error message:
::
undefined reference to Java_com_microej_example_partial_support_PartialBufferNatives_setFlushLimits
undefined reference to Java_com_microej_example_partial_support_PartialBufferNatives_getBufferHeight
This error is due to the missing implementation of the partial buffer natives.
Indeed, the linker expects to find the C implementation of the partial buffer natives.
The next section describes how to implement the partial buffer in the BSP code.
Implementing the partial buffer in the BSP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section shows the process for a STM32F7508-DK target using the GCC toolchain.
Please refer to the relevant ``Build a Java Platform`` guide in the ``Getting started`` section of MicroEJ Resource Center for indications on how to adapt this process to your specific target.
The partial buffer is designed to work with the ``copy`` mode of the MicroUI Display engine.
See the `Buffer Modes <https://docs.microej.com/en/latest/PlatformDeveloperGuide/uiDisplay.html#principle>`__ section of the MicroEJ GUI documentation for more information.
This ``copy`` mode is a prerequisite to complete the following steps.
The implementation of the partial buffer is done in the ``LLUI_DISPLAY.c`` file located in the ``stm32f7508_freertos-bsp/projects/microej/ui/src/`` folder.
Step 1: Allocate memory for the back buffer and the frame buffer
################################################################
In the ``LLUI_DISPLAY.c`` file, remove the following lines:
.. code-block:: C
#define DISPLAY_MEM_SIZE 0x80000
uint8_t display_mem[DISPLAY_MEM_SIZE] __ALIGNED(DISPLAY_MEM_SIZE) __attribute__((section(".DisplayMem")));
#define BUFFER_SIZE (RK043FN48H_WIDTH * RK043FN48H_HEIGHT * (DRAWING_DMA2D_BPP / 8))
#define BACK_BUFFER ((int32_t)&display_mem[0])
#define FRAME_BUFFER (BACK_BUFFER + BUFFER_SIZE)
Add the following lines to allocate a dedicated array for the frame buffer:
.. code-block:: C
#define FRAME_BUFFER_MEM_SIZE RK043FN48H_WIDTH * RK043FN48H_HEIGHT * DRAWING_DMA2D_BPP / 8
uint8_t frame_buffer_mem[FRAME_BUFFER_MEM_SIZE] __attribute__((section(".DisplayMem")));
#define FRAME_BUFFER ((int32_t)&frame_buffer_mem[0])
Add the following lines to allocate a dedicated array for the back buffer:
.. code-block:: C
#define BACK_BUFFER_HEIGHT 136
#define BACK_BUFFER_MEM_SIZE RK043FN48H_WIDTH * BACK_BUFFER_HEIGHT * DRAWING_DMA2D_BPP / 8
uint8_t back_buffer_mem[BACK_BUFFER_MEM_SIZE] __attribute__((section(".DisplayMem")));
#define BACK_BUFFER ((int32_t)&back_buffer_mem[0])
In the ``main.c`` file, update the MPU (Memory Protection Unit) configuration:
- Add the following lines to make a reference to the back buffer:
.. code-block:: C
extern uint8_t back_buffer_mem[];
#define BACK_BUFFER ((int32_t)&back_buffer_mem[0])
- In the ``MPU_Config`` function:
- Update the size of the protected region for the back buffer:
- Change the ``MPU_InitStruct.Size = MPU_REGION_SIZE_256KB;`` line to ``MPU_InitStruct.Size = MPU_REGION_SIZE_128KB;``
- Add the following lines after the last ``HAL_MPU_ConfigRegion(&MPU_InitStruct)`` line,
to protect the memory space of the frame buffer:
.. code-block:: C
MPU_InitStruct.BaseAddress = FRAME_BUFFER;
MPU_InitStruct.Size = MPU_REGION_SIZE_256KB;
MPU_InitStruct.IsCacheable = MPU_ACCESS_NOT_CACHEABLE;
MPU_InitStruct.DisableExec = MPU_INSTRUCTION_ACCESS_DISABLE;
MPU_InitStruct.Number = MPU_REGION_NUMBER6;
HAL_MPU_ConfigRegion(&MPU_InitStruct);
Note that the ``MPU_InitStruct.Number`` must be unique for each protected memory space.
Step 2: Setup variables for the partial buffer
##############################################
In the ``LLUI_DISPLAY.c`` file:
Declare a structure that will be used to store the parameters of the flushed region:
.. code-block:: C
typedef struct {
int32_t x_offset;
int32_t y_offset;
uint32_t width;
uint32_t height;
} flush_region_t;
static flush_region_t flush_region;
Step 3: Implement the partial buffer natives
############################################
Add the partial Buffer native functions, following the strict SNI naming convention mentioned earlier.
For the ``..._setFlushLimits`` native, use the ``flush_region`` structure to save the flush parameters:
.. code-block:: C
void Java_com_microej_example_partial_support_PartialBufferNatives_setFlushLimits(jint xOffset, jint yOffset, jint width, jint height)
{
flush_region.x_offset = xOffset;
flush_region.y_offset = yOffset;
flush_region.width = width;
flush_region.height = height;
}
For the ``..._getBufferHeight`` native, return the back buffer height:
.. code-block:: C
int32_t Java_com_microej_example_partial_support_PartialBufferNatives_getBufferHeight()
{
return BACK_BUFFER_HEIGHT;
}
Step 4: Adapt the LLUI_DISPLAY_IMPL_flush function to use the partial buffer
############################################################################
In the partial buffer mode, the role of the ``LLUI_DISPLAY_IMPL_flush`` function is to copy the content of the back buffer to a specific area of the frame buffer.
First, the back buffer content needs to be fetched without exceeding its boundaries.
Thus, ``Xmax`` and ``Ymax`` will respectively be the width and the height of the area to update:
.. code-block:: C
xmax = flush_region.width - 1;
ymax = flush_region.height - 1;
Secondly, that content needs to be copied to a specific area of the frame buffer.
This area is determined thanks to the X and Y flush offsets.
Slide the frame buffer address to copy the content to the right area:
.. code-block:: C
int y_flush_offset = flush_region.y_offset;
int x_flush_offset = flush_region.x_offset;
uint8_t* dest_addr = FRAME_BUFFER_ADDRESS + ((x_flush_offset + y_flush_offset * SCREEN_WIDTH) * DISPLAY_BPP / 8);
The ``SCREEN_WIDTH`` and ``DISPLAY_BPP`` constants are depending on the configuration of the target device.
Finally, copy the back buffer to the frame buffer, it can be done with a ``memcpy`` or thanks to DMA.
In this example, the DMA2D accelerator of the STM32F7508-DK board is used:
.. code-block:: C
DRAWING_DMA2D_configure_memcpy(srcAddr, dest_addr, xmin, ymin, xmax, ymax, SCREEN_WIDTH, &dma2d_memcpy);
DRAWING_DMA2D_start_memcpy(&dma2d_memcpy);
Extra: Switching to dual back buffer mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A dual back buffer can be implemented for performances enhancement.
It is interesting to implement it when the copy from the back buffer to the frame buffer takes a long time compared the time taken by the MicroEJ application to draw in the back buffer.
The dual back buffer mode is using 2 back buffers of the same size and the frame buffer:
- Back Buffer A (BB_A)
- Back Buffer B (BB_B)
- Frame Buffer (FB)
This switch mode will run the following way:
1. App is drawing in BB_A
2. BB_A is copied to FB
3. App is drawing in BB_B
4. BB_B is copied to FB
5. App is drawing in BB_A
6. ...
This process can be parallelized, doing the back buffer to frame buffer copy in a dedicated task (DMA flush task):
+------+----------------+------------------+
| Time | Flush function | DMA flush task |
+======+================+==================+
| T1 | App -> BB_A | WAITING |
+------+----------------+------------------+
| T2 | App -> BB_B | BB_A -> FB |
+------+----------------+------------------+
| T3 | App -> BB_A | BB_B -> FB |
+------+----------------+------------------+
| T4 | App -> BB_B | BB_A -> FB |
+------+----------------+------------------+
| T5 | ... | ... |
+------+----------------+------------------+
In the following example, the dual back buffer has already been implemented
in the `dual_back_buffer.c <stm32f7508_freertos-bsp/projects/microej/ui/src/dual_back_buffer.c>`__ file.
It can be enabled by adding the ``#define DUAL_BACK_BUFFER_MODE_ENABLED`` directive in the
in the `display_configuration.h <stm32f7508_freertos-bsp/projects/microej/ui/inc/display_configuration.h>`__ file.
The following steps explain how to implement this dual back buffer.
Step 1: Allocate the memory for a second back buffer
#####################################################
In the ``LLUI_DISPLAY.c`` file:
- Allocate the memory for the second back buffer:
.. code-block:: C
uint8_t back_buffer_B_mem[BACK_BUFFER_MEM_SIZE] __attribute__((section(".DisplayMem")));
#define BACK_BUFFER_B ((int32_t)&back_buffer_B_mem[0])
In the ``main.c`` file, update the MPU (Memory Protection Unit) configuration:
- Add the following lines to make a reference to the second back buffer:
.. code-block:: C
extern uint8_t back_buffer_B_mem[];
#define BACK_BUFFER_B ((int32_t)&back_buffer_B_mem[0])
- In the ``MPU_Config`` function, update the MPU configuration,
add the following lines after the last ``HAL_MPU_ConfigRegion(&MPU_InitStruct)`` line:
.. code-block:: C
MPU_InitStruct.BaseAddress = BACK_BUFFER_B;
MPU_InitStruct.Size = MPU_REGION_SIZE_128KB;
MPU_InitStruct.IsCacheable = MPU_ACCESS_NOT_CACHEABLE;
MPU_InitStruct.DisableExec = MPU_INSTRUCTION_ACCESS_DISABLE;
MPU_InitStruct.Number = MPU_REGION_NUMBER7;
HAL_MPU_ConfigRegion(&MPU_InitStruct);
Note that the ``MPU_InitStruct.Number`` must be unique for each protected memory space.
Step 2: Declare binary semaphores to synchronize the DMA flush task with the flush function
#############################################################################################
In the ``LLUI_DISPLAY.c`` file:
- Declare binary semaphores:
.. code-block:: C
static xSemaphoreHandle task_start_copy_sem;
static xSemaphoreHandle dma2d_end_of_copy_sem;
- Initialize the semaphores in the ``LLUI_DISPLAY_IMPL_initialize`` function:
.. code-block:: C
task_start_copy_sem = xSemaphoreCreateBinary();
dma2d_end_of_copy_sem = xSemaphoreCreateBinary();
Step 3: Implement a custom callback function for the DMA2D
###########################################################
By default, when the DMA copy ends, the callback function ``LLUI_DISPLAY_flushDone``
is called to notify the MicroEJ application that the flush is done.
Once received, the application will start drawing a new frame in the back buffer.
In the dual back buffer case, it is not necessary to wait for the end of the DMA copy anymore.
Indeed, one back buffer will be copied to the frame buffer while the application will draw in the other one.
A custom callback will be used to replace the call to the ``LLUI_DISPLAY_flushDone`` callback.
This callback will be used to notify the DMA flush task that the DMA have finished its job.
In the ``LLUI_DISPLAY.c`` file:
- Add a custom callback function that unlocks the ``dma2d_end_of_copy_sem`` semaphore:
.. code-block:: C
void DMA2D_EndOfCopy(bool under_isr)
{
LLUI_DISPLAY_IMPL_binarySemaphoreGive((void*)dma2d_end_of_copy_sem, under_isr);
}
In the ``drawing_dma2d.c`` file:
- Declare the ``DMA2D_EndOfCopy`` function:
.. code-block:: C
extern void DMA2D_EndOfCopy(bool under_isr);
- In the ``DRAWING_DMA2D_configure_memcpy`` function, configure the DMA2D to call the
``DMA2D_EndOfCopy`` callback :
.. code-block:: C
g_callback_notification = &DMA2D_EndOfCopy;
Step 4: Implement the DMA flush task
####################################
In the ``LLUI_DISPLAY.c`` file:
- Declare a structure that will be used to pass the flush parameters of the flush function to the DMA flush task:
.. code-block:: C
typedef struct {
uint8_t* srcAddr;
uint8_t* dest_addr;
uint32_t xmin;
uint32_t ymin;
uint32_t xmax;
uint32_t ymax;
} flush_params_t;
static flush_params_t flush_params;
- Create a new task in the ``LLUI_DISPLAY_IMPL_initialize`` function:
.. code-block:: C
xTaskCreate(&DMA_flush_task, "DMA_flush_task",
1024, &flush_params, DMA_TASK_PRIO, NULL);
The ``DMA_TASK_PRIO`` should have less priority than the MicroJVM task (``JAVA_TASK_PRIORITY``)
defined in the `main.c <stm32f7508_freertos-bsp/projects/microej/main/src/main.c>`__ file.
- Implement the ``DMA_flush_task`` function:
.. code-block:: C
void DMA_flush_task(void * params)
{
while(1){
// wait for flush asked by the Java application
LLUI_DISPLAY_IMPL_binarySemaphoreTake((void*)task_start_copy_sem);
flush_params_t* flush_p = (flush_params_t*) params; /* get the parameters */
// The DMA2D configure waits for the end of a previous DMA2D copy before starting
DRAWING_DMA2D_configure_memcpy(flush_p->srcAddr, flush_p->dest_addr, flush_p->xmin, flush_p->ymin, flush_p->xmax, flush_p->ymax, RK043FN48H_WIDTH, &dma2d_memcpy, false);
LLUI_DISPLAY_flushDone(false); /* send the flush done event to the Java world */
DRAWING_DMA2D_start_memcpy(&dma2d_memcpy);
// wait for the end of the DMA copy
LLUI_DISPLAY_IMPL_binarySemaphoreTake((void*)dma2d_end_of_copy_sem);
}
}
Note that the ``DRAWING_DMA2D_configure_memcpy`` and ``DRAWING_DMA2D_start_memcpy`` functions have been moved from the ``LLUI_DISPLAY_IMPL_flush`` to the DMA flush task.
Step 5: Update the LLUI_DISPLAY_IMPL_flush function
###################################################
In the ``LLUI_DISPLAY.c`` file, in the ``LLUI_DISPLAY_IMPL_flush`` function:
- Delete the call to the ``DRAWING_DMA2D_configure_memcpy`` and ``DRAWING_DMA2D_start_memcpy`` functions
- Store the flush parameters in the ``flush_params`` structure:
.. code-block:: C
flush_params.srcAddr=srcAddr;
flush_params.dest_addr=dest_addr;
flush_params.xmin=xmin;
flush_params.xmax=flush_region.width -1;
flush_params.ymin=ymin;
flush_params.ymax=flush_region.height-1;
- Wake up the DMA flush task:
.. code-block:: C
xSemaphoreGive(task_start_copy_sem);
- Change the returned address to switch between the back buffer A and B:
.. code-block:: C
return srcAddr == (uint8_t*)BACK_BUFFER_A ? (uint8_t*)BACK_BUFFER_B : (uint8_t*)BACK_BUFFER_A;
Tweaking the size of the partial buffer
---------------------------------------
The goal of using a partial buffer is to reduce the memory footprint used by the display.
The following section explains how to adapt the size of the partial buffer.
In the Front Panel
~~~~~~~~~~~~~~~~~~
1. Open the ``com.microej.example.partial.support.PartialBufferNatives`` class of your Front Panel project
2. Change the value of the ``BUFFER_HEIGHT`` constant to the desired value
In the BSP
~~~~~~~~~~
The generic formula to compute the size of a pixel buffer is the following one: ``SCREEN_WIDTH * BUFFER_HEIGHT * DISPLAY_BPP / 8``
The value of ``DISPLAY_BPP`` depends on the MicroUI configuration on the target board.
Refer to the `MicroEJ documentation <https://docs.microej.com/en/latest/PlatformDeveloperGuide/uiDisplay.html#section-display-installation>`__ for more information.
For the STM32F7508-DK board, the parameters are the following ones:
- ``SCREEN_WIDTH``: 480
- ``SCREEN_HEIGHT``: 272
- ``DISPLAY_BPP``: 16
Frame buffer size computation
#############################
Since the display uses a buffer in RAM to read the pixel data to display, this buffer has to be a complete buffer.
For example, on the STM32F7508-DK board, the size of the frame buffer would be ``262120`` bytes.
Back buffer size computation
############################
A partial buffer always has the same width as the screen but a smaller height.
For example, on the STM32F7508-DK board, the size of a back buffer presenting half the screen would be ``130560`` bytes.
https://github.com/MicroEJ/PlatformQualificationTools/tree/c103690e1ca34b511c567c00cda939d76416b274
Platform Qualification Tools
The Platform Qualification Tools (PQT) project provides the tools required to validate each component of a MicroEJ Platform.
TOOL for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
14 January 2021
Description
===========
The Platform Qualification Tools (PQT) project provides the tools required to validate each component of a MicroEJ Platform.
After porting or adding a feature to a MicroEJ Platform, it is necessary to validate its integration.
Clone this repository with ``git clone --recursive https://github.com/MicroEJ/PlatformQualificationTools``.
Test Suites Available
=====================
Core Engine Test Suite
----------------------
The CORE Test Suite contains a C Test Suite and a Java Test Suite. It is the most basic Test Suite to run.
It ensures MicroEJ Application will run correctly.
All other Test Suites assume the CORE Test Suite is validated.
See `CORE Readme <tests/core/README.rst>`_
Graphical User Interface Test Suite
-----------------------------------
The UI Test Suite is a C Test Suite. It checks the integration of the ``LLDisplay`` API and the tearing signal usage.
It also provides indication about the minimum draw time allowed to display animations at a given framerate.
See `UI Readme <tests/ui/README.rst>`_
Filesystem Test Suite
---------------------
The FS Test Suite is a Java Test Suite. It checks the integration of the ``LLFS*`` APIs over a C File System library.
See `FS Readme <tests/fs/README.rst>`_
Platform Qualification Tools Overview
=====================================
The Platform Qualification Tools (PQT) contains:
- a ``framework/`` folder with scripts and frameworks used by the tests
- a ``tests/`` folder with one sub-folder per Test Suite (e.g. ``tests/core/`` for the CORE Test Suite, etc.)
Each Test Suite sub-folder contains a ``README.rst`` that explain how to use the Test Suite in details.
The following sections give an overview of the Platform Qualification Tools (PQT).
Framework
---------
The ``framework/`` folder contains the infrastructure required to build and run the tests.
C infrastructure
----------------
The ``framework/c/`` folders contains the following:
- Embedded Unit (embUnit) is a unit testing framework used for C tests.
- CoreMark is a processor benchmark used by the CORE Test Suite.
- utils provides several utilities used by various C tests
Platform Configuration Additions
--------------------------------
The ``framework/platform/`` folder contains the MicroEJ Platform Configuration Additions.
See the `Platform Configuration Additions README <framework/platform/README.rst>`_ for more information.
For licenses management, please refer to `License <https://docs.microej.com/en/latest/overview/licenses.html>`_ .
Test Suites
-----------
The Platform Qualification Tools (PQT) provides two kinds of Test Suite:
- C Test Suite that must be added to the BSP
- Java Test Suite that are launched as standard MicroEJ Application
A Test Suite validates a particular component of a MicroEJ Platform.
The CORE Test Suite is applicable to every MicroEJ Platform.
The other Test Suites depends on the capabilities provided by the MicroEJ Platform to validate.
A detailed explanation how to use each Test Suite is provided in the ``README.rst`` present in each sub-folder.
For example, for the CORE Test Suite, refer to the `CORE Readme <tests/core/README.rst>`_.
C Test Suites
-------------
The C Test Suites validate that the hardware and RTOS (if applicable) are properly integrated in the BSP.
The C Test Suites uses Embunit framework. They have to be launched just
before MicroEJ Application (just before the call to ``microjvm_main()``).
At this moment, the BSP is fully initialized and the OS is started.
The C Test Suites perform some basic checks which ensures MicroEJ Application
will run. Unless specified otherwise, C Test Suites are linked with a MicroEJ Application
(``microejapp.o``) and a MicroEJ runtime library (``microejruntime.a``).
The C Test Suites often require some additional data (some specific functions have to
be implemented in addition of LLAPI implementation functions).
Java Test Suites
----------------
The Java Test Suites validate the Foundation Libraries integration.
The Java Test Suites verify the integration of the MicroEJ Platform over the
BSP. No specific unit test framework is used, each test describes how it
works.
..
Copyright 2019-2021 MicroEJ Corp. All rights reserved.
Use of this source code is governed by a BSD-style license that can be found with this software.
https://repository.microej.com/packages/referenceimplementations/M5QNX/1.2.0/STM32F7508-M5QNX-fullPackaging-eval-1.2.0.zip
VEE Port for STMicroelectronics STM32F7508-DK Discovery kit (MonoSandbox, GCC, FreeRTOS)
VEE Port for STMicroelectronics STM32F7508-DK Discovery kit.
JPF_ST for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Technical Ref.: PRI-EVAL-STM32F7508-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.
https://repository.microej.com/packages/referenceimplementations/KUVW3/1.2.0/STM32F7508-KUVW3-fullPackaging-eval-1.2.0.zip
VEE Port for STMicroelectronics STM32F7508-DK Discovery kit (MonoSandbox, IAR, FreeRTOS)
VEE Port for STMicroelectronics STM32F7508-DK Discovery kit.
JPF_ST for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Technical Ref.: PRI-EVAL-STM32F7508-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.
https://github.com/MicroEJ/Tool-DependencyDiscoverer/tree/d76c752d511f53d82c18dc359f465c27d5320a62
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:
19 November 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.
https://github.com/MicroEJ/ExampleTool-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:
18 November 2020
Overview
========
This project presents how to run the SonarQube⢠source code quality analyzer on a MicroEJ Java project.
It explains how to install and run a local SonarQube server, then how to analyze MicroEJ Java projects with MicroEJ recommended rules.
SonarQube is 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.
Project structure
-----------------
- *lib/*: SonarQube client, Ivy, HTTP ant task.
- *rules/*: MicroEJ recommended coding rules.
- *scripts/*: Ant script to run SonarQube analysis.
- *CHANGELOG.rst*.
- *LICENSE.md*.
- *README.rst*.
Usage
-----
Run SonarQube server with Docker
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Install Docker following instructions on https://www.docker.com/get-started.
- Install SonarQube on Docker: ``docker pull sonarqube:8.4.2-community``
- Run SonarQube instance on Docker: ``docker run -d --name mysonar -p 9000:9000 sonarqube:8.4.2-community``
- Once the Docker container is created, it can be:
- stopped: ``docker container stop mysonar``,
- and restarted: ``docker container start mysonar``.
Install necessary plugins
~~~~~~~~~~~~~~~~~~~~~~~~~
- Go to http://localhost:9000/.
- Log in. By default, the login and password are ``admin``.
- Go to *Administration*, *Marketplace*,
- Install the following plugins:
- Checkstyle (version 8.35 or later),
- Findbugs (version 4.0.1 or later),
- PMD (version 3.2.1 or later)
Analysis configuration
~~~~~~~~~~~~~~~~~~~~~~
Open the **scripts/sonarAnalysis.properties** file, edit it to match the project you want to analyze:
- ``sonar.projectBaseDir``: path to the project to analyze.
- ``sonar.login``: login token for the SonarQube server - https://docs.sonarqube.org/latest/user-guide/user-token/.
Other properties can also be configured. Please refer to the properties file.
Launch an analysis
~~~~~~~~~~~~~~~~~~
- Launch MicroEJ.
- *File->Import->General->Existing project into workspace*: import ExampleTool-Sonar folder.
- Edit the configuration **scripts/sonarAnalysis.properties** as described in the configuration section.
- Right-click on **scripts/sonarAnalysis.ant** *->Run asâ¦->Ant build*.
- The MicroEJ quality profile is automatically added on the server and set as default.
- The analysis report is then available on your SonarQube server. The URL is printed in the console during the analysis in the form: `ANALYSIS SUCCESSFUL, you can browse http://localhost:9000/dashboard?id=[organisation]:[name]`
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 ``skip.sonar`` property.
- Add ``sonar.host.url`` property with the URL of your local SonarQube instance (usually http://localhost:9000).
- Add ``sonar.login`` property with the login token of your local SonarQube instance.
Now when a MicroEJ project is built using EasyAnt (right-click on the project *-> Build with EasyAnt*), the sonar server will be populated.
..
Copyright 2015-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.
https://github.com/MicroEJ/Tool-CommandLineBuild/tree/d0ba41af06f6afd452d0945690d63fc848f60a42
This project details how to setup a local environment for building MicroEJ modules from the command line.
TOOL for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
3 November 2020
..
Copyright 2018-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.
Description
-----------
This project details how to setup a local environment for building MicroEJ modules from the command line.
It focuses on running on Windows operating system and can be adapted for other operating systems supported by MicroEJ SDK (Linux and MacOS).
Requirements
------------
* Windows OS ``7`` or higher
* Java Development Kit (JDK) ``1.8.x``
* MicroEJ SDK ``4.1.5`` or higher.
The latest MicroEJ SDK version can be downloaded at https://developer.microej.com/get-started/.
Prerequisites
-------------
#. Locate your JDK installation directory (typically something like ``C:\Program Files\Java\jdk1.8.0_[version]``)
#. Set the environment variable ``MICROEJ_BUILD_JDK_HOME`` to point to this directory.
#. Clone this repository with ``git clone --recursive https://github.com/MicroEJ/Tool-CommandLineBuild``.
Extract MicroEJ Build Kit
-------------------------
MicroEJ SDK comes with its own toolkit for building modules.
Depending on your MicroEJ SDK version, extracting the build kit from the SDK will differ.
Please consult https://docs.microej.com/en/latest/overview/editions.html#get-sdk-version to determine your MicroEJ SDK version.
MicroEJ SDK ``5.2.0`` or higher
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Create a directory named ``buildKit`` in the same directory as this ``README`` file.
#. In the SDK, go to ``Window`` > ``Preferences`` > ``MicroEJ`` > ``Module Manager``.
#. In subsection ``Build repository``, click on ``Export Build Kit``.
#. As ``Target directory``, choose the ``buildKit`` directory, then click on ``Finish``.
#. Go to directory ``buildKit`` and extract the content of the file ``microej-build-repository.zip`` to a directory named ``microej-build-repository``.
MicroEJ SDK ``5.1.0`` or lower
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Create a directory named ``buildKit`` in the same directory as this ``README`` file.
#. Create a sub-directory ``ant`` in the ``buildKit`` directory.
#. Locate your SDK installation directory (by default, ``C:/Program Files/MicroEJ/MicroEJ SDK-[version]``).
#. Within the SDK installation directory, go to the bundled RCP plugins directory (``/rcp/plugins/``).
#. Extract the toolkit runtime:
#. Open the file ``com.is2t.eclipse.plugin.easyant4e_[version].jar`` with an archive manager.
#. Extract the directory ``lib`` to the ``buildKit/ant/`` directory.
#. Extract the toolkit repositories:
#. Open the file ``com.is2t.eclipse.plugin.easyant4e.offlinerepo_[version].jar`` with an archive manager
#. Navigate to directory ``repositories``
#. Extract the file ``microej-build-repository.zip`` (or ``is2t_repo.zip`` for MicroEJ SDK ``4.1.x``) to the ``buildKit`` directory.
#. Go to directory ``buildKit`` and extract the content of the file ``microej-build-repository.zip`` (or ``is2t_repo.zip``) to a directory named ``microej-build-repository``.
At this point, the content of the directory ``buildKit`` should look like the following:
::
buildKit
âââ ant
â âââ lib
â âââ ant.jar
â âââ ant-launcher.jar
â âââ ...
âââ microej-build-repository
â âââ ant-contrib
â âââ be
â âââ ...
Configure the Module Repository
-------------------------------
A Module Repository is a portable ZIP file that bundles a set of modules for extending the MicroEJ development environment. For more information about Module Repositories, please refer to the `Application Developer Guide <https://docs.microej.com/en/latest/ApplicationDeveloperGuide/repository.html>`_.
In the following, we will use the MicroEJ Central Repository, which is the Module Repository used by MicroEJ SDK to fetch dependencies when starting an empty workspace.
It bundles Foundation Library APIs and numerous Add-On Libraries.
Import the MicroEJ Central Repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Next step is to import a local copy of this repository:
#. Visit the `Central Repository <https://developer.microej.com/central-repository/>`_ on the MicroEJ Developer website.
#. Navigate to the ``Working Offline`` section.
#. Click on the ``offline repository`` link. This will download the Central Repository as a zip file.
#. Unzip this file.
#. Open the file ``local-build.properties`` located in the same directory as this README.
#. Set the value of the property ``microej.central.repository.dir`` to be the absolute path to the extracted directory. **Important note**: ensure that the path uses Unix directory separator (``/``).
Set the Build Repository Location
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Personal builds will be published to ``~/.ivy2/repository/`` by default. For Release and Snapshot builds, the repositories location needs to be set manually.
#. Open the file ``local-build.properties``.
#. Set the value of the property ``snapshot.repository.dir`` to be the absolute path to a directory where ``snapshot`` builds will be published. **Important note**: ensure that the path uses Unix directory separator (``/``).
#. Set the value of the property ``release.repository.dir`` to be the absolute path to a directory where ``release`` builds will be published. **Important note**: ensure that the path uses Unix directory separator (``/``).
Create a New MicroEJ Module
---------------------------
In this example, we will create a very simple module using the Sandbox Application buildtype (``build-application``).
#. Start MicroEJ SDK.
#. Go to ``File`` > ``New`` > ``MicroEJ Sandboxed Application Project``.
#. Fill in the template fields and click ``Finish``. This will create the project files and structure.
#. In the ``Package Explorer`` view, right-click on the project and select ``Properties``.
#. In the ``Resources`` entry, copy the absolute path to your module (field ``Location``), it will be used in the next section.
For more details about MicroEJ applications development, refer to the `Application Developer Guide <https://docs.microej.com/en/latest/ApplicationDeveloperGuide/index.html>`_.
Build the Module
----------------
#. Open a terminal from the directory of this README.
#. Type the following command:
``.\build_module_local.bat \path\to\module snapshot``
The build starts.
On successful build, the module is published to ``[snapshot.repository.dir]\[organization]\[module]\[M.m.p-RCYYYYMMDDHHmm]``.
Please note that executing the command ``build_module_local.bat`` with no arguments will print the usage description.
Available Build Modes
~~~~~~~~~~~~~~~~~~~~~
* ``personal``: Fetches module dependencies in the personal, snapshot and release repositories and publish the module in the user's personal repository.
* ``snapshot``: Fetches module dependencies in the snapshot and release repositories and publish the module in the snapshot repository.
* ``fetchRelease``: Fetches module dependencies in the release repositories and publish the module in the snapshot repository.
* ``release``: Fetches module dependencies in the release repositories and publish the module in the release repository.
Build Options
~~~~~~~~~~~~~
Providing custom build options is possible by specifying an additional properties file.
Create a file listing all the custom properties prefixed with ``easyant.inject.``.
Then build the module with the following command:
``.\build_module_local.bat \path\to\module snapshot \path\to\custom\build.properties``
https://github.com/MicroEJ/ExampleJava-MWT/tree/749d957b3b889e66fecf3562791b8cfe5a1bd577
These MicroEJ projects provide examples for MWT.
EXAMPLE for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
3 November 2020
# Overview
This repository provides a collection of MWT examples. Each example has its own Eclipse/MicroEJ project.
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).
# Details
## com.microej.example.mwt.attribute
This example shows how to customize the style of widgets using attributes selectors, similar to CSS.
## com.microej.example.mwt.focus
This example shows how to introduce focus management in your project.
## com.microej.example.mwt.immutablestylesheet
This example shows how to define a stylesheet in an immutable file rather than with Java code.
## com.microej.example.mwt.lazystylesheet
This example shows how to use a lazy stylesheet rather than the default stylesheet implementation.
## com.microej.example.mwt.mvc
This example shows how to develop responsive widgets using a MVC design pattern and how to display a cursor image representing the pointer.
---
_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._
https://github.com/MicroEJ/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
https://github.com/MicroEJ/Example-Standalone-Java-C-Interface
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**
https://repository.microej.com/artifacts/com/google/protobuf/
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
https://repository.microej.com/artifacts/ej/api/bon/
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_ https://repository.microej.com/artifacts/ej/api/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.
https://repository.microej.com/artifacts/ej/api/ecom/
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.
https://repository.microej.com/artifacts/ej/api/ecom-comm/
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.
https://repository.microej.com/artifacts/ej/api/edc/
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._ https://repository.microej.com/artifacts/ej/api/fs/
FS (Foundation Library 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.
https://repository.microej.com/artifacts/ej/api/hal/
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
https://repository.microej.com/artifacts/ej/api/kf/
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.
https://repository.microej.com/artifacts/ej/api/microui/
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.
https://repository.microej.com/artifacts/ej/library/ui/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._ https://repository.microej.com/artifacts/ej/api/net/
NET (Foundation Library 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.
https://repository.microej.com/artifacts/ej/api/sni/
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.
https://repository.microej.com/artifacts/ej/api/sp/
SP (Foundation Library 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.
https://repository.microej.com/artifacts/ej/api/ssl/
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.
https://repository.microej.com/artifacts/ej/library/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._ https://repository.microej.com/artifacts/ej/library/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._ https://repository.microej.com/artifacts/ej/library/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._ https://repository.microej.com/artifacts/ej/library/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._ https://repository.microej.com/artifacts/ej/library/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._https://repository.microej.com/artifacts/ej/library/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._https://repository.microej.com/artifacts/ej/library/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._ https://repository.microej.com/artifacts/ej/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._ https://repository.microej.com/artifacts/ej/library/eclasspath/stringtokenizer/
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._https://repository.microej.com/artifacts/ej/library/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._ https://repository.microej.com/artifacts/ej/library/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._https://repository.microej.com/artifacts/ej/library/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._ https://repository.microej.com/artifacts/org/eclipse/paho/mqttv3-microej/
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
https://repository.microej.com/artifacts/org/eclipse/paho/mqttv3-ssl-microej/
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
https://repository.microej.com/artifacts/org/json/me/json/
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._ https://repository.microej.com/artifacts/org/kxml2/kxml2/
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.
https://repository.microej.com/artifacts/ej/library/iot/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._ https://repository.microej.com/artifacts/ej/library/iot/connectivity/
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._ https://repository.microej.com/artifacts/ej/library/iot/restclient/
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._ https://repository.microej.com/artifacts/ej/library/iot/cbor/
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._ https://repository.microej.com/artifacts/ej/library/iot/json/
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.
https://repository.microej.com/artifacts/ej/library/iot/data/pubsub-api/
The Publish-Subscribe Data API.
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
https://repository.microej.com/artifacts/ej/library/runtime/components/
Component-based programming library.
LIBRARY for CORE
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
https://repository.microej.com/artifacts/ej/library/test/junit/
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._ https://repository.microej.com/artifacts/ej/library/ui/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.
https://repository.microej.com/artifacts/ej/library/ui/widget/
LIBRARY for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
https://repository.microej.com/artifacts/ej/library/util/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._ https://repository.microej.com/artifacts/ej/library/util/exit/
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._ https://repository.microej.com/artifacts/ej/library/util/map/
LIBRARY for MISC
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
https://repository.microej.com/artifacts/ej/library/util/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.
https://repository.microej.com/artifacts/ej/library/util/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.
https://repository.microej.com/packages/blue/2.0.2/firmwares/OM13098/FMW-BLUE-OM13098-PQ9Y4-2.0.2.zip
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.
https://docs.microej.com/en/latest/PlatformDeveloperGuide/index.html
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
https://repository.microej.com/packages/referenceimplementations/HDAHT/1.5.1/ESP32WROVER-HDAHT-fullPackaging-eval-1.5.1.zip
VEE Port for Espressif ESP-WROVER-KIT V4.1 development board (MonoSandbox, GCC, FreeRTOS)
VEE Port for Espressif ESP-WROVER-KIT V4.1 development 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
https://github.com/MicroEJ/LibraryJava-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._
https://github.com/MicroEJ/Example-Hoka
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._https://repository.microej.com/packages/referenceimplementations/XPUWJ/2.0.0/MurataType1LD-XPUWJ-fullPackaging-eval-2.0.0.zip
VEE Port for Murata-Type1LD-EVB (MonoSandbox, GCC, FreeRTOS)
VEE Port 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:
https://repository.microej.com/packages/referenceimplementations/U3OER/2.0.1/OM13098-U3OER-platform-eval-2.0.1.jpf
https://repository.microej.com/packages/referenceimplementations/U3OER/2.0.1/OM13098-U3OER-fullPackaging-eval-2.0.1.zip
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
https://repository.microej.com/packages/referenceimplementations/846SI/3.4.2/STM32F746GDISCO-846SI-platform-eval-3.4.2.jpf
https://repository.microej.com/packages/referenceimplementations/846SI/3.4.2/STM32F746GDISCO-846SI-fullPackaging-eval-3.4.2.zip
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
https://github.com/MicroEJ/AWS/tree/MicroEJ_5.x
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._ https://github.com/MicroEJ/How-To/tree/master/FontForge
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/>`__
https://github.com/MicroEJ/Example-Wi-Fi-Setup
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.
-->https://github.com/MicroEJ/Example-NLS
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
https://repository.microej.com/architectures
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
https://github.com/MicroEJ/How-To/tree/master/MicroUI-Get-Started
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.
https://github.com/MicroEJ/How-To/tree/master/Widgets-Get-Started
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.
https://github.com/MicroEJ/How-To/tree/master/StandaloneToSandboxed
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**
https://github.com/MicroEJ/How-To/tree/master/FoundationLibrary-Get-Started
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-2022 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.4.1
- With a MicroEJ 5 Demonstration Platform imported into the
MicroEJ repository that contains:
- EDC-1.3
- BON-1.4
- 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 > Module Project**
- Set the project settings.
- Project Name: mylib-api
- Organization: com.mycompany.api
- Module: mylib
- Revision: 1.0.0
- Select **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 Module**.
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 > Module Project**
- Set the project settings.
- Project Name: mylib-impl
- Organization: com.mycompany.impl
- Module: mylib-impl
- Revision: 1.0.0
- Select **microej-javaimpl** skeleton.
- Click on **Finish**.
- Open **mylib-impl/module.ivy**
- replace ``microej.lib.name="mylib-impl-1.0"`` with ``microej.lib.name="mylib-1.0"``
- Save the file.
- 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 Module**.
After a successful build, the project build directory
**target~/artifacts** contains:
- **Rip** file (mylib-impl.rip), that will be embedded into a Platform.
Add the Implementation to the Platform
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Unzip **mylib-impl.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 > Standalone Application Project**
- Set the project settings.
- Project Name: mylib-test
- Organization: com.mycompany.test
- Module: mylib-test
- Revision: 1.0.0
- Open **module.ivy**
- Add the dependency ``<dependency org="com.mycompany.api" name="mylib" rev="1.0.0" />``
- Open 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 > Module Project**
- Set the project settings.
- Project Name: mylib-mock
- Organization: com.mycompany.mock
- Module: mylib-mock
- Revision: 1.0.0
- Select **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 Module**.
After a successful build, the project build directory
**target~/artifacts** contains:
- **Rip** file (mylib-mock.rip), that will be embedded into a Platform.
Add the Mock-up to the Platform
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Unzip **mylib-mock.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 <https://docs.microej.com/en/latest/PlatformDeveloperGuide/mock.html>`__
- Generate a mock with an UI: `Mock-Get-Started <https://github.com/MicroEJ/How-To/tree/master/Mock-Get-Started>`__
https://github.com/MicroEJ/How-To/tree/master/Proguard-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â);
}
https://github.com/MicroEJ/How-To/tree/master/Storage-Get-Started
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.
https://github.com/MicroEJ/How-To/tree/master/Mock-Get-Started
How to add a mock to your project
This project explain how to create a mock for SNI and SP functions on the simulator.
HOWTO for MISC
Supported MicroEJ Version: 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.
https://github.com/MicroEJ/How-To/tree/master/Multi-App-Security-Manager
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-2021 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 <java/NativeAPIs/src/main/java/com/microej/LedPermission.java>`__
class that extends ``java.security.BasicPermission``
2. In `Led <java/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
https://github.com/MicroEJ/How-To/tree/master/Single-App-to-Multi-App-Platform
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-2021 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.rst>`__, 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
https://github.com/MicroEJ/How-To/tree/master/SNI-LED
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/>`__.
https://github.com/MicroEJ/Example-Standalone-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._
https://github.com/MicroEJ/Example-Standalone-Foundation-Libraries
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 basic examples on how to use some 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.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): 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 to 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 movable images.
* [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.
### Drawing
The Drawing Foundation Library extends MicroUI drawing APIs with more complex ones.
**Available Examples**:
* [com.microej.example.foundation.drawing.transform](com.microej.example.foundation.drawing.transform): Shows how to use anti-aliased shapes.
* [com.microej.example.foundation.drawing.antialiased](com.microej.example.foundation.drawing.antialiased): Shows how to apply transformations on an image.
## 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 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._
https://repository.microej.com/p2
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
https://docs.microej.com/en/latest/ApplicationDeveloperGuide/index.html
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
https://docs.microej.com/en/latest/ApplicationDeveloperGuide/index.html
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
https://repository.microej.com/packages/indigo/1.1.0/firmwares/STM32F746GDISCO/FMW-INDIGO-STM32F746GDISCO-L9EBM-1.1.0.zip
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 the result of the binary link of a MicroEJ Standalone Application with a MicroEJ Platform.
MicroEJ Studio allows application developers to write Java applications, run them on a virtual (simulated) or real device, and publish them to MicroEJ Forge (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 applications and demos).
# Features
## Foundations Libraries
This MicroEJ 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://developer.microej.com/5/getting-started-studio.html](https://developer.microej.com/5/getting-started-studio.html).
# 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 (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
https://repository.microej.com/packages/indigo/1.1.0/firmwares/OM13098/FMW-INDIGO-OM13098-5H44X-1.1.0.zip
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 the result of the binary link of a MicroEJ Standalone Application with a MicroEJ Platform.
MicroEJ Studio allows application developers to write Java applications, run them on a virtual (simulated) or real device, and publish them to MicroEJ Forge (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 applications and demos).
# Features
## Foundations Libraries
This MicroEJ 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://developer.microej.com/5/getting-started-studio.html](https://developer.microej.com/5/getting-started-studio.html).
# 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 (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
https://repository.microej.com/packages/black/1.0.1/firmware/ESP32-WROVER/FMW-BLACK-ESP32WROVER-RQQAW-1.0.1.zip
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
https://github.com/MicroEJ/Example-Sandboxed-IOT
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-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._
https://repository.microej.com/packages/documentation/TLT-0831-SPE-MicroEJModuleManager-2.0-C.pdf
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
https://github.com/MicroEJ/Demo-Weather-Spresense/tree/master/SpresenseDemo
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.
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._
https://github.com/MicroEJ/VEEPort-Sony-Spresense
Sony Spresense VEE (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.
Docs
Resources
Forum