The Telnet Programming Interface

INTRO

The Oculus Telnet Interface allows you to converse with the Oculus-Java application via TCP socket connection. You can write automation scripts using any programming language that supports TCP socket connections and is capable of deciphering text strings; eg., Python, Ruby, C#, Visual Basic, C, Java, Perl, and many others. You can also use it interactively, with any telnet client.

When you or your program/script logs into the Oculus Telnet Interface, you have complete control over all the robot’s functions, and access to its real-time status output stream. A program can be running on the robot itself, or on a remote machine. The interface allows multiple connections, so you can have multiple programs running simultaneously, and your program can launch other programs.

NOTE: the other 2 ways clients communicate with the Oculus-Java application are through RTMP and HTTP protocols. The web-browser and Android/iOS clients primarily communicate via RTMP (a protocol originally developed by Macromedia and is used for streaming video and text)

GETTING STARTED

The telnet interface accepts any of the Oculus Text Commands, and has access to all of the Oculus-Java STATE variables and configuration settings.

The easiest way to familiarize yourself with the Oculus Telnet Interface is to log into it manually from another machine, and play around. By default, the telnet server is enabled on port 4444. To change this, you can edit the ‘oculus_settings.txt’ file and change the value for the ‘commandport’ setting to another port (or ‘disabled’ if you want to disable it).

With Oculus-Java running, connect to it using a telnet client. In Windows, you can use the ‘telnet.exe’ program if it’s installed, or putty.exe is another popular option. If you’re using Putty, set host to the robot’s IP address, port to ‘4444,’ and the connection type to ‘telnet.’ Under the ‘connections > telnet’ configuration category, set ‘telnet negotiation mode’ to ‘passive.’
If you’re using Linux, at a command prompt type something like ‘telnet 192.168.0.99 4444’ (replacing the IP address with the correct one).

You should be greeted with something like this:

Trying 192.168.0.99...
Connected to 192.168.0.99.
Escape character is '^]'.
<telnet‍> Welcome to Oculus build 639
<telnet‍> LOGIN with admin user:password OR user:encrypted_password

At this point you can enter your login credentials as ‘username:password’ OR replace the plain-text password with the encrypted version, found at the bottom of the file ‘Oculus/conf/oculus_settings.txt,’ at the line ‘pass0’. So, you would login with something like ‘username:Mup8F325S5CzeG6XM3xJug1AOeU=,’ if you have any concerns about sending a plain-text password over the network.

Once logged in correctly, a good thing to do now is to also log in with the web-browser client, start controlling the robot, and watch the telnet output stream.

SENDING COMMANDS AND UNDERSTANDING OUTPUT TAGS

With the telnet interface you have complete control of the robot. To see a list of all available commands, enter ‘help’ or enter ‘help command’ to see extended help on a particular command.

Try sending a command: with the robot camera turned off, enter:

publish camera

You will notice the video stream start in the web client, and the telnet server will output:

<‍messageclient‍> command received: publish camera
<‍state‍> stream camera
<‍messageserverhtml‍> streaming camera

Notice the XML style tags preceding each line—these are added by the telnet server to identify specific message types, to make the output easier to understand and be parsed by programs. There are currently 4 primary output tags:

1. <‍telnet‍> – These are messages sent by the telnet server to the currently connected telnet user only. For example, the login prompt always starts with ‘<‍telnet‍> LOGIN,’ so your script can know that the server is waiting for login information.

2. <‍messageclient‍> – These are messages sent to all connected users—they will appear in the message window of a RTMP-connected driver (not passengers), and any telnet output streams

3. <‍messageserverhtml> – These are messages sent only to the javascript running in the web-browser on the robot (either initialize.html or server.html), and to any telnet output streams

4. <‍state> – These are messages pertaining to Oculus STATE variables

Sometimes <‍messageclient‍> and <‍messageserverhtml> tags will be followed by the <‍status> tag. This represents information not sent to the message window, but for other purposes required by the web page (eg., in the case of the web-client, to update the upper-right status readouts)

Lastly, messages that span more than one line will be surrounded by the <‍multiline><‍/multiline> tags.

NEXT: an example telnet program