MIDI-MT - API of the Remote Control Panel Module

MIDI-MT Documentation in English

Remote Control API

Client requests
Server responses
Example Web Socket Applications
- JavaScript Web Socket
- Python Web Socket
Configuration files

You can use the remote control module’s “API” yourself in scripts in various runtime environments. The transport for interaction with “MIDI-MT” is Web Socket, commands and responses are in Json format. Communication is implemented only via the HTTP protocol, that is, only the standard ws:// prefix is supported. The solution is designed to work on a local network. If necessary, for access via the HTTPS protocol, you can install any front-end that supports HTTPS Web Socket, for example nginx.

Client requests

The endpoint in the server URL is always the /data tag.

"action": "config" - request configuration from the server. Implies a response in the form of the structure of the “units” section from the current server configuration.

{
   "action": "config"
}

"action": "change" - sending changes to control parameters. The sent control parameters, such as: scene, id, type, target, longtarget - must correspond to the parameters in the server configuration.

{
   "action": "change",
   "unit": {
       "scene":xxx,           // control scene 
       "id":xx,               // control key
       "type":x,              // control type
       "target":xxx,          // group | target
       "longtarget":xxx,      // target
       "onoff": true | false, // new value
       "value": 0-127         // new value
   }
}

"action": "wakeup" - a request to exit the server from sleep mode. In some cases, in Windows 10/11, some audio sources and USB devices are turned off in “sleep mode”.

{
   "action": "wakeup"
}

"action": "windowtotop" - sends the filename of the application that needs to be brought to the foreground. Required to use multimedia playback control buttons.

{
   "action": "windowtotop",
   "name": "application-file-name.exe"
}

"action": "getlog" - request to receive the current log file in Base64 format.

{
   "action": "getlog"
}

Server responses

All server responses, as well as requests, are executed in a Json container.

When “sending changed parameters”, “requesting the server to wake up from sleep mode” and “sending application file name”, there are no responses from the server.
to “request configuration from server” - the full configuration of the units section from the configuration file is sent.

{
   "action": "config",
   "units":[
       {"scene":177,"id":22,"type":0,"target":0,"longtarget":255,"onoff":false,"value":64},
       {"scene":177,"id":13,"type":1,"target":1,"longtarget":255,"onoff":true,"value":107,"app":["App1","App2"]},
       ...
   ]
}

to the “request to send a log file” - the currently relevant log file is sent in the Base64 format > UTF-8.

{
   "action": "getlog",
   "log": "BASE64-content"
}

"action": "changed" - sent if the parameters of the unit control are changed, from the units configuration section. Generated by the server when the parameters of controls are changed, as well as when new elements are added or old elements are removed.

{
   "action": "changed",
   "unit": {
       "scene":177,
       "id":22,
       "type":0,
       "target":0,
       "longtarget":255,
       "onoff": true,
       "value": 127
   }
}

Example Web Socket Applications

The “IP address” and “port” in the application must match the current configuration of the running server.

    "remote": {

        "port": 8888,
        "host": "x.x.x.x",
        ...
    },

JavaScript Web Socket

let socket = new WebSocket("ws://x.x.x.x:8888/data");

socket.onopen = function(e) {
  console.log("[open] Connection established, request configuration from server...");
  socket.send(JSON.stringify({ "action": "config" }));
};

socket.onmessage = function(event) {
  console.log("[message]", JSON.parse(event.data));
};

socket.onclose = function(event) {
  if (event.wasClean) {
    alert(`[close] Connection closed cleanly, code=${event.code} reason=${event.reason}`);
  } else {
    // server process killed or network down
    // event.code is usually 1006 in this case
    console.log("[close] Connection died");
  }
};

socket.onerror = function(error) {
  console.log(`[error]`);
};

View this example on BitBucket.

Learn more about JavaScript Web Socket programming on the MDN Web docs.

Python Web Socket

You will probably have to install packages:

pip install websocket-client
pip install rel

import websocket
import _thread
import time
import rel

def on_message(ws, message):
    print(message)

def on_error(ws, error):
    print(error)

def on_close(ws, close_status_code, close_msg):
    print("### closed ###")

def on_open(ws):
    print("Opened connection")
    ws.send("{ \"action\": \"config\" }")

if __name__ == "__main__":
    websocket.enableTrace(True)
    ws = websocket.WebSocketApp("ws://x.x.x.x:8888/data",
                              on_open=on_open,
                              on_message=on_message,
                              on_error=on_error,
                              on_close=on_close)

ws.run_forever(dispatcher=rel, reconnect=5)
rel.signal(2, rel.abort)
rel.dispatch()

View this example on BitBucket.

Learn more about Python Websocket programming, websocket-client documentation.