Oculus Prime - Command Reference

Jean-luc

15 oct. 2022 • 7 min read

The following listing is of text commands used by clients (javascript, mobile, and telnet clients) to communicate with the Oculus Prime server application. They can be grouped into the following categories:

Wheels
Camera and Lights
MALG board
Video/Audio
Users/Accounts
Dock/Power
Server Application
Operating System
Navigation
Sensing
Other

You can enter any command directly thru the web-browser remote interface:

MENU > advanced> telnet text command

OR, press ‘C’ at any time to get the same telnet text command prompt.

WHEELS

move left | right | forward | backward | stop
Wheel motors, continuous movement

nudge left | right | forward | backward
Move for amount of milliseconds (specified by ‘nudgedelay’ setting)

speed slow | med | fast OR {INT}
Set drive motor speed, either pre-set slow/medium/fast speeds, or set PWM directly with [0-255]

clicksteer {INT} {INT}
Camera tilt and drive motor movement macro to re-position center of screen by x,y pixels

motionenabletoggle (no arguments)
Enable/disable wheel motors

forward {DOUBLE}
Drives the robot forward by the specified distance, in meters, then stops. Determined by the onemeterdelay setting, or if odometry is running by the odomlinearmpms state variable if set

backward {DOUBLE}
Drives the robot backward by the specified distance, in meters, then stops. Determined by the onemeterdelay setting, or if odometry is running, by the odomlinearmpms state variable if set

left {INT}
Rotates the robot left by the specified angle, in degrees, then stops. Determined by the fullrotationdelay setting, or if odometry is running, by the odomturndpms state variable if set

right {INT}
Rotates the robot right by the specified angle, in degrees, then stops. Determined by the fullrotationdelay setting, or if odometry is running, by the odomturndpms state variable if set

rotate {INT}
Rotates the robot right by the specified angle, in degrees — left is positive, right is negative. If odometry is running and the odomturndpms state variable is set, will progressively turn incrementally for high accuracy. Otherwise uses fullrotationdelay setting

lefttimed {INT}
Rotates the robot left, stopping after the specified amount of milliseconds. Timing is done by the MALG microcontroller, good for very small movements

righttimed {INT}
Rotates the robot right, stopping after the specified amount of milliseconds. Timing is done by the MALG microcontroller, good for very small movements

forwardtimed {INT}
Moves the robot forward, stopping after the specified amount of milliseconds. Timing is done by the MALG microcontroller, good for precise movements

odometrystart (no arguments)
Enables gyro and encoder recording, resets counters to 0

odometryreport (no arguments)
Sends request for linear and rotational distance moved. Result is written to distanceangle state variable, counters are reset to 0

odometrystop (no arguments)
Sends request for linear and rotational distance moved, then disables gyro and encoder recording. Result is written to distanceangle state variable

calibraterotation (no arguments)
Runs macro to auto-calibrate gyrocomp setting using camera and dock target (default setting is typically fine, this is just in case).
Camera must be running, and robot must be approximately 1m in front of dock.

arcmove {DOUBLE} {INT}
Turn while travelling, for example:

arcmove 1.2 30

will move forward 1.2 meters while turning counter-clockwise 30 degrees. Turn radius accuracy can be calibrated with arcmovecomp setting

CAMERA AND LIGHTS

camtilt {INT}
Camera/Lights assembly tilt servo, move to specific angle [0-180]

spotlight {INT}
Set main spotlight intensity, percentage [0-100]

floodlight {INT}
Set rear flood light (docking light) intensity, percentage [0-100]

strobeflash on | off (optional) {INT} (optional) {INT}
Turns strobe flash on or off with required ‘on|off’ parameter, and optionally followed by duration (milliseconds), intensity (percentage). Examples:

strobeflash off <= turns strobeflash off
strobeflash on 500 30 <= turns strobeflash on for 500 ms at 30% intensity

MALG BOARD

motorsreset (no arguments)
Resets the MALG PCB

getdrivingsettings (no arguments)
Returns drive motor calibration settings (in bulk string form – intended for web browser interface)

drivingsettingsupdate {STRING}
Set drive motor calibration settings (in bulk string form – intended for web browser interface)

malgcommand {STRING}
Send byte sequence commands directly to the MALG PCB, in the form of:

{CHAR} single ASCII character, followed by one or more [0-255] separated by spaces

See the latest MALG firmware for the complete list of available commands, listed at the top in comments.

VIDEO/AUDIO

publish camera | camandmic | mic | stop
Robot video/audio control

streamsettingsset low | med | high | full | custom
Set robot camera resolution and quality

streamsettingscustom {STRING}
Set values for ‘custom’ stream: resolutionX_resolutionY_fps_quality

videosoundmode low | high
Set robot video compression codec

playerbroadcast mic | stop
Client microphone control (to be broadcast thru robot speaker)

framegrabtofile (optional) {STRING}
Saves a frame from the current camera stream to a JPG file with time/date stamp as filename. Saved to the folder: 'oculusPrime/webabpps/oculusPrime/framegrabs'
Outputs URL to telnet stream and message window
Optional {STRING} sets frameGrabHTTP developer parameter

record true | false
Toggle recording of current video stream (camera and/or mic must be running)

USERS/ACCOUNTS

driverexit (no arguments)
Disconnect/end driver RTMP connection with robot

disconnectotherconnections (no arguments)
Close all user RTMP connections other than current driver

who (no arguments)
Returns information on current driver connected via RTMP (eg., flash/web/mobile clients), and number of users connected via telnet

loginrecords (no arguments)
Returns list of RTMP driver (eg., flash/web/mobile clients) login history for current server session

chat {STRING}
Send text chat to all other connected users

messageclients {STRING}
Send text to all other connected users. Similar to ‘chat,’ but without preceding user info

DOCK/POWER

dock (no arguments)
Start manual dock routine (creep backward until dock connects)

autodock go | cancel
Start/quit auto-docking routine. Camera must be running

dockgrab (optional) highres | lowres
Attempts to find dock target within robots camera view. Initially sets state variable ‘dockfound’ to NULL, then sets to true or false depending on success, after short delay. Robot camera must be running
Optional resolution parameter 'highres' uses current resolution, 'lowres' (default) forces faster 320×240

redock (optional) noforward
Used by system if dock connection is weak, or unexpected un-dock.
Moves forward, turns on camera and floodlight, reverses tilt, checks for dock in view and engages autodock routine. If not in view, rotates until found. If not found, or otherwise unable to dock, posts alert to RSS and sends email. Use noforward parameter to skip initial forward move

battstats (no arguments)
Returns contents of state variable batteryinfo. Extended power information including individual cell voltages, system volts, current draw.

powerreset (no arguments)
Resets Xaxxon Power PCB

powershutdown (optional) {INT}
This will cause the OS to shut down gracefully, then the Xaxxon Power PCB will kill power to the system within 30-60 seconds. Requires unit to be in un-docked state.
If using the POWERv2 PCB, adding the optional parameter will cause the system to power back up again after the specified number in seconds

powercommand {STRING}
Use to send firmware commands to Xaxxon Power PCB

SERVER APPLICATION

uptime (no arguments)
Returns time in milliseconds since the server application started

restart (no arguments)
Restarts the server application

quitserver (no arguments)
Quits the server application

showlog (no arguments)
Returns partial output of oculusPrime/logs/jvm.stdout

writesetting {STRING} {STRING}
Uses format: key value
Write setting to configuration file oculus_settings.txt

readsetting {STRING}
Uses format: key
Reads and returns setting from configuration file oculus_settings.txt

settings (no arguments)
Dump bulk list of all settings to message window and telnet stream

log {STRING}
Write text to log file (can be used by scripts)

relayconnect {STRING} {STRING} {STRING}
Connect to relay server, use syntax (command and 3 expressions separated by spaces):

relayconnect hostname-or-ip-address username password

Admin username and password should be used, and client/server username should match. Server will attempt to reconnect if connection lost, including on restart/reboot.
Sets relayserver and relayserverauth settings, and relayserver state variable

relaydisable (no arguments)
Disables the relay server, and sets relayserver and relayserverauth settings to 'disabled'

OPERATING SYSTEM

systemcall {STRING}
Execute OS system command, with ‘oculusPrime/’ as the current working directory

setsystemvolume {INT}
Set robot operating system audio volume 0-100

reboot (no arguments)
Reboot the operating system

systemshutdown (no arguments)
Shut down the operating system (halt)

memory (no arguments)
Returns percent used, total memory, and free memory in use by the Java Virtual Machine. NOTE: JVM memory is not to be confused with system memory totals.

cpu (no arguments)
Writes current CPU utilization percentage to cpu state variable

waitforcpu (no arguments)
Sets state variable waitingforcpu to 'true', until CPU usage is below threshold (typically 60%, with a timeout of 20 seconds), whereupon state waitingforcpu will be set to 'false"

networkconnect {STRING}
Connects to wifi network with ssid {STRING}. Headless Wifi Manager app must be running

gotowaypoint {STRING}
Starts up navigation system (if not running) and sets waypoint {STRING} as the new navigation goal

startnav no arguments
Starts up the navigation system. State variable navsystemstatus is set to 'starting' while initializing, and 'running' when ready

startmapping no arguments
Starts up the navigation system in make-map mode. State variable navsystemstatus is set to 'starting' while initializing, and 'mapping' when ready

stopnav no arguments
Quits the navigation (and mapping) system. State variable navsystemstatus is set to 'stopping' while shutting down, and then 'stopped'

gotodock no arguments
Sets the 'dock' waypoint as the new navigation goal. Upon reaching it, navigation is shut down and auto-dock is initiated

runroute {STRING}
Sets route with the name {STRING} as the active route

cancelroute no arguments
Cancels any active route

savemap no arguments
Saves map currently generated by mapping system to file, overwriting any existing map after saving to backup

roslaunch {STRING}
Loads the ROS environment and launches the oculusprime_ros {STRING}.launch file by executing the ‘oculusPrime/ros.sh’ system command

savewaypoints {STRING}
Primarily used by javascript to write {STRING} to the rosmapwaypoints state variable, and also to the 'oculusPrime/conf/waypoints.txt' file

saveroute {STRING}
Primarily used by javascript to write XML data {STRING} to the 'oculusPrime/conf/navigationroutes.xml' file

SENSING

setstreamactivitythreshold {INT} {INT}
Set flash video motion, audio volume detection threshold, 0-100 (0=off)
Cancels on detection (setstreamactivitythreshold 0 0). Detections write to the streamactivity state variable

getlightlevel (no arguments)
Returns average pixel greyscale value (0-255) of frame from current stream

motiondetect (no arguments)
Enables motion detection mode, with sensitivity set by the motionthreshold setting. Camera must be running. Detections write to the streamactivity state variable

motiondetectcancel (no arguments)
Cancels motion detection mode

objectdetect {STRING}
Enables object detection mode. Currently supports 'human' as object type {STRING}
Camera must be running. Triggers write to streamactivity state variable

objectdetectcancel (no arguments)
Cancels object detection mode

sounddetect true | false
Call with 'true' to start sound detection, for use when setting useflash is set to FALSE. Call again with 'false' to cancel

OTHER

speech {STRING}
Voice synthesizer

serverbrowser (no arguments)
Launch new server.html browser webcam capture page on robot

email {STRING}
Uses format: email-address [subject] body
Send email to email-address, with subject [subject] and body text body
Example:

email bob@example.com [Test email] This is an email test

Uses mail server settings specified in oculus_settings.txt configuration file values for ‘email_smtp_server, email_smtp_port,’ (and ‘email_username, email_password’ if required)
Tip: To use Gmail to send mail: set the server to ‘smtp.gmail.com,’ port to 587, and use Gmail username and password

state (optional) {STRING} (optional) {STRING}
Uses format: key, or key value, or delete key
If called with no arguments: returns list of all non-null STATE variables
If called with one argument: returns value for single key
If called with two arguments: sets key to value
If called with arguments ‘delete key’: sets key value to null

quit (no arguments)
Disconnect current telnet session (telnet connection only)

rssadd {STRING}
Uses format: [title] description
Adds an item to Oculus Prime RSS feed XML file: oculusPrime/webapps/oculusPrime/rss.xml (creating it if not already present). Feed is publicly view-able via web url:
http://ip-address-or-domain-name:port/oculusPrime/rss.xml
Example:

http://69.163.206.138:5080/oculusPrime/rss.xml