The Stack API

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.

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
  }
]

2. Creating a hardware Widget reference:

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

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.