← back to Oculus Prime Contents

Oculus Prime - State Variables

STATE Variable Reference

STATE variables are used extensively by the Oculus Prime Java application to store real-time information about the current status, or state, of the robot’s various functions and systems. They are useful to access from the Telnet Programming Interface, when programming the robot via an external script. Scripts can access the built-in state variables listed below, or create their own, to use across multiple running scripts.

The ‘state’ command description is as follows:

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

Whenever a state variable changes, it is immediately written to the telnet output stream, preceded by the <‍state‍> tag. If a variable is deleted, it is assigned the value null, and, if the value was non-null to begin with, its demise is reported in the telnet output stream with:

<state> deleted: key

External scripts can react to these state-change events.

State Variable Groups:


motionenabled {BOOLEAN}
TRUE if wheel motors are allowed to move (typically FALSE when docked)

motorspeed {INT}
Current motor speed setting PWM value 0-255

moving {BOOLEAN}
TRUE if wheel motors are moving

movingforward {BOOLEAN}
TRUE if motors are moving wheels in forward direction

cameratilt {INT}
Position of camera/lights tilt servo motor

motorport {STRING}
Name of USB port communicating with MALG microcontroller


dockgrabbusy {BOOLEAN}
TRUE if the auto-docking system is in the process of grabbing a single frame from video feed, and trying to find the dock target within the image

docking {BOOLEAN}
TRUE if the final docking macro is in progress, where the robot is moving straight forward in increments, looking for battery charging status

dockstatus {STRING)
Current state of dock. Can be ‘docked,’ ‘un-docked,’ ‘docking,’ or ‘unknown’

autodocking {BOOLEAN}
TRUE if overall auto-docking routine is in progress

dockfound {BOOLEAN}
TRUE if dock target found within camera field of view

dockmetrics {STRING}
String containing space-separated numbers representing the dock target size/position within camera frame (if found). Format: Ctr x pixels, Ctr y pixels, width pixels, height pixels, slope radians


spotlightbrightness {INT}
Brightness of spotlight, percent: 100=full, 0=off

floodlightlevel {INT}
Brightness of rear flood light, percent: 100=full, 0=off

fwdfloodlevel {INT}
Brightness of forward flood light (not equipped by default), percent: 100=full, 0=off

strobeflashon {BOOLEAN}
TRUE if strobeflash mode is active (see strobeflash command)


driver {STRING}
Current driver username, connected via RTMP

logintime {LONG}
Last time driver RTMP client logged in (in milliseconds since epoch)

telnetusers {INT}
Number of current logins connected via the telnet interface

pendinguserconnected {STRING}
Username of rtmp connected user waiting to be driver/passenger


stream {STRING}
Current mode of robot camera/microphone stream.
Can be ‘camera,’ ‘camandmic,’ ‘mic,’ or ‘stop’

videosoundmode {STRING}
Video encoding mode employed by robot Flash/Actionscript camera/mic capture
'low' refers to h263 video with Nelly-Moser audio, and 'high' refers to h264 video with SPEEX audio

driverstream {BOOLEAN}
TRUE if driver (rtmp client) ‘self’ microphone stream is active

volume {INT}
System volume percent 0-100

framegrabbusy {BOOLEAN}
TRUE if waiting for single-frame pixel data to be fetched from camera

streamactivitythreshold {STRING}
Current value of video/audio activity thresholds, set by setstreamactivitythreshold command

streamactivityenabled {LONG}
Time streamActivityThreshold was set (in milliseconds since epoch), NULL if no activity detection is set

motiondetect {BOOLEAN}
TRUE if Java/OpenCV motion detection routine is running, set by motiondetect command

objectdetect {STRING}
If not NULL, OpenCV object detect is enabled, using mode {STRING}

streamactivity {STRING}
Results of most recent motion, audio, or object detection

controlsinverted {BOOLEAN}
TRUE if camera facing backwards, opposite movement commands

lightlevel {INT}
Result of getlightlevel command, average pixel greyscale value (0-255) of frame from camera stream

jpgstream {BOOLEAN}
TRUE if http JPG stream is active, camera capture via OpenCV instead of flash plugin

record {STRING}
Current video recording status, typically ‘camera,’ ‘camandmic,’ ‘mic,’ or ‘stop’

sounddetect {BOOLEAN}
TRUE if non-flash sound detection active, as set by sounddetect command


wallpower {BOOLEAN}
TRUE if wall power detected by Xaxxon Power PCB (note: 1st detection only, does NOT necessarily mean successful dock)

batterylife {STRING}
Indicates state of battery charge. Will have ‘CHARGING’ appended if charging

powerport {STRING}
Indicates hardware USB port connected to Xaxxon Power PCB

batteryinfo {STRING}
Extended battery info, including individual cell charging + idle voltages, current amps, pack mAh remaining, other debugging information (see log output).

battvolts {FLOAT}
Current battery pack voltage

powererror {INT}
Indicates current power error code, 0 if no error

forceundock {BOOLEAN}
TRUE if Xaxxon Power PCB indicating a force un-dock state (error code >= 80)


javastartup {BOOLEAN}
Time of server application startup (in milliseconds since epoch)

linuxboot {BOOLEAN}
Time of last operating system boot (in milliseconds since epoch)

httpport {INT}
Web server HTTP port (default 5080)

lastusercommand {LONG}
Time of last command received by server (in milliseconds since epoch)

guinotify {STRING}
Short message that will be presented as GUI popup to next available driver. Deleted when user clicks ‘OK’

ssid {STRING}
Currently connected wifi network

cpu {INT}
Latest cpu usage reading, percentage. Result of cpu command

waitingforcpu {BOOLEAN}
Set to 'true' in response to waitforcpu command. Set to 'false' by system when cpu usage drops below 60% threshold, or after 20 seconds

osarch {STRING}
System architecture, typically 'amd64' for x86/64 systems or 'arm' for ARM systems


localaddress {STRING}
Local wifi LAN IP address

externaladdress {STRING}
External WAN IP address

gatewayaddress {STRING}
External gateway address

networksinrange {STRING}
List of all wifi networks in range, and their respective signal strengths, comma separated

networksknown {STRING}
List of all known wifi networks, comma separated

relayserver {STRING}
Hostname or IP address of relay server, if system is acting as relay client

relayclient {STRING}
IP address of relay client, if system is acting as relay server
(NOTE: when acting as server, this variable will be accessible to Oculusprime Java only, since read by state command will be relayed to client)


distanceangle {STRING}
Last odometry info received from MALG PCB. {STRING} takes the form “distance angle” where distance = distance (integer) moved in mm, and angle = angle (float) in degrees

direction {STRING}
Current movement direction (of wheel motors). Can be ‘stop,’ ‘right,’ ‘left,’ ‘forward,’ or ‘backward’

odometry {BOOLEAN}
TRUE if MALG PCB is reporting odometry information

distanceanglettl {STRING}
Cummulative odometry info (developer mode only, non-ROS with openni camera running). {STRING} takes the form “distance angle” where distance = distance (integer) moved in mm, and angle = angle (float) in degrees

stopbetweenmoves {BOOLEAN}
TRUE if force stop between moves is enabled (robot must come to a complete stop before changing to a different direction, for accurate odometry)

odometrybroadcast {LONG}
If not NULL, request odometry report from MALG PCB and broadcast to telnet stream every {LONG} milliseconds

odomturndpms {FLOAT}
If not NULL, enables adaptive target degrees-per-millisecond turn rate when odometry is enabled and state odometrybroadcast is set (to around 250ms)

odomturnpwm {INT}
Most recent motor speed PWM value used to achieve target odomturndpms (typically varies with battery level, floor surface type)

odomlinearmpms {FLOAT}
If not NULL, enables adaptive target meters-per-millisecond linear speed rate when odometry is enabled

odomlinearpwm {INT}
Most recent motor speed PWM value used to achieve target odomlinearmpms (typically varies with battery level)

rosmapinfo {STRING}
Provided by ROS node ‘,’ used by javascript to render map. {STRING} takes the form ‘width height res originx originy originth updatetime’

rosamcl {STRING}
Estimated location on map info, provided by ROS node ‘,’ used by javascript to render map

rosinitialpose {STRING}
Read by ROS node ‘,’ to set current location on map (X_Y_TH)

rosglobalpath {STRING}
Global path set of points, provided by ROS node ‘,’ used by javascript to render map

rosscan {STRING}
Set of laser scan points, provided by ROS node ‘,’ used by javascript to render map

rossetgoal {STRING}
Read by ROS node ‘,’ to send goal pose to move_base action server

roscurrentgoal {STRING}
Current goal pose of ROS navigation system (X,Y,TH)

rosgoalstatus {STRING}
Current state of move_base action server, provided by ROS node ‘,’ typically NULL, ‘succeeded’ or ‘aborted’

rosgoalcancel {BOOLEAN}
If set to TRUE, will be read by ROS node ‘,’ and current goal will be canceled

rosmapupdated {BOOLEAN}
TRUE if change to map detected by ROS node ‘’

rosmapwaypoints {STRING}
Waypoint data, matching text in file ‘oculusPrime/conf/waypoints.txt’

roswaypoint {STRING}
Name of last waypoint set as navigation goal

nextroutetime {LONG}
Time of next route start (in milliseconds since epoch)

rosarcmove {BOOLEAN}
If TRUE, ROS navigation can move forward and turn at the same time, instead of only using turn-in-place moves. Enabled by usearcmoves setting and toggled by arcpwmthreshold setting

NEXT: Python Module

← back to Oculus Prime Contents

CART 0 items | US$
    Check Order Status
Follow →
instagram twitter facebook youtube
@XaxxonTech Twitter
© 2023 Xaxxon
Products Documentation Downloads Source Code
Warranty & Returns About Us Contact/Support News
instagram twitter facebook youtube