MicroEJ Developer
Get Started



Protocol Buffers (protobuf)

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

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

# Usage

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

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

# Requirements

This library requires the following Foundation Libraries:

    BON-1.2, EDC-1.2

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

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

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

# Restrictions

None

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

MQTT Client

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

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

# Setup

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

## Dependency injection

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

For information about this interfaces see the corresponding javadoc.

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

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

## Threads

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

## UTF-8

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

# Usage

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

This library requires the following Foundation Libraries:

    BON-1.3, EDC-1.2, NET-1.1

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

N/A

# Restrictions

None.

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

MQTT SSL Client

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

Paho MicroEJ client for MQTT:

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

# Setup

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

## Dependency injection

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

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

For information about this interfaces see the corresponding javadoc.

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

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

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

## Threads

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

## UTF-8

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

# Usage

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

## SSL

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

This library requires the following Foundation Libraries:

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

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

N/A

# Restrictions

None.

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

REST Client

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

ej.rest is a tiny RESTful services client. 

## Features

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

# Usage

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

This library requires the following Foundation Libraries:

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

# Dependencies

_All dependencies are retrieved transitively by Ivy resolver_.

# Source

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

# Restrictions

None.

# Embedded constraints

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

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

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

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


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

Hoka

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

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

It also includes tools for REST services and for authentication.

# Usage

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

# Requirements

This library requires the following Foundation Libraries:

    BON-1.4, EDC-1.3, NET-1.1

# Dependencies

*All dependencies are retrieved transitively by Ivy resolver*.

# Source

N.A.

# Restrictions

None.

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

Hoka Examples

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

This project contains examples using the Hoka HTTP Server :

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

# Usage

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

## Run on MicroEJ Simulator

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

## Run on device

### Build

1. Right Click on the example to build
2. Select **Run as -> Run Configuration**
3. Select **MicroEJ Application** configuration kind
4. Click on **New launch configuration** icon
5. In **Execution** tab

   1. In **Target** frame, in **Platform** field, select a relevant
      platform (but not a virtual device)
   2. In **Execution** frame

      1. Select **Execute on Device**
      2. In **Settings** field, select **Build & Deploy**

6. Press **Apply**
7. Press **Run**
8. Copy the generated ``.out`` file path

### Flash

1. Use the appropriate flashing tool.

# Requirements

This library requires the following Foundation Libraries:

    @FOUNDATION_LIBRARIES_LIST@

# Dependencies

*All dependencies are retrieved transitively by Ivy resolver*.

# Source

N.A.

# Restrictions

None.

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

AWS IoT Core Example

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

Demonstration of MQTT Publish / Subscribe functionalities for AWS IoT.

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

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

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

# Setup

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

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

Importing the Git repository in a MicroEJ SDK:

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

# Launching the AWS IoT Demo

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

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

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

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

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

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

# References

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

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

Wi-Fi Setup Example

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

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

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

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

# Dependencies
 _All dependencies are retrieved transitively by Ivy resolver_.

# Source
N/A

# Restrictions
None.



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

Using IOT Libraries APIs (Sandboxed)

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

This project gathers simple sandboxed applications using net libraries.

## Requirements

* MicroEJ Studio or SDK 5.1 or later

# Usage

Each subfolder contains a distinct IOT application.

# Changes

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

# License

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

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