OCube Max Plugin-40 Commands
The oCube Max plugin responds to the commands listed below, sent to it using a Max message object.
Commands can be sent while the digitizer is in host or standalone mode, with sensor data being output in either mode.
The command format has the general form "<inlet> <command> <value>", where <inlet> is a value between 0 and 8, and where <value> can be a float as well as an integer and is not required for all commands. If the inlet value is 0 it signifies the command applies system-wide, and not only for a specific output. All other values specified for <inlet> refer to the oCube inlet with the same number. Multiple commands can be entered as one message, ie. without commas between each command. The inlet parameter "<inlet>" can be substituted by "<inlet1> - <inlet2>" to specify all inlets from <inlet1> to <inlet2>, which range can be ascending or descending.
If a command has aliases they are listed following the command, in brackets and separated by commas.
Commands that in turn send commands as System Exclusive MIDI messages to the digitizer refer to the firmware command in capitals. More information about the command can be found in the applicable firmware section on this support wiki.
For each command (sent or received) messages are output via the message outlet that provides confirmation or reports an error. These messages can be used for eg. debugging or the sequential timing of communication with the digitizer.
Arguments
oCube takes 4 optional arguments. Arguments are entered after the name "oCube" with spaces between each argument. If no arguments are given, the oCube object will default to 8 inlets (virtual inputs) and the MIDI System Exclusive Device ID will default to 0. The first argument indicates the number of inlets. If the first argument is not in the range [0..8] an error message will be shown in the Max window as well as output via the message outlet. The second argument indicates the MIDI System Exclusive Device ID (which must match the System Exclusive Device ID of a connected digitizer in order to work). If only one argument is provided or if the second argument is less than zero, the System Exclusive Device ID defaults to 0 and an error message will be shown in the Max window as well as output via the message outlet. The third argument (a string with at most 99 characters) can be used to identify messages from the oCube object instance in the Max window. It can be left empty by typing " " (a space with two double quotes). The fourth argument specifies the digitizer firmware (where eg. firmware v7.5 is entered as "75"). If no firmware is specified, oCube will assume default digitizer specs (maximum 8 outputs and System Exclusive Device ID 0) and will try to identify the digitizer upon receipt of the first MIDI byte. See also the version command. If the fourth argument is -1 the oCube object will execute the sync command upon instantiation.
System-wide commands
version (0 version)
Reports the oCube version and, if available, digitizer version in the Max window.
reset (0 reset)
Initializes the oCube data structure as per the init command if the digitizer is in host mode, and sends a RESET command to the digitizer. If the connected digitizer is reset by other software, oCube will re-upload its configuration to the digitizer.
init (0 init)
Initializes the oCube data structure to the default settings as specified below.
System-wide:
- interval: 10 for firmwares greater than 5.1 and smaller than 6.0, greater than 6.2 and smaller than 7.0, or greater than 7.1, and 100 for other firmwares
- mute: 0, ie. off
- id: 0
- digid: 0
Output-specific:
- connect: connect each outlet to the sensor input with the same number
- address: 0
- function: 0, ie. binary (two-state) actuator with voltage input
- method: 0
sync (0 sync)
Retrieves all the configuration information from the digitizer and stores it in the oCube data structure. Use the report command to display the information. If multiple oCube objects are connected to the same digitizer, only one object needs to be sent the sync command to sync all objects to the digitizer.
digid <value> (setdigid <value>, 0 digid <value>)
Sends a SET ID command to the digitizer to set the digitizer's System Exclusive ID to the specified value [0..126]. This command is only useful when connected with digitizers that are serially connected via MIDI cables using the digitizer's MIDI thru function, allowing each digitizer to be identified via the MIDI ports.
id <value> (0 id <value>)
Sets the oCube to respond to and send System Exclusive messages with the System Exclusive ID equal to the specified value [0..126]. This command is only useful when connected with digitizers that are serially connected via MIDI cables using the digitizer's MIDI thru function, allowing each digitizer to be identified via the MIDI ports.
host (0 host, 0 hostmode)
Sends a SET MODE command to the digitizer to set it to host mode.
standalone (0 standalone, 0 standalonemode)
Sends a SET MODE command to the digitizer to set it to standalone mode.
mode <value> (0 mode <value>)
Sends a SET MODE command to the digitizer to set to its mode to the specified value [0..1] (0 is host mode, 1 is standalone mode).
pulse_interval <value> (0 pulse_interval <value>)
Sends an SET OUTPUT PULSE command to the digitizer to set its pulse interval to the specified value [1..16383] in milliseconds.
pulse_width_max <value> (0 pulse_width_max <value>)
Sends an SET OUTPUT PULSE command to the digitizer to set the maximum pulse width to the specified value [1 ..127] in milliseconds.
mute <value> (0 mute <value>)
Sends a SET MUTE command to the digitizer to set its mute status to the specified value [0..1] (0 is off, 1 is on).
report (0 report, print, 0 print)
Reports all the available data stored in the oCube data structure in the Max window.
verbose <value> (0 verbose)
Sets what kind of messages are printed in the Max window, according to the specified value [0..3]:
- 0: no messages
- 1: confirmation messages
- 2: confirmation and error messages
- 3: all messages
help (0 help)
Display the URL of the main page about oCube on this support wiki in the Max window.
thru <value> (0 thru <value>)
Sends a THRU command to the digitizer, if it is a microDig, miniDig or Digitizer, to set the MIDI thru status to the specified value [0..1] (0 is off, 1 is on).
midiout <value> (0 midiout <value>)
Sends a MIDIOUT command to the digitizer, if it is a USB-microDig, to set the MIDI out port status to the specified value [0..1] (0 is off, 1 is on). This command enables the USB-microDig to be used with a USB-microMIDICable.
Output-specific commands
Output-specific commands apply only to the specified inlet and the actuator output it is connected to, if any. Inlets and outputs are numbered starting with 1. The inlet parameter "<inlet>" can be substituted by "<inlet1> - <inlet2>" to specify all inlets from <inlet1> to <inlet2>, which range can be ascending or descending.
<inlet> reset
Initializes the oCube data structure for the specified inlet to the default values.
<inlet> init
Initializes the oCube data structure for the specified inlet to the default values.
<inlet> connect <output> (<inlet> assign <output>)
Connects the specified inlet to specified digitizer actuator output. Just like the inlet parameter "<inlet>" can be substituted by "<inlet1> - <inlet2>" to specify all inlets from <inlet1> to <inlet2>, which range can be ascending or descending, the output parameter "<output>" can be substituted by "<output1> - <output2>" to specify a range of outputs, which can also be ascending or descending. Example: "1 - 4 connect 4 - 1" connects inlets 1 thru 4 to outputs 4 thru 1, ie. inlet 1 is connected to output 4 etc.
<inlet> on
Sends a SET OUTPUT command to the digitizer to enable the actuator output connected to the specified inlet, where enabling means the actuator state corresponding to "1", ie. when applying 5 V to the actuator.
<inlet> off
Sends a SET OUTPUT command to the digitizer to disable the actuator output connected to the specified inlet, where disabling means the actuator state corresponding to "0", ie. when applying 0 V to the actuator.
<inlet> level <value>
Sends a SET OUTPUT command to the digitizer to set the actuator output connected to the specified inlet to the voltage level corresponding to the specified logic level [0..1] (0 is off or 0 V, 1 is on or 5 V).
<inlet> pulse <value>
Sends a SET OUTPUT command to the digitizer to set the actuator output connected to the specified inlet to the pulse generation state corresponding to the specified value [0..1] (0 is off, 1 is on).
<inlet> pulse_width <value>
Sends a SET OUTPUT command to the digitizer to set the actuator output connected to the specified inlet to output repeating pulses with the specified width [1..] ms.
<inlet> level_init <value>
Sends a SET OUTPUT INIT command to the digitizer to set the actuator output connected to the specified inlet to the voltage level corresponding to the specified logic level [0..1] (0 is off or 0 V, 1 is on or 5 V), at power up or upon execution of the init command.
<inlet> pulse_init <value>
Sends a SET OUTPUT INIT command to the digitizer to set the actuator output connected to the specified inlet to the pulse generation state corresponding to the specified value [0..1] (0 is off, 1 is on), at power up or upon execution of the init command.
<inlet> pulse_width_init <value>
Sends a SET OUTPUT INIT command to the digitizer to set the actuator output connected to the specified inlet to output repeating pulses with the specified width [1..] ms, at power up or upon execution of the init command.
<inlet> address <value>
Sends a FUNCTION command to the digitizer to set the I2C address of the digital actuator connected to the actuator output which in turn is connected to the specified inlet, to the specified value [0..127].
<inlet> function <value> (<inlet> func <value>)
Sends a FUNCTION command to the digitizer to set the function number of the digital actuator connected to the actuator output which in turn is connected to the specified inlet, to the specified value [0..127].
<inlet> method <value>
Sends a FUNCTION command to the digitizer to set the method number of the digital actuator connected to the actuator output which in turn is connected to the specified inlet, to the specified value [0..127].
<inlet> binary, feelvibe, seergb <value>
Sends a FUNCTION command to the digitizer to set the I2C address and function number according to the type (as specified by the name of the command) of the digital actuator connected to the actuator output which in turn is connected to the specified inlet, and its method to the specified value [0..127].
