QLC+ - Serial-to-OSC Bridge Plugin

Overview

• This plugins part of the Q Light Controller+ project.
• The purpose of this plugin is to provide a method to control QLC+ widgets using Arduino devices connected by USB.
• This is highly-technical setup, it is assumed the reader is familiar with QLC+, inputs, widgets, and also arduino C programming and a bit of hardware hacking.

Typical Setup

Inner workings

1. An Arduino microcontroller reads physical input (e.g. potentiometers, switches, etc.).
   Example (Arduino C Code):

   void setup()
   {
     Serial.begin(115200);
   }
   void loop()
   {
     int knob = analogRead(A0);
     knob = map(knob, 0, 1023, 0, 255); // map value from Arduino's 0-1023 range to QLC/DMX's 0-255 range.
   }
   		

2. Arduino sends a valid OSC frame to the PC over serial connection (see complete code in the next section):

   void loop()
   {
     int knob = analogRead(A0);
     knob = map(knob, 0, 1023, 0, 255);
   
     // QLC's will auto-detect this OSC input as "/mydevice/knob/1" with the
     // integer value read from the arduino analog pin:
     send_osc_simple_control_int("/mydevice/knob/", 1, knob ) ;
   }
   		

3. After every OSC frame, the Arduino sends a fixed 4-byte marker indicating the end-of-frame.
   This is required due to protocol differences between UDP (which is frame-aware, every datagram is a single frame) and tty/serial devices (which are one continuous stream).
   

   void loop()
   {
     int knob = analogRead(A0);
     knob = map(knob, 0, 1023, 0, 255);
   
     send_osc_simple_control_int("/mydevice/knob/", 1, knob ) ;
     send_osc_bridge_frame_marker();
   }
   		

4. The Arduino can send multiple OSC frames, as long as there's an end-of-frame marker after each one, e.g.:

   void loop()
   {
     while (1) {
       int knob1 = analogRead(A0);
       int knob2 = analogRead(A1);
       int slider1 = analogRead(A2);
       int switch1 = digitalRead(2);
       int switch2 = digitalRead(3);
   
       knob1 = map(knob1, 0, 1023, 0, 255);
       knob2 = map(knob2, 0, 1023, 0, 255);
       slider1 = map(slider1, 0, 1023, 0, 255);
   
       // hardware switches are either on or off, translate them to 0 or 255 for QLC.
       switch1 = (switch1) ? 255 : 0;
       switch2 = (switch2) ? 255 : 0;
   
       send_osc_simple_control_int("/mydevice/knob/", 1, knob1 ) ;
       send_osc_bridge_frame_marker();
   
       send_osc_simple_control_int("/mydevice/knob/", 2, knob2 ) ;
       send_osc_bridge_frame_marker();
   
       send_osc_simple_control_int("/mydevice/slider/", 1, slider1 ) ;
       send_osc_bridge_frame_marker();
   
       send_osc_simple_control_int("/mydevice/switch/", 1, switch1 ) ;
       send_osc_bridge_frame_marker();
   
       send_osc_simple_control_int("/mydevice/switch/", 2, switch2 ) ;
       send_osc_bridge_frame_marker();
   
       delay(10);
     }
   }
   		

5. In QLC's inputs/outputs tab, after setting OSC:127.0.0.1 as universe 1 input, and Serial-OSC-Bridge as universe 2 input, clicking on the "profiles" tab for universe 1 and clicking "add":
   
   
   The above Arduino code will result in the following auto-detected channels:
   
   
6. Then in QLC's Virtual Console, add a new widget and double-click on it to edit the its properties:
   
   
   Click "choose" to select the OSC input (as defined in the "profile", above):
   
   Then select the desired OSC input channel from the list:
   
   The widget will then be controlled by the changing values sent by the arduino:
   

Arduino Code

/*
  Arduino Code Example for the Serial-OSC-Bridge Plugin for QLC+

  Copyright (c) House Gordon Software Company LTD

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0.txt

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
*/

//Uncomment this during debugging, this will result in ASCII OSC frames
//sent over the serial port (viewable in Arduino Studio Serial Monitor)
//but not usable by QLC.
//#define DEBUG_ASCII_COMMUNICATION

#define BAUD_RATE 115200

void send_osc_bridge_frame_marker()
{
#ifndef DEBUG_ASCII_COMMUNICATION
  static const unsigned char frame_marker[4] = {0x89, 0x98, 0x12, 0xAB} ;
  Serial.write(frame_marker, 4);
#endif
}

// "num_sent" is the number of bytes ALREADY sent.
// e.g. if num_sent==11 , this function will send one additional NUL byte
// resulting in a 12 byte message (4-byte aligned in total).
void send_osc_zero_padding(unsigned int num_sent)
{
  // Fall-through here is intentional, similar to https://en.wikipedia.org/wiki/Duff%27s_device .
  // e.g. if the remainder is 1, three NUL bytes will be sent.
  switch (num_sent % 4)
  {
    case 1: Serial.write(0x00);
    /* FALLTHROUGH */
    case 2: Serial.write(0x00);
    /* FALLTHROUGH */
    case 3: Serial.write(0x00);
  }
}

void send_osc_simple_control_int(const String& address_prefix,
                                 int control_number,
                                 unsigned int value)
{
  // Send the OSC Address - no sanity checks on the validity of the address...
  size_t i = Serial.print(address_prefix);
  i += Serial.print(String(control_number));

#ifndef DEBUG_ASCII_COMMUNICATION
  send_osc_zero_padding(i);
#endif

  // Send the OSC type.
  //NOTE: "i/integer" in OSC protocol is a 32-bit integer
  Serial.print(",i");
#ifndef DEBUG_ASCII_COMMUNICATION
  send_osc_zero_padding(2);
#endif

#ifdef DEBUG_ASCII_COMMUNICATION
  Serial.print(",value = ");
  Serial.println(value);
#else
  // Send the value.
  // As AVR arduino 'int' is 16-bit, start with two NUL bytes to pad to 32 bit.
  send_osc_zero_padding(2);
  byte hi = value / 256;
  byte lo = value % 256;
  Serial.write(hi);
  Serial.write(lo);
#endif
}


void setup()
{
  Serial.begin(BAUD_RATE);
  while (!Serial) {
    ; // wait for serial port to connect. Needed for native USB port only
  }

  pinMode(2, INPUT_PULLUP);
  pinMode(3, INPUT_PULLUP);
}

void loop()
{
  int prev_knob1;
  int prev_knob2;
  int prev_slider1;
  int prev_switch1;
  int prev_switch2;

  while (1) {
    int knob1 = analogRead(A0);
    int knob2 = analogRead(A1);
    int slider1 = analogRead(A2);
    int switch1 = digitalRead(2);
    int switch2 = digitalRead(3);

    knob1 = map(knob1, 0, 1023, 0, 255);
    knob2 = map(knob2, 0, 1023, 0, 255);
    slider1 = map(slider1, 0, 1023, 0, 255);

    // hardware switches are either on or off, translate them to 0 or 255 for QLC.
    switch1 = (switch1) ? 255 : 0;
    switch2 = (switch2) ? 255 : 0;

    if (knob1 != prev_knob1) {
      send_osc_simple_control_int("/mydevice/knob/", 1, knob1 ) ;
      send_osc_bridge_frame_marker();
      prev_knob1 = knob1 ;
    }

    if (knob2 != prev_knob2) {
      send_osc_simple_control_int("/mydevice/knob/", 2, knob2 ) ;
      send_osc_bridge_frame_marker();
      prev_knob2 = knob2 ;
    }

    if (slider1 != prev_slider1) {
      send_osc_simple_control_int("/mydevice/slider/", 1, slider1 ) ;
      send_osc_bridge_frame_marker();
      prev_slider1 = slider1 ;
    }

    if (switch1 != prev_switch1) {
      send_osc_simple_control_int("/mydevice/switch/", 1, switch1 ) ;
      send_osc_bridge_frame_marker();
      prev_switch1 = switch1 ;
    }

    if (switch2 != prev_switch2) {
      send_osc_simple_control_int("/mydevice/switch/", 2, switch2 ) ;
      send_osc_bridge_frame_marker();
      prev_switch2 = switch2 ;
    }

    delay(10);
  }
}
	

Configuration

Operation and Troubleshooting

Real World Example