OMK Logo
OMK Title


OSC introspection

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/!"

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

   "type" : "node",
   "description" : "Group",
   "path" : "/sensors/group/",
   "items" : [

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" : [

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.

Beta Testers

After a high interest at Maker Faire Rome, we are now running a beta-testing campaign to collect more comprehensive feedback of first-hand experiences of our final Chimaera prototype design from interested individuals. Get in contact with us. Now.

Please support free/libre software and hardware designs.


donate bitcoins


request bank credentials via encrypted mail for SEPA transfers.

Last update - 16 Sep 2017

GitHub Vimeo

Copyright © 2014-2017, Hanspeter Portner, Open Music Kontrollers, cc-by-sa 4.0. Uses libre javascript.