TELNET PROTOCOL

Section: FreeVR Telnet/Socket Interface (7fv)
Updated: 12 June 2022
Index Return to Main Contents

NAME

FreeVR Telnet/Socket Interface — FreeVR's protocol for interfacing with a live application via sockets

DESCRIPTION

The FreeVR system provides a special process type that permits live access to a running VR application. This access is done through the use of a socket interface to that special process which parses inputs and either modifies the current configuration or status of the FreeVR application — such as stereoscopic vs. monoscopic rendering — or provides access to internal information about the running VR system.
As the telnet command is typical tool for interacting over socket communications links, this FreeVR process type is called the telnet process. But there are also other tools that enable socket access can also be used, such as the "netcat" command, or even socket interfaces from scripted and compiled languages such as TCL, Python or C/C++. (Such as the included "fvri.tcl" program.)
Examples of how to use these tools as well as the command protocol for interacting with FreeVR are provided herein.

CONFIGURATION

The FreeVR system must be configured to include a telnet (aka socket) process to enable this feature — the default system configuration does not include a telnet process because of the open nature of the socket communication. (There is no function that would provide a Trojan horse opportunity to a second party that might connect with someone's running application, but it would generally still be an undesirable to permit external users free access to the system.)
While the default system does not include a telnet process, there is a pre-defined, but unused telnet process description ("default-telnet") available to make it simple to add such a process. The typical place to enhance the default configuration is in a user's personal configuration file (~/.freevrrc).
Given that the $system variable contains the active system that will be engaged, the += operator can be used to augment the existing configuration, and thus add a telnet process. Thus the following lines added at the end of the configuration process will accomplish this:
    system $system += {
    procs += "default-telnet";
    }
(Note, because whitespace is ignored, that could be done on one line.)
The default port of the built-in telnet process is 3000, but this and other parameters can be altered by further modification to the configuration. Indeed, like all FreeVR process types.

ARGUMENT PARAMETERS
Like all FreeVR process types, argument parameters that are specific to the type of process are passed as a string via the args setting. Multiple argument settings can be specified by separating them with a semicolon. Thus the following will set both the port and the portrange values:
    args = "port = 4000; portrange = 0;";
(NOTE: the final semicolon terminates the args configuration statement.)
The available argument parameters are:

port <port number>;
The port option selects the numeric socket TCP endpoint at which the client should request the connection. The FreeVR default value is 3000. If the requested port is unavailable, depending on the value of the portrange parameter, either more ports will be searched (if portrange is positive), or the given port will be repeatedly attempted after a delay of 5 seconds (if portrange is zero or negative).
The telnet process will continue to request an available port until one is found, or until the application is terminated.

portrange <range number>
The portrange option sets the number of additional numeric socket TCP endpoints that the FreeVR telnet process will attempt to use before finding an available port. Thus, if the first port (as specified by the port parameter) is unavailable, the next port (port + 1) will be attempted, and continuing in sequence until range umber of additional ports have been tested, at which point the search will loop back to port.
NOTE: a portrange of 1 will alternatively search between the two ports port and port+1.

prompt <prompt string>
The prompt option sets the string that will be used to prompt a user for more input. The default prompt is "Freevr>". The prompt can be set to the empty string, which is useful when an automated process is communicating with the telnet process (though this is also accomplished by setting the machine print-style).

password <password string>
The password option sets the given string to be a required password entry before any commands will be recognized. Each new connection to the telnet process will require re-entry of the password.
NOTE: presently the password is both stored in clear-text form within the .freevrrc configuration file, as well as being shown as it is typed in when entered by the user. Lack of password hiding, in both cases, are listed as BUGS that need to be addressed.

USAGE

As the name implies, a common method of connecting to a FreeVR telnet process is with the telnet(1) command. Other options include the use of the netcat (or ncat) command line tool, or a sophisticated program or script using a language to automatically query and set values of a running FreeVR program. (Such as the included "fvri.tcl" program.)
Available commands are listed in the COMMANDS section below.

TELNET
The telnet command line tool can be used to establish a persistent connection with a FreeVR telnet process, and repeatedly enter commands, provide a response, and then wait for the next command.
When run on the same system as the application, the hostname can be specified as localhost, otherwise the assigned name or IP address of a computer can be given. By default FreeVR waits for a connection on port 3000, but this can be altered by the configuration.
Here is a simple telnet session:
    % telnet localhost 3000
    Enter FreeVR password> my-passw0rd
    FreeVR> echo $version
    v0.7e
    FreeVR> ^]
    telnet> quit
    %
NETCAT / NCAT
The netcat command line tool, or it's functional replacement ncat, both use the command line name nc. Typically only one will be installed on a system, and requesting the nc(1) manpage will inform which, if either, is installed. (While some of the arguments between the two differ, the simple examples here will work with either.)
The nc tool takes input via stdin (standard-in), and provides output to stdout (standard-out), so operation on the command line often will use the echo or cat tools to pipe commands to nc.
Note that when using FreeVR telnet variables, the '$' character will be first processed by most shells. Thus it must be protected from shell interpretation. Shell protection can usually be provided by "escaping" the '$' with a backslash — ie. "\$", or putting the entire command string within single-quotes.
Here are some typical uses — shown without the FreeVR response:
    % echo 'echo $version' | nc localhost 3000
    % echo "echo \$version" | nc localhost 3000
    % echo 'machine; print ui' | nc localhost 3000
    % echo "set inputdevice[1] nudget2rwT 2 0 1" | nc localhost 3000
    % echo 'term' | nc localhost 3000
When there is a password, it must be separated from the first command by an end-of-string marker, which is the NUL character, represented in octal as "\0". The echo command in most UNIX-style terminal shells requires the "-e" option to pass special characters, thus an example of sending a command to a password protected telnet process is:
    % echo -e 'my-passw0rd\0echo $version' | nc localhost 3000
Program Interface

It is also possible to use the telnet process to communicate with a running FreeVR application though an external program. This program may be written in any language that has a socket API, including TCL, Python, C or C++.
As with the command line tools, simply use the socket API to make a connection to the specific host and port, and then send commands over that socket.
Typically, for the programmatic interface, having a prompt returned after every command is a nuisance, thus there is a special machine print-style that will forgo sending the prompt.
As the socket API is language dependent for each language, no explicit example is provided here. However, the *fvri.tcl* (FreeVR Remote Interface) program provides an example program written in TCL that has a GUI that can be used to monitor the live application, including via the looping (frame) rate for each process, and the travel location for each user. It can also enable various on-screen displays (OSDs) such as FPS or overall process timing statistics, or set the near and far clipping planes. Other possible, but not yet implemented in "fvri.tcl", commands are to nudge the window and input device coordinates.

COMMAND PROTOCOL

The primary use of the FreeVR telnet/socket interface is to query and set values of the running system, and thus the most robust commands are print and set. Of course, there are several other commands that deal with the socket communication line itself, and then there are a few that provide special utility features.
The sub-commands to print and set are sufficiently numerous, that the following two sub-sections will provide details.
NOTE: case is ignored in all commands, even when shown otherwise in the manual or the help (any capitalization is for readability).

TOP-LEVEL COMMANDS

? or help
The help command outputs the top-level list of commands with a one-line description.

!! or !<n> or !<-n>
The "bang" / re-execute command re-executes a previous command sent to the telnet process. The !! (or "bang-bang") variant repeats the immediately preceding command. The !<n> variant re-executes the Nth command executed by this telnet process. And the !<-n> variants re-executes the Nth command before now — in other words, going back in the command history from this point. (See also the history command to see what previous commands have been executed.)

barrier or b <request>
The barrier command (which can be abbreviated as just "b") provides access to the internal semaphore barriers within a running FreeVR application. The full list of possible telnet queries available is in a following sub-section on BARRIER and LOCK SUB-COMMANDS, however this list is also available by submitting "help" as the request string.

brief
The brief command changes the output's print-style to a shorter version than the full (verbose) output, but generally longer than the shortest output (one_line style). (See also the file, machine, one_line, and verbose commands.)

close
The close command closes the socket connection with the FreeVR telnet process. Further socket connections to the same port WILL be possible.

diagram
The diagram command changes the output's print-style to the special "diagram" method, which outputs information in a format suitable for the GraphViz (aka "dot") program to generate a node graph. (Presently this is only useful for printing the configuration.) (See also the brief, file, machine, and verbose commands.)

echo <string>
The echo command simply repeats the given string, though with variable substitution performed, which makes it useful for requesting system information that is contained in any of the variables. (See the VARIABLES sub-section below.)

file
The file command changes the output's print-style to a format that can be used to create FreeVR configuration files. (See also the brief, machine, one_line, and verbose commands.)

history [<n>]
The history command outputs a list of previous commands from this telnet process. If the optional <n> argument is provided, only the previous <n> historical commands are output. (Note that the command history is not lost between multiple telnet or netcat sessions that communicate with the same telnet process.)

lock or l <request>
The lock command (which can be abbreviated as just "l") provides access to the internal locks within a running FreeVR application. The full list of possible telnet queries available is in a following sub-section on BARRIER and LOCK SUB-COMMANDS, however this list is also available by submitting "help" as the request string.

machine
The machine command changes the output's print-style to a format that can be easily parsed by an interactive software tool to simplify the implementation of such tools. It also disables the output of a prompt following each command. (See also the brief, file, one_line, and verbose commands.)

nudge
The nudge command is really just a special help output that lists all the commands related to making minor changes to the active configuration while an application is running. (See the sub-section on nudge commands below.)

one_line
The one_line command changes the output's print-style to the shortest amount of output (almost always) restricting the data to a single line. (See also the brief, file, machine, and verbose commands.)

pause
The pause command toggles between pausing and resuming the system simulation. While rendering and inputs continue to operate (as well as the telnet process), the main process, which handles the virtual world simulation and interactions will instead wait in a loop for the paused state to be cancelled. (Note that the paused state can be explicitly set to on or off using the set command.)

print or p <query>
The print command (which can be abbreviated as just "p") outputs the results of an information query into the live FreeVR application. The full list of possible telnet queries available is in the following sub-section, however this list is also available by submitting "help" as the query string.

printfile or pf [+]<filename> <query>
The printfile command (which can be abbreviated as just "pf", as with the print command, outputs the results of an information query into the live FreeVR application. However, it outputs this information to a file (or device such as a pseudo terminal). This can be useful when outputting information in configuration file format, which is to be used to create a new .freevrrc file. The optional + before the filename will open the destination <filename> in append mode.

printstyle or style [<style>]
The printstyle command can set the current printing output style (e.g. "brief", "verbose", "machine", etc.) to any of the available styles. It will always return the (now) current value of the print-style, so one can query the current setting by executing this command with no argument.

quit
The quit command quits (terminates) the FreeVR telnet process with which it is communicating. All other aspects of the FreeVR application will continue to operate. Further socket connections to the same port will NOT be possible.

relbar <barrier-address>
The relbar command releases a barrier at the given address within a live FreeVR application. The address must point to a FreeVR barrier structure. This is a shortcut (alias) for command "barrier relonce <barrier-address>".

set or s <request>
The set command (which can be abbreviated as just "s") sets a particular setting within a running FreeVR application. The full list of possible telnet queries available is in a following sub-section, however this list is also available by submitting "help" as the request string.

setenv <variable name> <value>
The setenv command sets a system ENVIRONMENT VARIABLE to the given value. While this sets an actual system ENVIRONMENT VARIABLE, that variable is only in scope within the FreeVR telnet process. Thus, in practice, this is more like using a standard programming variable. (Note that presently, variables are only interpreted by the echo command, though with the intension that a future version will do variable substitution for all commands.)

status
The status outputs a small amount of information that gives an overview of the system's state of operation, and what significant devices it is connected to (windows, input devices, etc.). Information includes running time, whether the system is paused, a quick list of windows and input devices, as well as spawned threads. Objects that are not operating as expected are generally highlighted in red.

style or printstyle [<style>]
(See printstyle.)

term
The term command terminates the entire FreeVR application. Presently this works by activating the defacto default button used to terminate a FreeVR application. Note that because the telnet command line tool blocks on user input, FreeVR will generally wait for one more carriage return before it can cleanly terminate the telnet process.

unsetenv <variable name>
The unsetenv command removes the given <variable name> from the list of ENVIRONMENT VARIABLES. While this sets an actual system ENVIRONMENT VARIABLE, that variable is only in scope within the FreeVR telnet process. Thus, in practice, this is more like using a standard programming variable.

verbose
The verbose command changes the output's print-style to the fullest (most complete) amount of output, which may be quite lengthy for some queries. (See also the brief, file, machine, and one_line commands.)

PRINT SUB-COMMANDS

The print command outputs the results of an information query into the live FreeVR application. In general, these are aspects of the running system that are the result of how the system is configured, but there are a handful of commands that are derived from the application (the ui) and it's interaction state (e.g. the state of a particular input).
Note that most print commands are affected by the current print-style setting, with verbose producing the most output and *one_line* producing the least. Other settings are brief, file and machine. These are all top-level commands.
Of course, each of the following commands is preceded with" print" or just "p".

? or help
The help command outputs this list of available print commands with a one-line description for each.

context
The context command outputs the overarching context structure of the FreeVR library. This structure contains information on the application (e.g. author names, status, etc), as well as points to all the other important structures of FreeVR — configuration, input, callbacks — plus memory, and timing information.

config
The config command outputs details about the entire operating configuration, including the detailed output of all running processes. In verbose print-style, this can be quite long, as it also includes system trace messages as well as the current state of each process. In file print-style, the output should be usable as the input configuration file for the current running system.

defaults
The defaults command outputs the list of inheritable system settings and their default values as set at the global level within the configuration.

eyes or eye[<num>]
The eyes command outputs information about all eyes, or eyes[<num>] about a specific eye in the running FreeVR application.
The eye objects describe specifics for one set of rendering parameters. These include the user whose perspective the rendering should be from (both where their head is positioned, as well as using their travel matrix), whether to render from the left, right or center of the head (for stereoscopic or monoscopic viewing), which portion of the frame buffer to render into, and whether to do anaglyphic color masking. (Of course, two eyes, one from the left of the head, and the other from the right are needed for stereoscopic rendering.)
The plural eyes option prints a "one_line" description of each of the eyes in the system. This listing also reveals the numeric mapping of the eyes to their types and names, which can then be used to request detailed information about a specific eye.
The specific eye[<num>] option prints information about the particular eye as specified by <num>, which is a 0-based numbering of all the eyes. The amount and style of output for the specific eyes is based on the currently active "print-style".

eyelists or eyelist[<num>]
The eyelists command outputs information about all eyelists, or eyelists[<num>] about a specific eyelist in the running FreeVR application.
The eyelist objects describe specifics for how a window object should render for particular stereoscopic rendering modes (including none, aka monoscopic). Specifically, six different lists of eyes are specified, only one of which will be used depending on whether a window is set to render monoscopically, stereo using a quad-buffer framebuffer, stereo using separate viewports in a single framebuffer, or stereo using anaglyphic masking in a single framebuffer.
The plural eyelists option prints a "one_line" description of each of the eyelists in the system. This listing also reveals the numeric mapping of the eyelists to their types and names, which can then be used to request detailed information about a specific eyelist.
The specific eyelist[<num>] option prints information about the particular eyelist as specified by <num>, which is a 0-based numbering of all the eyelists. The amount and style of output for the specific eyelists is based on the currently active "print-style".

far
The far command outputs the current value of the rendering parameter for the *far clipping plane*. The given value is either the system level value, or if not specified by the system, then the global default value. See also the near output query.
Note that window objects can further override this value, and to view that value, each individual window should be queried.

inputs or input<input-descriptor>
The inputs command outputs information about all inputs, or inputs <input-descriptor> about a specific input in the running FreeVR application.
The input objects describe specifics for how particular user actions are interpreted by the system (as buttons, valuators, 6DOF sensors, etc.). Input objects are derived some an inputdevice object which handles the actual communication with the physical hardware (or data server).
The plural inputs option prints a "one_line" description of each of the inputs in the system, along with other input-related objects such as inputdevices, users, and props (which are not yet implemented). This listing also reveals the numeric mapping of the inputs to their types and names, which can then be used to request detailed information about a specific input.
The specific input <input-descriptor> option prints information about the particular input as specified by <input-descriptor>, which is both a type of an input along with a 0-based index of that type. For example, the first button (officially "2-way") input is "2-way[0]". The amount and style of output for the specific inputs is based on the currently active "print-style".

inputdevices or inputdevice[<num>]
The inputdevices command outputs information about all inputdevices, or inputdevices[<num>] about a specific inputdevice in the running FreeVR application.
The inputdevice objects describe specifics for how FreeVR interfaces with a collection of inputs that are physically implemented, or provided from a data server. In general, a single inputdevice will provide many different inputs, and often of different types, such as several buttons, a handful of valuators (perhaps from a joystick or trigger), and also some 6-dof position trackers (6-sensors in FreeVR-speak). Thus the specifics of an inputdevice include a listing of the available inputs, and how to map the hardware or server to different inputs, as well as how to communicate with the hardware or server, such as via socket connections or serial ports.
The plural inputdevices option prints a "one_line" description of each of the inputdevices in the system. This listing also reveals the numeric mapping of the inputdevices to their types and names, which can then be used to request detailed information about a specific inputdevice.
The specific inputdevice[<num>] option prints information about the particular inputdevice as specified by <num>, which is a 0-based numbering of all the inputdevices. The amount and style of output for the specific inputdevices is based on the currently active "print-style".

near
The near command outputs the current value of the rendering parameter for the *near clipping plane*. The given value is either the system level value, or if not specified by the system, then the global default value. See also the far output query.
Note that window objects can further override this value, and to view that value, each individual window should be queried.

object <type> list or object <type> <name>
The object command outputs information about what objects of a given type exist in the configuration, or about a specific object in the configuration. Unlike the other operations that output information about objects in the running system, this request will also show objects that are defined in the configuration, but not actually in use in the particular running instance. "Object' <type> options are callback, system, process, window, *eyelist*, user, and the special address type. Other types, such as input objects aren't included because they are not individually configured. (For live-created objects such as inputs, use the basic *print inputs* command instead.)
The object request with the list argument will, unsurprisingly, list all the configured objects of the given type. This list can provide the names used with a name request.
The object request with the name argument will give a detailed output of that particular object within the configuration.
The special address type allows access to any object in the live system, even those that are not part of the configuration process. These include locks, barriers and inputs. Instead of providing a "<name>" instead a memory address is given; this address is often found in the listings of other objects which point to the objects they depend on.

procs or proc[<num>]
The procs command outputs information about all processes, or procs[<num>] about a specific process in the running FreeVR application.
The process objects describe specifics for how the FreeVR multiprocessing is performed. A VR system requires multiple disparate operations that are generally handled in independent processes (or threads). Thus, this first distinguishing feature of a process object is the aspect of the system that it handles (rendering, input/output, socket communications(!), or simulation). Internally, process objects handle things like barrier synchronization, keeping track of timing statistics, etc. Externally, process objects have lists of other objects that they manage, such as a rendering process will have a list of windows, whereas an input process will have a list of inputdevices. Also each process will have features such as how much (and in what color) debugging output to produce.
Finally, related to debugging output, each process keeps a (short) list of the previous 40 internal trace operations performed within. Process objects printed with the verbose print-style will output this entire list, which can be useful for debugging or profiling the operation of a VR application.
The plural procs option prints a "one_line" description of each of the processes in the system. This listing also reveals the numeric mapping of the processes to their types and names, which can then be used to request detailed information about a specific process.
The specific proc[<num>] option prints information about the particular process as specified by <num>, which is a 0-based numbering of all the processes. The amount and style of output for the specific processes is based on the currently active "print-style".

settings
The settings command outputs the list of inheritable system settings and their default values as set at the system level within the configuration.

shmem
The shmem command outputs basic information about the state of the shared memory system, such as the size of the memory, the current usage, and also how much has been used and freed over time.

system
The system command outputs basic details from the system structure within the running FreeVR application. This output includes the items which comprise how a system is configured, which primarily is the lists of processes, but also includes settings such as rendering mode, near and far clipping plane, etc.

ui
The ui command outputs application-specific user-interface operations. These are mappings from FreeVR inputs to actions within the application.
NOTE: the application is responsible for actually providing the description for the actions of each input. Inputs that aren't explicitly described by the application are not listed in this output.

users or user[<num>]
The users command outputs information about all users, or users[<num>] about a specific user in the running FreeVR application.
The user objects describe specifics for the person for whom (from whose perspective) the virtual world is rendered. On the configuration side, the primary parameter is the inter-ocular-distance (IOD) between the pupils. There is also the ability to set the user's simulator representation (avatar) to a particular color. In the running system the user object also points to a 6-sensor input tied to the user's head movements, the user's travel matrix, as well as near and far clipping plane override values. User objects are also used to link eye objects to the proper rendering parameters.
The plural users option prints a "one_line" description of each of the users in the system. This listing also reveals the numeric mapping of the users to their types and names, which can then be used to request detailed information about a specific user.
The specific user[<num>] option prints information about the particular user as specified by <num>, which is a 0-based numbering of all the users. The amount and style of output for the specific users is based on the currently active "print-style".

windows or window[<num>]
The windows command outputs information about all windows, or windows[<num>] about a specific window in the running FreeVR application.
The window objects describe both where in space (the coordinate system), and how to render the virtual world, as well as what on-screen-displays (OSDs) to overlay onto the view. It also points to the eyes of an eyelist which are to be rendered from their particular perspective.
The plural windows option prints a "one_line" description of each of the windows in the system. This listing also reveals the numeric mapping of the windows to their types and names, which can then be used to request detailed information about a specific window.
The specific window[<num>] option prints information about the particular window as specified by <num>, which is a 0-based numbering of all the windows. The amount and style of output for the specific windows is based on the currently active "print-style".

SET SUB-COMMANDS
The set command alters some values of a running (live) FreeVR application. Often these changes are just cosmetic, but a handful of these will have an impact on the quality of the VR experience.
Note that some set commands will respond back with information about the operation, and that this response can be affected by the current print-style setting. The verbose print-style will produce the most output and *one_line*, the least. Often the lower settings will result in no response presented, which is generally what is preferred when a program is interfacing with the telnet process.
Of course, each of the following commands is preceded with "set" or just "s".
? or help
The help command outputs this list of available set commands with a one-line description for each.

debuglevel|dl <value> or debuglevel[<num>] | dl[<num>]
As described in the "debug(1)" manpage, FreeVR has a myriad number of debug levels of detail, allowing the user to finely control how much informational output the receive from the system as an application is running. This level of detail can be set for the entire system, or any process can override the global setting.
The standard debuglevel operation sets <value> as the overall level of debug output detail for the system.
The debuglevel[<num>] operation sets <value> as the level of debug output detail just for the process <num>.

debugthistoo|dtt <setting>
As with the debuglevel settings, the "debug(1)" manpage describes the possible information that can be included or excluded from the FreeVR level of detailed output regarding the operation of the system. In the case of the debugthistoo setting, only the single additional classification of information is added to that output.
The standard debugthistoo operation sets <value> as the overall single debug output detail for the system.
The debugthistoo[<num>] operation sets <value> as the level of debug additional output detail just for the process <num>.

far <value>
The far setting command simply sets the global value of the system's far clipping plane.

input <name> <setting>
There are a variety of settings that can be made to an input. Not all input types can presently be manipulated via the telnet interface. Also, the current version of FreeVR has manipulations only for the 6-sensor (position tracking) types of inputs. Additional <setting> options and input types are added as they are found to be useful.
Available input settings are:

• input <6-sensor> id
Set the given 6-sensor's current 4x4 matrix to the identity matrix.

• input <6-sensor> loc <x> <y> <z>
Set the given 6-sensor's current 4x4 matrix to have the translation vector (<x> <y> <z>), without altering the rotation component of the matrix.

• input <6-sensor> move <x> <y> <z> <az> <el> <ro>
Move the given 6-sensor's current 4x4 matrix by the vector (<x> <y> <z>), and rotate it by the Azimuth <az>, Elevation <el>, and Roll <ro>.

• input <6-sensor> { nudger2eA | nra } id
Set the given 6-sensor's "r2e" (Receiver to Entity) rotation component (*Angles*) of the transform matrix to the identity matrix.

• input <6-sensor> { nudger2eA | nra } <el> <az> <ro>
Rotate the given 6-sensor's "r2e" (Receiver to Entity) transform matrix Angles by the Euler rotations <el> <az> <ro>.

• input <6-sensor> { nudger2eT | nrt } id
Set the given 6-sensor's "r2e" (Receiver to Entity) translation component to the identity matrix.

• input <6-sensor> { nudger2eT | nrt } <x> <y> <z>
Translate the given 6-sensor's "r2e" (Receiver to Entity) translation component by the vector (<x> <y> <z>).

inputdevice[<num>] <setting>
There are a couple settings that can be made to an inputdevice. The inputdevice settings are separate from the inputs themselves, and generally need to adjust the overall coordinate system of an entire input system.
Available inputdevice settings are:

• inputdevice[<num>] { nudget2rwA | nta } id
Set the given inputdevice's "t2tw" (Transmitter to Real-World) translation component to the identity matrix. Where transmitter can be interpreted as the origin of the position tracking system (which may or may not be an actual transmitter). The "t2rw" value is used to align position trackers with the overall coordinate system assigned to the VR system.

• inputdevice[<num>] { nudget2rwT | ntt } <x> <y> <z>
Move the given inputdevice's "t2tw" (Transmitter to Real-World) translation by the vector (<x> <y> <z>). Where transmitter can be interpreted as the origin of the position tracking system (which may or may not be an actual transmitter). The "t2rw" value is used to align position trackers with the overall coordinate system assigned to the VR system.

near <value>
The near setting command simply sets the global value of the system's near clipping plane.

object <object> <command>
The object command allows normal set commands to be applied to a configuration object regardless of whether it is in the running system. To do this, the object is referenced by its type and name. Presently only the window object type is implemented, and the usual usage for this is to turn on/off the window's frame rendering within the simulator view.
Available configuration object settings are:

• object window[<name>] <any window set command>
Apply <any window set command> to window named <name> in the configuration.

pause { 0 | 1 }
The pause setting command simply sets the global pause state to given value, where 1 pauses the simulation of a running system and 0 sets the system to be run the simulation.
NOTE: this feature depends on the application making use of the vrFrame() call in the update loop.

proc[<num>] <setting>
The proc setting command has several aspects of a running process that can be affected through the telnet interface.
Available process settings are:

• proc[<num>] end <value>
Set the given process' request to terminate to <value>. Of course, if the value is 0 (zero), then nothing will change. (So perhaps the argument isn't necessary.)

• proc[<num>] term <value>
Set the given process' terminated flag to <value>. Of course, if the value is 0 (zero), then nothing will change. Also, if the value is 1 (one), then the system thinks the process is terminated, but it may in fact continue to run. (So there are probably limited uses of this command.)

• proc[<num>] usec <value>
Set the given process' minimum frame delay to <value> microseconds (usecs). Each process will make sure that its own minimal looping time will at least be the usec set for it. The default usec value for FreeVR processes is 1000 (though this can be overridden by the configuration settings).

• proc[<num>] printcolor <value>
Set the given process' message output color to <value>, where <value> is one of the standard 16 ANSI codes for text color. (For example, green is "32", and blue is "34".)

• proc[<num>] stats_calc <value>
Set the given process' flag of whether to calculate statistics to be on (1) or off (0). Generally there is no need to disable the calculation of statistics.

• proc[<num>] stats_show <value>
Set the given process' flag of whether to be included in the on-screen-display.
By default each window prints it's own rendering statistics, with the primary window showing it's own, plus all non visren statistics. Note: this setting does not override the on-screen-display (OSD) setting, so the overall statistics display must be set on first.

• proc[<num>] stats_mask <value>
Set the given process' flag of which statistics values to show on the on-screen-display.
The mask is dependent on the type of process for which the statistics are being displayed. The labels for each process can be obtained by printing a particular process with the verbose print-style, and examine the "elem_labels" field of the ProcStats structure at the end of the output.
Presently, these elements are, for each process type:

   ♦ main:
sim-1, sim-2, paused, sleep

   ♦ input:
<inputdevice-1>, ... <inputdevice-N>, sleep, sync, freeze

   ♦ visren:
init, frame, render-1, render-2, info-render, wait, sync, freeze, swap

   ♦ telnet:
<none available>

• proc[<num>] stats_yloc <value>
Set the given process' statistics rendering height (Y) location to <value>. The <value> is floating point and should be between 0.0 (bottom) and 1.0 (top). Note though that this value is where the bottom of the statistics graph will be rendered, so putting the value too high will push portions of the graph off the top of the screen.

• proc[<num>] stats_top <value>
Set the given process' statistics bar scales to only go as high as <value>. The <value> argument is floating point, as has a unit of milliseconds, so 1.0 is 1 millisecond. Note that this does not affect the scale of the statistics graphs.

• proc[<num>] stats_interval <value>
Set the given process' statistics horizontal bar scale markers to be every <value> of time. The <value> argument is floating point, as has a unit of milliseconds, so 1.0 is 1 millisecond. The default value is every 20 microseconds, or 0.02 milliseconds.

• proc[<num>] stats_scale <value>
Set the given process' statistics vertical scale (time) to <value>. Where a <value> of 1.0 is the default, and takes approximately 30% of the windows's height.

• proc[<num>] stats_color <red> <green> <blue>
Set the given process' statistics background layer to the color indicated by the <red>, <green>, and <blue> color values which are each in the range of 0.0 to 1.0.

• proc[<num>] stats_opac <value>
Set the given process' statistics background layer opacity to <value>. Where <value> is from 0.0 (totally transparent) to 1.0 (totally opaque).

user[<num>] <setting>
The user setting command can affect two aspects of a running process related to the user — one of which is only apparent in a simulator view, the other of which is quite important for proper stereoscopic rendering.
Available user settings are:

• user[<num>] iod <value>
Set the user's Inter-Ocular Distance (IOD), which is the space between the pupils to the given <value>. The units for the iod are feet, and the default value is 0.23', which is 70.1mm.

• user[<num>] color <red> <green> <blue>
Set the given user's color representation in the simulator view to the color indicated by the <red>, <green>, and <blue> color values which are each in the range of 0.0 to 1.0.

window[<num>] <setting>
The window setting command can affect many aspects of how the world is rendered to a screen, along with several on-screen-display (OSD) parameters.
Available window settings are:
• window[<num>] brm <value>
Sets the brm (back polygon rendering mode) of the given window. As with the frm setting, this affects how the back-facing polygons are rendered. See the frm entry for more details.

• window[<num>] fps { 0 | 1 }
The fps (Frames Per Second), aka "frame-rate" setting controls whether the frame rate appears as an on-screen-display (OSD) on the given window (1) or not (0).
Note: the fps OSD can also be toggled with the * key on the numeric keypad.

• window[<num>] fps_color <red> <green> <blue>
Set the color of the given window's fps (Frame Rate) to the color indicated by the <red>, <green>, and <blue> color values which are each in the range of 0.0 to 1.0.

• window[<num>] fps_loc <x> <y>
The fps (Frames Per Second) setting controls where the frame rate appears as an on-screen-display (OSD) on the given window. The two values <x> and <y> are normalized to the sides of the window, with (0.0, 0.0) at the lower right, and (1.0, 1.0) at the upper left. The default location is (0.10, 0.10).

• window[<num>] frame { 0 | 1 }
Turns the frame rendering of the given window on (1) or off (0) in all the other windows. This is particularly useful when viewing a configuration in a simulator view to see where windows are with respect to the coordinate systems of the input devices.

• window[<num>] frm <value>
Sets the frm (front polygon rendering mode) of the given window. This is a parameter to the OpenGL glPolygonMode() function for how the rasterization of the front of polygons are interpreted. From the gl.h header file, the three value options for <value>, which are appropriate are:

   ♦
GL_POINT — 0x1B00
   ♦
GL_LINE — 0x1B01
   ♦
GL_FILL — 0x1B02

• window[<num>] nudgex <x>
The nudgex setting shifts the given window in the x-direction by <x> amount. This is generally used for tweaking the configuration.

• window[<num>] nudgey <y>
The nudgey setting shifts the given window in the y-direction by <y> amount. This is generally used for tweaking the configuration.

• window[<num>] nudgez <z>
The nudgez setting shifts the given window in the z-direction by <z> amount. This is generally used for tweaking the configuration.

• window[<num>] sim <move|mask command>
The sim command changes the view in a simulator window. Thus the given window should be of type simulator.
The available movement commands are:

   ♦
away — Push the simulator view away by 0.5 feet (as if walking out of a CAVE).
Note: this is the same functionality as the + key on the numeric keypad.

   ♦
toward — Pull the simulator view forward by 0.5 feet (as if walking into a CAVE).
Note: this is the same functionality as the - key on the numeric keypad.

   ♦
center — Reset the simulator view to the center position.
Note: this is the same functionality as the 5 key on the numeric keypad.

   ♦
sethome — Set a home view that can be jumped back to later.
Note: this is the same functionality as the Enter key on the numeric keypad.

   ♦
gohome — Jump back to the previously set home view (or the center if no home view has been set).
Note: this is the same functionality as the 7 key on the numeric keypad.

   ♦
posy — Rotate the view in the positive Y-direction. I.e. as if turning your body right in a CAVE.
Note: this is the same functionality as the 4 key on the numeric keypad.

   ♦
negy — Rotate the view in the negative Y-direction. I.e. as if turning your body left in a CAVE.
Note: this is the same functionality as the 6 key on the numeric keypad.

   ♦
posx — Rotate the view in the positive X-direction. I.e. as if tilting your head down.
Note: this is the same functionality as the 8 key on the numeric keypad.

   ♦
negx — Rotate the view in the negative X-direction. I.e. as if tilting your head up.
Note: this is the same functionality as the 2 key on the numeric keypad.

The available simulator mask commands are:

   ♦
toggle — Toggle the on-screen-display of the simulator elements — the simulator on-screen-display (OSD). This toggles just bit-0 of the simulator mask flags which controls the overall display flag. (i.e. it is the same as s window[0] sim mask togglebit 0.)
Note: the simulator OSD can also be toggled with the 0/Ins key on the numeric keypad.

   ♦
togglebit < bit-number > — Toggle a particular bit of the simulator render mask. Starting with bit-0, flags are: anything | CAVE outline | CAVE surface | Lighting | Head sensor | Other sensors | Sensors-as-solid | Sensor axes | InputDev axes | Window outlines | Window Frustums.
For example, to toggle the rendering of frustums on window[0]:
    FreeVR>s window[0] sim togglebit 10
♦
mask < mask-value > — Set the simulator render mask to a particular value. In other words, the or'd-together compilation of all the mask bits. The mask-value can be in decimal, hexadecimal (0x) or binary (0b) form. See togglebit (above) for the bit meanings. The default value of the mask is 0xFFFF.

♦
Simulator Mask Bits:
    bit  0 (0x0001) — Anything/Nothing
    bit  1 (0x0002) — Cave Outline
    bit  2 (0x0004) — Cave Surface
    bit  3 (0x0008) — Lighting
    bit  4 (0x0010) — Sensor Head
    bit  5 (0x0020) — Sensor Other
    bit  6 (0x0040) — Sensor Solid
    bit  7 (0x0080) — Sensor Axes
    bit  8 (0x0100) — Input Device Axes
    bit  9 (0x0200) — Window Outlines (and frustums)
    bit 10 (0x0400) — Window Frustums
• window[<num>] stats { 0 | 1 }
The stats (statistics) setting controls whether the statistics on-screen-display (OSD) is enabled (1) or not (0) on the given window.
Note: the stats OSD can also be toggled with the 9/PgUp key on the numeric keypad.

• window[<num>] ui { 0 | 1 }
The ui (User Interface) setting controls whether the interface documentation appears as an on-screen-display (OSD) on the given window (1) or not (0).
Note: the ui OSD can also be toggled with the ./Del key on the numeric keypad.

• window[<num>] ui_color <red> <green> <blue>
Set the color of the given window's ui (User Interface) documentation to the color indicated by the <red>, <green>, and <blue> color values which are each in the range of 0.0 to 1.0.

• window[<num>] ui_loc <x> <y>
The ui (User Interface) setting controls where the interface documentation appears as an on-screen-display (OSD) on the given window. The two values <x> and <y> are normalized to the sides of the window, with (0.0, 0.0) at the lower right, and (1.0, 1.0) at the upper left. The default location is (0.15, 0.90).

• window[<num>] world { 0 | 1 }
The world setting controls whether the entire virtual world is enabled (1) or not (0) on the given window, but only if that window is a simulator view.
Note: the stats OSD can also be toggled with the 0/End key on the numeric keypad — it's the end of the world as we know it.
NUDGE SUB-COMMANDS

The nudge command itself is, as indicated above, merely a special version of the help output that lists all the possible commands that permit the user to make slight tweaks (nudges) to the running system/application.
Those available nudge operations are (perhaps redundantly) listed here:

nudge
The nudge command outputs this list of possible commands to nudge a live FreeVR application.

set input <6-sensor> { nudger2eA | nra } { id | <x> <y> <z> }
Shift the 6-sensor's r2e (receiver to entity) Euler angles, or set them to the identity rotation (id).

set input <6-sensor> { nudger2eT | nrt } { id | <x> <y> <z> }
Shift the 6-sensor's r2e (receiver to entity) translation, or set it to the identity translation (id).

set inputdevice[<num>] { nudget2rwA | nta } { id | <x> <y> <z> }
Shift the given input-device's t2rw (tracker to real-world) Euler angles or set them to the identity rotation (id).

set inputdevice[<num>] { nudget2rwT | ntt } { id | <x> <y> <z> }
Shift the given input-device's t2rw (tracker to real-world) translation, or set it to the identity translation (id).

set window[<num>] nudgex <value>
Shift the given window (selected by <num> number) along the X-axis by <value> amount.

set window[<num>] nudgey <value>
Shift the given window (selected by <num> number) along the Y-axis by <value> amount.

set window[<num>] nudgez <value>
Shift the given window (selected by <num> number) along the Z-axis by <value> amount.

BARRIER and LOCK SUB-COMMANDS

The barrier and lock top-level commands both take a handful of requests to query or alter an active barrier or lock in the running FreeVR application. Barriers and locks can be assigned names, which is good for debugging, but they are referred to in these commands by their memory addresses.
The use of these commands is generally reserved for low-level debugging of the FreeVR library itself.
Barrier sub-requests:

? | help
The help barrier-request outputs this list of possible barrier operations.

create
The create barrier-request creates a new barrier. This new barrier is intended for testing and debugging the FreeVR barrier system, or for learning how to use the other barrier commands.

decrement <barrier-address>
The decrement barrier-request subtracts one from the member count of the given barrier. Of course, this doesn't change how may processes think they are a member of the barrier, so if this is done without first incrementing the member count of the barrier, it will release once all-but-one of the members reach a sync point, not waiting for the final member (or more if the value is decremented to be more than one below the actual count).

increment <barrier-address>
The increment barrier-request adds one to the member count of the given barrier. Of course, this doesn't change how may processes think they are a member of the barrier, so if this is done without first decrementing the member count of the barrier, it will block at the next sync operation until the member count is decremented back to the correct result. (Or until a barrier relonce request is made on this barrier.)

num
The num barrier-request outputs the number of barriers in the active system.

print or p <barrier-address>
The print barrier-request outputs detailed information about the barrier at the given memory address.

printall or pa
The printall barrier-request outputs all the barriers in the system, each with a one-line summary with their address, name, and their current status.

relonce <barrier-address.
The srelonce barrier-request causes the barrier at the given address to be released immediately (and thus generally prematurely), without waiting for all the barrier's members to reach the barrier.

sync <barrier-address.
The sync barrier-request causes the barrier at the given address to wait for all the barrier's members to reach the barrier.

Lock sub-requests:

? | help
The help lock-request outputs this list of possible lock operations.

create
The create lock-request creates a new lock. This new lock is intended for testing and debugging the FreeVR lock system, or for learning how to use the other lock commands.

num
The num lock-request outputs the number of locks in the active system.

print or p <lock-address>
The print lock-request outputs detailed information about the lock at the given memory address.

printall or pa
The printall lock-request outputs all the locks in the system, each with a one-line summary with their address, name, and their current status.

relread or rr or ur<lock-address>
The relread lock-request releases (or unlocks) the read-state of the lock specified by the given address.

relwrite or rw or uw<lock-address>
The relwrite lock-request releases (or unlocks) the write-state of the lock specified by the given address.

setread or sr<lock-address>
The setread lock-request sets the read-state of the lock specified by the given address to true. Of course, if the lock is currently held in write-state, the lock can't be set for reading until the write-state is released.

setwrite or sw<lock-address>
The setwrite lock-request sets the write-state of the lock specified by the given address to true. Of course, if the lock is currently held in read-state or write-state, the lock can't be set for writing until both state are unset.

trace or t<lock-address> {<0> | <1>}
The trace lock-request sets the trace-flag on the lock specified by the given address. The trace-flag causes debugging output to be produced whenever that lock changes state in the running application.

VARIABLES

FreeVR variables contain information about a running application, which includes information about the current state of the application, or information about how it was compiled, or information about how the current system is configured. Variables always begin with the dollar symbol ($) followed by a name that hints as to its purpose. Presently variables are only expanded when used in the echo command, so they are primarily a means to request information from the system.
FreeVR Variables aren't exclusive to the FreeVR telnet process, they are also used by the system configuration.

$<env var name> — any system ENVIRONMENT VARIABLE in the telnet process

$arch | $binaryformat — OS/HW architecture

$author — author(s) of the FreeVR application

$appstatus — status of the current FreeVR application

$compile — compile string that includes information about when the library was compiled and information about the operating system it was compiled on.
$compile_options — the "-D" flags set when the FreeVR library was built

$debug_level — the current value at (and below) which debugging output will be provided

$debugthistoo — a single additional debug level that will be reported

$def_visrenmode — the default visual rendering mode

$freevrhomedir — the system location where config and other files can be found

$fullversion — longer name of the library version

$gfx_style — type of graphics library (currently only OpenGL)

$hostname|$machine — name of the machine application is running on

$memsize — size of the shared memory segment (in bytes)

$mp_style — the type of multi-processing API used by this FreeVR build (e.g. FORK)

$name — name of the FreeVR application

$sem_style — method of semaphores implementation

$sim_time|$time — the number of seconds that the simulation has been running (NOTE: paused time is subtracted out of this number)

$sock_style — method of sockets interface implementation (usually BSD)

$startup_error — a bitwise flag of errors that may have occurred on startup (0 is good)

$status — current status of the library (running, ended, etc.)

$system — the FreeVR system object that is active

$time_immemorial — the (unix-style) time of when the library was started

$version — short name of the version of the library

$wall_time — the current time as reported by the system's operating system

$win_style — type of windows used by this library (GLX vs. MSWindows)

ENVIRONMENT VARIABLES

There are no environment variables that affect the execution of the telnet process. However, any environment variables in the shell from which the application was run are available as FreeVR variables though the telnet/*socket* interface using the echo command.
It is possible, through the command interface, to set, unset, and echo ENVIRONMENT VARIABLES. However, these changes are only in scope within the FreeVR telnet process.

NOTES

The variables available through the socket interface are not restricted to this protocol alone, but are the same variables that are available in the .freevrrc configuration parsing.

The telnet process blocks at user input, this has two significant consequences:

The application won't quit until the user hits enter at the prompt, allowing the process to loop and discover that the termination flag has been set (so if you type the term command, hit enter twice).

The telnet process can't be in a loop with any real-time process or things will hang until the user next types a carriage return. Thus, the telnet process is specifically disabled in the single-thread variant of FreeVR.

NOTE: If there isn't a live socket connection, then the *telnet* process does not block — so either never having connected, or using the close command to disconnect, or when using the netcat connections, then the telnet process will not be blocking for user input.

EXAMPLE USES

Some potential uses of the telnet/socket interface are mentioned elsewhere in this document, but this is a sufficiently important topic to deserve its own enumerating list of uses. Likely there are other good uses as well, but these are clearly valuable reasons for using the telnet/socket interface.

Adjusting rendering parameters to improve the VR experience is perhaps the most important use is to correct measurements such as the user's Inter-Ocular Distance (IOD) — aka Interpupillary Distance (IPD) to produce proper stereoscopic rendering. Similar, but less crucial parameters are to set the near and far clipping plane.
Also, the telnet/socket interface can be used to turn on and off any of the on-screen-displays (OSDs).

Another common use is to make adjustments for the purpose of performing better photography of a VR application. The two operations that are generally helpful for photography are to disable stereoscopic rendering, and to pause the simulation with a perspective amenable for the camera.

In conjunction with the other uses, the telnet/socket interface can be sent commands from a voice recognition system, allowing a user in a CAVE (or HMD) to alter the system without typing commands.

Especially with a program that interfaces with the telnet/socket process, like the fvri.tcl program mentioned in the "Program Interface" section, a running system can be analyzed to see where bottlenecks are, or review internals of the system to help with performance analysis.

Especially with the nudge commands, a configuration that is close, but requires some minute tweaks can use the configuration nudge adjustments to home in on a perfect configuration. One the perfect configuration is attained, objects can be printed with the file print-style to output a configuration object to copy paste. Alternatively, just print the history list to see what changes were needed and apply those to the configuration.

When the configuration is not yet close, and things are not working as expected, then more of the command can be useful such as printing out the entire context or config objects, or individual processes to figure out what the issue is.

And finally, if you happen to be making code changes to the FreeVR library itself, printing and setting values of the internal structures can often help pinpoint the cause of various problems.

BUGS

The typed password should be hidden from view (but isn't).

The password mechanism should use a PGP method to avoid having the password revealed "in the clear" in the .freevrrc configuration file.

The history mechanism is persistent to the running program, so disconnecting and reconnecting to the same telnet process will maintain the past history.

The telnet process blocks at user input. The consequences of this are that FreeVR may appear to hang when quitting and the telnet process is awaiting input; and that the telnet loop cannot be in series with any other process. (See also the NOTES section above where these are discussed in more detail.).

TODO

Better password management as flagged in the BUGS section.

Variable parsing/expansion should be performed on every command, not just the echo command.

Add the ability to make a setting across all objects of a particular type — such as perform at nudgex operation on all windows in one command.

It might be nice to have an aliasing feature that could be used to shorten frequently used commands. The relbar command is essentially a built-in alias.

It might be useful to allow the application to intercept the telnet/socket commands and have first rights to use them.

LOCATION

The telnet process is implemented in the source code" vr_telnet.c" file. Thus that file contains all the parsing and executing code for the parameters and commands.