Open Music Kontrollers

Introspect

Make sure to understand the OSC Query system we use to configure our devices before proceeding.

The Chimaera has a fair amount of configuration options. To help the user or UI programmer, the device uses a dedicated approach for introspection of all its Open Sound Control configuration nodes and methods. A request for introspection for a given node or method in the OSC tree is simply started by appending a bang (!) to the node or method the user wants more informations about. The device will return a JSON string with the nodes or methods attributes.

To get an introspection of a nested node tree, we start off by a request for introspection for the parent node itself:

$ oscsend osc.udp://chimaera.local:4444 /sensors/group/! i $[RANDOM]
/success iss 27353 "/sensors/group/!" "{"path":"/sensors/group/","type":"node","description":"Group", "items":["reset","number","attributes/"]}"

The nodes attributes are encoded in the reply string in JSON format (here pretty printed):

{
 "type" : "node",
 "description" : "Group",
 "path" : "/sensors/group/",
 "items" : [
        "reset",
        "number",
        "attributes/"
 ]
}

A method node lists all its child items, e.g. either nested nodes (note the trailing ‘/’) or methods (NO trailing ‘/’), which can be queried individually:

$ oscsend osc.udp://chimaera.local:4444 /sensors/group/reset! i $[RANDOM]

e.g. is a simple method that requires no arguments.

{
 "path" : "/sensors/group/reset",
 "arguments" : [],
 "type" : "method",
 "description" : "Reset all groups"
}
$ oscsend osc.udp://chimaera.local:4444 /sensors/group/attributes/0/min! i $[RANDOM]

e.g. is a more complex method with a single argument being both readable and writable.

{
 "path" : "/sensors/group/attributes/0/min",
 "type" : "method",
 "description" : "Minimum",
 "arguments" : [
        {
             "type" : "f",
             "description" : "Min",
             "write" : true,
             "read" : true,
             "range" : [
                    0,
                    1,
                    0
             ]
        }
 ]
}

An OSC method lists all its arguments including an OSC type, valid range of values and read/write attributes. As all parameters of the above method are both readable and writable, the method can be called in two ways:

Once to get parameters…

$ oscsend osc.udp://chimaera.local:4444 /sensors/group/attributes/0/min i $[RANDOM]
/success isffiii 20128 "/sensors/group/attributes/0/min" 0.000000

… and once to set them.

$ oscsend osc.udp://chimaera.local:4444 /sensors/group/attributes/0/min if $[RANDOM] 0.2
/success is 3940 "/sensors/group/attributes/0/min"

A method can have multiple arguments. The argument type denotes the required OSC type (i, f, s, b, h, d, t, …). Each argument can be readable and/or writable. Numbers (i, f, h, d) are accompanied with an allowed range of values and strings (s, S) with their maximal allowed length.

An introspection of the full method tree of a device can be queried by starting off at the root node, then recursively query for its child nodes and methods, and their nodes and methods, …

$ oscsend osc.udp://chimaera.local:4444 /! i $[RANDOM]

From there it is a tiny step to automatically build control, configuration or documentation systems for our devices. An example for such automatic interface documentation can be seen here.

Last update - 28 Sep 2018

Copyright © 2014-2018, Hanspeter Portner, Open Music Kontrollers, cc-by-sa 4.0.