illucia uses Open Sound Control. illucia's hardware controller sends, receives, and redirects OSC messages (via a program called illuciaConnect). This means illucia hardware can control and connect its own software suite of games and programs, but also any programs that speak OSC.
If you're new to OSC you might think of it as similar to MIDI, but more flexible and with higher resolution. It lets you easily send information within or between computer programs. Whenever this guide describes using illucia to control or connect programs on your computer, it assumes those programs support OSC.
illucia is best when paired with environments like Max, Pure Data, Processing, ChucK, Reaktor, SuperCollider, or programming languages with OSC libraries (most have them). These make it very easy to map illucia's OSC addresses, and give you access to things like LFOs, step sequencers, random generators, conversion to MIDI, and beyond. Having some background with such a program (or eagerness to learn) is strongly recommended.
To get illucia sending OSC messages, simply plug it into your computer via USB and run illuciaConnect software.
illuciaConnect is software that communicates between the illucia controller and your computer.
When you press buttons, flip switches, turn knobs, or connect jacks on the illucia controller, illuciaConnect sends OSC messages. You can then listen for these messages in any other OSC enabled programs.
For example, maybe you want Knob1 on illucia to control a paramater in a music synthesizer. Just tell your music software to listen on the address that illuciaConnect provides for that knob: /dtr/Continuous/1
illuciaConnect also listens for OSC messages: to control the brightness of illucia's LEDs, and for illucia's patchbay. Want to use LED1 on illucia to fade in and out with a software LFO? Have your software send the LFO's output to LED1's illuciaConnect address: /dtr/LED/1
For a list of of illuciaConnect's OSC addresses, and instructions on changing the ports, see the appendix at the end of the guide.
Think of the patchbay as a physical extension of OSC inputs and outputs.
It gives you real world jacks for the input&output addresses of OSC enabled software. This means you can connect and disconnect OSC addresses using cables (which can be a lot more fun, immediate, and performable than mouse pointing and clicking).
illuciaConnect makes the patchbay very easy to use. You can use any jack as an input, or as an output. If you want to use a jack as an output, just send OSC messages to its OutputJack address. If you want to use a jack as an input, listen on its InputJack address in whichever programs you want to control. Done.
For example, if you want to use illucia's Jack1 as an output for a random number generator in MaxMsp, just have Max send OSC messages to that jack's output address: /dtr/OutputJack/1
If you want to use Jack2 as an input that controls a parameter in Reaktor, then have Reaktor listen on the address: /dtr/InputJack/2
Now, if you connect Jack1 to Jack2 with a physical cable, Reaktor will receive the random numbers from MaxMsp. illuciaConnect handles all the message forwarding. You can even stack several cables out of a single OutputJack, and illuciaConnect will forward that output's messages to multiple inputs.
Once you map several inputs and outputs to the patchbay, then things get really interesting - you have a physical space for exploring and performing different connections.
Let's say you have some programs that you want to use with illucia:
The first step is to map your software outputs to illucia's OutputJacks, and your software inputs to InputJacks:
To do this,
How you direct the outputs and inputs will depend on the software you use. Max, Pure Data (free), or OSCulator would be good choices - they let you map OSC messages quickly and easily. Once you have things mapped, you don't have to think about addresses or computers anymore.
Just use cables to physically connect and disconnect jacks, and illuciaConnect will handle all the message forwarding!
Addresses are listed with the symbol '#'
Replace the symbol with the number that corresponds to the control item you want to use.
For example, you'd address the second OutputJack on illucia with the address: /dtr/OutputJack/2
Buttons (#1-4) and Switches (#5-8):
Buttons trigger a 1.0 when pressed and 0.0 when released.
Switches trigger a 1.0 when flipped on and 0.0 when flipped off.
/dtr/Digital/#
Knobs (#1-6)
Sends values between 0.0 and 1.0 when turned.
/dtr/Continuous/#
Input Jacks (#1-16)
If an InputJack is connected to an OutputJack, it will pass along any OSC messages that arrive at the OutputJack. Read the patchbay section for more info.
/dtr/InputJack/#
Jack Connection Indicator (#1-6)
Triggers a 1.0 when that jack gets connected to any other jacks, and a 0.0 when disconnected.
/dtr/JackIsPatched/#
LEDs (#1-4)
Send values between 0.0 (off) and 1.0 (full brightness) to set the brightness of illucia's LEDs. For example, sending 0.5 to /dtr/LED/2 will set the second LED to half brightness.
/dtr/LED/#
OutputJack Jacks (#1-16)
Send OSC messages to OutputJack addresses. It an InputJack is connected to an OutputJack, it will pass along any OSC messages that arrive at the OutputJack. Read the patchbay section for more info.
/dtr/OutputJack/#
illuciaConnect defaults to these ports
If you want to change illucia's ports, you can do it very easily by running illuciaConnect's code in Processing: