OSC

OpenDeck can expose supported physical I/O over OSC on network-enabled targets. OSC support is intentionally small: OpenDeck sends the current state of configured inputs and accepts simple incoming messages for output levels and state refresh. Higher-level behavior such as scenes, macros, routing, and automation is expected to live in the receiving AV, lighting, industrial, or show-control software.

• Configuration
• Discovery
• Outgoing messages
  • I/O messages
  • Sensor messages
• Incoming messages
• Forced refresh
• Notes and limitations

Configuration

OSC settings are in the Global configuration block. They can be changed in the Web configurator or through SysEx configuration. Sensor-specific OSC outputs are configured in the I2C configuration block.

Setting	Description
Destination 1-4 IPv4 address	Remote IPv4 addresses used for outgoing OSC packets. A destination set to 0.0.0.0 is disabled.
Destination 1-4 port	Remote UDP ports used for outgoing OSC packets. Default is 9000. Valid range is 1-65535.
Listen port	Local UDP port used for incoming OSC packets. Default is 9001. Valid range is 1-65535. Changing this setting restarts the OSC listen socket.
Restrict incoming to destination IP	When enabled, incoming OSC packets are accepted only from configured destination IPv4 addresses.

Outgoing OSC packets are sent to every configured destination. If all destination IPv4 addresses are 0.0.0.0, outgoing OSC packets are disabled.

Once DHCP assigns IP address to the OpenDeck board, a discovery announcement is sent and forced refresh will be performed so the remote side can receive current states for enabled components after boot or network reconnect.

Discovery

OpenDeck supports a simple discovery request:

/opendeck/discover

The message has no arguments. OpenDeck responds with device information on:

/opendeck/device

The device information packet has these arguments:

Argument	Type	Description
0	string	Product name. Currently opendeck.
1	string	OpenDeck target name.
2	string	Firmware version.
3	int32	OSC listen port.
4	string	mDNS host name.
5	string	IPv4 address.

Discovery announcements are sent to every configured OSC destination. Discovery responses are sent back to the sender IP address, but use each configured destination port. For example, if destination ports 9000 and 9100 are configured, a /opendeck/discover request from 192.168.1.50 receives one response on 192.168.1.50:9000 and one response on 192.168.1.50:9100.

OpenDeck also advertises OSC with mDNS/DNS-SD:

Field	Value
Service	_opendeck-osc._udp
TXT	type=osc
Port	Configured OSC listen port, default 9001

Outgoing messages

OpenDeck publishes I/O state using zero-based component indexes.

I/O messages

Address	Argument	Description
/opendeck/switch/<index>	int32	Digital switch state, 0 or 1.
/opendeck/encoder/<index>	int32	Encoder value for encoder modes that have a stored current value.
/opendeck/analog/<index>	float32	Normalized analog value, 0.0 to 1.0.
/opendeck/output/<index>	int32	Output level feedback, 0 to 100 percent.

Touchscreen buttons are published through the same /opendeck/switch/<index> path as physical switches.

Sensor messages

Sensor OSC output is sent only when the corresponding sensor and OSC output settings are enabled.

Address	Argument	Description
/opendeck/sensors/apds9960/proximity	int32	APDS9960 proximity value.
/opendeck/sensors/apds9960/ambient_light	float32	APDS9960 ambient light value normalized to the 0.0-1.0 range.
/opendeck/sensors/apds9960/rgb	float32, float32, float32	APDS9960 red, green, and blue ratios normalized to the 0.0-1.0 range.
/opendeck/sensors/apds9960/gesture	string	APDS9960 gesture value: up, down, left, or right.
/opendeck/sensors/bno085/quaternion	float32, float32, float32, float32	BNO085 quaternion as real, i, j, k.
/opendeck/sensors/bno085/euler	float32, float32, float32	BNO085 Euler angles as yaw, pitch, roll.
/opendeck/sensors/bno085/gyro	float32, float32, float32	BNO085 gyroscope x, y, z.
/opendeck/sensors/bno085/linear_accel	float32, float32, float32	BNO085 linear acceleration x, y, z.
/opendeck/sensors/bno085/gravity	float32, float32, float32	BNO085 gravity x, y, z.
/opendeck/sensors/cap1188/touch/<index>	int32	CAP1188 capacitive touch state, 0 or 1.
/opendeck/sensors/vl53l4cx/distance	int32	Raw VL53L4CX distance in millimeters.
/opendeck/sensors/vl53l4cx/distance_norm	float32	Calibrated VL53L4CX distance normalized to the 0.0-1.0 range.
/opendeck/sensors/vl53l5cx/row/<row>	int32...	VL53L5CX distance row in millimeters. 4x4 mode sends 4 values per row; 8x8 mode sends 8 values per row. Invalid or filtered zones are sent as 0.
/opendeck/sensors/vl53l5cx/nearest	int32, int32, int32, int32	Nearest valid VL53L5CX zone as distance in millimeters, zone index, x index, and y index.
/opendeck/sensors/vl53l5cx/centroid	float32, float32, float32, int32	Centroid of valid VL53L5CX zones as x position, y position, average distance in millimeters, and active zone count.
/opendeck/sensors/vl53l5cx/presence	int32, int32, int32, float32	Compact VL53L5CX presence state as present flag, active zone count, nearest distance in millimeters, and normalized energy.

VL53L5CX coordinates are zero-based after the configured rotation and axis inversion are applied. Presence mode reports whether any valid zone exists inside the configured distance window. With a wide maximum distance, fixed surfaces such as ceilings or walls can count as presence, so set the distance input maximum to exclude background surfaces for installation-style use.

Incoming messages

OpenDeck currently accepts output control and refresh messages.

Address	Argument	Description
/opendeck/output/<index>	int32	Sets output level, 0 to 100 percent. Values below 0 are clamped to 0; values above 100 are clamped to 100.
/opendeck/refresh	none	Requests a forced refresh of current component state.

Incoming packets with malformed OSC data, unsupported addresses, missing arguments, or wrong argument types are ignored. When Restrict incoming to destination IP is enabled, incoming packets are accepted only when the sender IPv4 address matches any configured destination IPv4 address.

Forced refresh

Forced refresh republishes current component state. It is useful after a controller application starts, reconnects, reloads a show file, or loses state.

OpenDeck performs forced refresh automatically:

• when USB MIDI becomes ready
• when the board becomes available on the network
• after preset changes, unless disabled in system settings

It can also be requested explicitly with:

/opendeck/refresh

Notes and limitations

OSC support is not a full configuration or preset-management API. Configuration remains available through the Web configurator and SysEx.

OSC output control always uses levels. On plain digital output hardware, any level above 0 is treated as on by the hardware backend. On PWM-capable output hardware, the level is used as duty percentage.