tiles-api-client-nodejs v0.2.7

Tiles API

Introduction

The Tiles API Client (nodejs) is a minimalistic nodejs client to speak to the MakeProAudio Tiles Hub. Using this client API, you can speak to Tile Chains connected to a Tiles Hub running on a local or remote computer. Click here for more information on Tiles Hub. Currently you can only speak to a single Tile Chain. Multiplicity of Tile Chains will be supported later.

Running The Hub

Find out the COM port you've connected your Tile Chain to. Using the appropriate start script relevant to your OS, run the following command. For example, if on Windows, the relevant COM port is COM23 and on Mac, the relevant COM port is /dev/tty.usbmodem1411201, you'd run:

//Windows
start.bat COM23

//Mac
sh start /dev/tty.usbmodem1411201

//Linux (tested on Raspberry Pi 3+)
sh start /dev/tty.usbmodem1411201

You'll need a JRE version (>=1.8) in order to run the Tiles Hub.

Installing The Package

In order to install the package, in your nodejs environment run:

npm i tiles-api-client-nodejs

You'll need a node version (>=6.0) in order to run the Tiles API Client.

Connection To The Hub

Ensure that the Tiles Hub is running before you start using the client. Once you know the host and port of the Tiles Hub, use the following command to establish a connection:

const { hub } = require('tiles-api-client-nodejs');
hub.init('localhost', 8192);

Tile

hub is an EventEmitter. You can register to Tiles being found on the Hub. For example, if you're looking to work with a 12 Button Tile

const { hub, Tile } = require('tiles-api-client-nodejs');
hub.on(Tile.LEDBUTTON12, tile => {
   console.log('A new Led Button 12 tile was found. There may be more tiles on the chain!')
}

The Tile enum defines the type of Tiles currently supported by the Client:

1. ENCODER8 (TileEncoder8)
2. ENCODER12 (TileEncoder12)
3. LEDBUTTON8 (TileLedButton8)
4. LEDBUTTON12 (TileLedButton12)
5. FADER4 (TileFader4)

Widget

A Tile has a widgets array. Each Widget has a widgetId property. Continuing from the previous example, the following gives a demonstration of accessing Widgets from a Tile, and the id from the widget:

const widget = tile.widgets[0].widgetId;

widget is an EventEmitter. Depending on the type of tile, you can register to Widget events. For example, if you want to listen to Button Pressed and Released events:

const { hub, Tile, LedButtonEvents } = require('tiles-api-client-nodejs');
hub.on(Tile.LEDBUTTON12, tile => {
  tile.widgets.forEach(w => {
    w.on(LedButtonEvents.PRESSED, button => {
      console.log(`${button.widgetId} pressed`);
    });

    w.on(LedButtonEvents.RELEASED, button => {
      console.log(`${button.widgetId} released`);
    });
  });
});

All Widget Events come with a widget argument. Additionally, here is a list of Events by Widget type:

Some Widgets have extra functions. Here is a list of these functions by Widget type:

Diagnostics

A simple Diagnostics module has been added to get you started out of the box. If started, each Event from each Widget for each Tile will be logged to the console.

const { hub, diagnostics } = require('tiles-api-client-nodejs');
const ENABLEDIAGNOSTICS = true;

hub.init('localhost', 8192);
if (ENABLEDIAGNOSTICS) diag.start(hub);

You should not leave the Diagnostics module started for your own applications.

A Simple Animation

You can do pretty cool things with Tiles! Depending on what is present on your Chain, if started, the AutoAnimate module will animate an Encoder Tile, a Fader Tile and a Button Tile in the following manner:

1. Pressing and Releasing any Encoder will cycle colours on the LED Buttons
2. Turning Encoders right and left will move Motor Faders up and down

const { hub, autoAnimate } = require('tiles-api-client-nodejs');
const AUTOANIMATE = true;

hub.init('localhost', 8192);
if (AUTOANIMATE) autoAnimate.start(hub);

For a full example, refer to autoanimate.ts in the src folder.

Running The Examples

There are several examples bundled with the repository. Clone this repository and take a look at the following in the scripts section of package.json:

1. diagnostics
2. autoanimate
3. encoderevents
4. buttonevents
5. buttonapi
6. motorfaderevents
7. motorfaderapi

To run any example, execute npm run <name of example from the list above>

Depending on the tiles connected to your hub, examples may produce varying results.

MakeHaus And Stack API

MakeHaus and the Stack API allow you to augment your tiles via your mobile devices. The API is designed to abstract widgets - both software and hardware - simply by minimal configuration. For more advanced makers, a full API is available to develop your layouts and control your widgets the way you like.

Introduction

The library has 4 important logical components - Widgets, Parameters, Stacks and Rows.

Widget

A Widget is a UI element. A Widget maybe a hardware Widget or a software Widget. The following types of Widgets exist in MakeHaus:

1. Selector - SELECTOR_VERTICAL, SELECTOR_HORIZONTAL
2. Slider - SLIDER_VERTICAL, SLIDER_HORIZONTAL
3. Toggle - TOGGLE
4. Button - BUTTON
5. Empty = EMPTY
6. LedButton - LEDBUTTON
7. Encoder - ENCODER
8. MotorFader - MOTORFADER

Widgets 1 to 5 are software Widgets, whereas widgets 6 to 8 are hardware Widgets.

Each Widget type supports a set of properties:

Additionally, hardware Widgets can be tuned into for events.

Widgets have additional properties, namely:

Referencing A Hardware Widget In JSON

Each hardware Widget in your tilechain has a unique semantic identifier which looks like this:

<BoardType>.<BoardInstance>.<Row>.<Widget>

BoardType can be 8E, 12E, 8B, 12B or 4F

For example, if your tilechain has a single 8 Encoder Tile, the 3rd widget on the 2nd row of the Tile would have the identifier 8E.1.2.3

Referencing a hardware Widget is a simple two step process.

1. Defining where MakeHaus should listen to for your Tilechain:

"tilechains": [
  {
    "name": "tilechain-1",
    "address": "localhost",
    "port": 8192
  }
]

2. Creating a hardware Widget reference:

{
  "name": "tcwidget-1",
  "tilechain": "tilechain-1",
  "identifier": "8E.1.1.2",
  "event": "PRESS"
},

Parameter

Stack

A Stack is a collection of Widgets with additional properties. The main purpose of a Stack is to abstract properties of different types of Widgets and present them to the user.

Stacks have additional properties, namely:

Consider the following trivial example:

Let's say you want to show a Slider on screen for an Encoder you have in your hardware Tile with Min set to 0, Max set to 100 and Step set to 5. You'd like the Value of the Slider to increase or decrease depending on when the Encoder is TURNED. Let's assume this Encoder stands for the brightness of your lamp.

While you could implement all of this programatically, the platform allows you to define this in simple json configuration, in the following manner:

{
  "name": "stack-1",
  "context": "Lamp",
  "label": "Brightness",
  "min": 0,
  "max": 100,
  "step": 5,
  "defaultValue": 0,
  "color": "1F1F1F",
  "widgets": [
    {
      "name": "widget-1",
      "type": "SLIDER_HORIZONTAL"
    },
    {
      "name": "tcwidget-1",
      "tilechain": "tilechain-1",
      "identifier": "8E.1.1.1",
      "event": "TURN"
    }
  ]
}

Instead, if you wanted the Value to be updated when the Encoder was PRESSED, simply update the event for that Widget to PRESS in the following manner:

{
  "name": "tcwidget-1",
  "tilechain": "tilechain-1",
  "identifier": "8E.1.1.1",
  "event": "PRESS"
}

Now in code, to bind to Value changes of this Stack, create a Parameter and bind to it in the following manner:

const { Stacks } = require('tiles-api-client-nodejs');
const { Parameters } = require('@makeproaudio/parameters');
const stack = Stacks.get('stack-1');
const param = Parameters.newParameter('maker', stack.name());
param.bindTo(stack, evt => {
  console.log(evt.value);
  // Update your MIDI value, your lamp's brightness or any other use case you can think of :)
});

Row

A Row is a logical horizontal arrangement of Widgets. MakeHaus doesn't differentiate between Rows of Widgets in a hardware Tile or Rows of Widgets on a software UI.

Rows have additional properties, namely:

A typical Row defined in JSON would look like this:

"rows": [
        {
            "name": "row-1",
            "weight": 1,
            "widgetstacks": [
                {
                    "name": "stack-1",
                    "weight": 1,
                    "context": "",
                    "label": "",
                    "color": "blue",
                    "widgets": [
                        {
                            "name": "widget-1",
                            "type": "BUTTON"
                        }
                    ]
                },
                {
                    "name": "stack-2",
                    "context": "",
                    "label": "",
                    "color": "blue",
                    "widgets": [
                        {
                            "name": "widget-2",
                            "type": "BUTTON"
                        }
                    ]
                }
            ]
        }

MakeHaus Initialization

To start off your own application, utilize the MakeHaus init function in the following manner:

MakeHaus.init(
  /* layout json is a string */
  layoutJson,
  () => {
    /* Web app initialization was successful. */
  },
  () => {
    /* TileChain initialization was successful */
  }
);

Running The Examples

There are several examples bundled with the repository. Clone this repository and take a look at the following in the scripts section of package.json:

1. makehaus-simple-butled8
2. makehaus-simple-butled12
3. makehaus-simple-encoder8-turn
4. makehaus-simple-encoder12-press
5. makehaus-simple-motordader4
6. makehaus-full-phone
7. makehaus-full-tablet

To run any example, execute npm run <name of example from the list above>

Depending on the tiles connected to your hub, examples may produce varying results.