MakeHaus Nodes for Node-RED

From MakeProAudio MediaWiki
Revision as of 14:34, 11 September 2020 by Mklug mpa (talk | contribs) (→‎Introduction)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Introduction

MakeHaus Nodes gives you direct access from Node-RED to the individual widgets of the MakeHaus hardware, or more precisely, of the MPA tiles. You can use them to monitor and evaluate all events of the widgets, such as a button press or a fader movement. In addition, you can also send values to the hardware, e.g. to move a motor fader to a specific position or to make the RGB LED buttons light up in color.

You just edit everything in your browser, like this:

2020-09-11 node-red-example.png


Prerequisites

So, for making use of our Nodes you will need

Once your Tiles are exposed to the network via the TilesHub, the node-red-contrib-makehaus package for Node-RED will connect to them and make them available within the Node-RED environment.

Installation

Get yourself a command prompt and change into the home folder of your Node-RED installation. Under Windows this usually would be C:\Users\YourName\.node-red\ whereas on the Raspberry Pi you should find the Node-RED home directory under /usr/lib/node_modules/node-red.

In the home folder, install the MakeHaus Nodes for Node-RED via the following command

npm install @makeproaudio/node-red-contrib-makehaus

Example: under Windows, the installation procedure could look like

C:somewhere> cd %homepath%
C:\Users\YourName\> cd .node-red
C:\Users\YourName\.node-red > npm install @makeproaudio/node-red-contrib-makehaus

The MakeHaus Nodes

For the beginning we introduce five nodes:

  • rgb button SL (a stateless button node with RGB LED)
  • encoder SL (a stateless Encoder Node)
  • rgb button SF (a stateful Button Node with RGB-LED that holds a state)
  • encoder SF (a stateful Encoder Node that holds a value)
  • fader SF (a stateful Fader Node for a Motorfader - there is no stateless version)

Also, there is the config node tiles-hub-config, which you create to hold the IP and port of a MakeHaus TilesHub. This release 0.0.5 supports multiple instances of config nodes sich that multiple TilesHub instances im the network can be used within the same Node-RED instance.

Overview of the individual Nodes

rgb button SL

rgb button SL

This stateless Button Node can be connected to a specific button of an RGB Button Tile, no matter if it is a 12 or an 8 Button Tile.

  • The output informs you about the basic events: the Button was pressed or released.
  • At its input, you can assign a color to the RGB LED of the button.

encoder SL

encoder SL

The stateless encoder node can be connected to a specific encoder of an encoder tile (8 encoders or 12 encoders).

  • At output #1 you get all basic events: the Encoder was touched, untouched, pressed (like a button), released, or turned.
  • Output #2 provides no events, but only the value if the encoder has been rotated. The value provides information about the direction of rotation and, if desired, the speed of rotation.
  • This node has no input.

rgb button SF

rgb button SF

This node allows you to directly add life to a particular button widget. Define several states that are switched through one after the other with each button press (round-robin). One simple application would be an on/off switch. If you assign a color value to each state, so you can see from the color of the RGB LED which state is currently active.

  • Output #1 provides the event of a state change with the state name as value.
  • Output #2 only provides the state as a value (without the event) if the state is changed.
  • Via the input, you can either set a specific state or advance to the next state.

encoder SF

encoder SF

The stateful Encoder Node provides an easy way to hold and change a numeric value. Things like value range, initial value etc. can be freely defined.

  • Output #1 provides a message about every change of the held value.
  • Output #2 delivers only the value without the event.
  • You can set the value directly via the input (within the value range).

fader SF

fader SF

There is only this stateful variant of the fader node, because a fader always holds a value - it cannot be stateless. You can also define any value range here.

  • At Output #1, you get a message about touching a fader, releasing it and every value change.
  • Output #2 only returns the pure value on change, no events.
  • Via the input you can set the value, the motorized fader moves to the corresponding position.

The basic message structure

Full message

The full message from all our nodes is structured as follows (JSON view below):

msg {
    topic:  < string > ,
    payload: {
        event:  < string > ,
        value:  < number >  |  < string >  | null
    }
}

Comments on this:

  • You can freely define the topic for each node.
  • The payload contains an object with the properties event and value:
    • The event describes what has happened (or, at the input, should happen), for example
      • "PRESSED" (a button was pressed)
      • "UPDATED" (the value held has changed)
      • "UPDATE" (the value held is to be changed)
    • The value contains the respective value or may be missing completely, depending on the type of the node and the type of the event.
  • This complete message is sent by all nodes on output #1 (or on the only output).

Value message

Most of the nodes additionally send only one value in case of a change on output #2:

msg {
    topic:  < string > ,
    payload:  < number >  |  < string >
}

Comments on this structure:

  • For the topic see above.
  • The payload directly contains the value that can be found in the full message under value.

This message is only sent on output #2 if there is a value change or similar (state change, encoder rotation, etc.), simple events like "button pressed" have no effect on this output.

Basics on the Node edit dialog

All nodes have some settings in the edit dialog in common. This is mainly about specifying the connection to the hardware. The figure shows the edit dialog of the rgb button SL, because this is the best way to show the common settings.

Image-20200814133547199.png

From top to bottom:

  • Tiles Hub: Select here which tile chain (via the TilesHub) you want to access. The connection must be set up in the config node tiles-hub-config.
  • Name: Assign any name you like.
  • Message Topic: Specify any topic that should be included in every outgoing message of this node.
  • Tile Size: Select whether you want to address a tile with 8 or 12 RGB buttons/encoders. Not available for the Fader Node.
  • Tile # (0..n): In a TileChain, all tiles of the same type (e.g. RGB button) and size variant (8 or 12) are numbered in ascending order from 0. Select here which tile you want to address exactly. If you have only one tile of a certain type, leave this value at 0.
  • Widget # (0..n): The widgets on each tile are also numbered consecutively, from left to right and from top to bottom if applicable.

Each Node in detail

rgb button SL

Edit dialog

(see Basics on the Node edit dialog)

Output

Action event value
Button is pressed "PRESSED" -
Button is released "RELEASED" -

Expected input

Desired action event value
Let the RGB LED shine in a specific color "COLOR" RGB color value, either numerically or as a hex value in "0xRRGGBB" format

encoder SL

Edit dialog

The figure shows only the special settings for this node:

Image-20200814143516544.png

  • Acceleration Maximum: The Encoder node delivers accelerated values via a parabolic curve, i.e. the faster you turn, the higher values you get. The minimum is fixed at 1, where you can set which value you want to receive as maximum (default is 10).
  • Integer values: Check this if you only want integer values, no floating point.
  • Disable Acceleration: Check this if you don't want any accelerated values at all. You will only get "single ticks".

Output

Action event value
Encoder is pressed "PRESSED" -
Encoder is released "RELEASED" -
Encoder is touched "TOUCHED" -
Encoder touch has ended "UNTOUCHED" -
Encoder has been turned "UPDATED-RELATIVE" 1..max acceleration (number) for clockwise rotation, corresponding negative values for counterclockwise rotation. If acceleration is disabled you will only get 1 or -1.

Expected input

This node has no input.

rgb button SF

Edit dialog

The figure shows only the special settings for this node:

Image-20200814145125521.png

  • State Names: Here you define how many different states your button can have by naming them. You must separate the individual names with commas. Note that the number of names listed here determines the number of possible states. The first state listed here is also the initial state to which the node is set after deploy.
  • State Colors: A color can be assigned to each state. The LED of the button then lights up in the color corresponding to the state. Format: Hexadecimal 0xRRGGBB. Separate the individual color values with commas as well.
  • State Brightnesses: (This functionality has not yet been implemented.)
  • Switch on Release: Check this box if you want the state to change on button release, not on button press.
  • Relay incoming values to outputs: Check this if you want state changes made via the node input to be forwarded to the outputs.

Output

Action event value
Button is pressed (or released, if "Switch on Release" is checked) "UPDATED" The name of the current state as <string>.

Expected input

Desired action event value Reaction
Switch to a specified state "UPDATE" The desired state name as <string>. The Button changes to the named state, the LED will indicate this if a color is specified. The state change will be relayed, if activated. If the submitted name does not match, nothing will happen.
Switch to the next state (like button press/release does) "NEXT_STATE" - The Button changes to the next state in line, the LED will indicate this if a color is specified. The state change will be relayed, if activated.

encoder SF

Edit dialog

The figure shows only the special settings for this node:

Image-20200814151622395.png

  • Minimum Value: Specify the minimum of the value range here.
  • Maximum Value: Specify the maximum of the value range here.
  • Initial Value: You must enter a start value that becomes valid after the deploy.
  • Acceleration Maximum: The Encoder node delivers accelerated values via a parabolic curve, i.e. the faster you turn, the higher values you get. The minimum is fixed at 1, where you can set which value you want to receive as maximum (default is 10).
  • Integer values: Check this if you only want integer values, not floating point.
  • Disable Acceleration: Check this if you don't want any accelerated values at all. You will only get "single ticks".
  • Switch on Release: Check this box if you want the state to change on button release, not on button press.
  • Relay incoming values to outputs: Check this if you want state changes made via the node input to be forwarded to the outputs.

Output

Action event value
Encoder is turned "UPDATED" The current value as a <number>.

Expected input

Desired action event value Reaction
Set the held value to a specific value. "UPDATE" The desired value as a <number>. The held value changes to the submitted value and is relayed, if this is activated.

fader SF

Edit dialog

The figure shows only the special settings for this node:

Image-20200814152424557.png

  • Minimum Value: Specify the minimum of the value range here. (The native value range of the Faders is 0..65535 as integer and is used as default).
  • Maximum Value: Specify the maximum of the value range here.
  • Initial Value: If you wish, you can assign a starting value. After deploy, the motor fader then moves to the corresponding position.
  • Integer values: Check this if you only want integer values, not floating point.

Output

Action event value
Fader is touched "TOUCHED" -
Fader touch has ended "UNTOUCHED" -
Fader has been moved "UPDATED" The current fader position as a <number> in the specified value range.

Expected input

Desired action event value Reaction
Move the fader to a specific position "UPDATE" The desired position as a <number> in the specified value range. The fader moves to the position corresponding to the submitted value.

Outlook

There is more to come. For now we wish you a lot of fun. Feel free to contact us at community@makeproaudio.com