If you like what you got, please consider to . Thank you! ❤️
A fast, modular MQTT-based signalling & display solution for Web Radio Stations using IDJC.
Or just to make your smart home even smarter.
git
to get and update StudioDisplay
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 …
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
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.
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:
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/.
git
to get and update StudioDisplayNormally, 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:
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!