The Stack API

From MakeProAudio Wiki
Jump to navigation Jump to search

Introduction

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.

Augement cellphone

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:

Widget Properties
Selector CONTEXT | COLOR | ABSOLUTE VALUE
Slider CONTEXT | COLOR | ABSOLUTE VALUE
Toggle CONTEXT | COLOR | ABSOLUTE VALUE
Button COLOR |
LedButton COLOR |
Encoder
MotorFader ABSOLUTE VALUE

Additionally, hardware Widgets can be tuned into for events.

Hardware Widget Events
LedButton PRESS
Encoder PRESS
MotorFader MOVE

Widgets have additional properties, namely:

Property Comments
Name string which identifies the Widget
Type string which specifies the type of the Widget. Valid only for software Widgets
Tilechain refer section below for more details
Identifier refer section below for more details
Event refer section below for more details



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
  }
]
  1. 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:

Property Comments
Name string which identifies the Stack
Context string
Label string
Color string
Min,Max,Step number either these properties or Values can be specified
Values number[] | boolean[]either this property or Min,Max,Step can be specified
Widgets Widget[]

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('@makeproaudio/makehaus-js');
const { Parameters } = require('@makeproaudio/parameters-js');
const stack = Stacks.get('stack-1');
const param = Parameters.newParameter('maker', stack.name());
stack.bindFrom(param, 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:

Property Comments
Name string which identifies the Row
Weight number which specifies the proportion of the row’s height compared to other Rows
WidgetStacks Stack[]

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. Visit MakeHaus Examples to learn more.