Controlling HyperDeck from Terminal

Hi all, I'm fairly adept at using the macOS Terminal, and yet don't know at all where to begin when trying to uncover exactly how to control the HyperDeck from terminal; either with nc, or Telnet.

I have given the HyperDeck a static IP address and can control it from various iPad apps.

I'd eventually like to write a script that can schedule recordings, but first things first, I just need to know how to successfully send it a command from the terminal.

Can anyone point me to where I can find the proper syntax? Thanks!

Hi Dave -- I can help you with this, at least get you started.

But because I too had a hell of a time finding instructions how to do this, I hope you'll indulge me -- I'd like to write all this out longhand so it's on the forum and available for the next time someone goes looking for this information. In my own experience over the past couple of days, I have been amazed how little there is on the web dealing specifically with communicating via TCP from the OS X Terminal application, or the MacOS command line. The HyperDeck manual goes into great detail about all the things you can do in a TCP session with the HyperDeck, but doesn't actually tell you how to start a TCP session -- it assumes you already know how to do that. And on the web, while there's a fair amount of discussion about TCP in general, and how it differs from UDP, getting to the crux of your question -- and mine! -- about how to do all this in OS X or macOS, is suprisingly hard to do.

I'd be strongly in favor of the HyperDeck manual including a section with something like "how to start your first remote session with your HyperDeck," where it went into these details for Mac, Windows, and Linux users -- telling us WHAT the commands are, but not WHERE to use them, is frustrating.

OK, so your first question -- you mentioned nc. Great little program, absolutely lousy name for search engines! So although "nc" is the program name on the Mac command line, I'm going to refer to it as netcat, since that's probably the term one would be searching for if one were looking for this information.

You need to know the IP address of your HyperDeck. Ideally, you've assigned it a static address, especially if you're planning to do any long-term scripting. But for purposes of this test, you can simply go to the HyperDeck's menu. Under the "Settings" tab, the deck shows the IP address it's currently assigned to.

From the HyperDeck manual, we know that HyperDeck listens for TCP connections on port 9993. Meaning (again, for someone who might be searching for this information), that in order to establish a TCP connection with the IP address the deck is using, you need to send the request to that port.

Using netcat, (or, as it's known in OS X / macOS, simply nc), you can open a TCP session with the deck.

Open the Terminal application and type the following:

nc [deck's ip address] 9993

Now -- this is the part where I got really tripped up. We are conditioned as web users and programmers to expect lots of different sorts of punctuation in order to help the program figure out what's what on a command -- quotes, commas, semicolons, etc. Even Blackmagic's communication protocol requires colons after each command as part of the syntax. Critically -- netcat does NOT. So in the above command, if your deck's IP address is 10.0.1.3, the command simply is

nc 10.0.1.3 9993

That's it -- no colon before the port, no http:, not quotes, nothing.

Assuming you've got your deck's IP address right, and it's working correctly, the above command will open a TCP session with the deck. HyperDecks are chatty little things, so you'll get the following long-winded response:

500 connection info:
protocol version: [version number
model: Blackmagic HyperDeck Studio Mini (or whichever version you're using

At that point, the session is open and the HyperDeck is ready to take commands. Critically, you will NOT see any sort of a prompt -- no mycomputer: ~myusername$ like you get when you first open the terminal window. All you'll get is a cursor on a new line.

Try typing a couple of commands to see if the deck responds. Again, no quotes or anything like that:

play
device info
ping

...and so on. Presto -- you are communicating with your Hyper Deck, via the MacOS terminal/command line, using a TCP session.

And BTW, the process is exactly the same using Telnet. Instead of using netcat or nc, from the command line, simply type (again, assuming your IP deck's IP address is 10.0.1.3 -- replace with whatever your deck is using:

telnet 10.0.1.3 9993

You should again get the longwinded "500 connection info" message from the deck, after which you'll just have a cursor on a blank line. From there, you can send any of the commands in the manual.

I hope that's helpful!
Matt

Adding a second post, to deal with the scripting question. Again, I had a hell of a time finding information about how to communicate with the HyperDeck using scripting, particularly, in my case, using Applescript.

I'm not sure what kind of scripting you're planning to do, but since it's semi-relevant, and since I had a really hard time finding it elsewhere, please, indulge me.

In Applescript, it's possible to send commands as if you were sending them from the macOS/OS X command line in the Terminal application. The command to do it is "do shell script." The command doesn't need to be directed at the Terminal program, even, in which case you can execute command-line commands without causing OS X to spawn a new Terminal window each time.

Here's the issue I struggled with a bit. While "do shell script" allows you to send commands using command-line syntax, it's not the same as if you'd simply typed them into a terminal window. Each "do shell script" is treated like a one-shot, one-command terminal session. It's as if the computer opens a terminal window, enters the command you've issued on the command line, hits return, and immediately closes the window.

This works fine with UDP messages, where one computer simply blasts out a datagram and doesn't wait or expect a response, but TCP messages require the computer to FIRST establish a connection with the remote computer, THEN send a command while the session is open.

Suppose you try to start a netcat session with your HyperDeck. Assuming the deck's address is 10.0.1.3, the command from the command line is:

Code: Select all

nc 10.0.1.3 9993

As I mentioned in my last post, that opens a TCP session with the deck, and you can then send whatever commands you want to the deck. But when you're trying to use netcat with "do shell script," that process gets short circuited. Why? Because as soon as the "do shell script" command is issued, it's as if Applescript immediately terminates the TCP session without ever listening for a response. So you're connecting to the deck, but not waiting around long enough for a response or to actually tell it to do anything before Applescript hangs up the phone on you.

The way to get around this -- at least, long enough to send a handful of commands to the deck, is using the "echo" command, and concatenating the two commands together in a single "do shell script" command. Again, assuming your deck is located at 10.0.1.3, type the following into the Script Editor, and execute it:

Code: Select all

do shell script "echo \"play\" | nc 10.0.1.3 9993"

This sends a "play" command to the deck. If everything is working properly, the deck should drop into play when you execute this command from Applescript. Note the backslashes around the word, and their order. Because the "echo" command requires quotes around the text to be echoed, the backslashes are escape characters to allow the command to be read correctly by Applescript's parser. Without them, you'll get an error when you try to compile the command in Applescript.

Now, specifically what is happening in the above command is --
1. Applescript opens a netcat (nc) connection with 10.0.1.3, port 9993.
2. The command to the left of the pipe character ( the | in the example above) is sent when the connection is opened.
3. Applescript immediately closes down the TCP connection to the deck.

I suspect this is probably not ideal in all situations, since you are effectively handshaking a new TCP session each and every time you send a command this way, which is not the most efficient thing in the world. And if anyone has any ideas, I'm trying to figure out the best way to OPEN a TCP communication session with the HyperDeck, and then LEAVE it open for commands. This is pretty straightforward, apparently, when one is designing an app, but I haven't seen how it's done in, say, Applescript.

But if your script only needs to send a few commands, and not send them in super-rapid sequence, the above, one-shot way to send a single command to the HyperDeck via the "do shell script" command in Applescript, seems to work reasonably well. The HyperDecks are chatty little suckers, so you'll see the same "500" status message each & every time you execute a command, but unless you have some need to act on the responses coming back from the deck, that's probably not a big deal.

Again, I hope this is useful. I wish this information was in the manual, but hopefully this makes it easier to locate this information for script-hounds like myself who are new to the HyperDeck and trying to get started with how to control these decks using TCP remote control.

Cheers!
Matt

Thank you! This has been SO VERY helpful.

However I did not find that AppleScript closed the connection so I had to add a timeout option (-W timeout) to the NC command string.

All works well for a few times. Via triggers to AppleScript I can start and stop the HyperDeck just as I want.

But after 3 or so times, the HyperDeck will no longer listen to the AppleScript commands (via do shell commands)

At this point I can't even connect manually using terminal and the NC command. Only solution is to disconnect power and reset the unit.

When it gets stuck, I can still ping it, so must have something to do with the port (9993).
So close...and ideas / tips would be appreciated.

Portion Applescript being use to control Hyperdeck via Midi Notes is below.

So close...and ideas / tips would be appreciated.

Pete +


-- Stop Hyperdeck Recorder if C#2 (1) on Channel 3 (143+3)
if (item 1 of message = 146) and (item 2 of message = 1) then
say "Stopping Hyperdeck recorder"
do shell script "echo \"stop\" | nc 192.168.1.111 9993 -w 3"
say "Check that Red Light is off and time code has stopped"
end if

Hi Pete,

I'm re-discovering my own notes on this topic, as I'm suddenly discovering, a couple of days before an event, that I am no longer able to get these commands to work.

I was under macOS Sierra when I wrote these posts last year. I have since moved to High Sierra.

I am still able to open a terminal session and simply type:

nc [address of deck] 9993

and then interact with the deck on a line-by-line basis.

But it would appear that the one-shot "echo" function no longer works. Rather than executing the command and closing the connection, macOS just hangs. So, from the terminal, this no longer works:

echo "play" | nc [address of deck] 9993

I went hunting to see if this was an Applescript issue, but I discovered that this command no longer works from the command line, either.

I am continuing to research this & hoping to find a solution, but wanted to confirm I'm seeing the same thing.

If anyone else has solved this, I'd be grateful for the details.

Hi Pete,

I confirm the same behavior you're describing above. If I include a -w timeout in the nc command, as follows, eg.:

echo "play" | nc -w 1 [address of deck] 9993

I am able to send a handful of commands to the deck as expected. On about the 5th or 6th try, the deck doesn't respond and the command fails back to the command prompt (i.e the timeout is observed but the deck doesn't respond).

After that, I am then no longer able to even establish basic nc sessions with the deck. Before, typing:

nc [address of deck] 9993

would open a session with the deck & give me the deck's status. After the echo'd commands stop working, this command just hangs.

My first thought was that this was somehow related to Apple's removal of telnet from macOS High Sierra, as there's quite a lot of chatter about that on the web, but the discussion I've seen always recommends using netcat as an alternative. So I'm going to table that idea for the moment. I want to try going back to a prior version of the HyperDeck firmware (when these commands didn't fail) and see if the behavior is any different. I'll post what I find out.

Cheers,
Matt

OK, update...

I rolled back to HyperDeck software version 5.2, which is the version I was using last spring when I wrote the thread above about using echo and netcat with do shell script.

I didn't try 5.3, although it might be worth testing with that version, too. I went straight to 5.2 only because that was the version that the code from last January worked with.

And interestingly, it appears to still work. So under v5.2, simply sending:

Code: Select all

echo "play" | nc [address of deck] 9993

should work -- no -w timeout needed. I can also confirm that Applescript commands sent using the same method go right through without any delay or hanging.

Kinda late here, but I'll bang on this some more tomorrow. For now, I'd simply say try rolling back to 5.2 and see if that fixes things for you. Please post what you find here.

Cheers,
Matt

OK, a few more findings...

First, the release notes for 5.3 don't mention that there's any updates for the HyperDeck Mini. I tried installing 5.3 on the deck that was running 5.2, and the setup app just opens without the "your deck needs a software update" message. If you run the 5.3 app on a Mini deck with 6.0, though, it will require you to install the "update" (which is actually a downgrade in this case).

So as far as the Minis are concerned, 5.2 is the last version with actual changes.

With 5.2 installed on all four of my decks, they are behaving as they previously did -- no -w timeouts or anything. I'm hammering all 4 decks with start and stop commands and they're responding normally, e.g.:

Code: Select all

do shell script "echo \"play\" | nc 0 10.0.1.31 9993; echo \"play\" | nc 10.0.1.32 9993; echo \"play\" | nc 10.0.1.33 9993; echo \"play\" | nc 10.0.1.34 9993"

Looks like we've been dealing with a bug introduced in 6.0!

Hey folks, thanks so much for this option.

I was trying to find a way to start two Blackmagic decks simultaneously. This guide helped me make it happen.

I had to do a command to two players at once, and I used this:

echo play: loop: true | nc 192.168.0.108 9993; echo play: loop: true | nc 192.168.0.164 9993

Just as it is, no quotes or quote-substitutes or anything.

A danger is that if I try to repeat this command, by hitting "up arrow" in terminal, it for some reason adds a space before the semi-colon and so the command fails.

On the HyperDeck Mini, I'm happy to report that this issue appears to have been resolved in the HyperDeck 7.1 update that was posted last month. "echo" commands now appear to be working correctly. I am able to repeatedly send "play" and "stop" commands to the deck as an "echo" string from AppleScript and they respond correctly (and instantaneously!)

This issue appears closed. Thanks BMD!

M2

Thanks a bunch for posting this! It worked great,

you're welcome! Glad to have this written down somewhere.

M2