MRAA and UPM Basics in Arduino Create

What is MRAA and UPM?

MRAA (mraa.io) – pronounced ‘em rah’ is the hardware abstraction layer in Arduino Create* for Linux* based platforms. It is an open source project, and it supports multiple boards and programming languages. Using MRAA allows you to initialize and work with pins on a board with an easy-to-understand API.

The way that MRAA abstracts the hardware is through a pin mapping at the user space level. So when you use MRAA, you need to set your platform so the mapping is done correctly for your specific board. A full list of supported boards can be found at https://github.com/intel-iot-devkit/mraa#supported-boards

MRAA supports GPIO, I2C, PWM, SPI, and UART. There is also a very useful library written on top of MRAA which is an abstraction for individual sensors. It’s called UPM and you can read about it at https://upm.mraa.io/ . UPM is supported in Arduino Create for platforms using MRAA.

Sub-platform

When using MRAA, you have the option to define a sub-platform. A sub-platform operates with the same APIs as the platform, but you are required to add an offset of 512 to all pins. Note that you can only have one sub-platform for each application using MRAA . The most common reason to use a sub-platform is to expand the I/O capabilities of a platform.

For example, if you want you can use a regular Arduino* board connected via USB to add sensors to a laptop, you can use the Arduino board as a sub-platform. You’d need to first flash the Arduino board with the StandardFirmata.ino sketch, and then add it as a sub-platform at the top of your code:

mraa_add_subplatform(MRAA_GENERIC_FIRMATA, "/dev/ttyACM0");

An Arduino device is typically added as ttyACM0, but sometimes as ttyACM1 or higher. The easiest way to check is to enter:

ls /dev/ttyACM*

Note: if you’re using an Arduino 101* (branded Genuino 101* outside the U.S.), you should use this sketch instead: http://iotdk.intel.com/misc/ConfigurableFirmataCurieImu.ino.bin

How do I use MRAA in Arduino Create*?

You can use the MRAA APIs directly for added functionality or if you just prefer that. For example:

void setup() {
  mraa_add_subplatform(MRAA_GENERIC_FIRMATA, "/dev/ttyS1");
  pinMode(516, OUTPUT);
}

void loop() {
  digitalWrite(516, HIGH);   // turn the LED on (HIGH is the voltage level)
  delay(1000);                       // wait for a second
  digitalWrite(516, LOW);    // turn the LED off by making the voltage LOW
  delay(1000);                       // wait for a second
}

And
mraa_gpio_context gpio;
void setup() {
  mraa_add_subplatform(MRAA_GENERIC_FIRMATA, "/dev/ttyS1"); 
  gpio = mraa_gpio_init(516);
  mraa_gpio_dir(gpio, MRAA_GPIO_OUT);
}
void loop() {
   mraa_gpio_write(gpio, 1);   // turn the LED on 
  delay(1000);                       // wait for a second
   mraa_gpio_write(gpio, 0);    // turn the LED off 
  delay(1000);                       // wait for a second
}

Do the same thing. Take note of the following:

• Subplatforms still need to be added using mraa_add_subplatform even if you’re using the Arduino API
• If using the MRAA API you need to set mraa_gpio_context and initialize gpio = mraa_gpio_init(516), this is already taken care of for you using the Arduino API

To see another example using mraa, see this tutorial.

The MRAA github repository includes lots of examples https://github.com/intel-iot-devkit/mraa/tree/master/examples and https://github.com/intel-iot-devkit/mraa/tree/master/examples/c%2B%2B that can be ported to Arduino Create.

How do I use UPM in Arduino Create*?

In order for any UPM library to work, you need to include the header file corresponding to that particular sensor.

Unfortunately, if you search for the library in Arduino Create and include it, all the UPM sensor libraries will be included, and you probably only need one or two.

The solution is to find your sensor first in the list https://iotdk.intel.com/docs/master/upm/modules.html

Then copy the name of the .h file.

At the top of your sketch include it, for example:
#include <jhd1313m1.h>

To see how it’s instantiated see https://github.com/intel-iot-devkit/up-squared-grove-IoT-dev-kit-arduino-create/tree/master/examples/GroveLCD

A more generic example can be found here: https://github.com/intel-iot-devkit/upm/blob/master/examples/c%2B%2B/jhd1313m1-lcd.cxx

Where do I go for help?

The best place to go if you’re running into problems is to create an issue on the MRAA or UPM github repository:

• MRAA - https://github.com/intel-iot-devkit/mraa
• UPM - https://github.com/intel-iot-devkit/upm