Using the Cognio Control Protocol

PROTOCOL STRUCTURE

Cognio uses the JSON-RPC 2.0 specification to format and send remote control commands. Each request is a JSON object. You can send a single request or package multiple requests into an array. The server accepts both formats. The default port number is TCP port 3012, but can be configured for a given Cognio device in a site.

Message Framing

Messages on the TCP socket are framed with a null byte (\0) terminator. When writing a raw socket client, send each request followed by a single null byte to signal the end of the message.

• The server buffers incoming bytes and does not process a message until it encounters the null-byte delimiter. If you never send the delimiter, the server never responds — a common cause of a client appearing to "hang".
• Multiple JSON requests may be combined within a single frame.
• Responses returned by the server are likewise null-byte terminated.

For example, a single NamedControl.Get request on the wire looks like the JSON object below immediately followed by a \0 byte:

{"jsonrpc":"2.0","method":"NamedControl.Get","params":["MyCPG/fader1"],"id":"getFader"}

Each JSON object request has some required properties and some optional ones.

Each JSON object response has some required properties and some optional ones.

REQUEST AND RESPONSE STRUCTURE

A properly formatted request will result in a structured response. If the request is missing required fields or contains invalid data, an error response is returned.

Properly Formatted Request:

{
  "jsonrpc": "2.0",
  "method": "NamedControl.Get",
  "params": ["MyCPG/fader1"],
  "id": "getFader"
}

Response:

{
  "jsonrpc": "2.0",
  "result": [
    { "name": "MyCPG/fader1", "text": "-6.0 dB", "value": -6.0 }
  ],
  "id": "getFader"
}

Improperly Formatted Request (Missing method):

{
  "jsonrpc": "2.0",
  "params": ["MyCPG/fader1"],
  "id": "getFader"
}

Response:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Invalid Request",
    "data": {
      "details": "Missing required property: method"
    }
  },
  "id": "getFader"
}

Responses

If the command succeeds, the value of the “result” property is the integer 1 and there is no “error” property.

If the command fails, there is no “result” property and an “error” property is returned. The value for this property is set based on the rules outlined in Section 5.1 of the protocol. JSON-RPC 2.0 Specification
The “error” property value is a JSON object with 3 properties:

The error codes are predefined by the protocol. The protocol allows for implementation specific custom error codes, but none are currently used. Any custom error codes must be outside the range of -32700 to -32000.

ERROR CODES

Application Specific Error Codes

PREREQUISITES

Before any Remote Control Protocol command will succeed, you must expose the controls you want to reach by configuring a Control Panel Group (CPG) in DesignOps. The protocol operates only on controls that have been explicitly enabled for remote access — if this setup is skipped, correctly formatted commands will still return errors or no response.

To make controls available to the protocol:

• Configure a Control Panel Group in DesignOps, set its Remote Enable property to on, and give it a non-empty Remote Name.
• For each control you want to expose, enable Remote Enable on that control and assign it a Remote Name.
• A control's full remote name is formed by joining the two with a slash: controlPanelGroupName/controlName. This is the name you pass in the params of a protocol command (see Control and Control Panel Group Naming below).
• The Cognio device that hosts the CPG is the device that serves the Remote Control Protocol for that group. Connect to that device (on the configured port) to reach its controls.

Only after this configuration is in place will methods such as NamedControl.Get and NamedControl.Set resolve the names you send.

SUPPORTED METHODS

Cognio supports the following remote control methods.

CONTROL AND CONTROL PANEL GROUP NAMING

The currently implemented methods operate on named controls. The user assigns these names to controls and control panel groups and enables access to the controls by the remote control protocol. Typically the names are concatenated names constructed by the control panel group name and the control name separated by a slash such as “controlPanelGroupName/controlName”. But some special cases are also permitted.

• If just one name is provide such as “controlName”, it is assumed to be for all accessible control panels. Each control panel enabled for remote control access is interrogated to see if it has a control by the specified name. For a get and subscribe methods, the values of the first matching control in all control panel groups is returned. If none are found, an error is returned. For set methods, all matching control's values are changed in all control panel groups. If none are found, an error is returned.
• If the control name is not specified such as “controlPanelGroupName/” (group names must be sent with the trailing "/"), for get and subscribe methods all accessible control’s values in the control panel group are returned. If there are no accessible controls in an accessible control panel group then an empty array is returned. An error is returned for set methods.
• If no names at all are specified for a get or subscribe method, an error is returned.
• If multiple names are provided for a get or subscribe method and one or more is not present or accessible, an error is returned.

Names are restricted to ASCII characters which no specific length limitation. Names are case sensitive. The character “/” are not allowed in a name. Other restricted characters may be added before release.

• If accessing a specific control panel group by name and multiple control panel groups have the same name, only the first will be accessible. If accessing a specific control by name and there are multiple controls in single control panel group that have the same name, only the first is accessible.

{
  "jsonrpc": "2.0",
  "method": "NamedControl.Set",
  "params": {
    "name": "MyControlPanelGroup/myControlName",
    "value": -12.0
  },
  "id": "setGain"
}

This structure helps organize your system and allows control references to remain human-readable and self-explanatory.

Resolving Control Names

When you send a request using just a control name, Cognio searches all accessible control panel groups for a matching control. For methods like Get or Subscribe, the first match found from all control panel groups will be returned.

{
  "jsonrpc": "2.0",
  "method": "NamedControl.Get",
  "params": ["mute"],
  "id": "getMute"
}

For Set methods, all matching controls across all groups will be updated:

{
  "jsonrpc": "2.0",
  "method": "NamedControl.Set",
  "params": { "name": "mute", "value": 0 },
  "id": "setAllMutes"
}

If no matching control is found, the server returns an error.

You can target all controls within a control panel group by specifying the group name followed by a trailing slash. This is useful for retrieving the full state of a panel.

{
  "jsonrpc": "2.0",
  "method": "NamedControl.Get",
  "params": ["MyGroup/"],
  "id": "getAllControls"
}

• Get and Subscribe will return values for all accessible controls in the specified group.
• If the group exists but has no accessible controls, the response will be an empty array.

If you send a request with no names at all in the params array, the server will return an error:

{
  "jsonrpc": "2.0",
  "method": "NamedControl.Get",
  "params": [],
  "id": "getNothing"
}

If you include multiple names in a request, and even one of them is invalid or inaccessible, the entire request fails:

{
  "jsonrpc": "2.0",
  "method": "NamedControl.Get",
  "params": ["MyGroup/fader1", "InvalidGroup/missingControl"],
  "id": "getMultiple"
}

This structure ensures consistent, predictable behavior and avoids partial or misleading results when controls are missing.

NAMING RULES

• Names must use ASCII characters.
• Names are case-sensitive.
• / is only allowed as a separator between control panel group and control name. (trailing / is required when sending just group names)
• If multiple controls or groups have the same name, only the first match is used.

Params Values

The “params” property defines the arguments for the method. Though not always required, in many commands it is required to preform any operation. If “params” is not specified and the method requires it, an error will be returned indicating that the operation could not be performed.

While the JSON-RPC 2.0 spec allows either an array of values or an object with properties.

Methods and their Specific “params” Properties

Shown is a section for each supported method describing it and listing the additional required or optional properties in the “params” object provided. In some cases, the response is discussed.

NAMEDCONTROL.GET | GETTEXT / GETVALUE

These methods return the current values of one or more named controls. You can request a single control, multiple controls, or all controls in a control panel group.

The params field is an array of control names or group names (ending in a slash). If you specify a group, all accessible controls in that group will be returned. If any name is invalid or inaccessible, the entire request fails.

{
  "jsonrpc": "2.0",
  "method": "NamedControl.Get",
  "params": ["channelName", "MyCpg/gain", "MyCpg/mute", "MyCpg/"],
  "id": "getMixerValues"
}

Response:

{
  "jsonrpc": "2.0",
  "result": [
    { "name": "MyCpg/channelName", "text": "FOH", "value":0},
    { "name": "AnotherGrp/channelName", "text": "1-Lobby", "value":1},
    { "name": "MyCpg/gain", "text": "-6.3 dB", "value": -6.3},
    { "name": "MyCpg/mute", "text": "muted", "value": 0},
    [ { "name": "MyCpg/channelName", "text": "FOH", "value":0},
      { "name": "MyCpg/gain", "text": "-6.3 dB", "value": -6.3},
      { "name": "MyCpg/mute", "text": "muted", "value": 0} ]
  "id": "getMixerValues"
}

NAMEDCONTROL.SET | SETTEXT / SETVALUE

These methods update the value of a named control. The params object includes:

• "name": The fully qualified name of the control
• "value": A numeric value (for SetValue)
• "text": A text value (for SetText)
• If both value and text are provided, value takes precedence

{
  "jsonrpc": "2.0",
  "method": "NamedControl.Set",
  "params": {"name":"MyCpg/gain", "value":-23.1},
  "id": "setMixerValue"
}

Response:

{
  "jsonrpc": "2.0",
  "result": 1,
  "id": "setMixerValues"
}

NAMEDCONTROL.MODIFYVALUE

This method adjusts a control’s value by a specified numeric offset.

The params object includes:

• "name": The fully qualified name of the control
• "offset": A numeric value to increment or decrement the control

{
  "jsonrpc": "2.0",
  "method": "NamedControl.ModifyValue",
  "params": {"name":"gain", "offset":-10.0},
  "id": "modifyMixerValue"
}

Response:

{
  "jsonrpc": "2.0",
  "result": [
    { "name": "MyCpg/gain", "value":-12.0},
    { "name": "AnotherGrp/gain", "value":-24.2} ]
  "id": "modifyMixerValues"
}

NAMEDCONTROL.SUBSCRIBE | SUBSCRIBETEXT / SUBSCRIBEVALUE

The “Subscribe” method is used to receive regular notifications of the value of a specific control or control panel group.

“params”: An object containing:

• A “name” property defining the controls to subscribe to. It can be a control’s remote name or be pre-pended with a specific control panel group’s remote name and slash, “” or “/”. Only the first control in a control panel group will be subscribed to, but if the control panel group is not specified, controls from multiple control panel groups could match. If the control panel group name is specified, only the first control panel group with that name will be selected.
• A “rate” property defining the minimum notification period in milliseconds.
• A “condition” property indicating if the notification should happen based on “change” or “time”.
• A “sync” integer property indicating if a notification should be sent if “change” is set and the value hasn’t changed. A “sync” value of 0 sends only if changed, 1 sends immediately then not again, and any other value skips that number of minimum update periods between sending notifications if there is no change. “Sync” only applies if the “condition” property is set to “change”.

The “rate”, “condition”, and “sync’ properties exactly match those used in the Site Manager Protocol.

Result:

The return is identical to the matching get method, refer to that example. If the method fails, the subscription is canceled. The subscription can be cancelled by using a rate of 0.

Request:

{ 
  "jsonrpc": "2.0", 
  "method": "NamedControl.Subscribe", 
  "params": {
    "name":"cpg/gain",
    "rate":5000,
    "condition":"change",
    "sync":1
  }
  "id": "subscribeMixerValues" 
}

Response:

A response is returned every time the value changes but no more frequently then every 5 seconds. The name in the response will include the control panel group’s remote name even if it was not specified.

{ 
  "jsonrpc": "2.0", 
  "result": [{ "name": "cpg/gain", "text": "-5.5", "value":-5.5}], 
  "id": "subscribeMixerValues"
}

To cancel a subscription, send the same request with "rate": 0.

Device.RecallPreset

The “RecallPreset” method is used to cause the recall of a preset exposed in the preset manager GUI interface by enabling for remote control and assigning a remote-control name. The preset is referenced by that name alone.

“params”: An object containing:

• The remote-control name of a preset or preset group to be recalled, or
• An array of remote-control names of preset or preset group names to be recalled.

Result:

The preset or presets found will be recalled. The presets do not have to have any control value changes defined for them. A log entry will be added for each preset or preset group recalled. If no “id” is provided, no response will be given. If an 'id” is provided, and one or more preset names are not present, an error will be returned. Any named presets that were present will be recalled. If all presets named were present, the result will be an object with a property “recalledControls” containing the number of controls that were found in the presets. It does not indicate the number of control values that were actually changed. Therefore it can be used to verify that the preset contains what is expected.

Request:

{  
    "jsonrpc": "2.0",
    "method": "Device.RecallPreset",
    "params": {
        ["preset1", "p2"]  
    }
    "id": "recallPresets" 
}

or

{
    "jsonrpc": "2.0",
    "method": "Device.RecallPreset",
    "params": {
        ["preset1", "p2"]  
    }
    "id": "recallPreset" 
}

Response:

A successful response of all provided preset names yields the response:

{
    "jsonrpc": "2.0",  
    "id": "recallPresets",  
    "result": {
        "recalledControls": 4
    } 
}

if one or more of the presets in not present, it will respond:

{
    "jsonrpc": "2.0",
    "id": "recallPreset",
    "error": {
        "code":-101,
        "message": "Preset not found"  
    } 
}

Device.UpdatePreset

The “UpdatePreset” method is used to cause the updating of any control values assigned to the specified preset or presets to their current values. Presets which can be updated are exposed in the preset manager GUI interface by enabling for remote control and assigning a remote-control name. The preset is referenced by that name alone.

“params”: An object containing:

• The remote-control name of a preset or preset group to be recalled, or
• An array of remote-control names of preset or preset group names to be recalled.

Result:

The preset or presets found will be updated. The presets do not have to have any control value changes defined for them, in which case nothing will change. A log entry will be added for each preset or preset group updated. If no “id” is provided, no response will be given. If an 'id” is provided, and one or more preset names are not present, an error will be returned. Any named presets that were present will be updated. If all presets named were present, the result will be an object with a property “updatedControls” containing the number of controls that were found in the presets. It does not indicate the number of presetvalues that were actually changed. Therefore it can be used to verify that the preset contains what is expected.

Request:

{
    "jsonrpc": "2.0",
    "method": "Device.UpdatePreset",
    "params": {
        ["preset1", "p2"]  
    }
    "id": "updatePresets" 
}

or

{
    "jsonrpc": "2.0",
    "method": "Device.UpdatePreset",
    "params": {
        "p3"  
    }
    "id": "updatePresets" 
}

Response:

A successful response of all provided preset names yields the response:

{
    "jsonrpc": "2.0",
    "id": "updatePresets",
    "result": {
        "updatedControls": 22
    } 
}

if one or more of the presets in not present, it will respond:

{
    "jsonrpc": "2.0",
    "id": "updatePreset",
    "error": {
        "code":-101,
        "message": "Preset not found"  
    } 
}

Device.GetLastRecalledPreset

The “GetLastRecalledPreset” method returns the preset that was most recently recalled on the device. Use it to display or act on the current preset state — for example, to show the active preset name on a control surface.

“params”: None. This method takes no parameters.

Result:

On success, the result is an object identifying the last recalled preset, including its remote-control name and its user-applied name. If no preset has been recalled since the device started, refer to the note below.

Request:

{
  "jsonrpc": "2.0",
  "method": "Device.GetLastRecalledPreset",
  "id": "getLastPreset"
}

Response:

TODO: Confirm the success response structure with the development team before release. On success, this method is expected to return an object containing the preset's remote name and its user-applied name.