Also in this section:
    Command Reference
    State Variables
    Python Module
    Script Examples
    Extending Oculusprime Java Server

INTRO

The Oculus Prime Telnet Programming Interface allows a script to converse with the Oculus Prime Server 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.

The telnet interface accepts any of the Oculus Prime Text Commands, and has access to all of the java application’s STATE variables and can manipulate the configuration settings. This combination gives a script complete control of all of the functions of the robot.

When you or your program/script connects to the Oculus Prime 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 LAN machine. The interface allows multiple connections, so you can have multiple programs running simultaneously.

If you’re using Python, the Oculus Prime Python Module provides a handful of convenience connection and conversing functions.

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) and HTTP.

GETTING STARTED

The easiest way to familiarize yourself with the Oculus Prime Telnet Interface is to connect to it manually using a telnet client, and test commands interactively. Typically 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 ‘telnetport’ setting to another port (or ‘disabled’ if you want to disable it).
NOTE: The telnet port connection has no authentication and intended for localhost or trusted LAN connections only. Read the Telnet Port section in the port forwarding section for more info.

With Oculus Prime Server 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 or OS X, at a command prompt enter:

$ telnet 192.168.0.99 4444

Replacing the IP address with the correct one, or ‘127.0.0.1’ or ‘localhost’ if you’re connecting from a login on the robot itself.

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 Prime v0.701
<telnet> 192.168.0.92 connected via socket
<telnet> 1 tcp connections active
<state> telnetusers 1

A good thing to do now is to also log in with the web-browser client, start controlling the robot from there, and watch the telnet output stream.

SENDING COMMANDS AND UNDERSTANDING OUTPUT TAGS

To see a list of all available commands, see the oculus prime command reference.

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
<messageserverhtml> <status> stream 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 4 primary output tags:

1. <‍telnet‍> – These are messages sent by the telnet server to the currently connected telnet user only.

2. <‍messageclient‍> – These are messages sent to all connected clients—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 Prime 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: Command Reference