MATRIX Level, Using the Gyroscope Sensor on the Creator

The Project

This guide provides an in-depth commentary on the code for an app (MATRIX Level) that implements the MATRIX Creator’s gyroscope sensor to measure the level of the MATRIX Creator and Raspberry Pi. Everloop, the LED array on the MATRIX Creator, will interact with the user adjusting the device orientation. If the whole everloop shows green, the MATRIX Creator is completely level otherwise the LEDs will flash yellow to red in the direction of the unleveled surface.

This easy-to-code app serves to offer a convenient way to measure the level of a surface.

Required Hardware

Before you get started, let’s review what you’ll need.

• Raspberry Pi 3 (Recommended) or Pi 2 Model B (Supported) - Buy at Amazon - Pi 3 or Pi 2.
• MATRIX Creator - Hardware to Support the Software - Buy Matrix Creator.
• Micro-USB power cable for Raspberry Pi.
• Micro SD Card (Minimum 8GB)
• Internet Connection (Ethernet or Wifi)
• Laptop Prepared with Text Editor (Code in Javascript)

Let's Get Started

To set up the MATRIX Creator and install the matrix-os operating system on your Raspberry Pi, follow the instructions provided under MATRIX Docs. Make sure the version is appropriately updated by running the commands under the “Upgrades” tab.

To create your own MATRIX Level app on your local computer, use the command "matrix create level". Then you will be directed to enter a description and keywords for your app. A new folder will be created for the app with four new files. The two you will be editing are the app.js file and the config.yaml file.

Admobilize-MacBook-Pro:~ admobilize$ matrix create level   
Create new application --  ( level ) Description Gyroscope Level   
Create new application --  ( level ) Keywords gyroscope, led   
New Folder:> level/   
        app.js - this is your application logic   
   config.yaml - change variables, indicate sensors, configure dashboard   
     README.MD - information about developing MATRIX apps   
      index.js - app entry point, do not modify   
  package.json - node.js information file, do not modify without knowledge   

The libraries for the Gyroscope sensor come as part of the MOS package installed with npm and matrix-os software. It outputs data in yaw, pitch, and roll, all depending on the values plotted on the x, y, and z axes.

MATRIX Level is available on the MATRIX App Store​ and can be installed using the command "matrix install level". The code explained below is also available on GitHub.

How to Call Gyroscope Sensor

To use specific sensors in an application, they must be identified in the config.yaml file.

In config.yaml,

sensors:   
 - gyroscope    

To initialize the Gyroscope feature in the actual application file app.js, the following function must be called. The options for the sensor must be defined prior to this header. By default, all sensors have refresh and timeout properties.

In app.js,

var options =   
{   
   refresh: 50,   
   timeout: 15000   
}   
matrix.sensor('gyroscope', options).then(function(data) { CODE });  

How The Program is Organized

The MATRIX Creator shows the direction of the tilt using the LED lights on the board. There are 35 LEDs, so to be more efficient and simplify the coding, the lights are divided into 4 quadrants and thus represents an X/Y plot. If both x and y values are positive (positive roll and pitch), the LED group would be quadrant 1.

Under the function, the values for x translate to the pitch data and the values for y translate to the roll data.

matrix.sensor('gyroscope', options).then(function(data)   
{   
   var y = data.roll;   
   var x = data.pitch;   

Depending on the sign of the pitch and roll (whether negative or positive), the tilt can then be associated with a particular quadrant, defined below. The code essentially bases the formatting on the X/Y plot.

if (y >= 0 && x >= 0) {  
   quad = 1;  
} else if (y >= 0 && x < 0) {  
   quad = 2;  
   x *= -1;  
} else if (x < 0) {  
   quad = 3;  
   y *= -1;  
   x *= -1;  
} else {  
   quad = 4;  
   y *= -1;  
}  

With these values, the angle for the specific light on the MATRIX Creator is calculated using arctangent. Angle 0 on the MATRIX Creator is in between quadrants 2 and 3 so the appropriate transformations are taken to account for such.

angle = Math.atan(y/x) * 180 / Math.PI;   
     
   switch(quad)   
   {   
       case 1:   
       {   
           angle = 180 - angle;   
           break;   
       }   
       //quad 2 is already accounted for   
       case 3:   
       {   
           angle = 360 - angle;   
           break;   
       }   
       case 4:   
       {   
           angle += 180;   
           break;   
       }   
   }   

Then, amplitude (covers which LEDs should light up based on direction and angle) is calculated by solving the square root of the sum of the powers of x and y.

amp = Math.sqrt(Math.pow(y, 2) + Math.pow(x, 2));    

For the LED commands, arcs cover the area in the direction of the tilt, and the colors switch from yellow to red depending on how far the MATRIX Creator is tilted.

var shape =   
   {   
       arc: amp * 8,   
       color: 'rgb(200, ' + (10 + (190 - 9.5 * amp)) + ', 0)',   
       start: angle - amp * 4   
   }   
   if(amp < 3)   
   {   
       shape.color = 'rgb(0, 25, 0)'   
       shape.arc = 360   
   }   
   matrix.led(shape).render();   

With that, your gyroscope should be ready to go and your MATRIX Creator can be used as a level for any surface!

Visit the MATRIX App Store to install MATRIX Level (on your local computer, use the command "matrix install level") and the Github Repository linked below to see the code.