Subscription command

The subscription command allows you to get periodic updates for one or multiple values from the device.

In this example we will set up audio monitoring for audio activity on the connected devices. To see all available commands that can be subscribed to see the command list section. For error codes returned by commands refer to eror code section.

Attention

Bundled audio activity is the only command that can subscribe to multiple parameters, all other parameters need to be subscribed to separately.

To subscribe to periodic updates for audio activity the following command needs to be sent:

{
    "subscribe": [{
        "#": {
            "enable": true,
            "period_ms": 1000
        },
        "activity": [{
            "tx1": null,
            "tx2": null,
            "usb_in": null,
            "aux": null,
            "master": null,
            "rca": null,
            "usb_out": null,
            "xlr1": null,
            "xlr2": null,
            "dante1": null,
            "dante2": null
        }]
    }]
}

Let's break it down.

The values in the first attribute tell the device whether the subscription is enabled true or false and what frequency the data should be sent with - period_ms. As the attribute name implies the parameter should be the frequency described in milliseconds.

Attention

The period_ms will accept values between 20 and 2^32 ms, however, you should not set the value below 40ms as there is a possibility of flooding the communication channel which will result in the device crashing.

An exception to above is period_ms set to 0. When period_ms is 0, subscription messages are only sent when parameter changes (all subscriptions except bundled audio activity). For bundled audio activity, period_ms values from 0 to 20 will default to 20.

The second, activity, attribute lists the parameters you wish to get updates for. Simply put, you will receive data about the listed values.

After calling the command you will get the initial response:

{
    "subscribe": [{
        "#": {
            "enable": true,
            "period_ms": 1000
        },
        "activity": [{
            "tx1": null,
            "tx2": null,
            "usb_in": null,
            "aux": null,
            "master": null,
            "rca": null,
            "usb_out": null,
            "xlr1": null,
            "xlr2": null,
            "dante1": null,
            "dante2": null
        }]
    }],
    "error": 0
}

This, as the rest of the commands, lets the client know that there were no errors when subscribing. The next message from the device will happen after the time set in the period_ms has elapsed and would be the following:

{
    "activity": [{
        "tx1": -100.00,
        "tx2": -100.00,
        "usb_in": -100.00,
        "aux": -91.53,
        "master": -97.53,
        "rca": -97.53,
        "usb_out": -97.53,
        "xlr1": -100.00,
        "xlr2": -100.00,
        "dante1": -100.00,
        "dante2": -100.00
    }],
    "error": 0
}

Note that only activity data and error parameters are returned.

When you no longer want the subscription data to be sent, you have to unsubscribe from the data stream. This can be done by setting the enabled flag to false in the initial command.

{
    "subscribe": [{
        "#": {
            "enable": false,
            "period_ms": 1000
        },
        "activity": [{
            "tx1": null,
            "tx2": null,
            "usb_in": null,
            "aux": null,
            "master": null,
            "rca": null,
            "usb_out": null,
            "xlr1": null,
            "xlr2": null,
            "dante1": null,
            "dante2": null
        }]
    }]
}