JSON Control

JavaScript Object Notation (JSON) is a widely used data interchange format. The M.1k2 allows you to query and set audio crosspoints via HTTP requests that contain JSON data. Also the current device status can be queried.

Almost all modern scripting languages support JSON, so integrating the M.1k2 in your corporate setup can be accomplished easily.

JSON Reference

Currently there are three methods implemented:

/json/status_get

Returns the current device and signal status.

{
  "serial": "12345678",
  "fpga_firmware": "2.2.87",
  "temperature": 49.3,
  "psu_1": "active",
  "psu_2": "off",
  "input_status": [
    {
      "status": "no signal",
      "frequency": 0,
      "ch": 56,
      "frame": 48,
      "last_change": 0,
      "label": "Input Port 1",
      "fg": "000000",
      "bg": "FFFFFF"
    },
    {
      "status": "sync",
      "frequency": 48000,
      "ch": 64,
      "frame": 48,
      "last_change": 1363553568,
      "label": "Input Port 2",
      "fg": "000000",
      "bg": "FFFFFF"
    },
    [..]
  ],
  "output_config": [
    {
      "clock": "wck_input",
      "fs": "1FS",
      "ch": 56,
      "frame": 48,
      "label": "Output Port 1",
      "fg": "000000",
      "bg": "FFFFFF"
    },
    [..]
  ],
  "wck_status": "sync",
  "wck_freq": 48000,
  "wck_last_change": 1363553562,
  "video_status": "no signal",
  "video_mode": "PAL",
  "video_freq_44": 44100,
  "video_freq_48": 48000
  "video_last_change": 0
}

/json/xps_get

The result is a fairly condensed JSON array containing all crosspoints indexed by destination channel. If a destination is connected, the corresponding source channel is given as a number (0..1023). If a destination is not connected, the value null is set.

[0,1,2,3,4,5,6,7,
 null,null,null,null,null,null,null,null, 
 [..] 
 1016,1017,1018,1019,1020,1021,1022,1023]

In the example above, we see unity connections except for destination channels 8..16, which are disconnected.

/json/xps_set

You can set any number of destination sources by passing a variable length object in the body of the POST request to this URL. The keys have to be the destination channels as decimal number in a string, the value has to be a decimal number of the source channel (0..1023) or the keyword null.

Note: All crosspoints in the same object will be set simultaneously.

If the JSON data could be parsed successfully and all commands are processed, you will receive a HTTP 200 status code reply. In case of an error, you will receive a HTTP 500 status code together with a (hopefully) meaningful error message.

Examples

1. This will create a unity matrix (all sources routes 1:1 on the destinations):

   
   { "0": 0,
     "1": 1,
     [..]
     "1022": 1022,
     "1023": 1023
   }
   

2. Set output channels 1/2 of MADI ports 1 and 2 to input channels 17/18 and disconnect output channels 5..8 on MADI port 1:

   
   { "0": 16, "1": 17,
     "64": 16, "65": 17,
     "4": null, "5": null,
     "6": null, "7": null
   }
   

/json/locks_get

Returns an array with 1024 entries of 0/1 values, with 1 indicating a locked channel.

[0,0,0,0,1,0,0,0,
 [..] 
 1,1,1,1,1,1,1,1]

/json/locks_set

You can set any number of channel locks by passing a variable length object in the body of the POST request to this URL. The keys have to be the destination channels as decimal number in a string, the value has to be a 0 or null to clear a lock, and 1 to lock the corresponding channel.

Note: All locks in the same object will be set simultaneously.

If the JSON data could be parsed successfully and all commands are processed, you will receive a HTTP 200 status code reply. In case of an error, you will receive a HTTP 500 status code together with a (hopefully) meaningful error message.

Example

This will lock all channels:

{ "0": 1,
  "1": 1,
  [..]
  "1022": 1,
  "1023": 1
}

/json/snapshots_get

Returns an array containing all system snapshots. Empty slots are not reported. The snapshots are not sorted by their ID.

		
[
  {
    "id": 2,
    "timestamp": 1384944120,
    "date_time": "2013/11/20 11:42",
    "project": "Soundfield Demo",
    "fg": "000000",
    "bg": "FF6300",
    "name": "Test 1',
    "comment": ""
  },
  [..]
]       

/json/snapshot_set

Recalls a system snapshot. This resource has two mandatory GET arguments:

So, to restore everything from a snapshot, the flags argument has to be 4087 (1+2+4+16+32+64+128+256+512+1024+2048, or (4096-1)-8).

Examples

1. Restore everything from system snapshot 10:

   /json/snapshot_set?10,4087

2. Just the online matrix from snapshot 2:

   /json/snapshot_set?2,4

3. Offline matrix into online matrix:

   /json/snapshot_set?2,3

/json/destination_status

Returns connection details for a range of destinations.

The GET arguments from and to define the destination channel range to report, ranging from 1..1024. The result is an object with this structure:

		
/json/destination_status?1,2
{
  "1": {
    "label": "Output 1/1",
    "fg": "000000",
    "bg": "FFFFFF",
    "locked": 0,
    "source": {
      "channel": 1,
      "label": "Input 1/1",
      "fg": "000000",
      "bg": "FFFFFF",
    }
  },
  "2": {
    "label": "Output 1/2",
    "fg": "000000",
    "bg": "FFFFFF",
    "locked": 0,
    "source": null
  }
}

/json/source_status

Similar to the destination_status resource, but returns the data from a source channel's perspective.

The GET arguments from and to define the source channel range to report, ranging from 1..1024. The result is an object with this structure:

		
/json/source_status?1,2
{
  "1": {
    "label": "Input 1/1",
    "fg": "000000",
    "bg": "FFFFFF",
    "destinations": {
      "1": {
        "label": "Output 1/1",
        "fg": "000000",
        "bg": "FFFFFF",
        "locked": 0},
      "3": {
        "label": "Output 1/3",
        "fg": "000000",
        "bg": "FFFFFF",
        "locked": 0}
    }
  },
  "2": {
    "label": "Output 1/2",
    "fg": "000000",
    "bg": "FFFFFF",
    "destinations": null
  }
}

JSON Security

All JSON commands are executed with the permissions for the plugin 'json'. If you want to restrict the execution of JSON commands to parts of the M.1k2, please choose a fitting permission class for the 'json' plugin - or create a new permission class to suit your needs.

Example Script

This PHP script queries and sets all JSON data and handles the HTTP requests all the way from scratch for demonstration purposes:

JSON Specification

For more information about JavaScript Object Notation (JSON), please consult the IETF's specification, RFC 4627.

Questions? Suggestions?

If you have questions, found a bug or need new features, please do not hesitate to contact us: support@directout.eu.