A fast, modular MQTT-based signalling & display solution for Web Radio Stations using IDJC.
Or just to make your smart home even smarter.

• Table of Contents
• Main features
• Currently available modules
• Getting Started
  • Make a plan (or sketch)
  • Prerequisites
  • Installing
    • StudioDisplay software
    • Weather Underground key and weather source
• Testing StudioDisplay
  • Start all modules
  • Check for errors
  • Check StudioDisplay fullscreen mode
  • Perform signalling test
  • Test with IDJC
• Next steps
  • Check out the documentation!
  • Install on a Raspberry Pi 3B/3B+
  • Install the IDJC monitor (on your broadcasting machine)
  • Install the SignalBox
  • Install extra SignalPis and UnicornLights
  • Fine-tuning
    • Change »Streaming/On Air« to »On Air/Mic live«
    • Switch languages, locales and measurement units
    • Add a simple studio webcam (MJPEG stream)
• Using git to get and update StudioDisplay
  • First install
  • Normal update
  • Destructive update (overwrite your changes with latest version)
• Tested with …
• Versioning
• Translation
• Author
• License
• Credits

• Runs on Linux (all modules except SignalPi and UnicornLight may even run on Windows).
• Perfect working integration with IDJC, the Internet DJ Console (others planned).
• Standard components (MQTT, Python, Javascript, HTML5/CSS3, USB, IOWarrior, 24VDC signal towers, …).
• Studio Wall Clock.
• Weather (incl. 3-day forecast) from Weather Underground (requires free developer key or better).
• Astronomy data (sunrise/sunset, moonrise/-set/phase etc.).
• Beautiful background images and text color change automatically during the day.
• Up to two 24VDC signal towers (max. 5 + 3 lamp units) using separate SignalBox hardware.
• 2 separate 120/230VAC outputs on SignalBox hardware (for »On Air« light outside studio, etc.).
• Live stream metadata.
• Adjustable silence detection (currently uses silentJACK).
• 2 talk timers (general plus announcement overtime).
• Mutes studio monitor speakers when microphone(s) open.
• Call monitor for request lines (for AVM Fritz!Box routers, others planned).
• KODI support (shows information, pauses/timeshifts playback when on phone or microphone open).
• Less than 10W when running on a Raspberry Pi (plus monitor and signals).
• Fully customizable using configuration files.
• Nearly all parameters can be changed on-the-fly, using simple MQTT messages.
• Fully translatable into any language using Unicode translation files.
• Compatible with the smarthome architecture proposed in mqtt-smarthome.
• Can easily be integrated into existing MQTT-based smarthome solutions, i.e. other brokers, FHEM, openHAB or Home Assistant.
• You can have as many StudioDisplays, SignalPis, SignalBoxes, and studios as you want, maybe for different studios or just showing different locations & weather data. All can run on one single MQTT broker.
• Most modules can be used separately (i.e., you might need weather data, astronomy data or a call monitor for your smart home, without running a radio station).

• StudioDisplay: Shows it all on the big screen (Raspberry Pi 3B/3B+ required, Blinkt module recommended).
• mqtt-weather-wunderground: Weather data provider, includes 3-day forecast (free Wunderground API key required). Now defunct, see #4.
• mqtt-weather-metno: Weather data from the Norwegian Meteorological Institute. Not yet complete (forecast missing).
• mqtt-astronomy: Sunrise, sunset, moonrise, moonset, moon phase and phases of the day. Can be used to control ambient lighting and anything dependent on the phase of the day.
• mqtt-callmonitor-fritz: Call monitor for AVM Fritz!Box routers, can also notify/control a KODI/LibreELEC media player.
• mqtt-radio: Live radio stream metadata display.
• mqtt-idjc: Monitor for IDJC (Internet DJ Console), provides studio signalling.
• mqtt-signalbox (SignalBox): Interface to professional signal towers & »On Air« door light (SignalBox or IOWarrior relais card required).
• mqtt-signalpi (SignalPi): The »poor man’s signal tower« (typically used on a Raspberry Pi Zero W, Blinkt module required).
• mqtt-unicornlight (UnicornLight): Experimental mini »ambient light« (Raspberry Pi Zero W or better and Unicorn pHAT or Unicorn HAT required).

These instructions will get you a copy of the project up and running on your local IDJC machine for development and testing purposes. See Next Steps for notes on how to deploy the project on a live system.

Making a little plan (or just a sketch) before you start is helpful. It should show …

• which MQTT broker to use (this might be an existing one, like on a Synology NAS, or the StudioDisplay Pi),
• how many devices of each type you want (i.e., more than one display, more than one SignalPi/SignalBox),
• what the machine’s hostnames are (we recommend self-explanatory names with sequential numbering, like »studio1«, »studiodisplay1«, »studiodisplay2« and so forth).

For starters, consult docs/architecture.md which has a nice overview.

You need:

• A Linux-based system (your IDJC machine is one). We assume here that you use some Debian-derivative (like Debian, Ubuntu, Linux Mint, Raspbian) but it will also work on other Linux distros. You only have to substitute different commands for your package management (like with Arch Linux or Manjaro, for instance).

  For installation hints on non-Debian-based Linuxes, see docs/install-non-debian.md.

• Python 2 and Python 3 with pip and pip3 installed. These might already be installed in your distro. If not, do a

  sudo apt-get update
  sudo apt-get install python3 python-pip python3-pip

• A working MQTT broker within in your local network. We recommend Eclipse Mosquitto which is lightweight and easy to install. You can install it on your local machine as follows:

  sudo apt-get install mosquitto mosquitto-clients

  Then create the simplest possible configuration for it, using nano (or another editor):

  sudo nano /etc/mosquitto/conf.d/`hostname`.conf

  and enter the following into it:

  # default listener
  port 1883
  
  # websockets listener
  listener 9001
  protocol websockets
  

  You can now save the file (Ctrl+O) and exit nano (Ctrl+X).

  Restart the mosquitto service so that it will work with the new configuration:

  sudo service mosquitto restart

• Install the Python MQTT client software:

  sudo pip install paho-mqtt
  sudo pip3 install paho-mqtt

Copy or git clone the software to your home folder on the Pi, into a folder named studiodisplay.

Example:

cd
git clone https://github.com/Moonbase59/studiodisplay.git
cd studiodisplay

Make the Python modules in ~/studiodisplay/python executable:

cd ~/studiodisplay/python/
chmod +x mqtt-*.py
chmod +x signaltest.py

You must have a configuration file set up in ~/studiodisplay/config/ that corresponds with your chosen hostname, i.e. studio1.

For starters, just copy and edit the example configuration file:

cd ~/studiodisplay/config/
cp example.cfg `hostname`.cfg

You can edit this file with nano, a very minimalistic commandline editor:

nano `hostname`.cfg

Read the comments within the file and make any changes as neccessary.

Changes are written with Ctrl+O and then pressing Enter. Exit nano with Ctrl+X.

UPDATE: Please read issue #4

Get your own Weather Underground API key. A developer key for up to 500 requests/day and max. 10/minute can be had for free. If you need more frequent updates than once per 15 minutes, or use StudioDisplay commercially, you might investigate into their other options.

Get the Wunderground Station ID of a reliable weather station near you. Check out their Wundermap.

Enter the API key and the weather station ID you found in your StudioDisplay configuration file, within the [weather-wunderground] section:

cd ~/studiodisplay/config/
nano `hostname`.cfg

[weather-wunderground]
…
wu_api_key = 0000000000000000
…
pws = IHAMBURG2112

Save and exit as usual with Ctrl+O, Enter, Ctrl+X.

With the example above, you will not yet have a SignalBox connected (for the signal towers and door light), nor will you have the SignalPi and/or UnicornLight modules running (these require a Raspberry Pi). Nevertheless, you’ll have a running StudioDisplay system that you can test locally (IDJC signalling, weather, web server, StudioDisplay web page, etc.).

For testing, we have included simple shell scripts that start and stop all modules within separate terminals (so you can see the debug messages):

cd ~/studiodisplay/
./startall.sh

This should (depending on your Linux distro, adapt as neccessary) fire up some terminals and start the Python modules, a simple Python webserver (running on port 8082) and Firefox, displaying the StudioDisplay web page.

Study each terminal’s output closely, just in case some modules are missing or errors occur (you must enable the Fritz!Box callmonitor by dialling #96*5* from a local phone first, specify a valid stream address for your radio station in the config file, and so forth).

When all looks good, watch StudioDisplay in fullscreen mode by pressing F11 in the browser. Remember, it is optimized to run on a 16:9 screen, so you probably won’t see everything otherwise.

You can now open another terminal and execute the signalling test:

cd ~/studiodisplay/python/
./signaltest.py

Your screen should follow the signals displayed.

Open IDJC and test out various functions, like

• start/stop streaming
• open/close microphone(s)
• stream silence
• check what happens when a song/playlist ends
• test that speakers are muted when a mic goes live

StudioDisplay can do much more than you suspect after the first tests. To exploit its full potential and make it a real-world, robust and reliable solution fitted to your needs, refer to the documentation in the docs folder.

• Read about the architecture.
• Check out the topic structure ([Freeplane document](docs/StudioStatus\ Topic\ Structure.mm)/[PDF](docs/StudioStatus\ Topic\ Structure.pdf)).
• Read about translations and how you can help.
• Find much more detailed installation and testing instructions in docs/install-raspberry-pi.md.

We really recommend installing the main parts of the software on a Raspberry Pi 3B or 3B+. It can run the MQTT broker, the web server and most of the other modules (except the IDJC monitor which you’ll use on your IDJC machine).

Comprehensive and detailed instructions are in docs/install-raspberry-pi.md.

Instructions are in docs/install-idjc.md.

Further instructions are in docs/install-signalbox.md.

The SignalBox is a USB-connected ready-made box to drive professional 24VDC signal towers, like WERMA, Patlite, Eaton, Allen Bradley, SIEMENS, Rittal, Pfannenberg. It features a 230VAC mains connection, a built-in 24VDC/1.5A power supply, two M12 (A-coded) industry-standard sockets for connection to the signal towers (max. 5/max. 3 lamp units, respectively) and two 230VAC/10A mains outlets (type CEE 7/4 »Schuko«), one for an external »On Air« doorlight and one for free use (switchable via MQTT command). The well-known IOWarrior24 chip is used to control the box, so it can easily be interfaced on Linux, MacOS and Windows systems.

These are your options:

• Get a pre-built box (contact me): Ideal for beginners or professional studios. No building, just buy, connect signal tower and forget. Please specify needed cable length(s) from SignalBox to the signal tower(s).
• Use existing compatible relais boards and build your own signal tower interface: Intermediate, some assembly required, but no hassle with software or drivers.
• Study and modify the code and build your own IOWarrior24-based interface: The hard way, for real enthusiasts. You should know what you do and not be afraid of bits and bytes and driver stuff.

These are usually run on Raspberry Pi Zero W’s and require a Blinkt, UnicornHAT (8x8 LEDs) or UnicornpHAT (4x8 LEDs) module. The Pi should have a clean Raspbian Lite (Stretch) installed before you start.

Instructions are in docs/install-signalpi.md and docs/install-unicornlight.md.

Some users asked me if they could have »Streaming« (yellow) changed to »On Air« and »On Air« (red) changed to »Mic live«. If you are more more happy with that, it’s very easy to change in the translation files, for example for the »en-US« locale, you would change the file ~/studiodisplay/config/lang-en-US.json from

"Ready": "Ready",
"Streaming": "Streaming",
"On Air": "On Air",
"Caller": "Caller",

"On Air, pausing": "On Air, pausing",
"Off Air, resuming": "Off Air, resuming",

to

"Ready": "Ready",
"Streaming": "On Air",
"On Air": "Mic live",
"Caller": "Caller",

"On Air, pausing": "Mic live, pausing",
"Off Air, resuming": "Mics closed, resuming",

Then reload your StudioDisplay and/or connected browsers and you’re set!

StudioDisplay is completely localizable and can even display the correct time and date formats for the selected locale. We currently include de-DE, en-GB and en-US, but need help for further languages—see Translation.

Let’s assume we have installed StudioDisplay in German (m, °C, hPa, km/h) and now wish to switch to American English (ft, °F, mbar, mph).

Log in to your StudioDisplay system (studiodisplay1 in our example):

ssh pi@studiodisplay1

Now find the configuration file and switch the locale from de-DE to en-US:

nano ~/studiodisplay/config/studiodisplay1.cfg

Find the locale = entries and change from:

locale = de-DE

to:

locale = en-US

Save and exit.

Now we need to reload the displays. This can easily be accomplished via MQTT:

mosquitto_pub -h studiodisplay1 -t studiodisplay/all/command/reload -n

All connected displays (and browsers) should now reload and display the page in the US-American locale. Watch how the measurement units change from meters, degrees Celsius, hectopascals and kilometers/hour to feet, degrees Fahrenheit, millibars and miles/hour. See the date change from »Dienstag, 29.05.2018« to »Tuesday, 05/29/2018« (and sunrise/sunset times from military to AM/PM time).

You say you still prefer pressure in inches mercury over the official millibars? Nothing easier than that:

Open the en-US language file and change to your preferred unit and number of decimal places:

nano ~/studiodisplay/config/lang-en-US.json

Find the following:

".pressure": "mbar",
".pressure_text": "mbar",
".pressure_decimals": "0",

and change to:

".pressure": "inHg",
".pressure_text": "inHg",
".pressure_decimals": "1",

Save and exit as usual.

Again, we need to reload the displays:

mosquitto_pub -h studiodisplay1 -t studiodisplay/all/command/reload -n

(On a normal browser, you can also use F5 or Ctrl+F5.)

Et voilà!

Using Calin Crisan’s streamEye and a Raspberry Pi camera module, you could even provide a live MJPEG camera stream showing what’s going on in your studio. The Raspberry Pi 3B/3B+ you used for StudioDisplay should be able to handle this extra load.

Copy the file raspimjpeg.py from streamEye’s extras folder to /usr/local/bin/, read the documentation and try everything out. (We recommend VLC for watching the stream.)

If you are happy with everything, make the software autostart using

crontab -e

and adding a line like

@reboot /usr/local/bin/raspimjpeg.py -w 1280 -h 720 -r 25 | /usr/local/bin/streameye -p 8081

(Adapt width, height and framerate to your needs.)

StreamEye will then autostart with your Raspberry Pi and provide the webcam stream at http://studiodisplay1:8081/.

Normally, you would install StudioDisplay by simply cloning this repository:

cd
git clone https://github.com/Moonbase59/studiodisplay.git

A standard update to the latest version works as follows:

cd ~/studiodisplay/
git pull

Pulling a new version will not overwrite any configuration files you added for your system in the config subfolder.

In case git complains and suggests to stash or merge, the most probable reason is that you have changed something in the source files.

If you want to revert your changes and return to the latest and greatest version here on GitHub, you might want a »hard reset«:

cd ~/studiodisplay/
git fetch --all
git reset --hard origin/master

This will overwrite all source files, documentation and the example configuration. Nevertheless, it will not destroy any configuration files you added for your system in the config folder.

StudioDisplay is in daily production use at several webradio studios. Here’s a non-comprehensive list of systems I personally tested with:

• Ubuntu Studio 14.04.5 LTS
• Ubuntu 16.04
• Linux Mint 17.3
• Linux Mint 18.3
• Manjaro 17.1.10
• Raspbian Stretch (on Raspberry Pi 3B, 3B+ and Zero W)

We use SemVer for versioning. For the versions available, see the tags on this repository.

Read more in docs/translation.md.

Help wanted: We currently have the en-GB, en-US and de-DE locales included but are looking for translation into French, Spanish, Dutch, Danish and Russian. Or whatever language you need.

If you think you can help, start with the ~/studiodisplay/config/lang-en-US.json file, translate and test it in your language and open an issue. It’d be a bonus if you know the correct meteorological terms and the official measurement units for your language and country.

Matthias C. Hormann – Moonbase59

This project is licensed under the GPL-v3 license. See the COPYING file for details.

Too many to mention them all here. Read CREDITS.md.

Thanks to all that make Free and Open Source Software possible!