Q Light Controller+ on the Raspberry Pi User guide Document revision: 1.5 The Raspberry Pi name and logo are property of the Raspberry Pi Foundation (http://www.raspberrypi.org/) 1 Table of contents 1 Introduction.....................................................................................................3 2 Features...........................................................................................................3 3 Download & install on a SD card.....................................................................4 4 Raspberry Pi connections................................................................................5 5 Booting and remote access.............................................................................7 5.1 Web interface...............................................................................................7 5.1.1 QLC+ Virtual Console................................................................................8 5.1.2 QLC+ Simple Desk.....................................................................................8 5.1.3 QLC+ Confguration...................................................................................8 5.1.4 Raspberry Pi System Confguration...........................................................9 5.2 Direct access..............................................................................................10 5.3 SSH access.................................................................................................10 6 Date and time................................................................................................11 7 Locales...........................................................................................................11 8 Overscan.......................................................................................................11 9 Displays and touchscreens............................................................................12 9.1 HDMI displays.............................................................................................12 9.2 VGA Displays..............................................................................................12 9.3 SPI Displays................................................................................................13 9.4 Touchscreens..............................................................................................14 10 Manual installation......................................................................................16 11 Frequently Asked Questions........................................................................17 1 Introduction Welcome to the QLC+ on the Raspberry Pi user guide ! A Raspberry Pi runs a Linux operating system, so please don't expect to fnd all the tools and windows of a desktop system like Windows or OSX. Also, please keep in mind that a Raspberry Pi cannot replace a PC, especially when it comes to designing a light show. This document is not meant to teach you how to use Linux. There's plenty of information about that on the internet, as well as specifc information on how to setup and tweak a Raspberry Pi Linux system. So please, before asking non QLC+ related questions, submit them to Google and not to the QLC+ forum. 2 Features QLC+ on Raspberry Pi is an optimized version that tries to get the best out of a limited device while keeping the whole set of functionalities ofered on the desktop version. Let's go directly into the techy details to let you understand what kind of gear is powering QLC+: • A Linux system based on Debian Jessie, with a 4.4 kernel and optimized for the ARM platform • Supports every Raspberry Pi model Around 800MB of free RAM memory when QLC+ is running. • Extremely tiny software image that fts into a SD card with a size of just 1GB and still leaves around 200MB of free space • Powered by Qt 5.6.2 directly running on OpenGL for fast 2D rendering of the User Interface. Xorg is not present in the image. • All the QLC+ plugins are available in this version, including OLA, UART, GPIO and a SPI plugin to natively control RGB LED Panels • Boots in about 12 seconds on a RPi3 (15s on Pi2, 25s on Pi Zero and 30s on Pi1). They start automatically in operate mode and with web access activated. It is possible to defne a project to be loaded and started at boot time. 3 Download & install on a SD card Starting to play with QLC+ on your Raspberry Pi requires a couple of quick and easy steps. 1. Download the software image from the URL provided via email. You need to use a download manager supporting fle transfer resuming, like the Chrome's C hrono Download Manager extension, jDownloader or simply the 'wget' command. 2. Once you have downloaded the software, you will notice that it is compressed into a 7z archive, to save you time and space. The 7z format is extremely space-saving but it requires an additional tool to be extracted. Here's how to obtain it for diferent platforms: ◦ Windows: The ofcial tool can be downloaded from here: http://www.7-zip.org/ ◦ Mac OSX: An unofcial tool can be downloaded from here: https://www.macupdate.com/app/mac/19139/ez7z ◦ Linux: depending on your distribution, you might fnd a 7z extractor already installed. On Ubuntu you need p7zip (sudo  apt­get install p7zip­full). Once installed, it should already be integrated with Ark, Nautilus, Gnome Archive Manager, and so on. Just double click the fle if unsure. Once extracted, you should obtain a fle with a name like this: qlcplus_raspbian_jessie_20160424.img 3. To copy the .img fle on your SD card, you obviously need a SD card at least 1GB big. Please keep in mind that this operation will fully erase your SD card, so backup your data frst if there is any ! On Windows and OSX you need additional tools to write the software on the SD card. In Linux you should already have everything you need. Here's an extensive guide to help you through this operation. Please follow the chapter named "Flashing the SD card using ...” for your operating system. http://elinux.org/RPi_Easy_SD_Card_Setup Please be very careful in doing this operation as you can loose important data of your computer ! 4 Raspberry Pi connections Depending on your needs, the Raspberry Pi itself might not be enough to control your lights. • [USB] If you're going to use USB devices, such as DMX adapters or MIDI- USB controllers, there shouldn’t be problems with RPi 2 and 3, just choose wisely the power adapter you're going to use. Depending on the needs, 5V/1,5A or 5V/2A should be OK. If your USB device is power demanding, it is then suggested to connect a powered USB HUB that can be found for a few $/€ on Amazon or eBay. • [HDMI] If you're going to use QLC+ like on your PC, then you will need all the above plus a TV set, connected to the HDMI connector (or the analog one if present) Please, don't expect to have the same performances of a PC, as the Raspberry Pi is not a PC. • [Ethernet] If you're going to use the ArtNet, E1.31 or OSC plugins, then you just need to plug an ethernet cable to your Raspberry and make sure a DHCP server (usually present in traditional routers) assigns a valid IP address to it. You can also use static IP addresses, for example if your hosts are connected just with an ethernet hub or directly with a cross cable. • [WiFi] WiFi connection is possible through USB dongles. Additional tweaks are needed to make them work. In general, here's a list of verifed devices that are known to be working with the Raspberry Pi: http://elinux.org/RPi_USB_Wi-Fi_Adapters http://elinux.org/RPi_VerifedPeripherals The 3 chipsets known to be working OK on the Raspberry Pi are: Broadcom BCM43143, Realtek 8188 and Ralink 3070 Raspberry Pi 3, instead, has an onboard WiFi module already active and ready to use at boot time. • [SPI] If you're going to connect some LED strips or a RGB panel on the SPI port, then you need to have a custom cable that you can't fnd on the market. Usually it's very easy to solder it, but it all depends on how the signals are mapped on your strips. The Raspberry PINs used to control a SPI device are mapped as in picture A. Basically you need to use PINs 19, 21, 23 and 25. At the moment, the QLC+ SPI plugin doesn't control CE (Chip Enable) signals. • [GPIO] If you're going to use the GPIO plugin, please be aware that not all the RPi IO PINs can be used as GPIO. Refer to picture A to understand the correct numbers you should confgure in the QLC+ GPIO plugin. Note also that since GPIO numbering starts from 0 and QLC+ DMX channels start from 1, there is a +1 delta you need to remember. For example GPIO.18 will control DMX channel 19. It should be possible to have more GPIO available by unloading the SPI and I²C kernel modules but for now this is out of the scope of this guide. Picture A 40 PIN IO RPi 1 model B+, RPi 2 and 3 Name Pin # Name 3.3V 1 2 5V I²C SDA.1 3 4 5V I²C SCL.1 5 6 GND 1-Wire 7 8 UART Tx GND 9 10 UART Rx GPIO.17 11 12 GPIO.18 GPIO.27 13 14 GND GPIO.22 15 16 GPIO.23 3.3V 17 18 GPIO.24 SPI MOSI 19 20 GND SPI MISO 21 22 GPIO.25 SPI SCLK 23 24 SPI CE0 GND 25 26 SPI CE1 I²C SDA.0 27 27 I²C SCL.0 GPIO.5 29 30 GND GPIO.6 31 32 GPIO.12 GPIO.13 33 34 GND GPIO.19 35 36 GPIO.16 GPIO.26 37 38 GPIO.20 GND 39 40 GPIO.21 • [UART] If you purchased a BitWizard DMX interface, be aware that by design the hardware is confgured for DMX Input. To switch it to output mode you need to add the following lines to the fle /etc/init.d/qlcplus, right before the line starting with QLCPLUS_OPTS=”...”: echo 18 > /sys/class/gpio/export echo out > /sys/class/gpio/gpio18/direction echo 1 > /sys/class/gpio/gpio18/value Those 3 commands will actually raise GPIO 18 and the BitWizard interface will start emitting DMX signal. Raspberry Pi 3 Note: add also the following to the config.txt fle: dtoverlay=pi3-disable-bt 5 Booting and remote access Before booting your Raspberry Pi, make sure the following requirements are met: • SD Card with QLC+ software is correctly inserted in the Pi SD card slot • Micro USB power plug is frmly plugged to the Pi • If you're using network plugins, make sure the Ethernet cable is correctly plugged in and the Pi can reach the target devices. If you're using a wireless network, make sure your USB WiFi dongle is plugged in and powered with enough current • If you're using USB adapters, make sure they're correctly plugged to a powered USB HUB, providing enough current to make them work • if you're using a SPI connection, make sure the cable is plugged to the right Pi PINs as described above Once all the preliminary checks are done, you are ready to turn your Raspberry Pi on. After around 15 seconds, you will be able to reach it on the network. By default, the QLC+ Raspberry software is confgured to receive an IP from a DHCP server. If the network cable is not connected, the boot sequence might be slow, and in this case it is suggested to use a static IP address. Hint: In general, to know which IP address your Raspberry is using, just connect a mouse and a TV to it and when QLC+ is started, go to the Input/Output panel and see which output the ArtNet and the E1.31 plugins are displaying. Otherwise, just quit QLC+ and the current IP address should be displayed at the end of the boot messages. There are three ways to access the device: Web interface, direct access or SSH. 5.1 Web interface By default, the QLC+ Raspberry software starts up with a web interface enabled. It can be accessed from any modern web browser running on any device, such as a computer, a tablet or a smartphone. Your browser need to support the web sockets technology to communicate with QLC+. To access the QLC+ web interface simply connect to this address: http://<IP address>:9999 Where <IP address> is the Raspberry Pi address. For example http://192.168.0 . 100 :9999 The web interface allows you to remotely control QLC+ and the Raspberry Pi system without the need to connect a TV set, thus making the system light and portable. On a Raspberry Pi, the web interface consists in three pages: • QLC+ Virtual Console • QLC+ Confguration • Raspberry Pi System Confguration 5.1.1 QLC+ Virtual Console This page is displayed by default when accessing the web interface address and it represents the QLC+ Virtual Console. If a project is loaded, this page will display the widgets previously created with QLC+, otherwise it will be just an empty page. It is possible to load a project with the “Load project” button placed on the top left corner of the page. A window will show up, allowing you to choose a fle from the device you're using to control the Raspberry Pi. The project fle will be transferred via web and loaded by QLC+ already in operate mode, thus ready to be used immediately. To access the QLC+ confguration page, just click on the “Confguration” button. 5.1.2 QLC+ Simple Desk Like in the QLC+ desktop version, the web interface exposes a simple desk page to quickly control single channels. This can be particularly useful when checking the DMX mapping of each fxture. Please note that the web Simple Desk is not as powerful as the desktop version. It is just a simplifed tool to help users in some circumstances. 5.1.3 QLC+ Confguration This page allows to remotely set the QLC+ confguration, divided in three areas: • Universes confguration: Allows to set the inputs, outputs, feedback, profles and passthrough mode for each QLC+ universe. This is basically the same functionality of the QLC+ input/output panel. Since a QLC+ project contains also the I/O information, most likely you won't have to manually confgure it on this page, but just check if everything is correct. • Audio confguration: Allows to select the audio devices used for audio playback or audio input. • User loaded fxtures: Allows to remotely load a custom fxture to QLC+. When clicking on the “Load fxture” button, a window will show up, allowing you to choose a fle from the device you're using to control the Raspberry Pi. The fxture fle will be transferred via web and loaded by QLC+. When adding new custom fxtures it is recommended to reload a project or either reboot the Raspberry Pi Once the confguration has been set, it is possible to go back to the web interface main page by clicking on the “Back” button, placed at the top left corner of the page. When clicking on the “System” button, instead, it is possible to access the Raspberry Pi system confguration page. 5.1.4 Raspberry Pi System Confguration This page has been specifcally designed for the Raspberry Pi and it's not present on the desktop version of QLC+. Here it is possible to do the following operations: • Network confguration: A list of the available network interfaces will be displayed here, showing how they are currently confgured. It is possible to confgure wired and wireless interfaces by setting automatic or manual IP address, subnet mask and default gateway. In case of wireless networking, it is also possible to set the Access Point name (SSID) and the access password. WPA-PSK is the only supported method. When done, click on the “Apply changes” button. A popup message will inform you that the changes will take efect at the next boot. • Project autostart: Here it is possible to set the currently loaded project to automatically start up when QLC+ starts. This functionality, in conjunction with the QLC+ “Function autostart” feature, will turn your Raspberry Pi into a completely standalone device. For example if you set a Chaser to play in loop mode, you can have a 24/7 light show very easily. When done, click on the “Apply changes” button. A popup message will inform you that the changes will take efect at the next boot. Once changes are applied, the currently loaded project will be copied into a fle in the /root/.qlcplus folder called “autostart.qxw”. At the next boot, QLC+ will detect the presence of the fle and will load it automatically. • Reboot: this button simply reboots the Raspberry Pi • Shutdown: this button initiate the shutdown sequence The “Back” button places at the top left corner of the page will lead you back to the Virtual Console page. 5.2 Direct access If you connect a TV to your Raspberry Pi through an HDMI or analog cable, you will notice that QLC+ is running in fullscreen, with the whole UI as in the desktop version. If you have a mouse and a keyboard plugged in, you can control QLC+ like the desktop version, but with limited performances due to the reduced CPU power. You can either purchase some HDMI+Touchscreen solutions available on the market to control the Virtual Console just with your fngers. It is not suggested to do project editing directly on the Raspberry Pi, but just live control. To gain control of the Raspberry Pi Linux system while QLC+ is running, just click on the exit icon in the main view toolbar or hit the keys CTRL+F12 (to exit from operate mode) and then CTRL+ALT+Backspace to obtain a shell access. From there login as “pi” with password “raspberry”. 5.3 SSH access This type of connection is for expert users. You don't need to worry about this if you don't need to manually make changes to the QLC+ Raspberry software. The ssh terminal command is normally present in Linux and OSX, while on Windows you will need an extra tool like PuTTY: http://www.putty.org/ The SSH access is possible with the 'root' user like this: ssh