OCube Max Plugin-83 Intro

From I-CubeX Wiki
Revision as of 20:54, 7 June 2023 by Admin (talk | contribs)
Jump to: navigation, search

The oCube Max plugin, or external object, provides a user interface for the control of actuators via an I-CubeX digitizer's outputs, and for the configuration of various settings that apply system-wide or output-specific to the digitizer.

The help patch includes various command examples, a basic getting started patch and various subpatches useful for integration into an interactive media application.


Ocube-830 ocube demo max patch.png Ocube-830 report max console.png


Actuator types

Digitizer outputs can operate binary (ie. two-state) actuators, PWM (pulse width modulated) actuators and I2C actuators.

Digital binary actuators are operated by the application of either 0 or 5 V, which then result in either of the two states of the binary actuator. Analog actuators can also be used but can only be set to two states by the application of either 0 or 5 V.

Digital pulse width modulated (PWM) actuators are operated by the application of a repeating pulse of variable width, a special case of which are servos which are usually operated by applying a repeating pulse with an interval of 20 ms and a width between 1 - 2 ms.

I2C actuators are operated by setting their method which is implemented by an exchange of pulse trains that represent a series of bytes as commands/messages.


Actuator connectors

Digital binary and PWM actuators are connected to a digitizer with actuator outputs using ground (black wire), power (red wire) and the actuator control (white wire) as follows. The WiDig and USB-microDig actuator controls are available at the 4th (top) row of the input/output connector, with ground defined as the bottom row. The (32-input) Digitizer actuator controls are the 5V power supplies for inputs 25 - 32 of the input/output connector. For Wi-microDigs with firmwares 6.300 - 6.330 the actuator controls are at the same positions on the input/output connector as the sensor inputs. Wi-microDigs with firmware 6.400 or higher do not have any actuator outputs.

I2C actuators are connected to a digitizer using four positions of the input/output connector, where ground (bottom or 1st row) is the black wire, power (3rd row) is the red wire, the SCL signal (2nd row) is the white wire, the SDA signal (4th or top row) is the grey wire. WiDigs and recent USB-microDigs require the four positions to be in one column of the input/output connector, whereas older USB-microDigs and the Wi-microDig require the SDA signal (grey wire) to be placed in a separate column to the right (when facing the plug's pins with the ground pin at the bottom) of the SCL wire in the same row as the SCL signal. The 32-input Digitizer is not I2C capable.


Actuator states

For a digital binary actuator "on" means the state corresponding to logic level "1", ie. when applying 5 V, and "off" means the state corresponding to logic level "0", ie. when applying 0 V.

For an I2C actuator "on" and "off" mean the states that result from specific pulse trains that represent a series of bytes which the actuator interprets as "on" or "off" commands.

The "on" and "off" definitions do not apply to digital PWM actuators.


oCube ins and outs

The oCube has a control inlet and status outlet for each actuator. Each control inlet is connected (assigned) to an actuator output of the digitizer, and commands refer to the control inlet, ie. not the actuator output. The oCube can be configured to have 1 - 8 control inlet / status outlet pairs. By default the oCube is instantiated with 8 such pairs, and each control inlet is connected to the actuator output with the same number. Commands can be sent to the oCube as list messages only to the first inlet, whereas number (int or float) messages can be sent to any of the control inlets.

The status outlets are emulated, and their timing may not be accurate sub-millisecond or when outputting pulses with durations in the order of a few milliseconds, nor are the outlets accurately synchronized to the digitizer's actuator outputs. Use an oscilloscope or logic analyzer to obtain more reliable information about the digitizer's actuator output timing.

The oCube has a separate inlet to receive MIDI bytes and a separate outlet to output MIDI bytes. The oCube has a separate outlet for confirmation and error messages.