Integration Docs

Important!

This is not made for end-users. If you are looking for a way to connect your USB controller to your computer via Ethernet, please refer to the Bridge Usage Guide.

General Information

The MPX Bridge is a software bridge between the MPX Controller and a Client speaking a bidirectional network protocol.
The Bridge is a single binary executable, which should be shipped with the client application.
It is executed as a child process of the client application.
Configuration is done using command line arguments (see below).

Configuration

hannes@Hannes-Desktop:~$ ./bridge --help

MPX Bridge

  A bridge between MPX Controllers and other network protocols.

Options

  -V, --verbose boolean   If enabled, additional debug information will be printed to the  
                          console.
  -v, --version boolean   Print the version number.
  -H, --help boolean      Print this usage guide.
  -i, --in string         How to connect to the controller. Can be a serial port (COM1,    
                          /dev/ttyUSB0, etc.), an IP address (e.g. 192.168.1.150[:1234])   
                          or "auto" (default) which will grab the first available usb      
                          serial port.
  -o, --out string        Output protocol. Can be "mpx" (default, used for Glue) or        
                          "osc".
  -p, --port number       Output port for the selected protocol
  -h, --host number       Local host / address to bind to. Defaults to 127.0.0.1, which    
                          is the loopback address. If you want to listen on all
                          interfaces, use 0.0.0.0
  -u, --udp number        If set, the OSC protocol will use UDP instead of TCP. Set this   
                          to the host:port to send data to, if you want to use UDP.        
  -d, --dnssd boolean     Enable DNS-SD (Bonjour) advertising. This will be the name of    
                          the service. If not specified, no DNS-SD advertising will be     
                          done. When using the MPX protocol, DNS-SD advertising will be    
                          done automatically, therefore this option is ignored.
  -j, --json boolean      If enabled, all output printed to the console will be in JSON    
                          format.

OSC Example

Client-side perspective

The following example is from the perspective of the client application. receive means, that the client application will receive messages sent by the Bridge, and send means, that the client application will send messages to the Bridge.

Transport

By default, the Bridge will use TCP for communication. If you want to use UDP, specify your target address as <ip>:<port> in the --udp argument.

General Info

Almost any command which is specified with a value, can be sent without a value in order to query the current value. The Bridge will respond with an osc message with the same address, but with the value appended.

Error messages

If the Bridge cannot process a message, it will send error messages to the client application
Error Messages are sent to the /error address
They have two arguments:
1. the original address
2. the error message

Info messages

Triggered by sending a message with one of the following addresses without values
In the following table parameters are enclosed in [], see below for details on how to address widgets
The /info/controller/widgets/[x]/[y] address can be used to query the info of a widget at a given position. It returns:
- the type of the widget
- the width of the widget
- the height of the widget
- if the provided x and y position does not match the top left corner of the widget, the left and top position of the widget will be returned as arguments 4 and 5

Address	Description	Return Type	Description	Example
`/info/controller/status`	Returns the current status of the controller	`i`	0: Disconnected, 1: Connected, 2: Connecting	`1`
`/info/controller/connection`	Returns the connection type and the address of the controller	`s`; `s`	`USB` or `ETHERNET`; Address	`USB`; `/dev/ttyUSB0`
`/info/controller/serial`	Returns the serial number of the controller	`s`	Serial Number	`SRO2D4`
`/info/controller/name`	Returns the name of the controller	`s`	Name	`MPX-1`
`/info/controller/layoutString`	Returns the layout string of the controller	`s`	Layout String (see here for more info)	`4E.8B.4O.4F60`
`/info/controller/dimensions`	Returns the dimensions of the controller	`i`; `i`	Width; Height	`8`; `10`
`/info/controller/widgets/[x]/[y]`	Returns the info of the widget at the given position	`s`; `i`; `i`; [`i`; `i`]	Type; Width; Height; [TopLeftX; TopLeftY]	`fader`; `1`; `4`; `0`; `0`
`/info/version`	Returns the version of the Bridge	`s`	Version	`1.0.0`

Control messages

Widgets are identified by their type and their x / y position
Positions are 0-based
A widget which is bigger than 1x1 should be addressed by its top left corner, however the Bridge will also accept the other positions

The format is as follows:

/control/widgets/[type]/[x]/[y]/[command]
[type] can be one of the following:
- buttons
- faders
- encoders
- oleds
- touchscreens
[command] can be one of the following:
- value
- color
- touched
- pressed
- left
- right
- url[/[index]]
- reload[/[index]]
- clear[/[index]]
- tab

Examples:

receive /control/widgets/buttons/0/2/value 
send    /control/widgets/buttons/0/2/color
receive /control/widgets/faders/1/0/value
receive /control/widgets/faders/1/0/touched
send    /control/widgets/faders/1/0/value
receive /control/widgets/encoders/0/0/pressed
receive /control/widgets/encoders/0/0/left
send    /control/widgets/touchscreens/0/1/url

Controlling the OLEDs is a bit more complex, see the section below for info.

Subtypes

Some widgets have subtypes, which can be addressed by appending the subtype to the widget type, separated by a colon (:). When sending events, the bridge will always send the subtype as well. To be future-proof, if you don't need the subtype, you should ignore everything after the first colon (:). Currently, the following widgets have subtypes:

buttons
- buttons:double (half-row)
- buttons:ts (tactile)

Buttons

Receive value messages: 1 (pressed) or 0 (released)
Send color messages (send string for rgb (#rgb or #rrggbb), or number for hsl, see hsl specification below)

Half-Row Buttons

There's a tile called 8BTS whose buttons are half the size of the normal buttons. The bottom row can be addressed by adding .5 to the y position.

Faders

Receive value messages: 0 - 65535 (0xFFFF)
Receive touched messages: 1 (touched) or 0 (untouched)
Send value messages: 0 - 65535 (0xFFFF)
For touched events with value 0, a second argument with the time in milliseconds since the last touch event is sent

Encoders

Receive left messages: 1 - 10
Receive right messages: 1 - 10
Receive pressed messages: 1 (pressed) or 0 (released)
Receive touched messages: 1 (touched) or 0 (untouched)
For touched events with value 0, a second argument with the time in milliseconds since the last touch event is sent
For pressed events with value 1, a second argument with the time in milliseconds since the last press event is sent

A note about acceleration

The Bridge will accelerate the encoder values, so that the values will increase faster the longer the encoder is turned. This is done to make the encoders more usable. That means, a left event with a value of 10 does not mean, that the encoder has been turned 10 ticks, but less than 10 ticks in a short amount of time.
Of course, for slow movements, the value will be the exact amount of ticks turned.

OLEDs

Each OLED Display has 4 virtual pages (0 - 3)
You can display one page at a time
Each page has a layout, see image below for the types of layouts
Each layout displays up to 3 widgets
Each widget has a label, a context, a valueString, a value, a barType, the inverse property and the valueInsteadOfBar property
To set the current page, send a page message with the page number (0 - 3):
- /control/widgets/oleds/[x]/[y]/page
To set the layout for a page, send a layout message with the layout number (0 - 13):
- /control/widgets/oleds/[x]/[y]/pages/[page]/layout

The format of the widget data commands looks as follows:

/control/widgets/oleds/[x]/[y]/pages/[page]/widgets/[widgetIndex]/[command]
[widgetIndex] must be 0 - 2
[command] can be one of the following:
- label
- context
- valueString
- value
- barType
- inverse
- valueInsteadOfBar

Examples:

send /control/widgets/oleds/0/0/page 0
send /control/widgets/oleds/0/0/pages/0/layout 1
send /control/widgets/oleds/0/0/pages/0/widgets/0/label "Fader 1"
send /control/widgets/oleds/0/0/pages/0/widgets/0/context "Fader 1 Context"
send /control/widgets/oleds/0/0/pages/0/widgets/0/valueString "Fader 1 Value"
send /control/widgets/oleds/0/0/pages/0/widgets/0/value 0x80FF
send /control/widgets/oleds/0/0/pages/0/widgets/0/barType 1
send /control/widgets/oleds/0/0/pages/0/widgets/0/inverse 0
send /control/widgets/oleds/0/0/pages/0/widgets/0/valueInsteadOfBar 0

OLED Layouts

OLED Bar Types

Bar Type	Description
1	BarUp
2	BarDown
3	BarMiddle
4	BarSpread
5	Meter
6	Meter with fallback
7	V-POT

XYZ Joystick

Receive valueX messages: 0 - 65534 (0xFFFF - 1)
Receive valueY messages: 0 - 65534 (0xFFFF - 1)
Receive valueZ messages: 0 - 65534 (0xFFFF - 1)

Why not 0xFFFF?

In order to have a real center position when the stick is idle, we needs an odd number of values. Therefore, the maximum value is 0xFFFF - 1.

XY Joysticks

Receive valueX messages: 0 - 65534 (0xFFFF - 1)
Receive valueY messages: 0 - 65534 (0xFFFF - 1)

Why not 0xFFFF?

In order to have a real center position when the stick is idle, we needs an odd number of values. Therefore, the maximum value is 0xFFFF - 1.

Datawheel

Receive left messages: 1 - 10
Receive right messages: 1 - 10

A note about acceleration

T-Bar

Receive value messages: 0 - 65535 (0xFFFF)

Touchscreens

Send url messages: string (the url to a webpage to display on the screen)
Send reload messages (no arguments) (reload the current webpage)
Send clear messages (no arguments) (clear the screen and display a black background)

The Touchscreens support up to 8 Tabs. Switching between tabs is more performant than reloading the whole page, so it is recommended to use tabs if you want to display multiple pages. Controlling a tab is done by adding /[index] to the url, reload or clear command. The index is 0-based. If no index is specified, the commands control the current tab.

Switching tabs can be done by sending a tab command with the index of the tab to switch to (0 - 7).

Troubleshooting

OLED Problems

The OLED Display shows a blank screen
- Make sure that you've set the current page
- Make sure that you've set a layout for that page
- Make sure that you've set a data for a widget which is used in that layout
The OLED Display's bar is always empty
- Make sure that you've set a bar type for that widget

Misc

HSL

HSL values are encoded as a 32-bit unsigned integers
- Bytes 0-1: 16bit Hue (0-65535)
- Byte 2: 8bit Saturation (0-255)
- Byte 3: 8bit Lightness (0-255)

LayoutString

The layout string is a string which describes the layout of the controller
It is a sequence of segment-strings separated by hyphens (-)
Each segment-string is a sequence of tile types separated by dots (.)

Tile Types

Type	Description
`12B`	12 LED Buttons
`8B`	8 LED Buttons
`4B`	4 LED Buttons
`12E`	12 Encoders
`8E`	8 Encoders
`4E`	4 Encoders
`4O`	4 OLED Displays
`4F60`	4 Faders (60mm)
`4F100`	4 Faders (100mm)
`XYZ`	XYZ Joystick
`TSB3`	B3 Touchscreen (2 segments wide and 3 rows high)
`TSC4`	C4 Touchscreen (3 segments wide and 4 rows high)
`8BTS`	8 Tactile LED Buttons
`4BTS`	4 Tactile LED Buttons
`8BHR`	8 Half-Row LED Buttons

Example

4E.8B.4O.4F60 is a valid layout string
It describes a controller with a 4 encoders tile, an 8 button tile, a 4 OLED displays tile and a 4 motorfaders (60mm) tile, all in a single segment below each other
A controller with two of these segments next to each other would have the layout string 4E.8B.4O.4F60-4E.8B.4O.4F60

Integration Docs

General Information​

Configuration​

OSC Example​

General Info​

Error messages​

Info messages​

Control messages​

Buttons​

Faders​

Encoders​

OLEDs​

OLED Layouts​

OLED Bar Types​

XYZ Joystick​

XY Joysticks​

Datawheel​

T-Bar​

Touchscreens​

Troubleshooting​

OLED Problems​

Misc​

HSL​

LayoutString​

Tile Types​

Example​