Skip navigation

Skip secondary navigation

Automation Interface

The SOS automation interface (also known as the show floor control protocol) is available via a TCP connection to the main SOS system. This interface allows extensive control of the operation of SOS by an external computer, as a coordinated part of a larger exhibit. For example, SOS could be sychronized with films or Powerpoint display programs, controlled by an interactive kiosk, or run on an automatic daily schedule of timed presentations.

Establishing and Using a Connection

To use the SOS Automation Interface, establish a TCP connection to socket 2468 on the main SOS host. The SOS Automation Interface uses an ASCII line-oriented protocol. Each command is a single line of text. Every command will result in a response from the SOS system. After establishing the TCP connection, it may be kept open and used for multiple commands, but the very first command must be the word "enable". This is neither an actionable command nor a real password, but is used as a simple-minded way to avoid dealing with random socket probes and scans.

Command responses are also ASCII and line-oriented. The error response is the letter "E" (for Error) followed by a two-digit error code, all on a single line. Future error codes may be more precise, but at present this is almost always the string "E04".

The default successful command response is the letter "R" (for Ready) on a single line. This indicates successful completion of commands that have no return value (e.g. stop). It also indicates success and the end of the list for commands that return more than one line (e.g. get_clip_info *). Commands that always return a single line of information (e.g. get_frame_count) return only that line of information in the successful case, and don't return an "R" character.

Command Summary (Version 2.1.x)

Here is a list of the available commands.

  • help
  • shutdown
  • open_playlist playlist_file
  • play [clip_number]
  • stop
  • next_clip
  • prev_clip
  • pause
  • step n_frames
  • skip frame_number
  • set_frame_rate fps [first_dwell_ms last_dwell_ms]
  • set_tilt x [y] [z]
  • get_animating
  • get_frame_count
  • get_frame_number
  • get_clip_count
  • get_clip_number
  • get_clip_info [clip_number|*]
  • get_frame_rates
  • get_tilt
  • identify [on|off]
  • alignment [alignment_command]
  • texture filename
  • load filename|dirname
  • set_auto_presentation_mode [0|1]
  • pic_mute
  • rotate_projectors
  • exit

Command Summary (Version 3.2.x)

Here is a list of available commands.

  • help
  • shutdown
  • open_playlist playlist_file
  • get_playlist_name
  • play [clip_number]
  • stop
  • next_clip
  • prev_clip
  • pause
  • step n_frames
  • skip frame_number
  • set_frame_rate fps [first_dwell_ms last_dwell_ms]
  • set_tilt x [y] [z]
  • get_animating
  • get_frame_count
  • get_frame_number
  • get_clip_count
  • get_clip_number
  • get_clip_info [clip_number|*]
  • get_frame_rate
  • get_tilt
  • identify [on|off]
  • alignment [alignment_command]
  • load filename|dirname
  • background filename
  • set_auto_presentation_mode [0|1]
  • pic_mute
  • rotate_projectors
  • pip filename
  • piptimer seconds
  • pipdelay seconds
  • pipwidth width (pip width in degrees of longitude)
  • pipheight height (pip height in degrees of latitude)
  • pipalpha value [0 to 1]
  • pipfadein seconds
  • pipfadeout seconds
  • pipvertical value (vertical placement in degrees)
  • piphorizontal value (horizontal placement in degrees)
  • pipstyle [projector|globe|room]
  • pipcoords lat,lon
  • pointer [on|off|onoff|red|green|grab|ungrab|lat,lon|Dlat,lon]
  • pointersize degrees
  • pointerimage filename
  • audio [mute|unmute|toggle|up|down]
  • set_simage [0|1]
  • zrotationenable [0|1] (enable sphere rotation. 0=disable, 1=enable - default:0)
  • zrotationtoggle (toggle the state of the zrotationenable flag)
  • zfps fps (set fps for zrotation - default: 30)
  • zrotationangle angle (set increment angle for zrotation - default: 0.1)
  • get_state timestamp
  • exit

Example

Here is a trivial example of the automation interface, using telnet to establish an interactive session. Commands typed by the user are shown in bold.

[sos@pt-nc ~]$ telnet localhost 2468
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
enable
R
help

            Available Commands:
            help
            shutdown
            open_playlist playlist_file
            play [clip_number]
            stop
            next_clip
            prev_clip
            pause
            step n_frames
            skip frame_number
            set_frame_rate fps [first_dwell_ms last_dwell_ms]
            set_tilt x [y] [z]
            get_animating
            get_frame_count
            get_frame_number
            get_clip_count
            get_clip_number
            get_clip_info [clip_number|*]
            get_frame_rates
            get_tilt
            identify [on|off]
            alignment [alignment_command]
            texture filename
            load filename|dirname
            set_auto_presentation_mode [0|1]
            pic_mute
            rotate_projectors
            set_simage [0|1]
            exit
        
R
get_clip_info *
1 Hot Topo (Wild Fires)
2 2004 Hurricane Season
3 NCDC SST Anomaly (1980 - 1999)
4 GFDL CO2 x 4
5 X-Ray Sun
6 Red Mars (23 degree tilt)
7 Paleo Geographic
8 BlueMarble (23 degree tilt)
9 ACARS track 24hr time seq (45 degree) 07-21-04
10 Indian Tsunami V3
11 NOAA Logo over EC
R
get_clip_number
10
get_frame_count
420
get_frame_number
243
get_frame_number
284
exit
Connection closed by foreign host.
[sos@pt-nc ~]$