HOW TO: Control OnTheAir Node with Telnet ?

Important notes about Telnet !!

Telnet was the first protocol that we used, and we continue to maintain it for our users, but if you start working with OnTheAir Node, you should use instead our RESTfull API.

Also, telnet is not available anymore in macOS. So we will use "nc" in this article. Check the alternatives and other options in the following article: https://softron.zendesk.com/hc/en-us/articles/360016368993

1. Connecting to a OnTheAir Node server with Terminal

Let's say you are controlling a OnTheAir Node that has an IP address 192.168.0.1, and you are controlling Node 1 which by default has Port Number set to 3001 (Node 2 will be 3002, etc...). To control this Node with Telnet, open Terminal application and type:

nc 192.168.0.1 3001

That's it you should be connected. Note that, unlike with Telnet, there is no confirmation. To check if you are connected, use a simple command such as "help", if you receive nothing back, it means you are not connected. Type "exit" to close the connection and try again.

2. Using the help commands to get the list of available commands

Now you can type

help

In terminal window, you will then get the list of all commands that can be asked at current time from OnTheAir Node, for example:

GLOBAL:
validatepassword <password>
unlock <password>
lock
version
versionstring
nodename
nodeuniqueid
exit

FILE MANAGEMENT:
fmstatus <media folder index>
fmprogress <media folder index>
fmmediafolderscount
fmmediafoldersuniqueids
fmmediafolderinfo <media folder unique id>
fmmediafolderpath <media folder unique id>
fmmediafolderuniqueid <media folder index>
fmmediaitemsuniqueids <media folder unique id>
fmmediaitemsabsolutepaths <media folder unique id>
fmmediaiteminfo <media folder unique id> <media item unique id>
fmmediaitemthumbnail <media folder unique id> <media item unique id> <position in seconds>
fmmediaitemthumbnailatpath <media item absolute path> <position in seconds>
fmmediaitemminithumbnail <media folder unique id> <media item unique id> <position in seconds>
fmmediaitemminithumbnailatpath <media item absolute path> <position in seconds>
fmlastchangenumber <media folder unique id>
fmmediaitemschangessince <media folder unique id> <change index>
fmmediafolderupdate <media folder unique id>
fmmediafolderupdatepath <media folder unique id> <path to update>

ATTRIBUTES:
atattributenames
atattributeinfo <attribute name>
atlastchangenumber
atattributechangessince <change index>

PLAYLIST:
plplaylist
plsetloopmode <0/1>
plsetcuemode <0/1>
plsetchainmode <0/1>
plsetuniqueid <playlist unique id>
pluniqueid
plclearall
plitemwithuniqueid <unique id of item>
plitematindex <index, zero-based>
plitemscount
pladditem <xml plist of item to append>
pladditems <xml plist of items array to append>
plinsertitematindex <index, zero-based> <xml plist of item to insert>
plinsertitemsatindex <index, zero-based> <xml plist of items array to insert>
plreplaceitematindex <index, zero-based> <xml plist of item to insert>
plreplaceallitems <xml plist of items to replace>
plremoveitem <unique id of item to remove>
plremoveitematindex <index, zero-based>
pllastchangenumber
plsetschedule <xml plist of schedule>
plgetschedule
plgetfirstscheduleevent
plgetlastscheduleevent
plclearschedule

PLAYBACK:
pbinitialize
pbclose
pbaudiomute <0/1>
pbaudiopassthrough <0/1>
pbstop
pbpause
pbplay ((<index of item to start> (<offset from start>))
pbplayitem ((<unique id of item to start> (<offset from start>))
pbcue ((<index of item to start> (<offset from start>))
pbcueitem ((<unique id of item to start> (<offset from start>))
pbskiptonext
pbresyncschedule
pbstopscheduler
pbstartscheduler
pbstatus

You can see that the commands are divided into 5 sections:

• GLOBAL: The general commands like "nodename" which will give you the name given to this node, "version" which will give the current version of OnTheAir Node or  "unlock" which will ask you the password so you can send the playback and playlist commands.
• FILE MANAGEMENT:  All the commands related to file management, to get the list of media folders, and the list of clips available on one node
• ATTRIBUTES: The commands to check the status of the available attributes (attributes are for example to put on/off a logo, sound level, GPI Commander, OnTheAir CG, Video router control, etc...)
• PLAYLIST: All the commands to send, receive or modify a playlist or schedule (only available when you are authenticated)
• PLAYBACK: All the commands to control the playback: start, stop, play next/previous clip, etc...  (only available when you are authenticated)

You can also see that a command for File Management is preceded with "fm", a command for playback with "pb", etc...

3. About "unlocking" the Node

Note that the commands in Bold are the ones that require you first to "unlock" the Node with the password. The logic is that to "see" what is playing, or the media available, you do not need to unlock the Node. For any command that will require an action or modification on the Node, you will be asked to first to enter the unlock code. The unlock code (password) is set in the Node system preference pane. The default code is "1234".