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.