osc : opensound control / serialosc protocol
What is serialosc? How does it work?
discovering and connecting to serialosc devices
The serialosc server listens on port 12002.
When devices are connected, serialosc spawns new ports for each device. querying the server allows you to discover the port number for each device.
Note that all of the messages listed in this section have argument types included, eg. si or iiii. These are not needed for top-level environments like Max/MSP, SuperCollider, and many others. We included them here to reflect lower-level use with oscsend and oscdump.
messages sent to serialosc server
| message | description |
|---|---|
/serialosc/list si <host> <port> | Request a list of the currently connected devices, sent to host:port |
/serialosc/notify si <host> <port> | Request that next device change (connect/disconnect) is sent to host:port. to keep receiving the notifications, send another message to /serialosc/notify from the notify handler. |
messages received from serialosc server
| message | description |
|---|---|
/serialosc/device ssi <id> <type> <port> | Currently connected device id and type, at this port |
/serialosc/add s <id> | Device added |
/serialosc/remove s <id> | Device removed |
to serialosc device
sys
These messages can be sent to a serialosc device to change settings:
| message | description |
|---|---|
/sys/port i <port> | Change destination port |
/sys/host s <host> | Change destination host |
/sys/prefix s <prefix> | Change message prefix (filtering) |
/sys/rotation i <degrees> | Rotate the grid by degrees, where degrees is one of 0, 90, 180, 270 |
info
Request information (settings) about this device.
/info can take the following arguments:
| message | description |
|---|---|
/sys/info si <host> <port> | Send /sys/info messages to host:port |
/sys/info i <port> | Send to localhost:port |
/sys/info | Send to current destination application’s host:port |
example:
to serialosc:
/sys/info localhost 9999
from serialosc to localhost:9999:
/sys/id m0000045
/sys/size 8 16
/sys/host localhost
/sys/port 23849
/sys/prefix /nubs
/sys/rotation 270
from serialosc
These messages are sent from serialosc to the destination port.
sys
The messages below are sent after a /sys/info request is received:
| message | description |
|---|---|
/sys/port i | Reports destination port |
/sys/host s | Reports destination host |
/sys/id s | Reports device id |
/sys/prefix s | Reports prefix |
/sys/rotation i | Reports grid device rotation |
/sys/size ii | Reports grid device size |
to device
grid
| message | description |
|---|---|
<prefix>/grid/led/set iii <x> <y> <s> | Set led at (x,y) to state s (0 or 1) |
<prefix>/grid/led/all i <s> | Set all leds to state s (0 or 1) |
<prefix>/grid/led/map iiiiiiiiii <x_offset> <y_offset> <s[8]> | Set a quad (8×8, 64 buttons) in a single message |
map
Each number in the map list is a bitmask of the buttons in a row, one number in the list for each row. The message will fail if the list doesn’t have 8 entries plus offsets.
Taken apart:
(<prefix>/grid/led/map) <- the message/route
(8 8) <- the offsets (must be multiples of 8)
(1 2 4 8 16 32 64 128) <- the bitmasks for each row
examples
<prefix>/grid/led/map iiiiiiiiii 0 0 4 4 4 4 8 8 8 8
<prefix>/grid/led/map iiiiiiiiii 0 0 254 253 125 247 239 36 191 4
row
<prefix>/grid/led/row x_offset ii.. <y> <s[..]>
Set a row in a quad in a single message. Offsets must be multiples of 8. Note that offsets for 64-sized grids should always be 0.
Each number in the list is a bitmask of the buttons in a row, one number in the list for each row being updated.
examples (for 256)
<prefix>/grid/led/row iiii 0 0 255 255
<prefix>/grid/led/row iii 8 5 255
examples (for 64)
<prefix>/grid/led/row iii 0 0 232
<prefix>/grid/led/row iii 0 3 129
col
<prefix>/grid/led/col iii[..] <x> <y_offset> <s[..]>
Set a column in a quad in a single message. Offsets must be multiples of 8. Note that offsets for 64-sized grids should always be 0
Each number in the list is a bitmask of the buttons in a column, one number in the list for each row being updated.
examples (for 256)
<prefix>/grid/led/col iiii 0 0 255 255 (updates quads 1 and 3)
<prefix>/grid/led/col iii 13 8 255 (updates quad 4 due to offset)
examples (for 64)
<prefix>/grid/led/col iii 0 0 232
<prefix>/grid/led/col iii 6 0 155
variable brightness
Valid values for <l> below are in the range [0, 15].
January 2011 devices only support four intensity levels (off + 3 brightness levels). The value passed in /level/ messages will be “rounded down” to the lowest available intensity as below:
- [0, 3] - off
- [4, 7] - low intensity
- [8, 11] - medium intensity
- [12, 15] - high intensity
Devices from June 2012 (and after) allow all 16 intensity levels.
<prefix>/grid/led/level/set iii <x> <y> <l>
<prefix>/grid/led/level/all i <l>
<prefix>/grid/led/level/map iii[64] <x_off> <y_off> <l[64]>
<prefix>/grid/led/level/row iii[..] <x_off> <y> <l[..]>
<prefix>/grid/led/level/col iii[..] <x> <y_off> <l[..]>
<prefix>/grid/led/intensity i <l>
tilt
<prefix>/tilt/set ii <n> <s>
Set active state of tilt sensor n to s (0 or 1, 1 = active, 0 = inactive).
arc
Note that LED 0 is north. LED numbers increase clockwise.
| message | description |
|---|---|
<prefix>/ring/set iii <n> <x> <l> | Set LED x (0-63) on encoder n (0-1 or 0-3) to level l (0-15) |
<prefix>/ring/all ii <n> <l> | Set all LEDs on encoder n (0-1 or 0-3) to level l (0-15) |
<prefix>/ring/map ii[64] <n> <l[64]> | Set all LEDs on encoder n (0-1 or 0-3) to 64 member array l[64] |
<prefix>/ring/range iiii <n> <x1> <x2> <l> | Set LEDs on encoder n (0-1 or 0-3) between (inclusive) x1 and x2 to level l (0-15). Direction of set is always clockwise, with wrapping. |
from device
grid
<prefix>/grid/key iii x y s
Key state change at (x,y) to s (0 or 1, 1 = key down, 0 = key up).
tilt
<prefix>/tilt iiii n x y z
Position change on tilt sensor n, integer (8-bit) values (x, y, z).
arc
<prefix>/enc/delta ii n d
Position change on encoder n by value d (signed). Clockwise is positive.
<prefix>/enc/key ii n s
Key state change on encoder n to s (0 or 1, 1 = key down, 0 = key up).