MIG | EmMate

You are not on the latest release. EmMate v2.1.0.1 is here. Try v2.1.0.1.

Introduction

Welcome to EmMate!! Your one stop solution for all your embedded requirements.

You are about to build a hardware platform agnostic embedded application.

The EmMate framework is built with the intent to support and work with multiple hardware platforms.

Here is your chance to be a part of build once and flash anywhere application ecosystem.

Getting Started

This guide will help you to set up, build and run an embedded application based on the EmMate framework.

Considerations

Since this framework is intended to work with multiple hardware platforms, you may choose any hardware to get started.

We will use ESP32 for this guide.

Prerequisites

There are few prior requirements.

First thing first

You will need a Computer running Linux.

The EmMate framework is tested with Ubuntu 16.04 LTS.
It is highly recommended to use Ubuntu 16.04 LTS as your environment as well.

Hardware

You will need any development board based on the following hardware platforms:

ESP32
PIC32
nRF51 or nRF52
STM32

We are using ESP32 for this guide.

It is recommended to use MIG SoM and MIG Thing boards.

Software

First you need download the EmMate Framework package. You will be directed to download it in the next section of the document.
You will need an editor to write code in C. We prefer using Eclipse .

Downloading the Required Files

Now that you have,

A Computer running Linux.
Chosen your preferred hardware platform. We are using ESP32 for this guide.

You may download a release package of EmMate framework.

Download Package

NOTE:

It is recommended to download the latest version under the 'Releases' Section from the link below as they have been tested and are stable. Remember to download the package that corresponds to your chosen hardware platform. We are using ESP32 for this guide.
Alternatively you may want to clone the source files from the git. You will get the link to EmMate's source in the link below.
Please note that this document only covers the steps for application development using the release packages of EmMate. If you have cloned the git repository then you need to take additional steps (coming soon) before following this document.

To download please visit Downloads

Assuming that you have successfully downloaded a release package, we would proceed further. You may keep the release package anywhere in your machine. We will keep it in /home/iquesters/emmate-framework/ for this guide.

NOTE: If you are using the same path as shown above then change the user (i.e. iquesters in this case) on the command above to your system username

Distribution package Contents

Extract files from the downloaded package.

The extracted package must contain the following directories:

platform: The platform directory contains the source code for the specific hardware platform you have chosen.
platform-resources: The platform-resources directory contains the scripts to setup the development environment specific to the hardware platform you have chosen
setup: The setup directory contains setup files which will help setting up projects that will be developed using the EmMate framework. Details of how to use the setup files is mentioned below in the Setting up an EmMate Application section.
src: The src directory contains the source code for the EmMate framework.
examples: The examples directory contains numerous example codes for learning and using the EmMate framework.

It must look like:

$ pwd
/home/iquesters/emmate-framework/esp32

$ cd esp32
$ ls -l
total 20
drwxr-xr-x 1 iquesters iquesters 4096 Jun 10 20:35 examples/
drwxr-xr-x 1 iquesters iquesters 4096 Jun 10 14:33 platform/
drwxr-xr-x 1 iquesters iquesters 4096 Jun 10 14:33 platform-resources/
drwxr-xr-x 1 iquesters iquesters 4096 Jun 10 20:35 setup/
drwxr-xr-x 1 iquesters iquesters 4096 Jun 10 14:33 src/

Setting up the Development Environment for EmMate

Now that you have,

Downloaded and extracted the release package of the EmMate framework.

You are ready to setup the development environment for writing, building and deploying embedded applications based on the EmMate Framework.

NOTE: Currently only ESP32 is supported. Other platforms are coming soon.

ESP32 - Prerequisites

To compile with ESP-IDF you need to get the following packages. Please run the below command in a terminal.

$ sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools

ESP32 - Toolchain Setup

Please follow the below steps to download and setup your toolchain:

Download and Setup Toolchain

To setup ESP32 Toolchain for Ubuntu 16.04 LTS, run the following commands in a Terminal:

$ mkdir /home/iquester/esp
$ cd /home/iquester/esp

then copy toolchain setup script from /home/iquester/emmate-framework/esp32/platform-resources/setup/setup-esp-toolchain.sh to /home/iquester/esp

$ cp -v -u -r /home/iquester/emmate-framework/esp32/platform-resources/setup/setup-esp-toolchain.sh /home/iquester/esp
$ ./setup-esp-toolchain.sh

It will take some time to download and setup the toolchain.

Set PATH Environment Variable

To use the toolchain, you will need to update your PATH environment variable in ~/.profile file. To make xtensa-esp32-elf available for all terminal sessions, add the following line to your ~/.profile file:

export PATH="/home/iquester/esp/xtensa-esp32-elf/bin:$PATH"

Make Changes Effective and Verify

Log off and log in back to make the .profile changes effective. Run the following command to verify if PATH is correctly set:

$ printenv PATH

You are looking for similar result containing toolchain's path at the beginning of displayed string:

$ printenv PATH
/home/user-name/esp/xtensa-esp32-elf/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin

Instead of /home/user-name there should be a home path specific to your installation.

ESP32 - ESP-IDF (SDK) Setup

Besides the toolchain, you also need ESP-IDF (SDK). Please follow the below steps to download and setup the SDK.

Download and Setup ESP-IDF (SDK)

First you need to copy the SDK setup script from /home/iquester/emmate-framework/esp32/platform-resources/setup/setup-esp-sdk.sh to /home/iquester/esp. To do so run the following commands:

$ cd /home/iquester/esp
$ cp -v -u -r /home/iquester/emmate-framework/esp32/platform-resources/setup/setup-esp-sdk.sh /home/iquester/esp
$ ./setup-esp-sdk.sh

ESP-IDF SDK will be downloaded into /home/iquester/esp/esp-idf. This will take several minutes to complete, depending upon your internet connection.

Set PATH Environment Variable

Set up IDF_PATH by adding the following line to ~/.profile file:

export IDF_PATH=/home/iquester/esp/esp-idf

Make Changes Effective and Verify

Log off and log in back to make this change effective.

Run the following command to check if IDF_PATH is set:

$ printenv IDF_PATH

The path previously entered in ~/.profile file should be printed out.

ESP32 - Required Python2 Packages

The python2 packages required by ESP-SDK are located in IDF_PATH/requirements.txt. You can install them by running:

$ python2 -m pip install --user -r $IDF_PATH/requirements.txt

ESP32 - Required Python3 Packages

The required python3 packages are: Kconfiglib and Python3 standard GUI Library (tkinter)

NOTE: If pip3 is not installed, then first install it using the command: sudo apt install python3-pip

$ pip3 install --user kconfiglib
$ sudo apt install python3-tk

ESP32 - Device Setup

After completing the above installations, you are now ready setup your ESP32 based device/board. So, connect your ESP32 based device/board to the computer and check under what serial port it is visible

Serial ports have the following patterns in their names:

Linux: starting with /dev/tty

To check the serial port name in Linux run the following command in a terminal

$ ls /dev/tty*

Adding user to dialout on Linux

The currently logged user should have read and write access the serial port over USB. So we need to run the following command on our Ubuntu Linux terminal

$ sudo usermod -a -G dialout $USER

Log off and log in back to make this change effective.

Setting up EmMate Examples and Applications

Now that you have,

Successfully setup your Development Environment
Successfully setup your Device

You may now start developing actual applications. You may as well try our examples and demo projects.

Getting Started with Examples

To setup, build, flash and run all the examples, please follow the below steps:

Steps to Setup an Example

For this guide we will use the hello-world example located in /home/iquester/emmate-framework/esp32/examples/getting-started/. All the other examples can be setup, built and run in the same process. Please refer each example's README.md file to know more about it.

Also note that on our end we have downloaded and extracted the EmMate release package at. So we will be using this path in this guide.

/home/iquester/emmate-framework/esp32

To setup an example project simply copy a example from the EmMate release package and paste it at your preferred location.

$ cd /home/iquester/my-emmate-projects
$ cp -r /home/iquester/emmate-framework/esp32/examples/getting-started/hello-world .

Now create a directory called setup inside hello-world

$ cd hello-world
$ mkdir setup

Now copy the files setup.sh and setup.conf

$ cd setup
$ cp /home/iquester/emmate-framework/esp32/setup/setup.sh .
$ cp /home/iquester/emmate-framework/esp32/setup/setup.conf .

Open setup.conf file and specify the directory location of the extracted EmMate release package against the property RELEASE_PKG_DIR

For example, If the distribution package is extracted at /home/iquester/emmate-framework/esp32/, then the RELEASE_PKG_DIR will be /home/iquester/emmate-framework/esp32/

Change

RELEASE_PKG_DIR=<directory location of the extracted emmate package>

RELEASE_PKG_DIR=/home/iquester/emmate-framework/esp32/

Now run the setup.sh (shell script). This will create the required folder structure and copy other dependency files in your project.

$ ./setup.sh

Next verify that the setup was successful or not

$ cd ..
$ ls -l

The following content should appear. If it does then you have successfully setup an EmMate Project, else please redo the above steps.

total 32
drwxrwxr-x 4 iquester iquester 4096 Sep 13 15:56 build
-rw-rw-r-- 1 iquester iquester 4729 Sep 13 15:54 emmate_config
drwxrwxr-x 2 iquester iquester 4096 Sep 13 15:54 fritzing
drwxrwxr-x 4 iquester iquester 4096 Sep 13 15:56 platform
-rw-rw-r-- 1 iquester iquester  754 Sep 13 15:54 README.md
drwxrwxr-x 2 iquester iquester 4096 Sep 13 15:55 setup
drwxrwxr-x 5 iquester iquester 4096 Sep 13 15:56 src

Now the example hello-world is successfully setup. You may proceed to the next step to build the example.

Steps to Build an Example

Change to the build directory

$ cd build

To build the example run the script build.sh like shown below:

$ ./build.sh -make

When you build an EmMate example/application for the first time, the EmMate Development Framework Configuration application will automatically open. With the help of this application you can configure the modules of EmMate Framework as per the needs of your application.

For all examples the required configurations are already provided in the file emmate-config. So we will simply click Save and close the application.

If any additional configurations are needed, you will need to do them and save the configurations and build your project again. To open the EmMate Development Framework Configuration tool again, please use the following command:

$ ./build.sh -menuconfig

Once the EmMate Development Framework Configuration tool is closed the hello-world example will start compiling. If all went ok then you will find the following message:

## Execute EmMate Make Successful ################################

Now you have successfully built your example/application using the EmMate Framework. Next you need to flash the binary file into a hardware.

Steps to Flash and View Log Messages

First open the README.md file inside the example directory and follow the section Prepare the Hardware. In this case hello-world
Once your hardware is ready, run the following command:

$ ./build.sh -flash -log

It will take some time to flash the binary on to the hardware. Once successful you will be able to see the following log messages. And that's all, you have successfully completed the required steps.

  ______           __  __       _         ______                                           _    
 |  ____|         |  \/  |     | |       |  ____|                                         | |   
 | |__   _ __ ___ | \  / | __ _| |_ ___  | |__ _ __ __ _ _ __ ___   _____      _____  _ __| | __
 |  __| | '_ ` _ \| |\/| |/ _` | __/ _ \ |  __| '__/ _` | '_ ` _ \ / _ \ \ /\ / / _ \| '__| |/ /
 | |____| | | | | | |  | | (_| | ||  __/ | |  | | | (_| | | | | | |  __/\ V  V / (_) | |  |   < 
 |______|_| |_| |_|_|  |_|\__,_|\__\___| |_|  |_|  \__,_|_| |_| |_|\___| \_/\_/ \___/|_|  |_|\_\
     _____                      _               _____       _       _   _                          
    |_   _|                    | |             / ____|     | |     | | (_)                         
      | |  __ _ _   _  ___  ___| |_ ___ _ __  | (___   ___ | |_   _| |_ _  ___  _ __  ___          
      | | / _` | | | |/ _ \/ __| __/ _ \ '__|  \___ \ / _ \| | | | | __| |/ _ \| '_ \/ __|         
     _| || (_| | |_| |  __/\__ \ ||  __/ |     ____) | (_) | | |_| | |_| | (_) | | | \__ \         
    |_____\__, |\__,_|\___||___/\__\___|_|    |_____/ \___/|_|\__,_|\__|_|\___/|_| |_|___/         
             | |                                                                                   
             |_| 

W (197) sysinfo: =============================================================================
W (207) sysinfo: System Information
W (207) sysinfo: =============================================================================
W (217) sysinfo: -----------------------------
W (217) sysinfo: Hardware Information
W (227) sysinfo: -----------------------------
W (227) sysinfo: Chip Name: ESP32
W (237) sysinfo: Chip Manufacturer: ESSPRESIF
W (237) sysinfo: Features:
W (247) sysinfo:     WIFI : YES
W (247) sysinfo:     BT : YES
W (247) sysinfo:     BLE : YES
W (257) sysinfo:     GSM 2G : NO
W (257) sysinfo:     GSM 3G : NO
W (257) sysinfo:     GSM 4G : NO
W (267) sysinfo:     LORA : NO
W (267) sysinfo:     NBIOT : NO
W (267) sysinfo: FLASH SIZE : 4194304 bytes
W (277) sysinfo: RAM SIZE : 532480 bytes
W (277) sysinfo: -----------------------------
W (287) sysinfo: SDK Information
W (287) sysinfo: -----------------------------
W (297) sysinfo: Running SDK : ESP-IDF
W (297) sysinfo: SDk Version : v4.0-dev-621-g81ca1c0-dirty
W (307) sysinfo: -----------------------------
W (307) sysinfo: Framework Information
W (317) sysinfo: -----------------------------
W (317) sysinfo: Core Version: 0.1.0.0.823
W (327) sysinfo: Application Version: NO APP VERSION FOUND
W (327) sysinfo: =============================================================================

If you want to erase the flash memory of the hardware, use the following command:

$ ./build.sh -erase-flash

To stop the log messages press following keys:

$ Ctrl-]

API Documentation

The API Documentation for the EmMate framework is a documentation generated using Doxygen.

Release Specific API Documentations

Release Version	API Documentation
v1.0.0.0	https://mig.iquesters.com/section/embedded/api-docs/v1.0.0.0