-
Notifications
You must be signed in to change notification settings - Fork 69
Configurable features
This section lists all possible configurable features on OpenDeck boards. All features on OpenDeck boards are grouped into several blocks. Each block has one or more sections. Configuration can be done either via SysEx configuration or using Web configuration tool.
This configuration block contains parameters applied globally.
This section allows configuration of several settings related to sending and receiving of MIDI messages. Boolean options are disabled by default.
- Standard note off - When enabled, standard MIDI note off will be sent. If disabled, note off is sent as note on event with velocity 0.
- Running status (DIN MIDI only) - When enabled, MIDI traffic can be reduced. See here for more info. This setting can cause issues on older MIDI gear so it's best to leave it disabled. DIN MIDI state must be enabled in order to use this option.
- DIN to USB thru - When enabled, all incoming traffic from DIN MIDI will be forwarded to USB MIDI out.
- DIN MIDI - When enabled, outgoing MIDI traffic will be sent to DIN MIDI out, and incoming messages will be processed.
- USB to DIN thru - When enabled, all incoming traffic from USB MIDI will be forwarded to DIN MIDI out.
- USB to USB thru - When enabled, all incoming traffic from USB MIDI will be forwarded to USB MIDI out.
- USB to BLE thru - When enabled, all incoming traffic from USB MIDI will be forwarded to BLE MIDI out.
- DIN to DIN thru - When enabled, all incoming traffic from DIN MIDI will be forwarded to DIN MIDI out.
- DIN to BLE thru - When enabled, all incoming traffic from DIN MIDI will be forwarded to BLE MIDI out.
- BLE MIDI - When enabled, outgoing MIDI traffic will be sent via BLE interface, and incoming messages will be processed.
- BLE to DIN thru - When enabled, all incoming traffic from BLE MIDI will be forwarded to DIN MIDI out.
- BLE to USB thru - When enabled, all incoming traffic from BLE MIDI will be forwarded to USB MIDI out.
- BLE to BLE thru - When enabled, all incoming traffic from BLE MIDI will be forwarded to BLE MIDI out.
- Use global MIDI channel - When enabled, specified global MIDI channel will be used for all components. Individual channel settings for components will be ignored.
- Global MIDI channel - Specifies global MIDI channel which will be used for all components if global channel usage is enabled. Accepted values are 1-17. Channel 17 is a special value indicating "omni" channel setting. When channel 17 is set, all outgoing MIDI traffic will be sent on each channel simultaneously (provided that the traffic is a channel message). As an example, switches won't just send a single channel message on specific channel, but they will do so for each channel, that is, 16 messages will be sent. For incoming data, channel 17 is akin to ignoring the channel completely, e.g. outputs will listen to messages on all channels if channel 17 is defined.
- Send MIDI clock on DIN - When enabled, generated MIDI clock traffic will also be sent on DIN MIDI out.
This section allows configuration of OSC on network-enabled targets. See OSC for message paths and usage.
-
Destination 1-4 IPv4 address - Remote IPv4 addresses used for outgoing OSC packets. A destination set to
0.0.0.0is disabled. -
Destination 1-4 port - Remote UDP ports used for outgoing OSC packets. Default is
9000. -
Listen port - Local UDP port used for incoming OSC packets. Default is
9001. - Restrict incoming to destination IP - When enabled, incoming OSC packets are accepted only from configured destination IPv4 addresses.
Network-enabled targets publish an mDNS name. By default, OpenDeck builds this from the opendeck prefix, hardware target name, and serial number. The default name is used if custom one isn't configured, but only in application. In bootloader mode, default name is always used since the bootloader has no access to application configuration. Custom hostnames may contain letters, numbers, and hyphens, and must not start or end with a hyphen.
This section contains the following parameters related to presets:
- Active preset - Currently active preset.
- Preset preservation - Controls whether or not active preset is preserved after the board is reset. Disabled by default (first preset will be always active on start-up).
- Disable forced value refresh after preset change - If disabled, all components will resend their values once the preset is changed. Disabled by default.
- Enable preset change with MIDI Program Change in - When enabled, upon receiving MIDI Program Change message (on any interface and any channel) the board will change the preset to corresponding program change value.
Current firmware supports up to 5 presets. The limit is hardcoded to reduce database memory requirements and RAM usage, especially on smaller boards.
Switches block is used to configure digital switches connected to OpenDeck boards. A switch can be a push button, toggle switch, footswitch, or any other digital input that reports on/off state.
Switches can be configured as momentary or latching. This setting is always respected by OSC messages. For MIDI, it can be overridden by message types that only act on press. When momentary type is set, different MIDI messages are sent when the switch is pressed or released. For example, if note message type is used, note on will be sent with configured velocity on press, and the same note will be sent with velocity 0 on release. When latching type is set, MIDI note on is sent when the switch is pressed, and note off is sent when the switch is pressed again.
The following are supported message types:
- Notes (default setting)
- Notes / Off only - Only note off will be sent. Sent on press only - switch type is ignored.
- Program change - Sent on press only - switch type is ignored.
- Program change, increment - Every press of the switch will increase the value of program for specified channel. Sent on press only - switch type is ignored.
- Program change, decrement - Every press of the switch will decrease the value of program for specified channel. Sent on press only - switch type is ignored.
- Program change offset, increment - Every press of the switch will increase the internal program change offset by the configured switch value. This offset is then applied to configured program for specific switch or encoder, e.g. if switch 0 sends Program Change 0 and offset is 1, the sent value will be 1 instead of configured 0. This option makes it possible to shuffle through entire program range with just few switches. No message is sent - switch type is ignored.
- Program change offset, decrement - Same behaviour as above, only the offset is decremented by the configured switch value.
- CC - Sent on press only - switch type is ignored.
- CC with 0 reset - Same as CC but on release (depending on switch type) CC with value 0 will be sent.
- CC / 0 only - Sends only configured controller number with value 0. Sent on press only - switch type is ignored.
- MMC Play - Sent on press only - switch type is ignored.
- MMC Stop - Sent on press only - switch type is ignored.
- MMC Pause - Sent on press only - switch type is ignored.
- MMC Record - Recording start message will be sent on first press and recording stop message on second. Sent on press only - switch type is ignored.
- Real Time Clock - Sent on press only - switch type is ignored.
- Real Time Start - Sent on press only - switch type is ignored.
- Real Time Continue - Sent on press only - switch type is ignored.
- Real Time Stop - Sent on press only - switch type is ignored.
- Real Time Active Sensing - Sent on press only - switch type is ignored.
- Real Time System Reset - Sent on press only - switch type is ignored.
- Change OpenDeck preset - No MIDI message is being sent. Sent on press only - switch type is ignored.
- None - No MIDI message is being sent.
- Multi Value IncReset Note - Each successive press will send MIDI note with increasing velocity. In this mode, velocity value is treated like step value by which each next sent velocity value is summed. For example, if velocity is set to 32, first sent MIDI note will have velocity 32, then 64, then 96 etc. Once the value reaches 127, next press will start from configured velocity (step) value. Sent on press only - switch type is ignored.
- Multi Value IncDec Note - Similar to Multi Value IncReset Note mode - once the velocity reaches maximum value, next presses will decrement the value until 0 is reached. This is more akin to how the actual multi-position switches behave. Sent on press only - switch type is ignored.
- Multi Value IncReset CC - Same as Multi Value IncReset Note, only CC message is sent instead of Note.
- Multi Value IncDec CC - Same as Multi Value IncDec Note, only CC message is sent instead of Note.
- BPM increment - Increments the internal BPM value by one. No MIDI message is sent - switch type is ignored.
- BPM decrement - Decrements the internal BPM value by one. No MIDI message is sent - switch type is ignored.
- MMC Play/Stop - Sends MMC Play on one press and MMC Stop on the next. Sent on press only - switch type is ignored.
Each switch can have assigned any MIDI ID between 0-127. By default, a switch has same MIDI ID as its index (switch 0 has ID 0, switch 1 has ID 1 etc.). This ID represents different value depending on message type:
- Notes - ID is MIDI note number
- Program change - ID is MIDI program number
- CC - ID is MIDI CC number
- MMC - ID is MMC channel number
- Real Time - ID is ignored
- Change OpenDeck preset - ID is preset being activated when the switch is pressed
Each switch can have assigned any MIDI velocity (for notes) or control value (for CC messages) between 0 and 127 for press (release velocity is always 0 and it isn't configurable). Program change offset increment/decrement modes also use this field as the offset step amount.
Each switch can have assigned any MIDI channel for MIDI messages (1-17). Channel 17 is "omni" channel. If "omni" channel is specified, channel messages will be sent on all channels at once. Default value is channel 1.
This block is used to configure encoders connected to digital inputs on OpenDeck boards.
Enables or disables encoder. All encoders are disabled by default, since enabling single encoder uses two digital inputs.
Reverses the logical encoder direction before the movement is mapped to a MIDI or system action. This swaps increment and decrement behavior as well as any direction-specific values or MIDI IDs. In two-note mode, clockwise normally uses MIDI ID 1 and counterclockwise uses MIDI ID 2; enabling inversion swaps those assignments. Disabled by default.
Disabled by default for all encoders. If enabled, acceleration is used if encoding mode is set to Control Change (both 7 and 14-bit variants), Pitch Bend or 7/14-bit NRPN. Acceleration can be set to the following values:
- Disabled
- Slow
- Medium
- Fast
The following are supported message types:
- 7Fh01h - Sends CC message with value 1 in one direction, and value 127 in other direction.
- 3Fh41h - Sends CC message with value 63 in one direction, and value 65 in other direction.
- Single Note with variable value - Sends single Note message with continuous range (0-127), with positive increments by one in one direction, and negative in other.
- Single Note with repeated value, both directions - Sends single Note message with repeated (fixed) value in both directions.
- Single Note with repeated value in single direction / value 0 in other - Sends single Note message with repeated (fixed) value in one direction and with value 0 in other.
- Two Note with repeated value, both directions - Sends one of two Note messages with a fixed value. Clockwise uses MIDI ID 1 and counterclockwise uses MIDI ID 2. Enabling encoder inversion swaps those assignments.
- Program change - Increments program on current encoder channel in one direction, and decrements it in other direction.
- CC 7-bit - Sends CC message with continuous range (0-127), with positive increments by one in one direction, and negative in other.
- CC 41h01h - Sends CC message with value 1 in one direction, and value 65 in the other.
- CC 14-bit - Also called "High resolution MIDI" in Ableton. Sends CC message with continuous range (0-16383), with positive increments by one in one direction, and negative in other. Sent as two CC messages with second having ID offset of 32 (ie. if CC ID is set to 0, second message will have CC ID set to 32). When used, ID must be set lower than 96, otherwise no data will be sent.
- Pitch bend - Sends Pitch Bend message with continuous range (0-16383), with positive increments by one in one direction, and negative in other.
- NRPN/7-bit - This message type is sent as three CC messages with first two being NRPN number (0-16383) and third one being CC value (0-127), with positive increments by one in one direction, and negative in other.
- NRPN/14-bit - This message type is sent as four CC messages with first two being NRPN number (0-16383) and last two being CC value (0-16383), with positive increments by one in one direction, and negative in other.
- Change OpenDeck preset - switches between OpenDeck presets with positive increments by one in one direction, and negative in other.
- BPM change - Increments or decrements the internal BPM value depending on encoder direction. No MIDI message is sent.
Each encoder can have assigned a MIDI ID between 0-16383. By default, encoder has same MIDI ID as its index (encoder 0 has ID 0, encoder 1 has ID 1 etc.). For 7-bit message types, only the lower 0-127 range is meaningful. Higher values are used by 14-bit modes such as NRPN. For 14-bit CC mode, MIDI ID 1 must still be lower than 96 because the paired second controller uses an offset of 32.
Second MIDI ID used only by the two-note encoder mode. Clockwise uses MIDI ID 1 and counterclockwise uses MIDI ID 2 unless encoder inversion is enabled, in which case the assignments are swapped. It supports the same 0-16383 configuration range.
Each encoder can have assigned any MIDI channel for MIDI messages (1-17). Channel 17 is "omni" channel. If "omni" channel is specified, channel messages will be sent on all channels at once. Default value is channel 1.
When enabled, supported incoming MIDI feedback updates the encoder's cached continuous value. This prevents the next encoder movement from jumping from a stale locally cached value.
The channel used for matching is the global MIDI channel when Use global MIDI channel is enabled; otherwise, the encoder's configured channel is used. If that effective channel is omni, the incoming channel is ignored.
Supported feedback types are:
- CC 7-bit - The encoder must be in continuous CC mode and the incoming CC ID must match MIDI ID 1.
- Pitch bend - The encoder must be in Pitch Bend mode. Pitch Bend has no controller ID, so matching uses only the effective channel.
CC 14-bit and NRPN feedback are not currently supported.
Disabled by default for all encoders.
Default lower limit is 0. Used only for continuous messages.
Default upper limit is 127/16383 (depending on the message type). Used only for continuous messages.
Note value to send when the encoder is configured in one of the fixed value modes.
Analog block is used to configure components connected to analog section on OpenDeck boards.
All analog inputs are disabled by default. Before using any component connected to analog input, input must be enabled first.
Potentiometers connected to OpenDeck boards send CC values 0-127, depending on their position. This setting can invert that range for any analog input. Disabled by default.
The following are supported message types:
- Control change (7-bit) - Sends CC message with control value being 0-127 depending on applied voltage, that is, potentiometer position. This is default option.
- Control change (14-bit) - Also called "High resolution MIDI" in Ableton. Sends CC message with continuous range (0-16383) depending on applied voltage, that is, potentiometer position. Sent as two CC messages with second having ID offset of 32 (i.e., if CC ID is set to 0, second message will have CC ID set to 32). When used, ID must be set to lower than 96, otherwise no data will be sent.
- Note - Sends note message with velocity being 0-127 depending on applied voltage, that is, potentiometer position.
- FSR - Used for FSR sensors. This type sends note message with velocity being applied pressure on FSR (0-127).
- Switch - Acts like a normal switch. When analog input is set to this type, further switch behavior is configured in the switch block after the physical digital switches, i.e., if maximum number of digital switches is 64, and analog input 0 (1 in web configurator) is configured as switch, that switch is configured in the switch block with index 64 (or 65 in web configurator). MIDI-specific analog settings are ignored once this option is enabled.
- NRPN/7-bit - This message type is sent as three CC messages with first two being NRPN number (0-16383) and third one being CC value (0-127).
- NRPN/14-bit - This message type is sent as four CC messages with first two being NRPN number (0-16383) and last two being CC value (0-16383).
- Pitch Bend - Type used to send pitch bend messages with 14-bit range (0-16383).
Each analog input can have assigned a MIDI ID between 0-16383. By default, analog input has same MIDI ID as its index (analog input 0 has ID 0, analog input 1 has ID 1 etc.). For 7-bit message types, only the lower 0-127 range is meaningful. Higher values are used by 14-bit modes such as NRPN. For 14-bit CC mode, MIDI ID must still be lower than 96 because the paired second controller uses an offset of 32.
Default lower limit is 0. When any other lower limit is used, the range gets scaled.
Default upper limit is 127/16383 (depending on the message type). When any other upper limit is used, the range gets scaled.
Each analog input can have assigned any MIDI channel for MIDI messages (1-17). Channel 17 is "omni" channel. If "omni" channel is specified, channel messages will be sent on all channels at once. Default value is channel 1.
Specifies lower offset percentage (0-100) which is used to calculate minimum ADC value upon which MIDI values will be based. Useful for inputs which cannot reach minimum ADC value. If for example, the board has nominal ADC range 0-4095, setting this value to 10 will calculate MIDI values based on 409-4095 range (assuming the upper offset is 0), that is, lower 10% of ADC range will be cut off. Set to 0 by default.
Specifies upper offset percentage (0-100) which is used to calculate maximum ADC value upon which MIDI values will be based. Useful for inputs which cannot reach maximum ADC value. If for example, the board has nominal ADC range 0-4095, setting this value to 10 will calculate MIDI values based on 0-3685 range (assuming the lower offset is 0), that is, upper 10% of ADC range will be cut off. Set to 0 by default.
This block is used to configure digital outputs connected to OpenDeck boards. Outputs are often LEDs, but the same firmware block can also drive other loads such as relays, as long as the board electronics support the connected hardware.
This section is used to configure various global settings related to outputs. Those settings are:
- Start-up animation - Enables or disables start-up animation. If enabled, all outputs will slowly fade in, stay on for 2 seconds, and then slowly fade out when board is powered on. This option is disabled by default. This is mainly useful for LED outputs.
- Pulse via MIDI clock - When this option is enabled, MIDI clock messages are used to sync output pulsing. Once the MIDI clock stops, all outputs stop pulsing as well. When disabled, MIDI clock is ignored and a timer is used to control pulsing.
- Use MIDI Program Change Offset - When enabled, current internal program change offset is added to configured output activation ID if the output control type is Program change. For example, if output is configured to indicate Program 0, current offset is 1, program switches to 1 and this option is enabled, the output will turn on. Useful when using only few outputs to indicate larger program change range.
Sets activation ID (Note, CC number or program value) which will control the output.
Specifies the mode in which outputs are being controlled. See Output control section for more details.
Note velocity or CC value which turns on an output when the selected control type matches one exact MIDI value. This applies to Note and CC control types marked as Single value in the output control page. By default this value is set to 127 for all outputs.
In Multi value Note and CC control types, this setting is ignored. The received MIDI value is scaled into an output level from 0% to 100% instead.
Each output can have assigned any MIDI channel for MIDI messages (1-17). Channel 17 is "omni" channel. If "omni" channel is specified, incoming MIDI channel will be ignored while global MIDI channel usage is disabled. When Use global MIDI channel is enabled, the global channel replaces the output channel completely, including its omni setting. Default value is channel 1.
This block is used to configure supported I2C peripherals connected to OpenDeck boards.
This section is used to configure an I2C display connected to OpenDeck boards.
-
Device info message on startup - If enabled, the display shows the OpenDeck device info screen (
OpenDeck, firmware version, and hardware target name when enough rows are available) during initialization. - Display controller - Specifies controller used on display. Currently only SSD1306 controller is supported.
- Display resolution - Specifies display resolution. Currently supported resolutions are 128x64px and 128x32px.
- MIDI event time - Specifies time in seconds the last MIDI event will stay on the display. If value 0 is set, it will be interpreted as infinite message duration, that is, the last sent/received MIDI message will stay on display until it is replaced.
- Alternate note display - When disabled, MIDI notes will be displayed as numbers (0-127). Otherwise, note/octave notation will be used instead (ie. C#4).
This section is used to configure APDS-9960 proximity, ambient light, RGB, and gesture OSC output.
- Proximity/gesture mode - Selects whether the APDS-9960 proximity OSC output, gesture OSC output, or neither is active.
- Invert left/right gestures - Swaps APDS-9960 left and right gesture OSC output.
- Invert up/down gestures - Swaps APDS-9960 up and down gesture OSC output.
- Ambient light - Enables or disables APDS-9960 ambient light OSC output.
- RGB - Enables or disables APDS-9960 RGB OSC output.
- Proximity gain - Configures proximity gain. Available values are 1x, 2x, 4x, and 8x.
- Ambient/RGB gain - Configures ambient light and RGB gain. Available values are 1x, 4x, 16x, and 64x.
-
Lower proximity value - Raw APDS9960 proximity reading that maps to OSC value
0. -
Upper proximity value - Raw APDS9960 proximity reading that maps to OSC value
255.
This section is used to configure BNO085 IMU OSC output.
- Quaternion - Enables or disables BNO085 quaternion OSC output.
- Euler - Enables or disables BNO085 Euler angle OSC output.
- Gyroscope - Enables or disables BNO085 gyroscope OSC output.
- Linear acceleration - Enables or disables BNO085 linear acceleration OSC output.
- Gravity - Enables or disables BNO085 gravity OSC output.
- Smoothing - Applies application-side smoothing to gyroscope, linear acceleration, and gravity OSC outputs. Quaternion and Euler orientation outputs are not smoothed. Available values are Off, Light, Medium, and Heavy.
All BNO085 outputs are disabled by default and can be enabled individually.
This section is used to configure CAP1188 capacitive touch OSC output.
- Sensitivity - Configures the CAP1188 touch sensitivity preset. Available values are Low, Medium, and High. Higher sensitivity detects lighter touches but can react more easily to noise.
This section is used to configure VL53L4CX distance OSC output.
- Distance mm - Enables or disables raw VL53L4CX distance OSC output in millimeters.
- Distance normalized - Enables or disables calibrated VL53L4CX distance OSC output as normalized floating-point values.
- Smoothing - Applies application-side distance smoothing before OSC values are published. Available values are Off, Light, Medium, and Heavy.
- Tracking area - Configures the active receiver area. Available values are Narrow, Medium, Wide, and Full.
- Distance mode - Configures the ST distance mode. Available values are Medium and Long.
-
Distance normalized input min - VL53L4CX reading in millimeters that maps to normalized OSC value
0. -
Distance normalized input max - VL53L4CX reading in millimeters that maps to normalized OSC value
1.
This section is used to configure VL53L5CX multi-zone distance OSC output.
- Output mode - Selects the active VL53L5CX OSC output. Available values are Disabled, Grid, Nearest, Centroid, and Presence.
- Resolution - Selects the ranging grid resolution. Available values are 8x8 and 4x4. 8x8 provides 64 zones; 4x4 provides 16 zones and allows faster ranging.
- Output rate - Limits how often processed VL53L5CX OSC packets are sent. Available values are Low, Normal, and High.
- Smoothing - Applies application-side smoothing and short invalid-frame hold to reduce jitter. Available values are Off, Light, Medium, and Heavy.
- Distance input min - Lower accepted distance in millimeters. Readings below this value are ignored.
- Distance input max - Upper accepted distance in millimeters. Readings above this value are ignored. In Presence mode, this setting defines the far edge of the interaction volume; lower it if fixed surfaces such as ceilings or walls should not count as presence.
- Rotation - Rotates the output grid before OSC publishing. Available values are 0, 90, 180, and 270 degrees.
- Invert X - Mirrors the output grid on the X axis before OSC publishing.
- Invert Y - Mirrors the output grid on the Y axis before OSC publishing.
Presence mode reports whether any valid zone exists inside the configured distance window, not whether the object is necessarily a person. For room-scale use, set Distance input min high enough to reject near-field noise and Distance input max close enough to exclude background surfaces.
This block is used to configure touchscreen connected to OpenDeck boards.
This section has the following settings:
- Touchscreen enabled - Specifies whether the usage of touchscreen is enabled or disabled.
- Touchscreen model - Specifies touchscreen model/manufacturer. Only Nextion is supported currently.
-
Brightness - Specifies touchscreen brightness. The following values are available:
- 10%
- 25%
- 50%
- 75%
- 80%
- 90%
- 100%
- Initial screen - Specifies the screen index which will be shown once the board is powered on. Changing this setting will also automatically switch to selected screen.
This section is used to specify X position of touchscreen icon on display. Touchscreen resolution should be taken into account here. The current firmware does not perform range check for this value because valid coordinates depend on the configured model and active display resolution.
This section is used to specify Y position of touchscreen icon on display. Touchscreen resolution should be taken into account here. The current firmware does not perform range check for this value because valid coordinates depend on the configured model and active display resolution.
This section is used to specify width of touchscreen icon on display. Touchscreen resolution should be taken into account here. Range is currently 0-1024, but practical values still depend on the configured display resolution.
This section is used to specify height of touchscreen icon on display. Touchscreen resolution should be taken into account here. Range is currently 0-600, but practical values still depend on the configured display resolution.
This section is used to specify screen on which icon in on state is located. Values 0-15 are allowed.
This section is used to specify screen on which icon in off state is located. Values 0-15 are allowed.
This section is used to specify whether the specific touchscreen icon/button can be used to switch to another page on screen.
This section is used to specify page to which specific touchscreen icon/button should switch to if page switching functionality for this icon/button is enabled. Values 0-15 are allowed.
Hardware
- Supported microcontrollers
- Supported components
-
Supported boards
- Adafruit
- Arduino
- Generic
- LILYGO
- Nordic Semiconductor
- Olimex
- PJRC
- Raspberry Pi
- Shantea Controls
- Silicognition
- STMicroelectronics
- Waveshare
- WIZnet
- Recommended components and where to get them
- LED indicators
Configuration and usage
- Configurable features
- Output control
- OSC
- Presets
- Timing and latency
- Configuring touchscreens
- Firmware update via bootloader
Advanced