Switchers
From Rivendell Wiki
Contents
Getting Rivendell working with an Audio Switcher
Using Rivendell to control an audio switcher is pretty easy as long as your switcher is supported but there are a few gotchas that might catch you out as a first timer. Hopefully by the end of this you'll be up and running with your own switcher and even if you have an unsupported switcher there are other things you can do to use Rivendell automation.
This guide was written on Ubuntu 14.04 with a Broadcast Tools ACS 8.2 Plus, the principles contained within are applicable to other switchers and distributions.
You can see what switchers are supported in Rivendell by looking at SWITCHERS.txt from the Docs directory or directly from Github:
Checking your switcher actually works
Before you dive into Rivendell, it will save you a lot of headaches if you can test it actually works under Linux first. This way you won't waste hours changing Rivendell settings just because your serial cable isn't working (there are undoubtedly fancier switchers that have network connections and web interfaces by now, I'm using the old school serial cable connections).
Assuming you've plugged your switcher in and attached the serial cable, the first thing you need to know is which port has Linux assigned it to?
There are a few tools to help with this:
dmesg | grep tty
This will search dmesg and output something like this:
[ 0.000000] console [tty0] enabled [ 0.666313] 00:04: ttyS1 at I/O 0x2f8 (irq = 3, base_baud = 115200) is a 16550A [ 0.686949] 00:05: ttyS0 at I/O 0x3f8 (irq = 4, base_baud = 115200) is a 16550A
Note: If you have a USB to serial adapter it will probably be something like ttyUSB0.
So we've already narrowed our serial port down to either ttyS1 or ttyS0 (tty0 is probably the console you're typing this stuff into unless you're conserving calories and using ssh). All of these ports live inside /dev:
ls -l /dev/tty*
In here you'll see a ton of tty listings that roughly look like this:
crw-rw---- 1 root dialout 4, 64 Nov 16 23:13 /dev/ttyS0 crw-rw---- 1 root dialout 4, 65 Nov 17 03:29 /dev/ttyS1 crw-rw---- 1 root dialout 4, 74 Nov 12 19:13 /dev/ttyS10
Hopefully now you can see why we grep'ed dmesg instead of starting the trial and error on all the matches you see from your own ls -l /dev/tty*. Next we need to start connecting to ports and trying them out. We will use a tool called minicom for this:
$ sudo apt-get install minicom
Minicom is a bit weird to get used to but the most important thing to remember, Ctrl + A and then X = quit. Don't forget this as you won't be able to Ctrl + C or anything else except login again and kill the process.
By looking at the SWITCHERS.txt doc, the Broadcast Tools ACS 8.2 gives us this information:
"Serial port speed on the ACS 8.2 should be set to 9600. Serial port parameters should be set to 9600 baud rate, no parity, 8 data bits, 1 stop bit, no termination."
So we'll connect to the first serial port with those options:
$ minicom -s
This brings you to minicom's setup menu.
+-----[configuration]------+ | Filenames and paths | | File transfer protocols | | Serial port setup | | Modem and dialing | | Screen and keyboard | | Save setup as dfl | | Save setup as.. | | Exit | | Exit from Minicom | +--------------------------+
First go into Serial port setup and change the settings so it matches:
+-----------------------------------------------------------------------+ | A - Serial Device : /dev/ttyS0 | | B - Lockfile Location : /var/lock | | C - Callin Program : | | D - Callout Program : | | E - Bps/Par/Bits : 9600 8N1 | | F - Hardware Flow Control : No | | G - Software Flow Control : No | | | | Change which setting? | +-----------------------------------------------------------------------+
Make sure you press Enter to save the settings, Escape quits without saving! Once you're back at the main menu select "Save setup as dfl [default for the abbreviation impaired]." Next select Exit. This doesn't actually Exit, it exits the settings mode and connects you to your serial port.
Here is the first gotcha. You probably won't have permission to use the serial ports as your Rivendell user. If you go back to our ls -l of /dev/tty you'll remember this:
crw-rw---- 1 root dialout 4, 64 Nov 16 23:13 /dev/ttyS0
This means the device is owned by root and the group dialout. This will probably be different in your distribution but I believe all the Debian based ones are the same. So we need to add our user to the dialout group, log out and back in (so that your new account permissions are activated) and then try again:
$ sudo adduser my_rivendell_user dialout
Once you've logged back in and loaded up minicom (its worth double checking with minicom -s to make sure the settings saved properly), you can now try to talk to your switcher. The broadcast tools ACS 8.2 switcher has a menu command that is handy as it spits out a bunch of text. Refer to your own manuals (the 8.2 ACS is linked here).
Note: You won't see what you're typing unless your switcher/minicom is set to echo the input. If you're unsure you typed correctly hit enter and try again.
To get the ACS menu type the following:
*0MM
Note: 0 is the ID of your unit, unless you've been messing with dip switches this should be correct.
If nothing happens, you probably have the wrong serial port or your wires are broken (or you've been messing with dip switches and the ACS 8.2 is no longer in its default 9600 baud rate mode). In my case, my switcher was on /dev/ttyS1 so I had to amend minicom's settings (minicom -s) and try again. Once you've found the correct serial port, you'll get an output like this:
ACS8.2c V1.16 - Menu 1 - PIP Min 0-2.55 sec Now: .02 (sec) 2 - O.C. Mode Now: "Follow" 3 - SS Acq Time (sec) Now: 10 4 - SS Rest Time (sec) Now: 10 5 - Dim (DB) Now: -10 6 - Fade (sec) Now: 5 7 - Relay Pulse (sec) Now: 1.0 8 - Turn ON Audio XPOINT 9 - Turn OFF Audio XPOINT A - Save Audio for Powerup B - Select Audio Macro D - Set Defaults Audio Status: 1->2 4->1 Enter Choice, or Q to quit:
With that working make a note of whatever /dev/tty_whatever worked for you and we can move onto Rivendell (Q to Quit then Ctrl + A then X to quit minicom)
Further hardware setup
Depending on what switcher you're using, you might be able to skip this section. Either way have a read through the SWITCHERS.txt file. For the Broadcast Tools Switcher I have, I need to make sure the device is set to 9600 baud and that it is set to "Mix" mode.
Note: Mix mode changes the behaviour of this particular switcher. By default, you press your output buttons and the switcher mutes the live output and changes it to the next one. In mix mode, pressing the button mixes inputs together. You have to press Mute + an Input to turn the input off. This is a bit of a faff but you can automate it with Riv or straight forward serial commands.
On the ACS 8.2, the settings switches are a small row of dip switches internal to the device. You'll have to remove the 4 screws for the lid. The switch is located at the front of the device roughly in the middle. In order to configure it for Rivendell check the following switches:
- OFF
- OFF - These two set the device ID, both off = 0.
- OFF
- OFF - These two set the baud rate, both off = 9600.
- ON
- ON - These two set the Audio mode to "Mix"
That's all you need to do in order for Rivendell to work with the ACS 8.2, obviously this won't apply directly to whatever switcher you're using.
Configuring Rivendell
Fire up rdadmin and edit the host which has the switcher attached to it. The first thing to do is enable the serial port. Click the "Serial Ports" button and you'll have a screen that looks like this:
Click Enabled and match the settings to your switcher. Make a note of the Port ID (Serial0) as this is what Rivendell uses to refer to the underlying serial port (in my case /dev/ttyS1).
Close this box and then click the "Switchers GPIO" button. You'll have to add a new switcher. You'll probably have something like this (change the Switcher type to your switcher):
Once this is added, you can edit the config. All you need to change here is the Serial Port setting to the one you created earlier (probably Serial0). Everything else is optional (you can label inputs and set up GPIO as required).
Make a note of the Matrix Number (probably 0), you'll need this for the Rivendell macros.
This is all the config, now you can get down to using it.
Using the Switcher
You could use rmlsend to automate macro commands from other machines, crontab, macros inside logs etc etc etc. I'm going to keep it simple and create a cart with the macros you'll need. Its up to you what you want to do with it after that.
Meet your new macro friend:
ST [matrix] [input] [output]!
ST is the only macro you need to make your switcher change audio inputs/outputs. E.g. you want to switch from Studio 1 to Studio 2. If you want to do fancier things than this, look at SWITCHERS.txt for information on what commands your switcher supports and then read up on the macro language.
I already know that my matrix number is 0, as noted earlier. So now you just need to know what inputs are from what "studio" and what outputs you need to switch them to.
On my switcher I have the following inputs:
- Studio 1
- Studio 2
- Automation / No humans required
- Emergency Player
- Inputs 5 - 8 are not in use
It also has the following outputs:
- Internal Monitoring
- Live
So lets suppose I want to take studio 1 live, I would run this command:
ST 0 1 2!
This is matrix 0, take input 1 to output 2. Lets assume its the end of the day and I want to go into Automation:
ST 0 3 2!
What about if I want to monitor the output from the Emergency Player:
ST 0 4 1!
You can add this to macro carts and give your presenters buttons to press (if you're trusting) or add them to a log within Rivendell that runs on the automation server, or you could even add them to cron via rmlsend:
#At 21:00 every day switch to auto 0 21 * * * rmlsend ST\ 0\ 3\ 2\!
Hopefully this helps demistify Rivendell's options for switchers and saves someone a few grey hairs.
The macros didn't work
So you've got this far, you've created macros or used RML Send but nothing worked. Obviously check all your settings but you're most likely suffering from a serial port config bug. As far as I can tell, Rivendell is meant to open the serial port at the given baud rates etc but for whatever reason under Ubuntu 14.04 it is not doing so.
This is easy enough to work around. You could use minicom however I prefer to use screen as I can check in on what is happening at any time (if needed).
$ sudo apt-get install screen
The command I'm using is this:
screen -fn -L -d -m -S switcher /dev/ttyS1 9600
Obviously thats quite a lot to digest but its fairly simple:
- -fn => Turn flow control off so it matches our serial settings
- -L => Log the output to screenlog.0 (this will be in the directory that screen runs from)
- -d -m => Load this in the background (it loads up and "detaches" from the screen)
- -S switcher => This lets you label the instance of screen. In this case I'm calling it switcher.
- /dev/ttyS1 9600 => connect to /dev/ttyS1 at 9600 baud.
Useful screen commands
With screen running, you can monitor it with this:
screen -r
If you have more than one screen running for other purposes you will have to supply your screen label e.g.
screen -r switcher
Once there its a lot like minicom in that you can't really do much. If you try your macros now, you should see the response from the switcher scrolling by. For example when I change my monitor output (1) to input 1, I get the following in screen:
SOL1,1,0,0,1,0,0,0,0 SOL2,1,0,0,0,0,0,0,0 SOL1,1,0,0,0,0,0,0,0 SOL2,1,0,0,0,0,0,0,0
Most importantly, Ctrl + a then d detaches from the screen session. If you want to end screen so that the serial port is closed you have to reattach and then press, Ctrl + a then K (yes capital) then y to confirm. You can also do this from the command line:
screen -X -S switcher quit
Note: If you quit screen and try and reload, you may get port in use errors. All you see from screen is that it terminates which is a bit annoying to debug. It seems to take a few minutes for the kernel to realise the port is free before you can use it again.
Automating Screen
So we have screen working all you need to do is make sure it loads on startup. Depending on your distribution you could add it to the login scripts, cron should work fine though, just make sure its cron for your Rivendell user.
crontab -e
#Open Serial Port with screen @reboot screen -fn -L -d -m -S switcher /dev/ttyS1 9600
Unsupported Switchers
Obviously all the above instructions are fine if your switcher is supported. If it isn't then you'll need to investigate how you can talk to the device. If you have a fancy web enabled switcher that has an API of sorts (e.g. if you type in an address in your browser and the switcher does things) you can use curl:
$ sudo apt-get install curl
A very basic curl is just to call a web page directly:
curl http://myswitcher/input=1&output=2
Obviously I have no idea how your switcher works so your command will change. If you need to authenticate curl has extra options to supply user names/passwords with the request.
If your switcher is used via serial ports. You can continue to use screen as before but you'll have to figure out what serial commands to send to the device. For example on the broadcast tools ACS 8.2, I can route input 1 to output 1 with the following command (via minicom or screen):
*0011
Input 2 to output one is this:
*0021
If I then want to do that via screen I can do this:
screen -S switcher -X stuff *0011
Once you get to the stage where you know the commands you use, the easiest thing to do is set up some bash scripts e.g. :
#!/bin/bash #Switches input 1 to output 1 screen -S switcher -X stuff *0011
Save all those scripts individually and we can then use the Rivendell RN macro to run the commands:
rmlsend RN\ path_to_script.sh!
After getting this far, adding them to logs or whatever is entirely up to you.
My Switcher stopped working
So you've been running the switcher for a few days and without reason, the switcher stops responding to Rivendell commands. The first thing to do is fire up minicom and see if the device is responding. You can also try running:
rmlsend SY 0! rmlsend SZ 0!
SY reloads the serial port (change 0 to 1 etc if you're not using Serial0 in Rivendell). SZ reloads the switcher (again change 0 to 1 etc if you're not using matrix 0 in Rivendell).
If it still doesn't respond and you have screen running you might also get some clues from the log. In my case I kept seeing lines like this:
SOS,0,0 SOS,1,0
I would normally expect SOL lines when it was switching properly. After a lot of digging, all I could think of was that Ubuntu didn't like the way Rivendell talked to the serial port (hence having to use screen in the first place). So I used bash and screen to talk directly to the serial port and then used Rivendell RN macros to call the script.
The script itself is only applicable for a Broadcast Tools ACS 8.2 Plus. You'll have to amend the screen lines to whatever serial commands your device supports.
#!/bin/bash
#Changes the broadcast tools switcher as specified in the args
#Usage: {INPUT} {OUTPUT}
MAX_INPUTS=4
MAX_OUTPUTS=2
#Check the arguments before trying to switch to a weird state
#We need two arguments
if [ "$#" -ne 2 ]; then
echo "Usage: $0 INPUT OUTPUT"
exit 1
fi
#We have two arguments, check the range
if [[ $1 < 1 || $1 > $MAX_INPUTS ]]; then
echo "Input $1 is not between 1 and $MAX_INPUTS"
exit 1
fi
if [[ $2 < 1 || $2 > $MAX_OUTPUTS ]]; then
echo "Output $2 is not between 1 and $MAX_OUTPUTS"
exit 1
fi
# ACS 8.2 Serial Commands
# *0MM = Main Menu
# *0iio = Input to Output (Input needs two figures e.g. 1 = 01)
# *0ii5 = Set Input to Off for output 1 (Input needs two figures)
# *0ii6 = Set Input to Off for output 2 (Input needs two figures)
# *0Mo = Mute output o
# Basic flow
# Mute all inputs
# Set new input on new output
logger "SWITCHER" "Switching Input $1 to Output $2"
#Mute all inputs on output (this is required because we swapped to mix mode)
screen -S switcher -X stuff *0M$2
#Set new input to output
screen -S switcher -X stuff *00$1$2
#Finished
All you need to do is save this somewhere accessible to your Rivendell user and make it executable (chmod ug+x). Then in your macros/rmlsend/whatever, instead of calling ST 0 1 2 (matrix 0, input 1 to output 2); you use RN as follows:
RN /path_to_script/the_script.sh 1 2!
For me I save this in ukstudio's script directory and the script is called switcher:
RN /home/ukstudio/scripts/switcher.sh 1 2!
You can still use this with crontab and all the rest as before. If this guide hasn't been updated in a few days, it means there have been no errors since (18/11/2015).
References
http://www.cyberciti.biz/faq/find-out-linux-serial-ports-with-setserial/
