Scripting API Guide

This document provides the information necessary to write test procedures using the COSMOS scripting API. Scripting in COSMOS is designed to be simple and intuitive. The code completion ability for command and telemetry mnemonics makes Script Runner the ideal place to write your procedures, however any text editor will do. If there is functionality that you don't see here or perhaps an easier syntax for doing something, please submit a ticket.

Concepts

Programming Languages

COSMOS scripting is implemented using either Ruby or Python. Ruby and Python are very similar scripting languages and in many cases the COSMOS APIs are identical between the two. This guide is written to support both with additional language specific information found in the Script Writing Guide.

Using Script Runner

Script Runner is a graphical application that provides the ideal environment for running and implementing your test procedures. The Script Runner tool is broken into 4 main sections. At the top of the tool is a menu bar that allows you to do such things as open and save files, perform a syntax check, and execute your script.

Next is a tool bar that displays the currently executing script and three buttons, "Start/Go", "Pause/Retry", and "Stop". The Start/Go button is used to start the script and continue past errors or waits. The Pause/Retry button will pause the executing script. If an error is encountered the Pause button changes to Retry to re-execute the errored line. Finally, the Stop button will stop the executing script at any time.

Third is the display of the actual script. While the script is not running, you may edit and compose scripts in this area. A handy code completion feature is provided that will list out the available commands or telemetry points as you are writing your script. Simply begin writing a cmd( or tlm( line to bring up code completion. This feature greatly reduces typos in command and telemetry mnemonics.

Finally, the bottom of the display is the log messages. All commands that are sent, errors that occur, and user print statements appear in this area.

Telemetry Types

There are four different ways that telemetry values can be retrieved in COSMOS. The following chart explains their differences.

Telemetry Type	Description
Raw	Raw telemetry is exactly as it is in the telemetry packet before any conversions. All telemetry items will have a raw value except for Derived telemetry points which have no real location in a packet. Requesting raw telemetry on a derived item will return nil.
Converted	Converted telemetry is raw telemetry that has gone through a conversion factor such as a state conversion or a polynomial conversion. If a telemetry item does not have a conversion defined, then converted telemetry will be the same as raw telemetry. This is the most common type of telemety used in scripts.
Formatted	Formatted telemetry is converted telemetry that has gone through a printf style conversion into a string with units appended. Formatted telemetry will always have a string representation. If no format string or units are defined for a telemetry point, then formatted telemetry will be the same as converted telemetry except represented as string.

Script Runner API

The following methods are designed to be used in Script Runner procedures. Many can also be used in custom built COSMOS tools. Please see the COSMOS Tool API section for methods that are more efficient to use in custom tools.

Including APIs

When writing a script for a microservice, interface, or something run within COSMOS you should include the openc3/api library. When writing a script that connects to COSMOS from outside of the COSMOS cluster you should include the openc3/script library. For more information see API vs Script

Migration from COSMOS v6 to v7

See the Migrating From COSMOS 6 to COSMOS 7 guide for other changes including password hashing, JSON API session tokens, and configuration changes.

The following API methods have been removed from COSMOS v7. Since WITH_UNITS were removed in COSMOS 7 those APIs are deprecated and simply return the formatted result.

Method	API	Status
tlm_with_units	tlm_api	Deprecated, use tlm_formatted
check_with_units	api_shared	Deprecated, use check_formatted
tlm_variable	tlm_api	Removed, use tlm and pass type
check_tolerance_raw	api_shared	Removed, use check_tolerance and pass type
wait_raw	api_shared	Removed, use wait and pass type
wait_check_raw	api_shared	Removed, use wait_check and pass type
wait_tolerance_raw	api_shared	Removed, use wait_tolerance and pass type
wait_check_tolerance_raw	api_shared	Removed, use wait_check_tolerancet and pass type

The following API methods now return COSMOS__CANCEL instead of Cancel when the Cancel button is pushed in Script Runner: ask, ask_string, message_box, vertical_message_box, combo_box, check_box, prompt, prompt_for_hazardous, prompt_for_critical_cmd, metadata_input, open_file_dialog, open_files_dialog, open_bucket_dialog. Unless you are explicitly checking the return value for the word 'Cancel' there are no changes required.

Migration from COSMOS v5 to v6

See the Migrating From COSMOS 5 to COSMOS 6 guide for other changes including migrating to Vue 3 and Vuetify 3.

The following API methods have been removed from COSMOS v6. Most of the deprecated API methods still remain for backwards compatibility.

Method	API	Status
get_all_target_info	target_api	Removed, use get_target_interfaces
play_wav_file	api_shared	Removed
status_bar	api_shared	Removed

Migration from COSMOS v4 to v5

The following API methods are removed (will not be ported to COSMOS 5):

Method	Tool	Status
clear	Telemetry Viewer	Removed, use clear_screen
clear_all	Telemetry Viewer	Removed, use clear_all_screens
close_local_screens	Telemetry Viewer	Removed, use clear_screen
clear_disconnected_targets	Script Runner	Removed
cmd_tlm_clear_counters	Command and Telemetry Server	Removed
cmd_tlm_reload	Command and Telemetry Server	Removed
display	Telemetry Viewer	Removed, use display_screen
get_all_packet_logger_info	Command and Telemetry Server	Removed
get_all_target_info	Command and Telemetry Server	Removed, use get_target_interfaces
get_background_tasks	Command and Telemetry Server	Removed
get_all_cmd_info	Command and Telemetry Server	Removed, use get_all_cmds
get_all_tlm_info	Command and Telemetry Server	Removed, use get_all_tlm
get_cmd_list	Command and Telemetry Server	Removed, use get_all_cmds
get_cmd_log_filename	Command and Telemetry Server	Removed
get_cmd_param_list	Command and Telemetry Server	Removed, use get_cmd
get_cmd_tlm_disconnect	Script Runner	Removed
get_disconnected_targets	Script Runner	Removed
get_interface_info	Command and Telemetry Server	Removed, use get_interface
get_interface_targets	Command and Telemetry Server	Removed
get_output_logs_filenames	Command and Telemetry Server	Removed
get_packet	Command and Telemetry Server	Removed, use get_packets
get_packet_data	Command and Telemetry Server	Removed, use get_packets
get_packet_logger_info	Command and Telemetry Server	Removed
get_packet_loggers	Command and Telemetry Server	Removed
get_replay_mode	Replay	Removed
get_router_info	Command and Telemetry Server	Removed, use get_router
get_scriptrunner_message_log_filename	Command and Telemetry Server	Removed
get_server_message	Command and Telemetry Server	Removed
get_server_message_log_filename	Command and Telemetry Server	Removed
get_server_status	Command and Telemetry Server	Removed
get_stale	Command and Telemetry Server	Removed
get_target_ignored_items	Command and Telemetry Server	Removed, use get_target
get_target_ignored_parameters	Command and Telemetry Server	Removed, use get_target
get_target_info	Command and Telemetry Server	Removed, use get_target
get_target_list	Command and Telemetry Server	Removed, use get_target_names
get_tlm_details	Command and Telemetry Server	Removed
get_tlm_item_list	Command and Telemetry Server	Removed
get_tlm_list	Command and Telemetry Server	Removed
get_tlm_log_filename	Command and Telemetry Server	Removed
interface_state	Command and Telemetry Server	Removed, use get_interface
override_tlm_raw	Command and Telemetry Server	Removed, use override_tlm
open_directory_dialog	Script Runner	Removed
play_wav_file	Script Runner	Removed
replay_move_end	Replay	Removed
replay_move_index	Replay	Removed
replay_move_start	Replay	Removed
replay_play	Replay	Removed
replay_reverse_play	Replay	Removed
replay_select_file	Replay	Removed
replay_set_playback_delay	Replay	Removed
replay_status	Replay	Removed
replay_step_back	Replay	Removed
replay_step_forward	Replay	Removed
replay_stop	Replay	Removed
require_utility	Script Runner	Deprecated, use load_utility
router_state	Command and Telemetry Server	Removed, use get_router
save_file_dialog	Script Runner	Removed, use put_target_file
save_setting	Command and Telemetry Server	Deprecated, use set_setting
set_cmd_tlm_disconnect	Script Runner	Removed, use disconnect_script
set_disconnected_targets	Script Runner	Removed
set_replay_mode	Replay	Removed
set_stdout_max_lines	Script Runner	Removed
set_tlm_raw	Script Runner	Removed, use set_tlm
show_backtrace	Script Runner	Removed, backtrace always shown
status_bar	Script Runner	Removed
shutdown_cmd_tlm	Command and Telemetry Server	Removed
start_cmd_log	Command and Telemetry Server	Removed
start_logging	Command and Telemetry Server	Removed
start_new_scriptrunner_message_log	Command and Telemetry Server	Removed
start_new_server_message_log	Command and Telemetry Server	Removed
start_tlm_log	Command and Telemetry Server	Removed
stop_background_task	Command and Telemetry Server	Removed
stop_cmd_log	Command and Telemetry Server	Removed
stop_logging	Command and Telemetry Server	Removed
stop_tlm_log	Command and Telemetry Server	Removed
subscribe_limits_events	Command and Telemetry Server	Removed
subscribe_packet_data	Command and Telemetry Server	Removed, use subscribe_packets
subscribe_server_messages	Command and Telemetry Server	Removed
tlm_variable	Script Runner	Deprecated, use tlm and pass type
unsubscribe_limits_events	Command and Telemetry Server	Removed
unsubscribe_packet_data	Command and Telemetry Server	Removed
unsubscribe_server_messages	Command and Telemetry Server	Removed
wait_raw	Script Runner	Deprecated, use wait and pass type
wait_check_raw	Script Runner	Deprecated, use wait_check and pass type
wait_tolerance_raw	Script Runner	Deprecated, use wait_tolerance and pass type
wait_check_tolerance_raw	Script Runner	Deprecated, use wait_check_tolerance and pass type

Retrieving User Input

These methods allow the user to enter values that are needed by the script.

ask

Since 5.0.0

Prompts the user for input with a question. User input is automatically converted from a string to the appropriate data type. For example if the user enters "1", the number 1 as an integer will be returned.

Python Syntax
Ruby Syntax

ask("<question>", <Blank or Default>, <Password>)

ask("<question>", <Blank or Default>, <Password>)

Parameter	Description
question	Question to prompt the user with.
Blank or Default	Whether or not to allow empty responses (optional - defaults to false). If a non-boolean value is passed it is used as a default value.
Password	Whether to treat the entry as a password which is displayed with dots and not logged. Default is false.

Python Example
Ruby Example

value = ask("Enter an integer")
value = ask("Enter a value or nothing", True)
value = ask("Enter a value", 10)
password = ask("Enter your password", False, True)

value = ask("Enter an integer")
value = ask("Enter a value or nothing", true)
value = ask("Enter a value", 10)
password = ask("Enter your password", false, true)

ask_string

Since 5.0.0

Prompts the user for input with a question. User input is always returned as a string. For example if the user enters "1", the string "1" will be returned.

Python Syntax
Ruby Syntax

ask_string("<question>", <Blank or Default>, <Password>)

ask_string("<question>", <Blank or Default>, <Password>)

Parameter	Description
question	Question to prompt the user with.
Blank or Default	Whether or not to allow empty responses (optional - defaults to false). If a non-boolean value is passed it is used as a default value.
Password	Whether to treat the entry as a password which is displayed with dots and not logged. Default is false.

Python Example
Ruby Example

string = ask_string("Enter a String")
string = ask_string("Enter a value or nothing", True)
string = ask_string("Enter a value", "test")
password = ask_string("Enter your password", False, True)

string = ask_string("Enter a String")
string = ask_string("Enter a value or nothing", true)
string = ask_string("Enter a value", "test")
password = ask_string("Enter your password", false, true)

message_box

Since 5.0.0

vertical_message_box

Since 5.0.0

combo_box

Since 5.0.0

check_box

Since 7.0.0

The message_box, vertical_message_box, combo_box and check_box methods create a message box with buttons / selections / checkboxes that the user can click. The text of the button / selection / checkbox is returned.

Python Syntax
Ruby Syntax

message_box("<Message>", "<button text 1>", ...)
vertical_message_box("<Message>", "<button text 1>", ...)
combo_box("<Message>", "<selection text 1>", ...)
check_box("<Message>", "<checkbox text 1>", ...)

message_box("<Message>", "<button text 1>", ...)
vertical_message_box("<Message>", "<button text 1>", ...)
combo_box("<Message>", "<selection text 1>", ...)
check_box("<Message>", "<checkbox text 1>", ...)

Parameter	Description
Message	Message to prompt the user with.
Button/Selection/Checkbox Text	Text for a button or selection
informative	Named parameter to add additional info to the dialog
details	Named parameter to add additional details to the dialog
multiple	Named parameter to make the combo_box multi-select

Python Example
Ruby Example

value = message_box("Select the sensor number", 'One', 'Two', informative="Smaller informative font")
value = vertical_message_box("Select the sensor number", 'One', 'Two' details="Regular details")
value = combo_box("Select the sensor number", 'One', 'Two')
match value:
    case 'One':
        print('Sensor One')
    case 'Two':
        print('Sensor Two')
values = combo_box("Select sensors to enable", 'One', 'Two', 'Three', multiple=True)
for value in values:
    print(f"Enabling {value}")
values = check_box("Select sensors to enable", 'One', 'Two', 'Three')
for value in values:
    print(f"Enabling {value}")

value = message_box("Select the sensor number", 'One', 'Two', informative: "Smaller informative font")
value = vertical_message_box("Select the sensor number", 'One', 'Two', details: "Regular details")
value = combo_box("Select the sensor number", 'One', 'Two')
case value
when 'One'
  puts 'Sensor One'
when 'Two'
  puts 'Sensor Two'
end
values = combo_box("Select sensors to enable", 'One', 'Two', 'Three', multiple: true)
values.each do |value|
  puts "Enabling #{value}"
end
values = check_box("Select sensors to enable", 'One', 'Two', 'Three')
values.each do |value|
  puts "Enabling #{value}"
end

open_file_dialog

Since 5.0.0

open_files_dialog

Since 5.0.0

The open_file_dialog and open_files_dialog methods create a file dialog box so the user can select a single or multiple files. The selected file(s) is returned.

Note: COSMOS 5 has deprecated the save_file_dialog and open_directory_dialog methods. save_file_dialog can be replaced by put_target_file if you want to write a file back to the target. open_directory_dialog doesn't make sense in new architecture so you must request individual files.

Python Syntax
Ruby Syntax

open_file_dialog("<Title>", "<Message>", filter="<filter>")
open_files_dialog("<Title>", "<Message>", filter="<filter>")

open_file_dialog("<Title>", "<Message>", filter: "<filter>")
open_files_dialog("<Title>", "<Message>", filter: "<filter>")

Parameter	Description
Title	The title to put on the dialog. Required.
Message	The message to display in the dialog box. Optional parameter.
filter	Named parameter to filter allowed file types. Optional parameter, specified as comma delimited file types, e.g. ".txt,.doc". See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept for more information.

Python Example
Ruby Example

file = open_file_dialog("Open a single file", "Choose something interesting", filter=".txt")
print(file)
print(file.read())
file.close()

files = open_files_dialog("Open multiple files") # message is optional
print(files) # Array of File objects (even if you select only one)
for file in files:
    print(file)
    print(file.read())
    file.close()

file = open_file_dialog("Open a single file", "Choose something interesting", filter: ".txt")
puts file # Ruby File object
puts file.read
file.delete

files = open_files_dialog("Open multiple files") # message is optional
puts files # Array of File objects (even if you select only one)
files.each do |file|
  puts file
  puts file.read
  file.delete
end

open_bucket_dialog

Since 7.0.0

The open_bucket_dialog method creates a dialog box that allows the user to browse S3 bucket files and select one. It presents the available buckets (similar to Bucket Explorer) and allows navigating directories within the selected bucket. The selected file is downloaded and returned as a file object, similar to open_file_dialog.

Python Syntax
Ruby Syntax

open_bucket_dialog("<Title>", "<Message>")

open_bucket_dialog("<Title>", "<Message>")

Parameter	Description
Title	The title to put on the dialog. Required.
Message	The message to display in the dialog box. Optional parameter.

Python Example
Ruby Example

file = open_bucket_dialog("Select a File", "Choose a file from a bucket")
print(file.filename) # The name of the selected file
print(file.read())
file.close()

file = open_bucket_dialog("Select a File", "Choose a file from a bucket")
puts file.filename # The name of the selected file
puts file.read
file.delete

File Manipulation

These methods provide capability to interact with files in the target directory.

get_target_file

Since 5.0.0

Return a file handle to a file in the target directory. Returns None (Python) or nil (Ruby) if the file is not found.

Python Syntax
Ruby Syntax

get_target_file("<File Path>", original=False)

get_target_file("<File Path>", original: false)

Parameter	Description
File Path	The path to the file in the target directory. Should assume to start with a TARGET name, e.g. INST/procedures/proc.rb
original	Whether to get the original file from the plug-in, or any modifications to the file. Default is false which means to grab the modified file. If the modified file does not exist the API will automatically try to pull the original.

Python Example
Ruby Example

from openc3.utilities.string import formatted

file = get_target_file("INST/data/attitude.bin")
print(formatted(file.read())) # format a binary file
file.close() # delete file
file = get_target_file("INST/procedures/checks.rb", original=True)
print(file.read())
file.close() # delete file

file = get_target_file("INST/data/attitude.bin")
puts file.read().formatted # format a binary file
file.unlink # delete file
file = get_target_file("INST/procedures/checks.rb", original: true)
puts file.read()
file.unlink # delete file

put_target_file

Since 5.0.0

Writes a file to the target directory

Python Syntax
Ruby Syntax

put_target_file("<File Path>", "IO or String")

put_target_file("<File Path>", "IO or String")

Parameter	Description
File Path	The path to the file in the target directory. Should assume to start with a TARGET name, e.g. INST/procedures/proc.rb. The file can previously exist or not. Note: The original file from the plug-in will not be modified, however existing modified files will be overwritten.
IO or String	The data can be an IO object or String

Python Example
Ruby Example

from io import BytesIO

put_target_file("INST/test1.txt", "this is a string test")
file = tempfile.NamedTemporaryFile(mode="w+t")
file.write("this is a Io test")
file.seek(0)
put_target_file("INST/test2.txt", file)
put_target_file("INST/test3.bin", b"\x00\x01\x02\x03\xFF\xEE\xDD\xCC") # binary

buf = BytesIO()
buf.write(b'\xDE\xAD\xBE\xEF')
buf.seek(0)
put_target_file("INST/test4.bin", buf)

put_target_file("INST/test1.txt", "this is a string test")
file = Tempfile.new('test')
file.write("this is a Io test")
file.rewind
put_target_file("INST/test2.txt", file)
put_target_file("INST/test3.bin", "\x00\x01\x02\x03\xFF\xEE\xDD\xCC") # binary

buf = StringIO.new
buf.write([0xDEADBEEF].pack('N'))
buf.seek(0)
put_target_file("INST/test4.bin", buf)

delete_target_file

Since 5.0.0

Delete a file in the target directory

Python Syntax
Ruby Syntax

delete_target_file("<File Path>")

delete_target_file("<File Path>")

Parameter	Description
File Path	The path to the file in the target directory. Should assume to start with a TARGET name, e.g. INST/procedures/proc.rb. Note: Only files created with put_target_file can be deleted. Original files from the plugin installation will remain.

Python Example
Ruby Example

put_target_file("INST/delete_me.txt", "to be deleted")
delete_target_file("INST/delete_me.txt")

put_target_file("INST/delete_me.txt", "to be deleted")
delete_target_file("INST/delete_me.txt")

download_file

Since 5.8.0

Prompts the user to download a file from the OpenC3 system to their local machine.

Python Syntax
Ruby Syntax

download_file("<File Path>")

download_file("<File Path>")

Parameter	Description
File Path	File Path to the file to download within the OpenC3 system.

Python Example
Ruby Example

download_file("targets/INST/procedures/my_data.csv")

download_file("targets/INST/procedures/my_data.csv")

Providing information to the user

These methods notify the user that something has occurred.

prompt

Since 5.0.0

Displays a message to the user and waits for them to press an ok button.

Python Syntax
Ruby Syntax

prompt("<Message>")

prompt("<Message>")

Parameter	Description
Message	Message to prompt the user with.

Python Example
Ruby Example

prompt("Press OK to continue")

prompt("Press OK to continue")

Commands

These methods provide capability to send commands to a target and receive information about commands in the system.

cmd

Since 5.0.0

Sends a specified command.

Python Syntax
Ruby Syntax

cmd("<Target Name> <Command Name> with <Param #1 Name> <Param #1 Value>, <Param #2 Name> <Param #2 Value>, ...")
cmd("<Target Name>", "<Command Name>", {"Param #1 Name": <Param #1 Value>, "Param #2 Name": <Param #2 Value>, ...})

cmd("<Target Name> <Command Name> with <Param #1 Name> <Param #1 Value>, <Param #2 Name> <Param #2 Value>, ...")
cmd("<Target Name>", "<Command Name>", "Param #1 Name" => <Param #1 Value>, "Param #2 Name" => <Param #2 Value>, ...)

Parameter	Description
Target Name	Name of the target this command is associated with.
Command Name	Name of this command. Also referred to as its mnemonic.
Param #x Name	Name of a command parameter. If there are no parameters then the 'with' keyword should not be given.
Param #x Value	Value of the command parameter. Values are automatically converted to the appropriate type.
timeout	Optional named parameter to change the default timeout value of 5 seconds
log_message	Optional named parameter to prevent logging of the command
validate	Optional named parameter to enable/disable validation (default is True)

Python Example
Ruby Example

cmd("INST COLLECT with DURATION 10, TYPE NORMAL")
cmd("INST", "COLLECT", { "DURATION": 10, "TYPE": "NORMAL" })
cmd("INST ABORT", timeout=10, log_message=False, validate=False)

cmd("INST COLLECT with DURATION 10, TYPE NORMAL")
# In Ruby the brackets around parameters are optional
cmd("INST", "COLLECT", "DURATION" => 10, "TYPE" => "NORMAL")
cmd("INST", "COLLECT", { "DURATION" => 10, "TYPE" => "NORMAL" })
cmd("INST ABORT", timeout: 10, log_message: false, validate: false)

cmd_no_range_check

Since 5.0.0

Sends a specified command without performing range checking on its parameters. This should only be used when it is necessary to intentionally send a bad command parameter to test a target.

Python Syntax
Ruby Syntax

cmd_no_range_check("<Target Name> <Command Name> with <Param #1 Name> <Param #1 Value>, <Param #2 Name> <Param #2 Value>, ...")
cmd_no_range_check("<Target Name>", "<Command Name>", {"Param #1 Name": <Param #1 Value>, "Param #2 Name": <Param #2 Value>, ...})

cmd_no_range_check("<Target Name> <Command Name> with <Param #1 Name> <Param #1 Value>, <Param #2 Name> <Param #2 Value>, ...")
cmd_no_range_check("<Target Name>", "<Command Name>", "Param #1 Name" => <Param #1 Value>, "Param #2 Name" => <Param #2 Value>, ...)

Parameter	Description
Target Name	Name of the target this command is associated with.
Command Name	Name of this command. Also referred to as its mnemonic.
Param #x Name	Name of a command parameter. If there are no parameters then the 'with' keyword should not be given.
Param #x Value	Value of the command parameter. Values are automatically converted to the appropriate type.
timeout	Optional named parameter to change the default timeout value of 5 seconds
log_message	Optional named parameter to prevent logging of the command

Python Example
Ruby Example

cmd_no_range_check("INST COLLECT with DURATION 11, TYPE NORMAL")
cmd_no_range_check("INST", "COLLECT", {"DURATION": 11, "TYPE": "NORMAL"})

cmd_no_range_check("INST COLLECT with DURATION 11, TYPE NORMAL")
cmd_no_range_check("INST", "COLLECT", "DURATION" => 11, "TYPE" => "NORMAL")

cmd_no_hazardous_check

Since 5.0.0

Sends a specified command without performing the notification if it is a hazardous command. This should only be used when it is necessary to fully automate testing involving hazardous commands.

Python Syntax
Ruby Syntax

cmd_no_hazardous_check("<Target Name> <Command Name> with <Param #1 Name> <Param #1 Value>, <Param #2 Name> <Param #2 Value>, ...")
cmd_no_hazardous_check("<Target Name>", "<Command Name>", {"Param #1 Name": <Param #1 Value>, "Param #2 Name": <Param #2 Value>, ...})

cmd_no_hazardous_check("<Target Name> <Command Name> with <Param #1 Name> <Param #1 Value>, <Param #2 Name> <Param #2 Value>, ...")
cmd_no_hazardous_check("<Target Name>", "<Command Name>", "Param #1 Name" => <Param #1 Value>, "Param #2 Name" => <Param #2 Value>, ...)

Parameter	Description
Target Name	Name of the target this command is associated with.
Command Name	Name of this command. Also referred to as its mnemonic.
Param #x Name	Name of a command parameter. If there are no parameters then the 'with' keyword should not be given.
Param #x Value	Value of the command parameter. Values are automatically converted to the appropriate type.
timeout	Optional named parameter to change the default timeout value of 5 seconds
log_message	Optional named parameter to prevent logging of the command

Python Example
Ruby Example

cmd_no_hazardous_check("INST CLEAR")
cmd_no_hazardous_check("INST", "CLEAR")

cmd_no_hazardous_check("INST CLEAR")
cmd_no_hazardous_check("INST", "CLEAR")

cmd_no_checks

Since 5.0.0

Sends a specified command without performing the parameter range checks or notification if it is a hazardous command. This should only be used when it is necessary to fully automate testing involving hazardous commands that intentionally have invalid parameters.

Python Syntax
Ruby Syntax

cmd_no_checks("<Target Name> <Command Name> with <Param #1 Name> <Param #1 Value>, <Param #2 Name> <Param #2 Value>, ...")
cmd_no_checks("<Target Name>", "<Command Name>", {"Param #1 Name": <Param #1 Value>, "Param #2 Name": <Param #2 Value>, ...})

cmd_no_checks("<Target Name> <Command Name> with <Param #1 Name> <Param #1 Value>, <Param #2 Name> <Param #2 Value>, ...")
cmd_no_checks("<Target Name>", "<Command Name>", "Param #1 Name" => <Param #1 Value>, "Param #2 Name" => <Param #2 Value>, ...)

Parameter	Description
Target Name	Name of the target this command is associated with.
Command Name	Name of this command. Also referred to as its mnemonic.
Param #x Name	Name of a command parameter. If there are no parameters then the 'with' keyword should not be given.
Param #x Value	Value of the command parameter. Values are automatically converted to the appropriate type.
timeout	Optional named parameter to change the default timeout value of 5 seconds
log_message	Optional named parameter to prevent logging of the command

Python Example
Ruby Example

cmd_no_checks("INST COLLECT with DURATION 11, TYPE SPECIAL")
cmd_no_checks("INST", "COLLECT", {"DURATION": 11, "TYPE": "SPECIAL"})

cmd_no_checks("INST COLLECT with DURATION 11, TYPE SPECIAL")
cmd_no_checks("INST", "COLLECT", "DURATION" => 11, "TYPE" => "SPECIAL")

cmd_raw

Since 5.0.0

Sends a specified command without running conversions.

Python Syntax
Ruby Syntax

cmd_raw("<Target Name> <Command Name> with <Param #1 Name> <Param #1 Value>, <Param #2 Name> <Param #2 Value>, ...")
cmd_raw("<Target Name>", "<Command Name>", {"<Param #1 Name>": <Param #1 Value>, "<Param #2 Name>": <Param #2 Value>, ...})

cmd_raw("<Target Name> <Command Name> with <Param #1 Name> <Param #1 Value>, <Param #2 Name> <Param #2 Value>, ...")
cmd_raw("<Target Name>", "<Command Name>", "<Param #1 Name>" => <Param #1 Value>, "<Param #2 Name>" => <Param #2 Value>, ...)

Parameter	Description
Target Name	Name of the target this command is associated with.
Command Name	Name of this command. Also referred to as its mnemonic.
Param #x Name	Name of a command parameter. If there are no parameters then the 'with' keyword should not be given.
Param #x Value	Value of the command parameter. Values are automatically converted to the appropriate type.
timeout	Optional named parameter to change the default timeout value of 5 seconds
log_message	Optional named parameter to prevent logging of the command

Python Example
Ruby Example

cmd_raw("INST COLLECT with DURATION 10, TYPE 0")
cmd_raw("INST", "COLLECT", {"DURATION": 10, "TYPE": 0})

cmd_raw("INST COLLECT with DURATION 10, TYPE 0")
cmd_raw("INST", "COLLECT", "DURATION" => 10, "TYPE" => 0)

cmd_raw_no_range_check

Since 5.0.0

Sends a specified command without running conversions or performing range checking on its parameters. This should only be used when it is necessary to intentionally send a bad command parameter to test a target.

Python Syntax
Ruby Syntax

cmd_raw_no_range_check("<Target Name> <Command Name> with <Param #1 Name> <Param #1 Value>, <Param #2 Name> <Param #2 Value>, ...")
cmd_raw_no_range_check("<Target Name>", "<Command Name>", {"<Param #1 Name>": <Param #1 Value>, "<Param #2 Name>": <Param #2 Value>, ...})

cmd_raw_no_range_check("<Target Name> <Command Name> with <Param #1 Name> <Param #1 Value>, <Param #2 Name> <Param #2 Value>, ...")
cmd_raw_no_range_check("<Target Name>", "<Command Name>", "<Param #1 Name>" => <Param #1 Value>, "<Param #2 Name>" => <Param #2 Value>, ...)

Parameter	Description
Target Name	Name of the target this command is associated with.
Command Name	Name of this command. Also referred to as its mnemonic.
Param #x Name	Name of a command parameter. If there are no parameters then the 'with' keyword should not be given.
Param #x Value	Value of the command parameter. Values are automatically converted to the appropriate type.
timeout	Optional named parameter to change the default timeout value of 5 seconds
log_message	Optional named parameter to prevent logging of the command

Python Example
Ruby Example

cmd_raw_no_range_check("INST COLLECT with DURATION 11, TYPE 0")
cmd_raw_no_range_check("INST", "COLLECT", {"DURATION": 11, "TYPE": 0})

cmd_raw_no_range_check("INST COLLECT with DURATION 11, TYPE 0")
cmd_raw_no_range_check("INST", "COLLECT", "DURATION" => 11, "TYPE" => 0)

cmd_raw_no_hazardous_check

Since 5.0.0

Sends a specified command without running conversions or performing the notification if it is a hazardous command. This should only be used when it is necessary to fully automate testing involving hazardous commands.

Python Syntax
Ruby Syntax

cmd_raw_no_hazardous_check("<Target Name> <Command Name> with <Param #1 Name> <Param #1 Value>, <Param #2 Name> <Param #2 Value>, ...")
cmd_raw_no_hazardous_check("<Target Name>", "<Command Name>", {"<Param #1 Name>": <Param #1 Value>, "<Param #2 Name>": <Param #2 Value>, ...})

cmd_raw_no_hazardous_check("<Target Name> <Command Name> with <Param #1 Name> <Param #1 Value>, <Param #2 Name> <Param #2 Value>, ...")
cmd_raw_no_hazardous_check("<Target Name>", "<Command Name>", "<Param #1 Name>" => <Param #1 Value>, "<Param #2 Name>" => <Param #2 Value>, ...)

Parameter	Description
Target Name	Name of the target this command is associated with.
Command Name	Name of this command. Also referred to as its mnemonic.
Param #x Name	Name of a command parameter. If there are no parameters then the 'with' keyword should not be given.
Param #x Value	Value of the command parameter. Values are automatically converted to the appropriate type.
timeout	Optional named parameter to change the default timeout value of 5 seconds
log_message	Optional named parameter to prevent logging of the command

Python Example
Ruby Example

cmd_raw_no_hazardous_check("INST CLEAR")
cmd_raw_no_hazardous_check("INST", "CLEAR")

cmd_raw_no_hazardous_check("INST CLEAR")
cmd_raw_no_hazardous_check("INST", "CLEAR")

cmd_raw_no_checks

Since 5.0.0

Sends a specified command without running conversions or performing the parameter range checks or notification if it is a hazardous command. This should only be used when it is necessary to fully automate testing involving hazardous commands that intentionally have invalid parameters.

Python Syntax
Ruby Syntax

cmd_raw_no_checks("<Target Name> <Command Name> with <Param #1 Name> <Param #1 Value>, <Param #2 Name> <Param #2 Value>, ...")
cmd_raw_no_checks("<Target Name>", "<Command Name>", {"<Param #1 Name>": <Param #1 Value>, "<Param #2 Name>": <Param #2 Value>, ...})

cmd_raw_no_checks("<Target Name> <Command Name> with <Param #1 Name> <Param #1 Value>, <Param #2 Name> <Param #2 Value>, ...")
cmd_raw_no_checks("<Target Name>", "<Command Name>", "<Param #1 Name>" => <Param #1 Value>, "<Param #2 Name>" => <Param #2 Value>, ...)

Parameter	Description
Target Name	Name of the target this command is associated with.
Command Name	Name of this command. Also referred to as its mnemonic.
Param #x Name	Name of a command parameter. If there are no parameters then the 'with' keyword should not be given.
Param #x Value	Value of the command parameter. Values are automatically converted to the appropriate type.
timeout	Optional named parameter to change the default timeout value of 5 seconds
log_message	Optional named parameter to prevent logging of the command

Python Example
Ruby Example

cmd_raw_no_checks("INST COLLECT with DURATION 11, TYPE 1")
cmd_raw_no_checks("INST", "COLLECT", {"DURATION": 11, "TYPE": 1})

cmd_raw_no_checks("INST COLLECT with DURATION 11, TYPE 1")
cmd_raw_no_checks("INST", "COLLECT", "DURATION" => 11, "TYPE" => 1)

build_cmd

Since 5.8.0

Builds a command binary string so you can see the raw bytes for a given command. Previously build_command. Use the get_cmd to get information about a command like endianness, description, items, etc.

Python Syntax
Ruby Syntax

build_cmd(<ARGS>, range_check=True, raw=False)

build_cmd(<ARGS>, range_check: true, raw: false)

Parameter	Description
ARGS	Command parameters (see cmd)
range_check	Whether to perform range checking on the command. Default is true.
raw	Whether to write the command arguments as RAW or CONVERTED value. Default is CONVERTED.

Python Example
Ruby Example

x = build_cmd("INST COLLECT with DURATION 10, TYPE NORMAL")
print(x)  # => {'id': '1697298167748-0', 'result': 'SUCCESS', 'time': '1697298167749155717', 'received_time': '1697298167749155717', 'target_name': 'INST', 'packet_name': 'COLLECT', 'received_count': '2', 'buffer': bytearray(b'\x13\xe7\xc0\x00\x00\x0c\x00\x01\x00\x00A \x00\x00\xab\x00\x00\x00\x00')}

x = build_cmd("INST COLLECT with DURATION 10, TYPE NORMAL")
puts x  # => {"id"=>"1696437370872-0", "result"=>"SUCCESS", "time"=>"1696437370872305961", "received_time"=>"1696437370872305961", "target_name"=>"INST", "packet_name"=>"COLLECT", "received_count"=>"3", "buffer"=>"\x13\xE7\xC0\x00\x00\f\x00\x01\x00\x00A \x00\x00\xAB\x00\x00\x00\x00"}

enable_cmd

Since 5.15.1

Enables a disabled command. Sending a disabled command raises DisabledError with a message like 'INST ABORT is Disabled'.

Python Syntax
Ruby Syntax

buffer = enable_cmd("<Target Name> <Command Name>")
buffer = enable_cmd("<Target Name>", "<Command Name>")

buffer = enable_cmd("<Target Name> <Command Name>")
buffer = enable_cmd("<Target Name>", "<Command Name>")

Parameter	Description
Target Name	Name of the target.
Packet Name	Name of the command (packet).

Python Example
Ruby Example

enable_cmd("INST ABORT")

enable_cmd("INST ABORT")

disable_cmd

Since 5.15.1

Disables a command. Sending a disabled command raises DisabledError with a message like 'INST ABORT is Disabled'.

Python Syntax
Ruby Syntax

buffer = disable_cmd("<Target Name> <Command Name>")
buffer = disable_cmd("<Target Name>", "<Command Name>")

buffer = disable_cmd("<Target Name> <Command Name>")
buffer = disable_cmd("<Target Name>", "<Command Name>")

Parameter	Description
Target Name	Name of the target.
Packet Name	Name of the command (packet).

Python Example
Ruby Example

disable_cmd("INST ABORT")

disable_cmd("INST ABORT")

send_raw

Since 5.0.0

Sends raw data on an interface.

Python Syntax
Ruby Syntax

send_raw(<Interface Name>, <Data>)

send_raw(<Interface Name>, <Data>)

Parameter	Description
Interface Name	Name of the interface to send the raw data on.
Data	Raw ruby string of data to send.

Python Example
Ruby Example

send_raw("INST_INT", data)

send_raw("INST_INT", data)

get_all_cmds

Since 5.13.0

Returns an array of the commands that are available for a particular target. The returned array is an array of hashes / list of dicts which fully describe the command packet. Previously get_all_commands.

Python Syntax
Ruby Syntax

get_all_cmds("<Target Name>")

get_all_cmds("<Target Name>")

Parameter	Description
Target Name	Name of the target.

Python Example
Ruby Example

cmd_list = get_all_cmds("INST")
print(cmd_list)  # =>
# [{'target_name': 'INST',
#   'packet_name': 'ABORT',
#   'endianness': 'BIG_ENDIAN',
#   'description': 'Aborts a collect on the INST instrument',
#   'items': [{'name': 'CCSDSVER', 'bit_offset': 0, 'bit_size': 3, ... }]
# ...
# }]

cmd_list = get_all_cmds("INST")
puts cmd_list  # =>
# [{"target_name"=>"INST",
#   "packet_name"=>"ABORT",
#   "endianness"=>"BIG_ENDIAN",
#   "description"=>"Aborts a collect on the instrument",
#   "items"=> [{"name"=>"CCSDSVER", "bit_offset"=>0, "bit_size"=>3, ... }]
# ...
# }]

get_all_cmd_names

Since 5.13.0

Returns an array of the command names for a particular target. Previously get_all_command_names.

Python Syntax
Ruby Syntax

get_all_cmd_names("<Target Name>")

get_all_cmd_names("<Target Name>")

Parameter	Description
Target Name	Name of the target

Python Example
Ruby Example

cmd_list = get_all_cmd_names("INST")
print(cmd_list)  # => ['ABORT', 'ARYCMD', 'ASCIICMD', ...]

cmd_list = get_all_cmd_names("INST")
puts cmd_list  # => ['ABORT', 'ARYCMD', 'ASCIICMD', ...]

get_cmd

Since 5.13.0

Returns a command hash which fully describes the command packet. Previously get_command. To get the binary buffer of an as-built command use build_cmd.

Python Syntax
Ruby Syntax

get_cmd("<Target Name> <Packet Name>")
get_cmd("<Target Name>", "<Packet Name>")

get_cmd("<Target Name> <Packet Name>")
get_cmd("<Target Name>", "<Packet Name>")

Parameter	Description
Target Name	Name of the target.
Packet Name	Name of the packet.

Python Example
Ruby Example

abort_cmd = get_cmd("INST ABORT")
print(abort_cmd)  # =>
# [{'target_name': 'INST',
#   'packet_name': 'ABORT',
#   'endianness': 'BIG_ENDIAN',
#   'description': 'Aborts a collect on the INST instrument',
#   'items': [{'name': 'CCSDSVER', 'bit_offset': 0, 'bit_size': 3, ... }]
# ...
# }]

abort_cmd = get_cmd("INST ABORT")
puts abort_cmd  # =>
# [{"target_name"=>"INST",
#   "packet_name"=>"ABORT",
#   "endianness"=>"BIG_ENDIAN",
#   "description"=>"Aborts a collect on the instrument",
#   "items"=> [{"name"=>"CCSDSVER", "bit_offset"=>0, "bit_size"=>3, ... }]
# ...
# }]

get_param

Since 5.13.0

Returns a hash of the given command parameter. Previously get_parameter.

Python Syntax
Ruby Syntax

get_param("<Target Name> <Command Name> <Parameter Name>")
get_param("<Target Name>", "<Command Name>", "<Parameter Name>")

get_param("<Target Name> <Command Name> <Parameter Name>")
get_param("<Target Name>", "<Command Name>", "<Parameter Name>")

Parameter	Description
Target Name	Name of the target.
Command Name	Name of the command.
Parameter Name	Name of the parameter.

Python Example
Ruby Example

param = get_param("INST COLLECT TYPE")
print(param)  # =>
# {'name': 'TYPE', 'bit_offset': 64, 'bit_size': 16, 'data_type': 'UINT',
#  'description': 'Collect type which can be normal or special', 'default': 0,
#  'minimum': 0, 'maximum': 65535, 'endianness': 'BIG_ENDIAN', 'required': True, 'overflow': 'ERROR',
#  'states': {'NORMAL': {'value': 0}, 'SPECIAL': {'value': 1, 'hazardous': ''}}, 'limits': {}}

param = get_param("INST COLLECT TYPE")
puts param  # =>
# {"name"=>"TYPE", "bit_offset"=>64, "bit_size"=>16, "data_type"=>"UINT",
#  "description"=>"Collect type which can be normal or special", "default"=>0,
#  "minimum"=>0, "maximum"=>65535, "endianness"=>"BIG_ENDIAN", "required"=>true, "overflow"=>"ERROR",
#  "states"=>{"NORMAL"=>{"value"=>0}, "SPECIAL"=>{"value"=>1, "hazardous"=>""}}, "limits"=>{}}

get_cmd_buffer

Since 5.0.0

Returns a packet hash (similar to get_cmd) along with the raw packet buffer as a Ruby string.

Python Syntax
Ruby Syntax

buffer = get_cmd_buffer("<Target Name> <Packet Name>")['buffer']
buffer = get_cmd_buffer("<Target Name>", "<Packet Name>")['buffer']

buffer = get_cmd_buffer("<Target Name> <Packet Name>")['buffer']
buffer = get_cmd_buffer("<Target Name>", "<Packet Name>")['buffer']

Parameter	Description
Target Name	Name of the target.
Packet Name	Name of the packet.

Python Example
Ruby Example

packet = get_cmd_buffer("INST COLLECT")
print(packet)  # =>
# {'time': '1697298923745982470', 'received_time': '1697298923745982470',
#  'target_name': 'INST', 'packet_name': 'COLLECT', 'received_count': '21', 'stored': 'false',
#  'buffer': bytearray(b'\x13\xe7\xc0\x00\x00\x0c\x00\x01\x00\x00@\xe0\x00\x00\xab\x00\x00\x00\x00')}

packet = get_cmd_buffer("INST COLLECT")
puts packet  # =>
# {"time"=>"1697298846752053420", "received_time"=>"1697298846752053420",
#  "target_name"=>"INST", "packet_name"=>"COLLECT", "received_count"=>"20", "stored"=>"false",
#  "buffer"=>"\x13\xE7\xC0\x00\x00\f\x00\x01\x00\x00@\xE0\x00\x00\xAB\x00\x00\x00\x00"}

get_cmd_hazardous

Since 5.0.0

Returns true/false indicating whether a particular command is flagged as hazardous.

Python Syntax
Ruby Syntax

get_cmd_hazardous("<Target Name>", "<Command Name>", <Command Params - optional>)

get_cmd_hazardous("<Target Name>", "<Command Name>", <Command Params - optional>)

Parameter	Description
Target Name	Name of the target.
Command Name	Name of the command.
Command Params	Hash of the parameters given to the command (optional). Note that some commands are only hazardous based on parameter states.

Python Example
Ruby Example

hazardous = get_cmd_hazardous("INST", "COLLECT", {'TYPE': 'SPECIAL'})
print(hazardous) # => True

hazardous = get_cmd_hazardous("INST", "COLLECT", {'TYPE' => 'SPECIAL'})
puts hazardous  # => true

get_cmd_value

Since 5.0.0

Returns reads a value from the most recently sent command packet. The pseudo-parameters 'PACKET_TIMESECONDS', 'PACKET_TIMEFORMATTED', 'RECEIVED_COUNT', 'RECEIVED_TIMEFORMATTED', and 'RECEIVED_TIMESECONDS' are also supported.

Python Syntax
Ruby Syntax

get_cmd_value("<Target Name>", "<Command Name>", "<Parameter Name>", <Value Type - optional>)

get_cmd_value("<Target Name>", "<Command Name>", "<Parameter Name>", <Value Type - optional>)

Parameter	Description
Target Name	Name of the target.
Command Name	Name of the command.
Parameter Name	Name of the command parameter.
Value Type	Value Type to read. RAW, CONVERTED or FORMATTED. NOTE: Symbol in Ruby and str in Python

Python Example
Ruby Example

value = get_cmd_value("INST", "COLLECT", "TEMP", "RAW")
print(value)  # => 0.0

value = get_cmd_value("INST", "COLLECT", "TEMP", :RAW)
puts value  # => 0.0

get_cmd_time

Since 5.0.0

Returns the time of the most recent command sent.

Python Syntax
Ruby Syntax

get_cmd_time("<Target Name - optional>", "<Command Name - optional>")

get_cmd_time("<Target Name - optional>", "<Command Name - optional>")

Parameter	Description
Target Name	Name of the target. If not given, then the most recent command time to any target will be returned
Command Name	Name of the command. If not given, then the most recent command time to the given target will be returned

Python Example
Ruby Example

target_name, command_name, time = get_cmd_time() # Name of the most recent command sent to any target and time
target_name, command_name, time = get_cmd_time("INST") # Name of the most recent command sent to the INST target and time
target_name, command_name, time = get_cmd_time("INST", "COLLECT") # Name of the most recent INST COLLECT command and time

target_name, command_name, time = get_cmd_time() # Name of the most recent command sent to any target and time
target_name, command_name, time = get_cmd_time("INST") # Name of the most recent command sent to the INST target and time
target_name, command_name, time = get_cmd_time("INST", "COLLECT") # Name of the most recent INST COLLECT command and time

get_cmd_cnt

Since 5.0.0

Returns the number of times a specified command has been sent.

Python Syntax
Ruby Syntax

get_cmd_cnt("<Target Name> <Command Name>")
get_cmd_cnt("<Target Name>", "<Command Name>")

get_cmd_cnt("<Target Name> <Command Name>")
get_cmd_cnt("<Target Name>", "<Command Name>")

Parameter	Description
Target Name	Name of the target.
Command Name	Name of the command.

Python Example
Ruby Example

cmd_cnt = get_cmd_cnt("INST COLLECT") # Number of times the INST COLLECT command has been sent

cmd_cnt = get_cmd_cnt("INST COLLECT") # Number of times the INST COLLECT command has been sent

get_cmd_cnts

Since 5.0.0

Returns the number of times the specified commands have been sent.

Python Syntax
Ruby Syntax

get_cmd_cnts([["<Target Name>", "<Command Name>"], ["<Target Name>", "<Command Name>"], ...])

get_cmd_cnts([["<Target Name>", "<Command Name>"], ["<Target Name>", "<Command Name>"], ...])

Parameter	Description
Target Name	Name of the target.
Command Name	Name of the command.

Python Example
Ruby Example

cmd_cnt = get_cmd_cnts([['INST', 'COLLECT'], ['INST', 'ABORT']]) # Number of times the INST COLLECT and INST ABORT commands have been sent

cmd_cnt = get_cmd_cnts([['INST', 'COLLECT'], ['INST', 'ABORT']]) # Number of times the INST COLLECT and INST ABORT commands have been sent

critical_cmd_status

Since 5.20.0

Returns the status of a critical command. One of APPROVED, REJECTED, or WAITING.

Python Syntax
Ruby Syntax

critical_cmd_status(uuid)

critical_cmd_status(uuid)

Parameter	Description
uuid	UUID for the critical command (displayed in the COSMOS GUI)

Python Example
Ruby Example

status = critical_cmd_status("2fa14183-3148-4399-9a74-a130257118f9") # => WAITING

status = critical_cmd_status("2fa14183-3148-4399-9a74-a130257118f9") # => WAITING

critical_cmd_approve

Since 5.20.0

Approve the critical command as the current user.

Python Syntax
Ruby Syntax

critical_cmd_approve(uuid)

critical_cmd_approve(uuid)

Parameter	Description
uuid	UUID for the critical command (displayed in the COSMOS GUI)

Python Example
Ruby Example

critical_cmd_approve("2fa14183-3148-4399-9a74-a130257118f9")

critical_cmd_approve("2fa14183-3148-4399-9a74-a130257118f9")

critical_cmd_reject

Since 5.20.0

Reject the critical command as the current user.

Python Syntax
Ruby Syntax

critical_cmd_reject(uuid)

critical_cmd_reject(uuid)

Parameter	Description
uuid	UUID for the critical command (displayed in the COSMOS GUI)

Python Example
Ruby Example

critical_cmd_reject("2fa14183-3148-4399-9a74-a130257118f9")

critical_cmd_reject("2fa14183-3148-4399-9a74-a130257118f9")

critical_cmd_can_approve

Since 5.20.0

Returns whether or not the current user can approve the critical command.

Python Syntax
Ruby Syntax

critical_cmd_can_approve(uuid)

critical_cmd_can_approve(uuid)

Parameter	Description
uuid	UUID for the critical command (displayed in the COSMOS GUI)

Python Example
Ruby Example

status = critical_cmd_can_approve("2fa14183-3148-4399-9a74-a130257118f9") # => True / False

status = critical_cmd_can_approve("2fa14183-3148-4399-9a74-a130257118f9") # => true / false

Command Queues

Command queues can be used to store commands prior to "releasing" them for execution. Commands are sent to queues via the queue keyword argument to the various cmd API calls. Queues can be in three different states: HOLD, RELEASE, and DISABLE. HOLD builds up a FIFO of commands as they are generated. RELEASE sends the commands to the interface for execution. DISABLE rejects all commands that are sent via the cmd API calls. Sending a command while a queue is in the DISABLE state will raise an exception and stop the script.

By setting the environment variable OPENC3_DEFAULT_QUEUE in the .env file you can create a "default" queue that all commands will go to unless explicitly excluded by passing false/False to the queue keyword argument. This queue is created during COSMOS initialization and is created in RELEASE mode so normal commanding will still work. Note that this will introduce delay in the command chain because all commands will flow through the queue instead of being directly executed by the interface.

Here is an example of sending a command to a queue:

Python Example
Ruby Example

cmd("INST ABORT", queue="TEST")
# Do NOT queue the command (useful if OPENC3_DEFAULT_QUEUE is set)
cmd("INST ABORT", queue=False)

cmd("INST ABORT", queue: "TEST")
# Do NOT queue the command (useful if OPENC3_DEFAULT_QUEUE is set)
cmd("INST ABORT", queue: false)

queue_create

Since 6.8.0

Create a command queue. Queues are initially created in HOLD state.

Python Syntax
Ruby Syntax

queue_create('<Queue Name>')

queue_create('<Queue Name>')

Parameter	Description
Queue Name	Case sensitive name of the queue

Python Example
Ruby Example

queue_create('TEST')

queue_create('TEST')

queue_get

Since 6.8.0

Get information about a command queue including what state it is in.

Python Syntax
Ruby Syntax

queue_get('<Queue Name>')

queue_get('<Queue Name>')

Parameter	Description
Queue Name	Case sensitive name of the queue

Python Example
Ruby Example

queue = queue_get('TEST')
print(queue) # =>

queue = queue_get('TEST')
puts queue # =>

queue_all

Since 6.8.0

Get information about all command queues.

Python Example
Ruby Example

all = queue_all()
print(all) # =>

all = queue_all()
puts all # =>

queue_list

Since 6.8.0

List all the commands in the queue including the username, the creation time, and the command itself.

Python Syntax
Ruby Syntax

queue_list('<Queue Name>')

queue_list('<Queue Name>')

Parameter	Description
Queue Name	Case sensitive name of the queue

Python Example
Ruby Example

cmds = queue_list('TEST')
print(cmds) # =>

cmds = queue_list('TEST')
puts cmds # =>

queue_hold

Since 6.8.0

Puts the specified queue into HOLD mode which means that commands are queued up and not released to the interface.

Python Syntax
Ruby Syntax

queue_hold('<Queue Name>')

queue_hold('<Queue Name>')

Parameter	Description
Queue Name	Case sensitive name of the queue

Python Example
Ruby Example

queue_hold('TEST')

queue_hold('TEST')

queue_release

Since 6.8.0

Puts the specified queue into RELEASE mode which means that commands in the queue are released to the interface. Any new commands added to the queue are immediately released to the interface.

Python Syntax
Ruby Syntax

queue_release('<Queue Name>')

queue_release('<Queue Name>')

Parameter	Description
Queue Name	Case sensitive name of the queue

Python Example
Ruby Example

queue_release('TEST')

queue_release('TEST')

queue_disable

Since 6.8.0

Puts the specified queue into DISABLE mode which means that commands are rejected and not added to the queue. Commands added to a queue in DISABLE mode via script will raise an exception and stop.

Python Syntax
Ruby Syntax

queue_disable('<Queue Name>')

queue_disable('<Queue Name>')

Parameter	Description
Queue Name	Case sensitive name of the queue

Python Example
Ruby Example

queue_disable('TEST')

queue_disable('TEST')

queue_exec

Since 6.8.0

Removes a command from the queue and executes it.

Python Syntax
Ruby Syntax

queue_exec('<Queue Name>', '<Optional Index>')

queue_exec('<Queue Name>', '<Optional Index>')

Parameter	Description
Queue Name	Case sensitive name of the queue
Index	Remove and execute at the specified index. If the index is not given the first command is removed and executed.

Python Example
Ruby Example

queue_exec('TEST') # Removes and executes the first command in the queue
queue_exec('TEST', index=5) # Removes and executes the command at index 5

queue_exec('TEST') # Removes and executes the first command in the queue
queue_exec('TEST', index: 5) # Removes and executes the command at index 5

queue_remove

Since 6.9.1

Removes a command from the queue.

Python Syntax
Ruby Syntax

queue_remove('<Queue Name>', '<Optional Index>')

queue_remove('<Queue Name>', '<Optional Index>')

Parameter	Description
Queue Name	Case sensitive name of the queue
Index	Remove at the specified index. If the index is not given the first command is removed.

Python Example
Ruby Example

queue_remove('TEST') # Removes the first command in the queue
queue_remove('TEST', index=5) # Removes the command at index 5

queue_remove('TEST') # Removes the first command in the queue
queue_remove('TEST', index: 5) # Removes the command at index 5

queue_delete

Since 6.8.0

Deletes the specified queue and any commands that it holds.

Python Syntax
Ruby Syntax

queue_delete('<Queue Name>')

queue_delete('<Queue Name>')

Parameter	Description
Queue Name	Case sensitive name of the queue

Python Example
Ruby Example

queue_delete('TEST')

queue_delete('TEST')

Handling Telemetry

These methods allow the user to interact with telemetry items.

check, check_raw, check_formatted

Since 5.0.0

Performs a verification of a telemetry item using its specified telemetry type. If the verification fails then the script will be paused with an error. If no comparison is given to check then the telemetry item is simply printed to the script output. Note: In most cases using wait_check is a better choice than using check.

Python Syntax
Ruby Syntax

check("<Target Name> <Packet Name> <Item Name> <Comparison - optional>")

check("<Target Name> <Packet Name> <Item Name> <Comparison - optional>")

Parameter	Description
Target Name	Name of the target of the telemetry item.
Packet Name	Name of the telemetry packet of the telemetry item.
Item Name	Name of the telemetry item.
Comparison	A comparison to perform against the telemetry item. If a comparison is not given then the telemetry item will just be printed into the script log.

Python Example
Ruby Example

check("INST HEALTH_STATUS COLLECTS > 1")
check_raw("INST HEALTH_STATUS COLLECTS > 1")
check_formatted("INST HEALTH_STATUS COLLECTS > 1")
# Python passes type as string
check("INST HEALTH_STATUS COLLECTS > 1", type='RAW')

check("INST HEALTH_STATUS COLLECTS > 1")
check_raw("INST HEALTH_STATUS COLLECTS > 1")
check_formatted("INST HEALTH_STATUS COLLECTS > 1")
# Ruby passes type as symbol
check("INST HEALTH_STATUS COLLECTS > 1", type: :RAW)

check_tolerance

Since 5.0.0

Checks a converted telemetry item against an expected value with a tolerance. If the verification fails then the script will be paused with an error. Note: In most cases using wait_check_tolerance is a better choice than using check_tolerance.

Python Syntax
Ruby Syntax

check_tolerance("<Target Name> <Packet Name> <Item Name>", <Expected Value>, <Tolerance>)

check_tolerance("<Target Name> <Packet Name> <Item Name>", <Expected Value>, <Tolerance>)

Parameter	Description
Target Name	Name of the target of the telemetry item.
Packet Name	Name of the telemetry packet of the telemetry item.
Item Name	Name of the telemetry item.
Expected Value	Expected value of the telemetry item.
Tolerance	± Tolerance on the expected value.
type	CONVERTED (default) or RAW (Ruby symbol, Python string)

Python Example
Ruby Example

check_tolerance("INST HEALTH_STATUS COLLECTS", 10.0, 5.0)
check_tolerance("INST HEALTH_STATUS TEMP1", 50000, 20000, type='RAW')

check_tolerance("INST HEALTH_STATUS COLLECTS", 10.0, 5.0)
check_tolerance("INST HEALTH_STATUS TEMP1", 50000, 20000, type: :RAW)

check_expression

Since 5.0.0

Evaluates an expression. If the expression evaluates to false the script will be paused with an error. This method can be used to perform more complicated comparisons than using check as shown in the example. Note: In most cases using wait_check_expression is a better choice than using check_expression.

Remember that everything inside the check_expression string will be evaluated directly and thus must be valid syntax. A common mistake is to check a variable like so (Ruby variable interpolation):

check_expression("#{answer} == 'yes'") # where answer contains 'yes'

This evaluates to yes == 'yes' which is not valid syntax because the variable yes is not defined (usually). The correct way to write this expression is as follows:

check_expression("'#{answer}' == 'yes'") # where answer contains 'yes'

Now this evaluates to 'yes' == 'yes' which is true so the check passes.

Python Syntax
Ruby Syntax

check_expression(exp_to_eval, globals=None, locals=None)

check_expression(exp_to_eval, context = nil)

Parameter	Description
exp_to_eval	An expression to evaluate.
context (ruby only)	The context to call eval with. Defaults to nil. Context in Ruby is typically binding() and is usually not needed.
globals (python only)	The globals to call eval with. Defaults to None. Note that to use COSMOS APIs like tlm() you must pass globals().
locals (python only)	The locals to call eval with. Defaults to None. Note that if you're using local variables in a method you must pass locals().

Python Example
Ruby Example

def check(value):
    # Here we using both tlm() and a local 'value' so we need to pass globals() and locals()
    check_expression("tlm('INST HEALTH_STATUS COLLECTS') > value", 5, 0.25, globals(), locals())
check(5)

check_expression("tlm('INST HEALTH_STATUS COLLECTS') > 5 and tlm('INST HEALTH_STATUS TEMP1') > 25.0")

check_exception

Since 5.0.0

Executes a method and expects an exception to be raised. If the method does not raise an exception, a CheckError is raised.

Python Syntax
Ruby Syntax

check_exception("<Method Name>", "<Method Params - optional>")

check_exception("<Method Name>", "<Method Params - optional>")

Parameter	Description
Method Name	The COSMOS scripting method to execute, e.g. 'cmd', etc.
Method Params	Parameters for the method

Python Example
Ruby Example

check_exception("cmd", "INST", "COLLECT", {"TYPE": "NORMAL"})

check_exception("cmd", "INST", "COLLECT", "TYPE" => "NORMAL")

tlm, tlm_raw, tlm_formatted

Since 5.0.0

Reads the specified form of a telemetry item.

Python Syntax
Ruby Syntax

tlm("<Target Name> <Packet Name> <Item Name>")
tlm("<Target Name>", "<Packet Name>", "<Item Name>")

tlm("<Target Name> <Packet Name> <Item Name>")
tlm("<Target Name>", "<Packet Name>", "<Item Name>")

Parameter	Description
Target Name	Name of the target of the telemetry item.
Packet Name	Name of the telemetry packet of the telemetry item.
Item Name	Name of the telemetry item.
type	Named parameter specifying the type. RAW, CONVERTED (default) or FORMATTED (Ruby symbol, Python string).

Python Example
Ruby Example

value = tlm("INST HEALTH_STATUS COLLECTS")
value = tlm("INST", "HEALTH_STATUS", "COLLECTS")
value = tlm_raw("INST HEALTH_STATUS COLLECTS")
value = tlm_formatted("INST HEALTH_STATUS COLLECTS")
# Equivalent to tlm_raw
raw_value = tlm("INST HEALTH_STATUS COLLECTS", type='RAW')

value = tlm("INST HEALTH_STATUS COLLECTS")
value = tlm("INST", "HEALTH_STATUS", "COLLECTS")
value = tlm_raw("INST HEALTH_STATUS COLLECTS")
value = tlm_formatted("INST HEALTH_STATUS COLLECTS")
# Equivalent to tlm_raw
raw_value = tlm("INST HEALTH_STATUS COLLECTS", type: :RAW)

get_tlm_buffer

Since 5.0.0

Returns a packet hash (similar to get_tlm) along with the raw packet buffer.

Python Syntax
Ruby Syntax

buffer = get_tlm_buffer("<Target Name> <Packet Name>")['buffer']
buffer = get_tlm_buffer("<Target Name>", "<Packet Name>")['buffer']

buffer = get_tlm_buffer("<Target Name> <Packet Name>")['buffer']
buffer = get_tlm_buffer("<Target Name>", "<Packet Name>")['buffer']

Parameter	Description
Target Name	Name of the target.
Packet Name	Name of the packet.

Python Example
Ruby Example

packet = get_tlm_buffer("INST HEALTH_STATUS")
packet['buffer']

packet = get_tlm_buffer("INST HEALTH_STATUS")
packet['buffer']

get_tlm_packet

Since 5.0.0

Returns the names, values, and limits states of all telemetry items in a specified packet. The value is returned as an array of arrays with each entry containing [item_name, item_value, limits_state].

Python Syntax
Ruby Syntax

get_tlm_packet("<Target Name> <Packet Name>", <type>)
get_tlm_packet("<Target Name>", "<Packet Name>", <type>)

get_tlm_packet("<Target Name> <Packet Name>", <type>)
get_tlm_packet("<Target Name>", "<Packet Name>", <type>)

Parameter	Description
Target Name	Name of the target.
Packet Name	Name of the packet.
type	Named parameter specifying the type. RAW, CONVERTED (default) or FORMATTED (Ruby symbol, Python string).

Python Example
Ruby Example

names_values_and_limits_states = get_tlm_packet("INST HEALTH_STATUS", type='FORMATTED')

names_values_and_limits_states = get_tlm_packet("INST HEALTH_STATUS", type: :FORMATTED)

get_tlm_available

Since 6.7.0

Returns the actual items available based on the specified set of telemetry items. For example, if you request INST__HEALTH_STATUS__CCSDSVER__FORMATTED the method will return INST__HEALTH_STATUS__CCSDSVER__RAW for that item because it does not have formatting or conversions so only the RAW value is available. This must be called before calling get_tlm_values when passing a start_time / end_time as it ensures a correct request of historical data.

Python Syntax
Ruby Syntax

actual = get_tlm_available(<Items>)

actual = get_tlm_available(<Items>)

Parameter	Description
Items	Array of strings of the form ['TGT__PKT__ITEM__TYPE', ... ]

Python Example
Ruby Example

values = get_tlm_available(["INST__HEALTH_STATUS__CCSDSVER__FORMATTED", "INST__HEALTH_STATUS__TEMP1__FORMATTED"])
print(values) # ["INST__HEALTH_STATUS__CCSDSVER__RAW", "INST__HEALTH_STATUS__TEMP1__FORMATTED"]

actual = get_tlm_available(["INST__HEALTH_STATUS__CCSDSVER__FORMATTED", "INST__HEALTH_STATUS__TEMP1__FORMATTED"])
puts values # ["INST__HEALTH_STATUS__CCSDSVER__RAW", "INST__HEALTH_STATUS__TEMP1__FORMATTED"]

get_tlm_values

Since 5.0.0

Returns the values and current limits state for a specified set of telemetry items. Items can be in any telemetry packet in the system. They can all be retrieved using the same value type or a specific value type can be specified for each item.

Python Syntax
Ruby Syntax

values, limits_states, limits_settings, limits_set = get_tlm_values(<Items>)

values, limits_states, limits_settings, limits_set = get_tlm_values(<Items>)

Parameter	Description
Items	Array of strings of the form ['TGT__PKT__ITEM__TYPE', ... ]

Python Example
Ruby Example

values = get_tlm_values(["INST__HEALTH_STATUS__TEMP1__CONVERTED", "INST__HEALTH_STATUS__TEMP2__RAW"])
print(values) # [[-100.0, :RED_LOW], [0, :RED_LOW]]

values = get_tlm_values(["INST__HEALTH_STATUS__TEMP1__CONVERTED", "INST__HEALTH_STATUS__TEMP2__RAW"])
puts values # [[-100.0, :RED_LOW], [0, :RED_LOW]]

get_all_tlm

Since 5.13.0

Returns an array of all target packet hashes. Previously get_all_telemetry.

Python Syntax
Ruby Syntax

get_all_tlm("<Target Name>")

get_all_tlm("<Target Name>")

Parameter	Description
Target Name	Name of the target.

Python Example
Ruby Example

packets = get_all_tlm("INST")
print(packets)
#[{"target_name"=>"INST",
#  "packet_name"=>"ADCS",
#  "endianness"=>"BIG_ENDIAN",
#  "description"=>"Position and attitude data",
#  "stale"=>true,
#  "items"=>
#   [{"name"=>"CCSDSVER",
#     "bit_offset"=>0,
#     "bit_size"=>3,
#     ...

packets = get_all_tlm("INST")
puts packets
#[{"target_name"=>"INST",
#  "packet_name"=>"ADCS",
#  "endianness"=>"BIG_ENDIAN",
#  "description"=>"Position and attitude data",
#  "stale"=>true,
#  "items"=>
#   [{"name"=>"CCSDSVER",
#     "bit_offset"=>0,
#     "bit_size"=>3,
#     ...

get_all_tlm_names

Since 5.13.0

Returns an array of all target packet names. Previously get_all_telemetry_names.

Python Syntax
Ruby Syntax

get_all_tlm_names("<Target Name>")

get_all_tlm_names("<Target Name>")

Parameter	Description
Target Name	Name of the target

Python Example
Ruby Example

get_all_tlm_names("INST")  # => ["ADCS", "HEALTH_STATUS", ...]

get_all_tlm_names("INST")  # => ["ADCS", "HEALTH_STATUS", ...]

get_all_tlm_item_names

Since 6.3.0

Returns all the item names for every packet in a target

Python Syntax
Ruby Syntax

get_all_tlm_item_names("<Target Name>")

get_all_tlm_item_names("<Target Name>")

Parameter	Description
Target Name	Name of the target

Python Example
Ruby Example

get_all_tlm_item_names("INST")  # => ["ARY", "ARY2", "ASCIICMD", "ATTPROGRESS", ...]

get_all_tlm_item_names("INST")  # => ["ARY", "ARY2", "ASCIICMD", "ATTPROGRESS", ...]

get_tlm

Since 5.13.0

Returns a packet hash. Previously get_telemetry.

Python Syntax
Ruby Syntax

get_tlm("<Target Name> <Packet Name>")
get_tlm("<Target Name>", "<Packet Name>")

get_tlm("<Target Name> <Packet Name>")
get_tlm("<Target Name>", "<Packet Name>")

Parameter	Description
Target Name	Name of the target.
Packet Name	Name of the packet.

Python Example
Ruby Example

packet = get_tlm("INST HEALTH_STATUS")
print(packet)
#{"target_name"=>"INST",
# "packet_name"=>"HEALTH_STATUS",
# "endianness"=>"BIG_ENDIAN",
# "description"=>"Health and status from the instrument",
# "stale"=>true,
# "processors"=>
#  [{"name"=>"TEMP1STAT",
#    "class"=>"OpenC3::StatisticsProcessor",
#    "params"=>["TEMP1", 100, "CONVERTED"]},
#   {"name"=>"TEMP1WATER",
#    "class"=>"OpenC3::WatermarkProcessor",
#    "params"=>["TEMP1", "CONVERTED"]}],
# "items"=>
#  [{"name"=>"CCSDSVER",
#    "bit_offset"=>0,
#    "bit_size"=>3,
#    ...

packet = get_tlm("INST HEALTH_STATUS")
puts packet
#{"target_name"=>"INST",
# "packet_name"=>"HEALTH_STATUS",
# "endianness"=>"BIG_ENDIAN",
# "description"=>"Health and status from the instrument",
# "stale"=>true,
# "processors"=>
#  [{"name"=>"TEMP1STAT",
#    "class"=>"OpenC3::StatisticsProcessor",
#    "params"=>["TEMP1", 100, "CONVERTED"]},
#   {"name"=>"TEMP1WATER",
#    "class"=>"OpenC3::WatermarkProcessor",
#    "params"=>["TEMP1", "CONVERTED"]}],
# "items"=>
#  [{"name"=>"CCSDSVER",
#    "bit_offset"=>0,
#    "bit_size"=>3,
#    ...

get_item

Since 5.0.0

Returns an item hash.

Python Syntax
Ruby Syntax

get_item("<Target Name> <Packet Name> <Item Name>")
get_item("<Target Name>", "<Packet Name>", "<Item Name>")

get_item("<Target Name> <Packet Name> <Item Name>")
get_item("<Target Name>", "<Packet Name>", "<Item Name>")

Parameter	Description
Target Name	Name of the target.
Packet Name	Name of the packet.
Item Name	Name of the item.

Python Example
Ruby Example

item = get_item("INST HEALTH_STATUS CCSDSVER")
print(item)
#{"name"=>"CCSDSVER",
# "bit_offset"=>0,
# "bit_size"=>3,
# "data_type"=>"UINT",
# "description"=>"CCSDS packet version number (See CCSDS 133.0-B-1)",
# "endianness"=>"BIG_ENDIAN",
# "required"=>false,
# "overflow"=>"ERROR"}

item = get_item("INST HEALTH_STATUS CCSDSVER")
puts item
#{"name"=>"CCSDSVER",
# "bit_offset"=>0,
# "bit_size"=>3,
# "data_type"=>"UINT",
# "description"=>"CCSDS packet version number (See CCSDS 133.0-B-1)",
# "endianness"=>"BIG_ENDIAN",
# "required"=>false,
# "overflow"=>"ERROR"}

get_tlm_cnt

Since 5.0.0

Returns the number of times a specified telemetry packet has been received.

Python Syntax
Ruby Syntax

get_tlm_cnt("<Target Name> <Packet Name>")
get_tlm_cnt("<Target Name>", "<Packet Name>")

get_tlm_cnt("<Target Name> <Packet Name>")
get_tlm_cnt("<Target Name>", "<Packet Name>")

Parameter	Description
Target Name	Name of the target.
Packet Name	Name of the telemetry packet.

Python Example
Ruby Example

tlm_cnt = get_tlm_cnt("INST HEALTH_STATUS") # Number of times the INST HEALTH_STATUS telemetry packet has been received.

tlm_cnt = get_tlm_cnt("INST HEALTH_STATUS") # Number of times the INST HEALTH_STATUS telemetry packet has been received.

set_tlm

Since 5.0.0

Sets a telemetry item value in the Command and Telemetry Server. This value will be overwritten if a new packet is received from an interface. For that reason this method is most useful if interfaces are disconnected or for testing via the Script Runner disconnect mode. Manually setting telemetry values allows for the execution of many logical paths in scripts.

Python Syntax
Ruby Syntax

set_tlm("<Target> <Packet> <Item> = <Value>", <type>)

set_tlm("<Target> <Packet> <Item> = <Value>", <type>)

Parameter	Description
Target	Target name
Packet	Packet name
Item	Item name
Value	Value to set
type	Value type RAW, CONVERTED (default) or FORMATTED (Ruby symbol, Python string)

Python Example
Ruby Example

set_tlm("INST HEALTH_STATUS COLLECTS = 5") # type is CONVERTED by default
check("INST HEALTH_STATUS COLLECTS == 5")
set_tlm("INST HEALTH_STATUS COLLECTS = 10", type='RAW')
check("INST HEALTH_STATUS COLLECTS == 10", type='RAW')

set_tlm("INST HEALTH_STATUS COLLECTS = 5") # type is :CONVERTED by default
check("INST HEALTH_STATUS COLLECTS == 5")
set_tlm("INST HEALTH_STATUS COLLECTS = 10", type: :RAW)
check("INST HEALTH_STATUS COLLECTS == 10", type: :RAW)

inject_tlm

Since 5.0.0

Injects a packet into the system as if it was received from an interface.

Python Syntax
Ruby Syntax

inject_tlm("<target_name>", "<packet_name>", <item_hash>, type=<type>, stored=<stored>)

inject_tlm("<target_name>", "<packet_name>", <item_hash>, type: <type>, stored: <stored>)

Parameter	Description
Target	Target name
Packet	Packet name
Item Hash	Hash of item name/value for each item. If an item is not specified in the hash, the current value table value will be used. Optional parameter, defaults to nil.
type	Type of values in the item hash, RAW, CONVERTED (default) or FORMATTED (Ruby symbol, Python string)
stored Since 7.1.0	Whether the packet should be marked as stored (default false). Stored packets are written to the telemetry stream but do not update the current value table (CVT).

Python Example
Ruby Example

inject_tlm("INST", "PARAMS", {'VALUE1': 5.0, 'VALUE2': 7.0})
inject_tlm("INST", "PARAMS", {'VALUE1': 5.0, 'VALUE2': 7.0}, stored=True)

inject_tlm("INST", "PARAMS", {'VALUE1' => 5.0, 'VALUE2' => 7.0})
inject_tlm("INST", "PARAMS", {'VALUE1' => 5.0, 'VALUE2' => 7.0}, stored: true)

override_tlm

Since 5.0.0

Sets the converted value for a telmetry point in the Command and Telemetry Server. This value will be maintained even if a new packet is received on the interface unless the override is canceled with the normalize_tlm method.

Python Syntax
Ruby Syntax

override_tlm("<Target> <Packet> <Item> = <Value>", <type>)

override_tlm("<Target> <Packet> <Item> = <Value>", <type>)

Parameter	Description
Target	Target name
Packet	Packet name
Item	Item name
Value	Value to set
type	Type to override, ALL (default), RAW, CONVERTED or FORMATTED (Ruby symbol, Python string)

Python Example
Ruby Example

override_tlm("INST HEALTH_STATUS TEMP1 = 5") # All requests for TEMP1 return 5
override_tlm("INST HEALTH_STATUS TEMP2 = 0", type='RAW') # Only RAW tlm set to 0

override_tlm("INST HEALTH_STATUS TEMP1 = 5") # All requests for TEMP1 return 5
override_tlm("INST HEALTH_STATUS TEMP2 = 0", type: :RAW) # Only RAW tlm set to 0

normalize_tlm

Since 5.0.0

Clears the override of a telmetry point in the Command and Telemetry Server.

Python Syntax
Ruby Syntax

normalize_tlm("<Target> <Packet> <Item>", <type>)

normalize_tlm("<Target> <Packet> <Item>", <type>)

Parameter	Description
Target	Target name
Packet	Packet name
Item	Item name
type	Type to normalize, ALL (default), RAW, CONVERTED or FORMATTED (Ruby symbol, Python string)

Python Example
Ruby Example

normalize_tlm("INST HEALTH_STATUS TEMP1") # clear all overrides
normalize_tlm("INST HEALTH_STATUS TEMP1", type='RAW') # clear only the RAW override

normalize_tlm("INST HEALTH_STATUS TEMP1") # clear all overrides
normalize_tlm("INST HEALTH_STATUS TEMP1", type: :RAW) # clear only the RAW override

get_overrides

Since 5.4.2

Returns an array of the the currently overridden values set by override_tlm. NOTE: This returns all the value types that are overridden which by default is all 4 values types when using override_tlm.

Python Syntax
Ruby Syntax

get_overrides()

get_overrides()

Python Example
Ruby Example

override_tlm("INST HEALTH_STATUS TEMP1 = 5")
print(get_overrides()) # =>
# [ {'target_name': 'INST', 'packet_name': 'HEALTH_STATUS', 'item_name': 'TEMP1', 'value_type': 'RAW', 'value': 5},
#   {'target_name': 'INST', 'packet_name': 'HEALTH_STATUS', 'item_name': 'TEMP1', 'value_type': 'CONVERTED', 'value': 5},
#   {'target_name': 'INST', 'packet_name': 'HEALTH_STATUS', 'item_name': 'TEMP1', 'value_type': 'FORMATTED', 'value': '5'} ]

override_tlm("INST HEALTH_STATUS TEMP1 = 5")
puts get_overrides() # =>
# [ {"target_name"=>"INST", "packet_name"=>"HEALTH_STATUS", "item_name"=>"TEMP1", "value_type"=>"RAW", "value"=>5}
#   {"target_name"=>"INST", "packet_name"=>"HEALTH_STATUS", "item_name"=>"TEMP1", "value_type"=>"CONVERTED", "value"=>5}
#   {"target_name"=>"INST", "packet_name"=>"HEALTH_STATUS", "item_name"=>"TEMP1", "value_type"=>"FORMATTED", "value"=>"5"} ]

Packet Data Subscriptions

APIs for subscribing to specific packets of data. This provides an interface to ensure that each telemetry packet is received and handled rather than relying on polling where some data may be missed.

subscribe_packets

Since 5.0.0

Allows the user to listen for one or more telemetry packets of data to arrive. A unique id is returned which is used to retrieve the data.

Python Syntax
Ruby Syntax

subscribe_packets(packets)

subscribe_packets(packets)

Parameter	Description
packets	Nested array of target name/packet name pairs that the user wishes to subscribe to.

Returns a unique id string which should be passed to get_packets to retrieve the subscribed data.

Python Example
Ruby Example

id = subscribe_packets([['INST', 'HEALTH_STATUS'], ['INST', 'ADCS']])

id = subscribe_packets([['INST', 'HEALTH_STATUS'], ['INST', 'ADCS']])

get_packets

Since 5.0.0

Streams packet data from a previous subscription. Returns an updated id and an array of packet hashes/dictionaries. The updated id should be passed to the next call to get_packets to continue streaming.

Python Syntax
Ruby Syntax

id, packets = get_packets(id, block=None, count=1000)

id, packets = get_packets(id, block: nil, count: 1000)

Parameter	Description
id	Unique id returned by subscribe_packets or the previous call to get_packets
block	Number of seconds to block while waiting for packets from ANY stream, default nil / None (do not block)
count	Maximum number of packets to return from EACH packet stream

Returns a two element array containing the updated id and an array of packet hashes/dictionaries. Each packet hash/dictionary contains the following keys:

Metadata keys:

Key	Type	Description
target_name	String	Target name, e.g. "INST"
packet_name	String	Packet name, e.g. "HEALTH_STATUS"
time	Integer	Packet time as nanoseconds since the Unix epoch
received_time	Integer	Time the packet was received as nanoseconds since the Unix epoch
received_count	Integer	Running count of packets received
stored	String	"true" or "false" indicating if the packet was stored (not realtime)

Telemetry item keys:

Each telemetry item in the packet is included with up to four keys using the item name with different suffixes:

Key	Description
ITEM_NAME	Raw value of the telemetry item
ITEM_NAME__C	Converted value (present if the item has states or a read conversion)
ITEM_NAME__F	Formatted value (present if the item has a format string or units)
ITEM_NAME__L	Limits state, e.g. "GREEN", "YELLOW", "RED" (present if the item has limits set)

For example, if the HEALTH_STATUS packet has a TEMP1 item with a conversion and limits, the packet hash/dictionary would contain TEMP1 (raw), TEMP1__C (converted), TEMP1__F (formatted), and TEMP1__L (limits state).

Python Example
Ruby Example

id = subscribe_packets([['INST', 'HEALTH_STATUS'], ['INST', 'ADCS']])
wait(0.1)
id, packets = get_packets(id)
for packet in packets:
    print(f"{packet['PACKET_TIMESECONDS']}: {packet['target_name']} {packet['packet_name']}")

# Reuse ID from last call, allow for 1s wait, only get 1 packet
id, packets = get_packets(id, block=1000, count=1)
for packet in packets:
    print(f"{packet['PACKET_TIMESECONDS']}: {packet['target_name']} {packet['packet_name']}")

id = subscribe_packets([['INST', 'HEALTH_STATUS'], ['INST', 'ADCS']])
wait 0.1
id, packets = get_packets(id)
packets.each do |packet|
  puts "#{packet['PACKET_TIMESECONDS']}: #{packet['target_name']} #{packet['packet_name']}"
end
# Reuse ID from last call, allow for 1s wait, only get 1 packet
id, packets = get_packets(id, block: 1000, count: 1)
packets.each do |packet|
  puts "#{packet['PACKET_TIMESECONDS']}: #{packet['target_name']} #{packet['packet_name']}"
end

get_tlm_cnt

Since 5.0.0

Get the receive count for a telemetry packet

Python Syntax
Ruby Syntax

get_tlm_cnt("<Target> <Packet>")
get_tlm_cnt("<Target>", "<Packet>")

get_tlm_cnt("<Target> <Packet>")
get_tlm_cnt("<Target>", "<Packet>")

Parameter	Description
Target	Target name
Packet	Packet name

Python Example
Ruby Example

get_tlm_cnt("INST HEALTH_STATUS")  # => 10

get_tlm_cnt("INST HEALTH_STATUS")  # => 10

get_tlm_cnts

Since 5.0.0

Get the receive counts for an array of telemetry packets

Python Syntax
Ruby Syntax

get_tlm_cnts([["<Target>", "<Packet>"], ["<Target>", "<Packet>"]])

get_tlm_cnts([["<Target>", "<Packet>"], ["<Target>", "<Packet>"]])

Parameter	Description
Target	Target name
Packet	Packet name

Python Example
Ruby Example

get_tlm_cnts([["INST", "ADCS"], ["INST", "HEALTH_STATUS"]])  # => [100, 10]

get_tlm_cnts([["INST", "ADCS"], ["INST", "HEALTH_STATUS"]])  # => [100, 10]

get_packet_derived_items

Since 5.0.0

Get the list of derived telemetry items for a packet

Python Syntax
Ruby Syntax

get_packet_derived_items("<Target> <Packet>")
get_packet_derived_items("<Target>", "<Packet>")

get_packet_derived_items("<Target> <Packet>")
get_packet_derived_items("<Target>", "<Packet>")

Parameter	Description
Target	Target name
Packet	Packet name

Python Example
Ruby Example

get_packet_derived_items("INST HEALTH_STATUS")  # => ['PACKET_TIMESECONDS', 'PACKET_TIMEFORMATTED', ...]

get_packet_derived_items("INST HEALTH_STATUS")  # => ['PACKET_TIMESECONDS', 'PACKET_TIMEFORMATTED', ...]

Delays

These methods allow the user to pause the script to wait for telemetry to change or for an amount of time to pass.

wait

Since 5.0.0

Pauses the script for a configurable amount of time (minimum 10ms) or until a converted telemetry item meets given criteria. It supports three different syntaxes as shown. If no parameters are given then an infinite wait occurs until the user presses Go. Note that on a timeout, wait does not stop the script, usually wait_check is a better choice.

Python Syntax
Ruby Syntax

elapsed = wait() # => Returns the actual time waited as float
elapsed = wait(<Time>) # => Returns the actual time waited as float

elapsed = wait() # => Returns the actual time waited as float
elapsed = wait(<Time>) # => Returns the actual time waited as float

Parameter	Description
Time	Time in Seconds to delay for.

Python Syntax
Ruby Syntax

# Returns True or False based on the whether the expression is True or False
success = wait(
  "<Target Name> <Packet Name> <Item Name> <Comparison>",
  <Timeout>,
  <Polling Rate (optional)>,
  type="CONVERTED",
  quiet=False
) # => True / False

# Returns true or false based on the whether the expression is true or false
success = wait(
  "<Target Name> <Packet Name> <Item Name> <Comparison>",
  <Timeout>,
  <Polling Rate (optional)>,
  type: :CONVERTED,
  quiet: false
) # => true / false

Parameter	Description
Target Name	Name of the target of the telemetry item.
Packet Name	Name of the telemetry packet of the telemetry item.
Item Name	Name of the telemetry item.
Comparison	A comparison to perform against the telemetry item.
Timeout	Timeout in seconds. Script will proceed if the wait statement times out waiting for the comparison to be true.
Polling Rate	How often the comparison is evaluated in seconds. Defaults to 0.25 if not specified.
type	Named parameter specifying the type. RAW, CONVERTED (default) or FORMATTED (Ruby symbol, Python string).
quiet	Named parameter indicating whether to log the result. Defaults to false which means log the wait.

Python Example
Ruby Example

elapsed = wait()
elapsed = wait(5)
success = wait("INST HEALTH_STATUS COLLECTS == 3", 10)
success = wait("INST HEALTH_STATUS COLLECTS == 3", 10, type='RAW', quiet=True)

elapsed = wait
elapsed = wait 5
success = wait("INST HEALTH_STATUS COLLECTS == 3", 10)
success = wait("INST HEALTH_STATUS COLLECTS == 3", 10, type: :RAW, quiet: true)

wait_tolerance

Since 5.0.0

Pauses the script for a configurable amount of time or until a converted telemetry item meets equals an expected value within a tolerance. Note that on a timeout, wait_tolerance does not stop the script, usually wait_check_tolerance is a better choice.

Python Syntax
Ruby Syntax

# Returns True or False based on the whether the expression is true or false
success = wait_tolerance(
  "<Target Name> <Packet Name> <Item Name>",  # Can also be given as individual parameters
  <Expected Value>,
  <Tolerance>,
  <Timeout>,
  <Polling Rate (optional)>,
  type="CONVERTED",
  quiet=False
) # => True / False

# Returns true or false based on the whether the expression is true or false
success = wait_tolerance(
  "<Target Name> <Packet Name> <Item Name>", # Can also be given as individual parameters
  <Expected Value>,
  <Tolerance>,
  <Timeout>,
  <Polling Rate (optional)>,
  type: :CONVERTED,
  quiet: false
) # => true / false

Parameter	Description
Target Name	Name of the target of the telemetry item.
Packet Name	Name of the telemetry packet of the telemetry item.
Item Name	Name of the telemetry item.
Expected Value	Expected value of the telemetry item.
Tolerance	± Tolerance on the expected value.
Timeout	Timeout in seconds. Script will proceed if the wait statement times out waiting for the comparison to be true.
Polling Rate	How often the comparison is evaluated in seconds. Defaults to 0.25 if not specified.
type	Named parameter specifying the type. RAW, CONVERTED (default) or FORMATTED (Ruby symbol, Python string).
quiet	Named parameter indicating whether to log the result. Defaults to false which means log the wait.

Ruby Examples:

success = wait_tolerance("INST HEALTH_STATUS COLLECTS", 10.0, 5.0, 10)
success = wait_tolerance("INST HEALTH_STATUS COLLECTS", 10.0, 5.0, 10, type: :RAW, quiet: true)

Python Examples:

success = wait_tolerance("INST HEALTH_STATUS COLLECTS", 10.0, 5.0, 10)
success = wait_tolerance("INST HEALTH_STATUS COLLECTS", 10.0, 5.0, 10, type='RAW', quiet=True)

wait_expression

Since 5.0.0

Pauses the script until an expression is evaluated to be true or a timeout occurs. If a timeout occurs the script will continue. This method can be used to perform more complicated comparisons than using wait as shown in the example. Note that on a timeout, wait_expression does not stop the script, usually wait_check_expression is a better choice.

Python Syntax
Ruby Syntax

# Return True or False based on the expression evaluation
wait_expression(
    exp_to_eval,
    timeout,
    polling_rate=DEFAULT_TLM_POLLING_RATE,
    globals=None,
    locals=None,
    quiet=False,
) # => True / False

# Return true or false based the expression evaluation
wait_expression(
  exp_to_eval,
  timeout,
  polling_rate = DEFAULT_TLM_POLLING_RATE,
  context = nil,
  quiet: false
) # => true / false

Parameter	Description
expression	An expression to evaluate.
timeout	Timeout in seconds. Script will proceed if the wait statement times out waiting for the comparison to be true.
polling_rate	How often the comparison is evaluated in seconds. Defaults to 0.25 if not specified.
context (ruby only)	The context to call eval with. Defaults to nil. Context in Ruby is typically binding() and is usually not needed.
globals (python only)	The globals to call eval with. Defaults to None. Note that to use COSMOS APIs like tlm() you must pass globals().
locals (python only)	The locals to call eval with. Defaults to None. Note that if you're using local variables in a method you must pass locals().
quiet	Whether to log the result. Defaults to false which means log the wait.

Python Example
Ruby Example

def check(value):
    # Here we using both tlm() and a local 'value' so we need to pass globals() and locals()
    return wait_expression("tlm('INST HEALTH_STATUS COLLECTS') > value", 5, 0.25, globals(), locals(), quiet=True)
success = check(5)

success = wait_expression("tlm('INST HEALTH_STATUS COLLECTS') > 5 and tlm('INST HEALTH_STATUS TEMP1') > 25.0", 10, 0.25, nil, quiet: true)

wait_packet

Since 5.0.0

Pauses the script until a certain number of packets have been received. If a timeout occurs the script will continue. Note that on a timeout, wait_packet does not stop the script, usually wait_check_packet is a better choice.

Python Syntax
Ruby Syntax

# Returns True or False based on the whether the packet was received
success = wait_packet(
  "<Target>",
  "<Packet>",
  <Num Packets>,
  <Timeout>,
  <Polling Rate (optional)>,
  quiet=False
) # => True / False

# Returns true or false based on the whether the packet was received
success = wait_packet(
  "<Target>",
  "<Packet>",
  <Num Packets>,
  <Timeout>,
  <Polling Rate (optional)>,
  quiet: false
) # => true / false

Parameter	Description
Target	The target name
Packet	The packet name
Num Packets	The number of packets to receive
Timeout	Timeout in seconds.
Polling Rate	How often the comparison is evaluated in seconds. Defaults to 0.25 if not specified.
quiet	Named parameter indicating whether to log the result. Defaults to false which means log the wait.

Python Example
Ruby Example

success = wait_packet('INST', 'HEALTH_STATUS', 5, 10) # Wait for 5 INST HEALTH_STATUS packets over 10s

success = wait_packet('INST', 'HEALTH_STATUS', 5, 10) # Wait for 5 INST HEALTH_STATUS packets over 10s

wait_check

Since 5.0.0

Combines the wait and check keywords into one. This pauses the script until the converted value of a telemetry item meets given criteria or times out. On a timeout the script stops.

Python Syntax
Ruby Syntax

# Returns the amount of time elapsed waiting for the expression
elapsed = wait_check(
  "<Target Name> <Packet Name> <Item Name> <Comparison>",
  <Timeout>,
  <Polling Rate (optional)>,
  type="CONVERTED"
) # => float

# Returns the amount of time elapsed waiting for the expression
elapsed = wait_check(
  "<Target Name> <Packet Name> <Item Name> <Comparison>",
  <Timeout>,
  <Polling Rate (optional)>,
  type: :CONVERTED
) # => float

Parameter	Description
Target Name	Name of the target of the telemetry item.
Packet Name	Name of the telemetry packet of the telemetry item.
Item Name	Name of the telemetry item.
Comparison	A comparison to perform against the telemetry item.
Timeout	Timeout in seconds. Script will stop if the wait statement times out waiting for the comparison to be true.
Polling Rate	How often the comparison is evaluated in seconds. Defaults to 0.25 if not specified.
type	Named parameter specifying the type. RAW, CONVERTED (default) or FORMATTED (Ruby symbol, Python string).

Python Example
Ruby Example

elapsed = wait_check("INST HEALTH_STATUS COLLECTS > 5", 10)
elapsed = wait_check("INST HEALTH_STATUS COLLECTS > 5", 10, type='RAW')

elapsed = wait_check("INST HEALTH_STATUS COLLECTS > 5", 10)
elapsed = wait_check("INST HEALTH_STATUS COLLECTS > 5", 10, type: :RAW)

wait_check_tolerance

Since 5.0.0

Pauses the script for a configurable amount of time or until a converted telemetry item equals an expected value within a tolerance. On a timeout the script stops.

Python Syntax
Ruby Syntax

# Returns the amount of time elapsed waiting for the expression
elapsed = wait_check_tolerance(
  "<Target Name> <Packet Name> <Item Name>",
  <Expected Value>,
  <Tolerance>,
  <Timeout>,
  <Polling Rate (optional)>,
  type="CONVERTED"
) # => float

# Returns the amount of time elapsed waiting for the expression
elapsed = wait_check_tolerance(
  "<Target Name> <Packet Name> <Item Name>",
  <Expected Value>,
  <Tolerance>,
  <Timeout>,
  <Polling Rate (optional)>,
  type: :CONVERTED
) # => float

Parameter	Description
Target Name	Name of the target of the telemetry item.
Packet Name	Name of the telemetry packet of the telemetry item.
Item Name	Name of the telemetry item.
Expected Value	Expected value of the telemetry item.
Tolerance	± Tolerance on the expected value.
Timeout	Timeout in seconds. Script will stop if the wait statement times out waiting for the comparison to be true.
Polling Rate	How often the comparison is evaluated in seconds. Defaults to 0.25 if not specified.
type	Named parameter specifying the type. RAW, CONVERTED (default) or FORMATTED (Ruby symbol, Python string).

Python Example
Ruby Example

elapsed = wait_check_tolerance("INST HEALTH_STATUS COLLECTS", 10.0, 5.0, 10)
elapsed = wait_check_tolerance("INST HEALTH_STATUS COLLECTS", 10.0, 5.0, 10, type='RAW')

elapsed = wait_check_tolerance("INST HEALTH_STATUS COLLECTS", 10.0, 5.0, 10)
elapsed = wait_check_tolerance("INST HEALTH_STATUS COLLECTS", 10.0, 5.0, 10, type: :RAW)

wait_check_expression

Since 5.0.0

Pauses the script until an expression is evaluated to be true or a timeout occurs. If a timeout occurs the script will stop. This method can be used to perform more complicated comparisons than using wait as shown in the example. Also see the syntax notes for check_expression.

Python Syntax
Ruby Syntax

# Return time spent waiting for the expression to evaluate to True
wait_check_expression(
    exp_to_eval,
    timeout,
    polling_rate=DEFAULT_TLM_POLLING_RATE,
    globals=None,
    locals=None
) # => float

# Return time spent waiting for the expression to evaluate to true
wait_check_expression(
  exp_to_eval,
  timeout,
  polling_rate = DEFAULT_TLM_POLLING_RATE,
  context = nil
) # => float

Parameter	Description
expression	An expression to evaluate.
timeout	Timeout in seconds. Script will proceed if the wait statement times out waiting for the comparison to be true.
polling_rate	How often the comparison is evaluated in seconds. Defaults to 0.25 if not specified.
context (ruby only)	The context to call eval with. Defaults to nil. Context in Ruby is typically binding() and is usually not needed.
globals (python only)	The globals to call eval with. Defaults to None. Note that to use COSMOS APIs like tlm() you must pass globals().
locals (python only)	The locals to call eval with. Defaults to None. Note that if you're using local variables in a method you must pass locals().

Python Example
Ruby Example

# Note that for Python we need to pass globals() to be able to use COSMOS API methods like tlm()
elapsed = wait_check_expression("tlm('INST HEALTH_STATUS COLLECTS') > 5 and tlm('INST HEALTH_STATUS TEMP1') > 25.0", 10, 0.25, globals())

elapsed = wait_check_expression("tlm('INST HEALTH_STATUS COLLECTS') > 5 and tlm('INST HEALTH_STATUS TEMP1') > 25.0", 10)

wait_check_packet

Since 5.0.0

Pauses the script until a certain number of packets have been received. If a timeout occurs the script will stop.

Python Syntax
Ruby Syntax

# Returns the amount of time elapsed waiting for the packets
elapsed = wait_check_packet(
  "<Target>",
  "<Packet>",
  <Num Packets>,
  <Timeout>,
  <Polling Rate (optional)>,
  quiet=False
) # => float

# Returns the amount of time elapsed waiting for the packets
elapsed = wait_check_packet(
  "<Target>",
  "<Packet>",
  <Num Packets>,
  <Timeout>,
  <Polling Rate (optional)>,
  quiet=false
) # => float

Parameter	Description
Target	The target name
Packet	The packet name
Num Packets	The number of packets to receive
Timeout	Timeout in seconds. Script will stop if the wait statement times out waiting specified number of packets.
Polling Rate	How often the comparison is evaluated in seconds. Defaults to 0.25 if not specified.
quiet	Named parameter indicating whether to log the result. Defaults to false which means log the wait.

Python Example
Ruby Example

elapsed = wait_check_packet('INST', 'HEALTH_STATUS', 5, 10) # Wait for 5 INST HEALTH_STATUS packets over 10s

elapsed = wait_check_packet('INST', 'HEALTH_STATUS', 5, 10) # Wait for 5 INST HEALTH_STATUS packets over 10s

Limits

These methods deal with handling telemetry limits.

limits_enabled?, limits_enabled

Since 5.0.0

The limits_enabled? method returns true/false depending on whether limits are enabled for a telemetry item.

Python Syntax
Ruby Syntax

limits_enabled("<Target Name> <Packet Name> <Item Name>")

limits_enabled?("<Target Name> <Packet Name> <Item Name>")

Parameter	Description
Target Name	Name of the target of the telemetry item.
Packet Name	Name of the telemetry packet of the telemetry item.
Item Name	Name of the telemetry item.

Python Example
Ruby Example

enabled = limits_enabled("INST HEALTH_STATUS TEMP1") # => True or False

enabled = limits_enabled?("INST HEALTH_STATUS TEMP1") # => true or false

enable_limits

Since 5.0.0

Enables limits monitoring for the specified telemetry item.

Python Syntax
Ruby Syntax

enable_limits("<Target Name> <Packet Name> <Item Name>")

enable_limits("<Target Name> <Packet Name> <Item Name>")

Parameter	Description
Target Name	Name of the target of the telemetry item.
Packet Name	Name of the telemetry packet of the telemetry item.
Item Name	Name of the telemetry item.

Python Example
Ruby Example

enable_limits("INST HEALTH_STATUS TEMP1")

enable_limits("INST HEALTH_STATUS TEMP1")

disable_limits

Since 5.0.0

Disables limits monitoring for the specified telemetry item.

Python Syntax
Ruby Syntax

disable_limits("<Target Name> <Packet Name> <Item Name>")

disable_limits("<Target Name> <Packet Name> <Item Name>")

Parameter	Description
Target Name	Name of the target of the telemetry item.
Packet Name	Name of the telemetry packet of the telemetry item.
Item Name	Name of the telemetry item.

Python Example
Ruby Example

disable_limits("INST HEALTH_STATUS TEMP1")

disable_limits("INST HEALTH_STATUS TEMP1")

enable_limits_group

Since 5.0.0

Enables limits monitoring on a set of telemetry items specified in a limits group.

Python Syntax
Ruby Syntax

enable_limits_group("<Limits Group Name>")

enable_limits_group("<Limits Group Name>")

Parameter	Description
Limits Group Name	Name of the limits group.

Python Example
Ruby Example

enable_limits_group("SAFE_MODE")

enable_limits_group("SAFE_MODE")

disable_limits_group

Since 5.0.0

Disables limits monitoring on a set of telemetry items specified in a limits group.

Python Syntax
Ruby Syntax

disable_limits_group("<Limits Group Name>")

disable_limits_group("<Limits Group Name>")

Parameter	Description
Limits Group Name	Name of the limits group.

Python Example
Ruby Example

disable_limits_group("SAFE_MODE")

disable_limits_group("SAFE_MODE")

get_limits_groups

Since 5.0.0

Returns the list of limits groups in the system.

Python Example
Ruby Example

limits_groups = get_limits_groups()

limits_groups = get_limits_groups()

set_limits_set

Since 5.0.0

Sets the current limits set. The default limits set is DEFAULT.

Python Syntax
Ruby Syntax

set_limits_set("<Limits Set Name>")

set_limits_set("<Limits Set Name>")

Parameter	Description
Limits Set Name	Name of the limits set.

Python Example
Ruby Example

set_limits_set("DEFAULT")

set_limits_set("DEFAULT")

get_limits_set

Since 5.0.0

Returns the name of the current limits set. The default limits set is DEFAULT.

Python Example
Ruby Example

limits_set = get_limits_set()

limits_set = get_limits_set()

get_limits_sets

Since 5.0.0

Returns the list of limits sets in the system.

Python Example
Ruby Example

limits_sets = get_limits_sets()

limits_sets = get_limits_sets()

get_limits

Since 5.0.0

Returns hash / dict of all the limits settings for a telemetry point.

Python Syntax
Ruby Syntax

get_limits(<Target Name>, <Packet Name>, <Item Name>)

get_limits(<Target Name>, <Packet Name>, <Item Name>)

Parameter	Description
Target Name	Name of the target of the telemetry item
Packet Name	Name of the telemetry packet of the telemetry item
Item Name	Name of the telemetry item

Python Example
Ruby Example

result = get_limits('INST', 'HEALTH_STATUS', 'TEMP1')
print(result) # => {'DEFAULT'=>[-80.0, -70.0, 60.0, 80.0, -20.0, 20.0], 'TVAC'=>[-80.0, -30.0, 30.0, 80.0]}
print(result.keys()) # => dict_keys(['DEFAULT', 'TVAC'])
print(result['DEFAULT']) # => [-80.0, -70.0, 60.0, 80.0, -20.0, 20.0]

result = get_limits('INST', 'HEALTH_STATUS', 'TEMP1')
puts result # => {"DEFAULT"=>[-80.0, -70.0, 60.0, 80.0, -20.0, 20.0], "TVAC"=>[-80.0, -30.0, 30.0, 80.0]}
puts result.keys # => ['DEFAULT', 'TVAC']
puts result['DEFAULT'] # => [-80.0, -70.0, 60.0, 80.0, -20.0, 20.0]

set_limits

Since 5.0.0

The set_limits method sets limits settings for a telemetry point. Note: In most cases it would be better to update your config files or use different limits sets rather than changing limits settings in realtime.

Python Syntax
Ruby Syntax

set_limits(<Target Name>, <Packet Name>, <Item Name>, <Red Low>, <Yellow Low>, <Yellow High>, <Red High>, <Green Low (optional)>, <Green High (optional)>, <Limits Set (optional)>, <Persistence (optional)>, <Enabled (optional)>)

set_limits(<Target Name>, <Packet Name>, <Item Name>, <Red Low>, <Yellow Low>, <Yellow High>, <Red High>, <Green Low (optional)>, <Green High (optional)>, <Limits Set (optional)>, <Persistence (optional)>, <Enabled (optional)>)

Parameter	Description
Target Name	Name of the target of the telemetry item.
Packet Name	Name of the telemetry packet of the telemetry item.
Item Name	Name of the telemetry item.
Red Low	Red Low setting for this limits set. Any value below this value will be make the item red.
Yellow Low	Yellow Low setting for this limits set. Any value below this value but greater than Red Low will be make the item yellow.
Yellow High	Yellow High setting for this limits set. Any value above this value but less than Red High will be make the item yellow.
Red High	Red High setting for this limits set. Any value above this value will be make the item red.
Green Low	Optional. If given, any value greater than Green Low and less than Green_High will make the item blue indicating a good operational value.
Green High	Optional. If given, any value greater than Green Low and less than Green_High will make the item blue indicating a good operational value.
Limits Set	Optional. Set the limits for a specific limits set. If not given then it defaults to setting limits for the CUSTOM limits set.
Persistence	Optional. Set the number of samples this item must be out of limits before changing limits state. Defaults to no change. Note: This affects all limits settings across limits sets.
Enabled	Optional. Whether or not limits are enabled for this item. Defaults to true. Note: This affects all limits settings across limits sets.

Python Example
Ruby Example

set_limits('INST', 'HEALTH_STATUS', 'TEMP1', -10.0, 0.0, 50.0, 60.0, 30.0, 40.0, 'TVAC', 1, True)

set_limits('INST', 'HEALTH_STATUS', 'TEMP1', -10.0, 0.0, 50.0, 60.0, 30.0, 40.0, 'TVAC', 1, true)

get_out_of_limits

Since 5.0.0

Returns an array with the target_name, packet_name, item_name, and limits_state of all items that are out of their limits ranges.

Python Example
Ruby Example

out_of_limits_items = get_out_of_limits()

out_of_limits_items = get_out_of_limits()

get_overall_limits_state

Since 5.0.0

Returns the overall limits state for the COSMOS system. Returns 'GREEN', 'YELLOW', or 'RED'.

Python Syntax
Ruby Syntax

get_overall_limits_state(<Ignored Items> (optional))

get_overall_limits_state(<Ignored Items> (optional))

Parameter	Description
Ignored Items	Array of arrays with items to ignore when determining the overall limits state. [['TARGET_NAME', 'PACKET_NAME', 'ITEM_NAME'], ...]

Python Example
Ruby Example

overall_limits_state = get_overall_limits_state()
overall_limits_state = get_overall_limits_state([['INST', 'HEALTH_STATUS', 'TEMP1']])

overall_limits_state = get_overall_limits_state()
overall_limits_state = get_overall_limits_state([['INST', 'HEALTH_STATUS', 'TEMP1']])

get_limits_events

Since 5.0.0

Returns limits events based on an offset returned from the last time it was called.

Python Syntax
Ruby Syntax

get_limits_event(<Offset>, count)

get_limits_event(<Offset>, count)

Parameter	Description
Offset	Offset returned by the previous call to get_limits_event. Default is nil for the initial call
count	Named parameter specifying the maximum number of limits events to return. Default is 100

Python Example
Ruby Example

events = get_limits_event()
print(events)
#[["1613077715557-0",
#  {"type"=>"LIMITS_CHANGE",
#   "target_name"=>"TGT",
#   "packet_name"=>"PKT",
#   "item_name"=>"ITEM",
#   "old_limits_state"=>"YELLOW_LOW",
#   "new_limits_state"=>"RED_LOW",
#   "time_nsec"=>"1",
#   "message"=>"message"}],
# ["1613077715557-1",
#  {"type"=>"LIMITS_CHANGE",
#   "target_name"=>"TGT",
#   "packet_name"=>"PKT",
#   "item_name"=>"ITEM",
#   "old_limits_state"=>"RED_LOW",
#   "new_limits_state"=>"YELLOW_LOW",
#   "time_nsec"=>"2",
#   "message"=>"message"}]]
# The last offset is the first item ([0]) in the last event ([-1])
events = get_limits_event(events[-1][0])
print(events)
#[["1613077715657-0",
#  {"type"=>"LIMITS_CHANGE",
#   ...

events = get_limits_event()
puts events
#[["1613077715557-0",
#  {"type"=>"LIMITS_CHANGE",
#   "target_name"=>"TGT",
#   "packet_name"=>"PKT",
#   "item_name"=>"ITEM",
#   "old_limits_state"=>"YELLOW_LOW",
#   "new_limits_state"=>"RED_LOW",
#   "time_nsec"=>"1",
#   "message"=>"message"}],
# ["1613077715557-1",
#  {"type"=>"LIMITS_CHANGE",
#   "target_name"=>"TGT",
#   "packet_name"=>"PKT",
#   "item_name"=>"ITEM",
#   "old_limits_state"=>"RED_LOW",
#   "new_limits_state"=>"YELLOW_LOW",
#   "time_nsec"=>"2",
#   "message"=>"message"}]]
# The last offset is the first item ([0]) in the last event ([-1])
events = get_limits_event(events[-1][0])
puts events
#[["1613077715657-0",
#  {"type"=>"LIMITS_CHANGE",
#   ...

Plugins / Packages

APIs for getting knowledge about plugins and packages.

plugin_list

Since 5.6.0

Returns all the installed plugins.

Python Syntax
Ruby Syntax

plugin_list(default = False)

plugin_list(default: false)

Parameter	Description
default	Whether to include the default COSMOS plugins (all the regular applications)

Python Example
Ruby Example

plugins = plugin_list() # => ['openc3-cosmos-demo-6.0.3.pre.beta0.20250116214358.gem__20250116214539']
plugins = plugin_list(default=True) # =>
# ['openc3-cosmos-demo-6.0.3.pre.beta0.20250116214358.gem__20250116214539',
#  'openc3-cosmos-tool-admin-6.0.3.pre.beta0.20250115200004.gem__20250116211504',
#  'openc3-cosmos-tool-bucketexplorer-6.0.3.pre.beta0.20250115200008.gem__20250116211525',
#  'openc3-cosmos-tool-cmdsender-6.0.3.pre.beta0.20250115200012.gem__20250116211515',
#  'openc3-cosmos-tool-cmdtlmserver-6.0.3.pre.beta0.20250115200015.gem__20250116211512',
#  'openc3-cosmos-tool-dataextractor-6.0.3.pre.beta0.20250115200005.gem__20250116211521',
#  'openc3-cosmos-tool-dataviewer-6.0.3.pre.beta0.20250115200009.gem__20250116211522',
#  'openc3-cosmos-tool-docs-6.0.3.pre.beta0.20250117042104.gem__20250117042154',
#  'openc3-cosmos-tool-handbooks-6.0.3.pre.beta0.20250115200014.gem__20250116211523',
#  'openc3-cosmos-tool-iframe-6.0.3.pre.beta0.20250115200011.gem__20250116211503',
#  'openc3-cosmos-tool-limitsmonitor-6.0.3.pre.beta0.20250115200017.gem__20250116211514',
#  'openc3-cosmos-tool-packetviewer-6.0.3.pre.beta0.20250115200004.gem__20250116211518',
#  'openc3-cosmos-tool-scriptrunner-6.0.3.pre.beta0.20250115200012.gem__20250116211517',
#  'openc3-cosmos-tool-tablemanager-6.0.3.pre.beta0.20250115200018.gem__20250116211524',
#  'openc3-cosmos-tool-tlmgrapher-6.0.3.pre.beta0.20250115200005.gem__20250116211520',
#  'openc3-cosmos-tool-tlmviewer-6.0.3.pre.beta0.20250115200008.gem__20250116211519',
#  'openc3-tool-base-6.0.3.pre.beta0.20250115195959.gem__20250116211459']

plugins = plugin_list() # => ['openc3-cosmos-demo-6.0.3.pre.beta0.20250116214358.gem__20250116214539']
plugins = plugin_list(default: true) # =>
# ['openc3-cosmos-demo-6.0.3.pre.beta0.20250116214358.gem__20250116214539',
#  'openc3-cosmos-tool-admin-6.0.3.pre.beta0.20250115200004.gem__20250116211504',
#  'openc3-cosmos-tool-bucketexplorer-6.0.3.pre.beta0.20250115200008.gem__20250116211525',
#  'openc3-cosmos-tool-cmdsender-6.0.3.pre.beta0.20250115200012.gem__20250116211515',
#  'openc3-cosmos-tool-cmdtlmserver-6.0.3.pre.beta0.20250115200015.gem__20250116211512',
#  'openc3-cosmos-tool-dataextractor-6.0.3.pre.beta0.20250115200005.gem__20250116211521',
#  'openc3-cosmos-tool-dataviewer-6.0.3.pre.beta0.20250115200009.gem__20250116211522',
#  'openc3-cosmos-tool-docs-6.0.3.pre.beta0.20250117042104.gem__20250117042154',
#  'openc3-cosmos-tool-handbooks-6.0.3.pre.beta0.20250115200014.gem__20250116211523',
#  'openc3-cosmos-tool-iframe-6.0.3.pre.beta0.20250115200011.gem__20250116211503',
#  'openc3-cosmos-tool-limitsmonitor-6.0.3.pre.beta0.20250115200017.gem__20250116211514',
#  'openc3-cosmos-tool-packetviewer-6.0.3.pre.beta0.20250115200004.gem__20250116211518',
#  'openc3-cosmos-tool-scriptrunner-6.0.3.pre.beta0.20250115200012.gem__20250116211517',
#  'openc3-cosmos-tool-tablemanager-6.0.3.pre.beta0.20250115200018.gem__20250116211524',
#  'openc3-cosmos-tool-tlmgrapher-6.0.3.pre.beta0.20250115200005.gem__20250116211520',
#  'openc3-cosmos-tool-tlmviewer-6.0.3.pre.beta0.20250115200008.gem__20250116211519',
#  'openc3-tool-base-6.0.3.pre.beta0.20250115195959.gem__20250116211459']

plugin_get

Since 5.6.0

Returns information about an installed plugin.

Python Syntax
Ruby Syntax

plugin_get(<Plugin Name>)

plugin_get(<Plugin Name>)

Parameter	Description
Plugin Name	Full name of the plugin (typically taken from plugin_list())

Python Example
Ruby Example

plugin_get('openc3-cosmos-demo-6.0.3.pre.beta0.20250116214358.gem__20250116214539') # =>
# { "name"=>"openc3-cosmos-demo-6.0.3.pre.beta0.20250116214358.gem__20250116214539",
#   "variables"=>{"inst_target_name"=>"INST", ...},
#   "plugin_txt_lines"=>["# Note: This plugin includes 4 targets ..."],
#   "needs_dependencies"=>true,
#   "updated_at"=>1737063941094624764 }

plugin_get('openc3-cosmos-demo-6.0.3.pre.beta0.20250116214358.gem__20250116214539') # =>
# { "name"=>"openc3-cosmos-demo-6.0.3.pre.beta0.20250116214358.gem__20250116214539",
#   "variables"=>{"inst_target_name"=>"INST", ...},
#   "plugin_txt_lines"=>["# Note: This plugin includes 4 targets ..."],
#   "needs_dependencies"=>true,
#   "updated_at"=>1737063941094624764 }

package_list

Since 5.12.0

List all the packages installed in COSMOS.

Python Example
Ruby Example

package_list() # => {'ruby': ['openc3-cosmos-demo-6.0.3.pre.beta0.20250116214358.gem', ..., 'openc3-tool-base-6.0.3.pre.beta0.20250115195959.gem'],
               #    'python': ['numpy-2.1.1', 'pip-24.0', 'setuptools-65.5.0']}

package_list() # => {"ruby"=>["openc3-cosmos-demo-6.0.3.pre.beta0.20250116214358.gem", ..., "openc3-tool-base-6.0.3.pre.beta0.20250115195959.gem"],
               #    "python"=>["numpy-2.1.1", "pip-24.0", "setuptools-65.5.0"]}

Targets

APIs for getting knowledge about targets.

get_target_names

Since 5.9.1

Returns a list of the targets in the system in an array. Previously get_target_list.

Python Example
Ruby Example

targets = get_target_names() # => ['INST', 'INST2', 'EXAMPLE', 'TEMPLATED']

targets = get_target_names() # => ['INST', 'INST2', 'EXAMPLE', 'TEMPLATED']

get_target

Since 5.0.0

Returns a target hash containing all the information about the target.

Python Syntax
Ruby Syntax

get_target("<Target Name>")

get_target("<Target Name>")

Parameter	Description
Target Name	Name of the target.

Python Example
Ruby Example

target = get_target("INST")
print(target)
# {"name"=>"INST",
#  "folder_name"=>"INST",
#  "requires"=>[],
#  "ignored_parameters"=>
#   ["CCSDSVER",
#    "CCSDSTYPE",
#    "CCSDSSHF",
#    "CCSDSAPID",
#    "CCSDSSEQFLAGS",
#    "CCSDSSEQCNT",
#    "CCSDSLENGTH",
#    "PKTID"],
#  "ignored_items"=>
#   ["CCSDSVER",
#    "CCSDSTYPE",
#    "CCSDSSHF",
#    "CCSDSAPID",
#    "CCSDSSEQFLAGS",
#    "CCSDSSEQCNT",
#    "CCSDSLENGTH",
#    "RECEIVED_COUNT",
#    "RECEIVED_TIMESECONDS",
#    "RECEIVED_TIMEFORMATTED"],
#  "limits_groups"=>[],
#  "cmd_tlm_files"=>
#   [".../targets/INST/cmd_tlm/inst_cmds.txt",
#    ".../targets/INST/cmd_tlm/inst_tlm.txt"],
#  "cmd_unique_id_mode"=>false,
#  "tlm_unique_id_mode"=>false,
#  "id"=>nil,
#  "updated_at"=>1613077058266815900,
#  "plugin"=>nil}

target = get_target("INST")
puts target
# {"name"=>"INST",
#  "folder_name"=>"INST",
#  "requires"=>[],
#  "ignored_parameters"=>
#   ["CCSDSVER",
#    "CCSDSTYPE",
#    "CCSDSSHF",
#    "CCSDSAPID",
#    "CCSDSSEQFLAGS",
#    "CCSDSSEQCNT",
#    "CCSDSLENGTH",
#    "PKTID"],
#  "ignored_items"=>
#   ["CCSDSVER",
#    "CCSDSTYPE",
#    "CCSDSSHF",
#    "CCSDSAPID",
#    "CCSDSSEQFLAGS",
#    "CCSDSSEQCNT",
#    "CCSDSLENGTH",
#    "RECEIVED_COUNT",
#    "RECEIVED_TIMESECONDS",
#    "RECEIVED_TIMEFORMATTED"],
#  "limits_groups"=>[],
#  "cmd_tlm_files"=>
#   [".../targets/INST/cmd_tlm/inst_cmds.txt",
#    ".../targets/INST/cmd_tlm/inst_tlm.txt"],
#  "cmd_unique_id_mode"=>false,
#  "tlm_unique_id_mode"=>false,
#  "id"=>nil,
#  "updated_at"=>1613077058266815900,
#  "plugin"=>nil}

get_target_interfaces

Since 5.0.0

Returns the interfaces for all targets. The return value is an array of arrays where each subarray contains the target name, and a String of all the interface names.

Python Example
Ruby Example

target_ints = get_target_interfaces()
for target_name, interfaces in target_ints:
    print(f"Target: {target_name}, Interfaces: {interfaces}")

target_ints = get_target_interfaces()
target_ints.each do |target_name, interfaces|
  puts "Target: #{target_name}, Interfaces: #{interfaces}"
end

Interfaces

These methods allow the user to manipulate COSMOS interfaces.

get_interface

Since 5.0.0

Returns an interface status including the as built interface and its current status (cmd/tlm counters, etc).

Python Syntax
Ruby Syntax

get_interface("<Interface Name>")

get_interface("<Interface Name>")

Parameter	Description
Interface Name	Name of the interface.

Python Example
Ruby Example

interface = get_interface("INST_INT")
print(interface)
# {"name"=>"INST_INT",
#  "config_params"=>["interface.rb"],
#  "target_names"=>["INST"],
#  "connect_on_startup"=>true,
#  "auto_reconnect"=>true,
#  "reconnect_delay"=>5.0,
#  "disable_disconnect"=>false,
#  "options"=>[],
#  "protocols"=>[],
#  "log"=>true,
#  "log_raw"=>false,
#  "plugin"=>nil,
#  "updated_at"=>1613076213535979900,
#  "state"=>"CONNECTED",
#  "clients"=>0,
#  "txsize"=>0,
#  "rxsize"=>0,
#  "txbytes"=>0,
#  "rxbytes"=>0,
#  "txcnt"=>0,
#  "rxcnt"=>0}

interface = get_interface("INST_INT")
puts interface
# {"name"=>"INST_INT",
#  "config_params"=>["interface.rb"],
#  "target_names"=>["INST"],
#  "connect_on_startup"=>true,
#  "auto_reconnect"=>true,
#  "reconnect_delay"=>5.0,
#  "disable_disconnect"=>false,
#  "options"=>[],
#  "protocols"=>[],
#  "log"=>true,
#  "log_raw"=>false,
#  "plugin"=>nil,
#  "updated_at"=>1613076213535979900,
#  "state"=>"CONNECTED",
#  "clients"=>0,
#  "txsize"=>0,
#  "rxsize"=>0,
#  "txbytes"=>0,
#  "rxbytes"=>0,
#  "txcnt"=>0,
#  "rxcnt"=>0}

get_interface_names

Since 5.0.0

Returns a list of the interfaces in the system in an array.

Python Example
Ruby Example

interface_names = get_interface_names() # => ['INST_INT', 'INST2_INT', 'EXAMPLE_INT', 'TEMPLATED_INT']

interface_names = get_interface_names() # => ['INST_INT', 'INST2_INT', 'EXAMPLE_INT', 'TEMPLATED_INT']

connect_interface

Since 5.0.0

Connects to targets associated with a COSMOS interface.

Python Syntax
Ruby Syntax

connect_interface("<Interface Name>", <Interface Parameters (optional)>)

connect_interface("<Interface Name>", <Interface Parameters (optional)>)

Parameter	Description
Interface Name	Name of the interface.
Interface Parameters	Parameters used to initialize the interface. If none are given then the interface will use the parameters that were given in the server configuration file.

Python Example
Ruby Example

connect_interface("INT1")
connect_interface("INT1", hostname, port)

connect_interface("INT1")
connect_interface("INT1", hostname, port)

disconnect_interface

Since 5.0.0

Disconnects from targets associated with a COSMOS interface.

Python Syntax
Ruby Syntax

disconnect_interface("<Interface Name>")

disconnect_interface("<Interface Name>")

Parameter	Description
Interface Name	Name of the interface.

Python Example
Ruby Example

disconnect_interface("INT1")

disconnect_interface("INT1")

start_raw_logging_interface

Since 5.0.0

Starts logging of raw data on one or all interfaces. This is for debugging purposes only.

Python Syntax
Ruby Syntax

start_raw_logging_interface("<Interface Name (optional)>")

start_raw_logging_interface("<Interface Name (optional)>")

Parameter	Description
Interface Name	Name of the Interface to command to start raw data logging. Defaults to 'ALL' which causes all interfaces that support raw data logging to start logging raw data.

Python Example
Ruby Example

start_raw_logging_interface("int1")

start_raw_logging_interface("int1")

stop_raw_logging_interface

Since 5.0.0

Stops logging of raw data on one or all interfaces. This is for debugging purposes only.

Python Syntax
Ruby Syntax

stop_raw_logging_interface("<Interface Name (optional)>")

stop_raw_logging_interface("<Interface Name (optional)>")

Parameter	Description
Interface Name	Name of the Interface to command to stop raw data logging. Defaults to 'ALL' which causes all interfaces that support raw data logging to stop logging raw data.

Python Example
Ruby Example

stop_raw_logging_interface("int1")

stop_raw_logging_interface("int1")

get_all_interface_info

Since 5.0.0

Returns information about all interfaces. The return value is an array of arrays where each subarray contains the interface name, connection state, number of connected clients, transmit queue size, receive queue size, bytes transmitted, bytes received, command count, and telemetry count.

Python Example
Ruby Example

interface_info = get_all_interface_info()
for interface in interface_info():
    # [interface_name, connection_state, num_clients, tx_q_size, rx_q_size, tx_bytes, rx_bytes, cmd_count, tlm_count]
    print(f"Interface: {interface[0]}, Connection state: {interface[1]}, Num connected clients: {interface[2]}")
    print(f"Transmit queue size: {interface[3]}, Receive queue size: {interface[4]}, Bytes transmitted: {interface[5]}, Bytes received: {interface[6]}")
    print(f"Cmd count: {interface[7]}, Tlm count: {interface[8]}")

interface_info = get_all_interface_info()
interface_info.each do |interface_name, connection_state, num_clients, tx_q_size, rx_q_size, tx_bytes, rx_bytes, cmd_count, tlm_count|
  puts "Interface: #{interface_name}, Connection state: #{connection_state}, Num connected clients: #{num_clients}"
  puts "Transmit queue size: #{tx_q_size}, Receive queue size: #{rx_q_size}, Bytes transmitted: #{tx_bytes}, Bytes received: #{rx_bytes}"
  puts "Cmd count: #{cmd_count}, Tlm count: #{tlm_count}"
end

map_target_to_interface

Since 5.0.9

Map a target to an interface allowing target commands and telemetry to be processed by that interface. Note this will cause the interface to respawn.

Python Syntax
Ruby Syntax

map_target_to_interface("<Target Name>", "<Interface Name>", cmd_only=False, tlm_only=False, unmap_old=True)

map_target_to_interface("<Target Name>", "<Interface Name>", cmd_only: false, tlm_only: false, unmap_old: true)

Parameter	Description
Target Name	Name of the target
Interface Name	Name of the interface
cmd_only	Named parameter whether to map target commands only to the interface (default: false)
tlm_only	Named parameter whether to map target telemetry only to the interface (default: false)
unmap_old	Named parameter whether remove the target from all existing interfaces (default: true)

Python Example
Ruby Example

map_target_to_interface("INST", "INST_INT", unmap_old=False)
map_target_to_interface("INST", "INST_INT", cmd_only=True)
map_target_to_interface("INST", "INST_INT", tlm_only=True)

map_target_to_interface("INST", "INST_INT", unmap_old: false)
map_target_to_interface("INST", "INST_INT", cmd_only: true)
map_target_to_interface("INST", "INST_INT", tlm_only: true)

unmap_target_from_interface

Since 6.9.0

Unmap a target from an interface. This removes all knowledge of the target and will cause the interface to respawn.

Python Syntax
Ruby Syntax

unmap_target_from_interface("<Target Name>", "<Interface Name>", cmd_only=False, tlm_only=False)

unmap_target_from_interface("<Target Name>", "<Interface Name>", cmd_only: false, tlm_only: false)

Parameter	Description
Target Name	Name of the target
Interface Name	Name of the interface
cmd_only	Named parameter whether to unmap target commands only to the interface (default: false)
tlm_only	Named parameter whether to unmap target telemetry only to the interface (default: false)

Python Example
Ruby Example

unmap_target_from_interface("INST", "INST_INT")
unmap_target_from_interface("INST", "INST_INT", cmd_only=True)
unmap_target_from_interface("INST", "INST_INT", tlm_only=True)

unmap_target_from_interface("INST", "INST_INT")
unmap_target_from_interface("INST", "INST_INT", cmd_only: true)
unmap_target_from_interface("INST", "INST_INT", tlm_only: true)

interface_cmd

Since 5.3.0

Send a command directly to an interface. This has no effect in the standard COSMOS interfaces but can be implemented by a custom interface to change behavior.

Python Syntax
Ruby Syntax

interface_cmd("<Interface Name>", "<Command Name>", "<Command Parameters>")

interface_cmd("<Interface Name>", "<Command Name>", "<Command Parameters>")

Parameter	Description
Interface Name	Name of the interface
Command Name	Name of the command to send
Command Parameters	Any parameters to send with the command

Python Example
Ruby Example

interface_cmd("INST", "DISABLE_CRC")

interface_cmd("INST", "DISABLE_CRC")

interface_protocol_cmd

Since 5.3.0

Send a command directly to an interface protocol. This has no effect in the standard COSMOS protocols but can be implemented by a custom protocol to change behavior.

Python Syntax
Ruby Syntax

interface_protocol_cmd("<Interface Name>", "<Command Name>", "<Command Parameters>")

interface_protocol_cmd("<Interface Name>", "<Command Name>", "<Command Parameters>")

Parameter	Description
Interface Name	Name of the interface
Command Name	Name of the command to send
Command Parameters	Any parameters to send with the command
read_write	Whether command gets send to read or write protocols. Must be one of READ, WRITE, or READ_WRITE (Ruby symbols, Python strings). The default is READ_WRITE.
index	Which protocol in the stack the command should apply to. The default is -1 which applies the command to all.

Python Example
Ruby Example

interface_protocol_cmd("INST", "DISABLE_CRC", read_write='READ_WRITE', index=-1)

interface_protocol_cmd("INST", "DISABLE_CRC", read_write: :READ_WRITE, index: -1)

interface_target_enable

Since 6.9.0

Enable commanding and telemetry processing for a given target in an interface.

Python Syntax
Ruby Syntax

interface_target_enable("<Interface Name>", "<Target Name>", cmd_only=False, tlm_only=False)

interface_target_enable("<Interface Name>", "<Target Name>", cmd_only: false, tlm_only: false)

Parameter	Description
Interface Name	Name of the interface
Target Name	Name of the target
cmd_only	Named parameter whether to enable target commands only to the interface (default: false)
tlm_only	Named parameter whether to enable target telemetry only to the interface (default: false)

Python Example
Ruby Example

interface_target_enable("INST_INT", "INST")
interface_target_enable("INST_INT", "INST", cmd_only=True)
interface_target_enable("INST_INT", "INST", tlm_only=True)

interface_target_enable("INST_INT", "INST")
interface_target_enable("INST_INT", "INST", cmd_only: true)
interface_target_enable("INST_INT", "INST", tlm_only: true)

interface_target_disable

Since 6.9.0

Disable commanding and telemetry processing for a given target in an interface.

Python Syntax
Ruby Syntax

interface_target_disable("<Interface Name>", "<Target Name>", cmd_only=False, tlm_only=False)

interface_target_disable("<Interface Name>", "<Target Name>", cmd_only: false, tlm_only: false)

Parameter	Description
Interface Name	Name of the interface
Target Name	Name of the target
cmd_only	Named parameter whether to disable target commands only to the interface (default: false)
tlm_only	Named parameter whether to disable target telemetry only to the interface (default: false)

Python Example
Ruby Example

interface_target_disable("INST_INT", "INST")
interface_target_disable("INST_INT", "INST", cmd_only=True)
interface_target_disable("INST_INT", "INST", tlm_only=True)

interface_target_disable("INST_INT", "INST")
interface_target_disable("INST_INT", "INST", cmd_only: true)
interface_target_disable("INST_INT", "INST", tlm_only: true)

interface_details

Since 6.9.0

Get details on the interface and its protocols.

Python Syntax
Ruby Syntax

interface_details("<Interface Name>")

interface_details("<Interface Name>")

Parameter	Description
Interface Name	Name of the interface

Python Example
Ruby Example

interface_details("INST_INT")

interface_details("INST_INT")

Routers

These methods allow the user to manipulate COSMOS routers.

connect_router

Since 5.0.0

Connects a COSMOS router.

Python Syntax
Ruby Syntax

connect_router("<Router Name>", <Router Parameters (optional)>)

connect_router("<Router Name>", <Router Parameters (optional)>)

Parameter	Description
Router Name	Name of the router.
Router Parameters	Parameters used to initialize the router. If none are given then the router will use the parameters that were given in the server configuration file.

Python Example
Ruby Example

connect_router("INST_ROUTER")
connect_router("INST_ROUTER", 7779, 7779, nil, 10.0, 'PREIDENTIFIED')

connect_router("INST_ROUTER")
connect_router("INST_ROUTER", 7779, 7779, nil, 10.0, 'PREIDENTIFIED')

disconnect_router

Since 5.0.0

Disconnects a COSMOS router.

Python Syntax
Ruby Syntax

disconnect_router("<Router Name>")

disconnect_router("<Router Name>")

Parameter	Description
Router Name	Name of the router.

Python Example
Ruby Example

disconnect_router("INT1_ROUTER")

disconnect_router("INT1_ROUTER")

get_router_names

Since 5.0.0

Returns a list of the routers in the system in an array.

Python Example
Ruby Example

router_names = get_router_names() # => ['ROUTER_INT']

router_names = get_router_names() # => ['ROUTER_INT']

get_router

Since 5.0.0

Returns a router status including the as built router and its current status (cmd/tlm counters, etc).

Python Syntax
Ruby Syntax

get_router("<Router Name>")

get_router("<Router Name>")

Parameter	Description
Router Name	Name of the router.

Python Example
Ruby Example

router = get_router("ROUTER_INT")
print(router)
#{"name"=>"ROUTER_INT",
# "config_params"=>["router.rb"],
# "target_names"=>["INST"],
# "connect_on_startup"=>true,
# "auto_reconnect"=>true,
# "reconnect_delay"=>5.0,
# "disable_disconnect"=>false,
# "options"=>[],
# "protocols"=>[],
# "log"=>true,
# "log_raw"=>false,
# "plugin"=>nil,
# "updated_at"=>1613076213535979900,
# "state"=>"CONNECTED",
# "clients"=>0,
# "txsize"=>0,
# "rxsize"=>0,
# "txbytes"=>0,
# "rxbytes"=>0,
# "txcnt"=>0,
# "rxcnt"=>0}

router = get_router("ROUTER_INT")
puts router
#{"name"=>"ROUTER_INT",
# "config_params"=>["router.rb"],
# "target_names"=>["INST"],
# "connect_on_startup"=>true,
# "auto_reconnect"=>true,
# "reconnect_delay"=>5.0,
# "disable_disconnect"=>false,
# "options"=>[],
# "protocols"=>[],
# "log"=>true,
# "log_raw"=>false,
# "plugin"=>nil,
# "updated_at"=>1613076213535979900,
# "state"=>"CONNECTED",
# "clients"=>0,
# "txsize"=>0,
# "rxsize"=>0,
# "txbytes"=>0,
# "rxbytes"=>0,
# "txcnt"=>0,
# "rxcnt"=>0}

get_all_router_info

Since 5.0.0

Returns information about all routers. The return value is an array of arrays where each subarray contains the router name, connection state, number of connected clients, transmit queue size, receive queue size, bytes transmitted, bytes received, packets received, and packets sent.

Python Example
Ruby Example

router_info = get_all_router_info()
# router_name, connection_state, num_clients, tx_q_size, rx_q_size, tx_bytes, rx_bytes, pkts_rcvd, pkts_sent
for router in router_info:
    print(f"Router: {router[0]}, Connection state: {router[1]}, Num connected clients: {router[2]}")
    print(f"Transmit queue size: {router[3]}, Receive queue size: {router[4]}, Bytes transmitted: {router[5]}, Bytes received: {router[6]}")
    print(f"Packets received: {router[7]}, Packets sent: {router[8]}")

router_info = get_all_router_info()
router_info.each do |router_name, connection_state, num_clients, tx_q_size, rx_q_size, tx_bytes, rx_bytes, pkts_rcvd, pkts_sent|
  puts "Router: #{router_name}, Connection state: #{connection_state}, Num connected clients: #{num_clients}"
  puts "Transmit queue size: #{tx_q_size}, Receive queue size: #{rx_q_size}, Bytes transmitted: #{tx_bytes}, Bytes received: #{rx_bytes}"
  puts "Packets received: #{pkts_rcvd}, Packets sent: #{pkts_sent}"
end

map_target_to_router

Since 6.9.0

Map a target to an router allowing target commands and telemetry to be processed by that router. Note: this will cause the router to respawn.

Python Syntax
Ruby Syntax

map_target_to_router("<Target Name>", "<Router Name>", cmd_only=False, tlm_only=False, unmap_old=True)

map_target_to_router("<Target Name>", "<Router Name>", cmd_only: false, tlm_only: false, unmap_old: true)

Parameter	Description
Target Name	Name of the target
Router Name	Name of the router
cmd_only	Named parameter whether to map target commands only to the router (default: false)
tlm_only	Named parameter whether to map target telemetry only to the router (default: false)
unmap_old	Named parameter whether remove the target from all existing routers (default: true)

Python Example
Ruby Example

map_target_to_router("INST", "INST_ROUTER", unmap_old=False)
map_target_to_router("INST", "INST_ROUTER", cmd_only=True)
map_target_to_router("INST", "INST_ROUTER", tlm_only=True)

map_target_to_router("INST", "INST_ROUTER", unmap_old: false)
map_target_to_router("INST", "INST_ROUTER", cmd_only: true)
map_target_to_router("INST", "INST_ROUTER", tlm_only: true)

unmap_target_from_router

Since 6.9.0

Unmap a target from an router. This removes all knowledge of the target and will cause the router to respawn.

Python Syntax
Ruby Syntax

unmap_target_from_router("<Target Name>", "<Router Name>", cmd_only=False, tlm_only=False)

unmap_target_from_router("<Target Name>", "<Router Name>", cmd_only: false, tlm_only: false)

Parameter	Description
Target Name	Name of the target
Router Name	Name of the router
cmd_only	Named parameter whether to unmap target commands only to the router (default: false)
tlm_only	Named parameter whether to unmap target telemetry only to the router (default: false)

Python Example
Ruby Example

unmap_target_from_router("INST", "INST_ROUTER")
unmap_target_from_router("INST", "INST_ROUTER", cmd_only=True)
unmap_target_from_router("INST", "INST_ROUTER", tlm_only=True)

unmap_target_from_router("INST", "INST_ROUTER")
unmap_target_from_router("INST", "INST_ROUTER", cmd_only: true)
unmap_target_from_router("INST", "INST_ROUTER", tlm_only: true)

start_raw_logging_router

Since 5.0.0

Starts logging of raw data on one or all routers. This is for debugging purposes only.

Python Syntax
Ruby Syntax

start_raw_logging_router("<Router Name (optional)>")

start_raw_logging_router("<Router Name (optional)>")

Parameter	Description
Router Name	Name of the Router to command to start raw data logging. Defaults to 'ALL' which causes all routers that support raw data logging to start logging raw data.

Python Example
Ruby Example

start_raw_logging_router("router1")

start_raw_logging_router("router1")

stop_raw_logging_router

Since 5.0.0

Stops logging of raw data on one or all routers. This is for debugging purposes only.

Python Syntax
Ruby Syntax

stop_raw_logging_router("<Router Name (optional)>")

stop_raw_logging_router("<Router Name (optional)>")

Parameter	Description
Router Name	Name of the Router to command to stop raw data logging. Defaults to 'ALL' which causes all routers that support raw data logging to stop logging raw data.

Python Example
Ruby Example

stop_raw_logging_router("router1")

stop_raw_logging_router("router1")

router_cmd

Since 5.3.0

Send a command directly to a router. This has no effect in the standard COSMOS routers but can be implemented by a custom router to change behavior.

Python Syntax
Ruby Syntax

router_cmd("<Router Name>", "<Command Name>", "<Command Parameters>")

router_cmd("<Router Name>", "<Command Name>", "<Command Parameters>")

Parameter	Description
Router Name	Name of the router
Command Name	Name of the command to send
Command Parameters	Any parameters to send with the command

Python Example
Ruby Example

router_cmd("INST", "DISABLE_CRC")

router_cmd("INST", "DISABLE_CRC")

router_protocol_cmd

Since 5.3.0

Send a command directly to an router protocol. This has no effect in the standard COSMOS protocols but can be implemented by a custom protocol to change behavior.

Python Syntax
Ruby Syntax

router_protocol_cmd("<Router Name>", "<Command Name>", "<Command Parameters>", read_write, index)

router_protocol_cmd("<Router Name>", "<Command Name>", "<Command Parameters>", read_write, index)

Parameter	Description
Router Name	Name of the router
Command Name	Name of the command to send
Command Parameters	Any parameters to send with the command
read_write	Whether command gets send to read or write protocols. Must be one of READ, WRITE, or READ_WRITE (Ruby symbols, Python strings). The default is READ_WRITE.
index	Which protocol in the stack the command should apply to. The default is -1 which applies the command to all.

Python Example
Ruby Example

router_protocol_cmd("INST", "DISABLE_CRC", read_write='READ_WRITE', index=-1)

router_protocol_cmd("INST", "DISABLE_CRC", read_write: :READ_WRITE, index: -1)

router_target_enable

Since 6.9.0

Enable commanding and telemetry processing for a given target in a router.

Python Syntax
Ruby Syntax

router_target_enable("<Router Name>", "<Target Name>", cmd_only=False, tlm_only=False)

router_target_enable("<Router Name>", "<Target Name>", cmd_only: false, tlm_only: false)

Parameter	Description
Router Name	Name of the router
Target Name	Name of the target
cmd_only	Named parameter whether to enable target commands only to the router (default: false)
tlm_only	Named parameter whether to enable target telemetry only to the router (default: false)

Python Example
Ruby Example

router_target_enable("INST_ROUTER", "INST")
router_target_enable("INST_ROUTER", "INST", cmd_only=True)
router_target_enable("INST_ROUTER", "INST", tlm_only=True)

router_target_enable("INST_ROUTER", "INST")
router_target_enable("INST_ROUTER", "INST", cmd_only: true)
router_target_enable("INST_ROUTER", "INST", tlm_only: true)

router_target_disable

Since 6.9.0

Disable commanding and telemetry processing for a given target in a router.

Python Syntax
Ruby Syntax

router_target_disable("<Router Name>", "<Target Name>", cmd_only=False, tlm_only=False)

router_target_disable("<Router Name>", "<Target Name>", cmd_only: false, tlm_only: false)

Parameter	Description
Router Name	Name of the router
Target Name	Name of the target
cmd_only	Named parameter whether to disable target commands only to the router (default: false)
tlm_only	Named parameter whether to disable target telemetry only to the router (default: false)

Python Example
Ruby Example

router_target_disable("INST_ROUTER", "INST")
router_target_disable("INST_ROUTER", "INST", cmd_only=True)
router_target_disable("INST_ROUTER", "INST", tlm_only=True)

router_target_disable("INST_ROUTER", "INST")
router_target_disable("INST_ROUTER", "INST", cmd_only: true)
router_target_disable("INST_ROUTER", "INST", tlm_only: true)

router_details

Since 6.9.0

Get details on the router and its protocols.

Python Syntax
Ruby Syntax

router_details("<Router Name>")

router_details("<Router Name>")

Parameter	Description
Router Name	Name of the router

Python Example
Ruby Example

router_details("INST_ROUTER")

router_details("INST_ROUTER")

Tables

These methods allow the user to script Table Manager.

table_create_binary

Since 6.1.0

Creates a table binary based on a table definition file. You can achieve the same result in the Table Manager GUI with File->New File. Returns the path to the binary file created.

Python Syntax
Ruby Syntax

table_create_binary(<Table Definition File>)

table_create_binary(<Table Definition File>)

Parameter	Description
Table Definition File	Path to the table definition file, e.g. INST/tables/config/ConfigTables_def.txt

Python Example
Ruby Example

# Full example of using table_create_binary and then editing the binary
from openc3.tools.table_manager.table_config import TableConfig
# Returns a dict: {'filename': 'INST/tables/bin/ConfigTables.bin'}
table = table_create_binary("INST2/tables/config/ConfigTables_def.txt")
file = get_target_file(table['filename'])
table_binary = file.read()

# Get the definition file so we can process the binary
def_file = get_target_file("INST2/tables/config/MCConfigurationTable_def.txt")
# Access the internal TableConfig to process the definition
config = TableConfig.process_file(def_file.name)
# Grab the table by the definition name, e.g. TABLE "MC_Configuration"
table = config.table('MC_CONFIGURATION')
# Now you can read or write individual items in the table
table.write("MEMORY_SCRUBBING", "DISABLE")
# Finally write the table.buffer (the binary) back to storage
put_target_file("INST2/tables/bin/MCConfigurationTable_NoScrub.bin", table.buffer)

# Full example of using table_create_binary and then editing the binary
require 'openc3/tools/table_manager/table_config'
# This returns a hash: {"filename"=>"INST/tables/bin/MCConfigurationTable.bin"}
table = table_create_binary("INST/tables/config/MCConfigurationTable_def.txt")
file = get_target_file(table['filename'])
table_binary = file.read()

# Get the definition file so we can process the binary
def_file = get_target_file("INST/tables/config/MCConfigurationTable_def.txt")
# Access the internal TableConfig to process the definition
config = OpenC3::TableConfig.process_file(def_file.path())
# Grab the table by the definition name, e.g. TABLE "MC_Configuration"
table = config.table('MC_CONFIGURATION')
# Now you can read or write individual items in the table
table.write("MEMORY_SCRUBBING", "DISABLE")
# Finally write the table.buffer (the binary) back to storage
put_target_file("INST/tables/bin/MCConfigurationTable_NoScrub.bin", table.buffer)

table_create_report

Since 6.1.0

Creates a table binary based on a table definition file. You can achieve the same result in the Table Manager GUI with File->New File. Returns the path to the binary file created.

Python Syntax
Ruby Syntax

table_create_report(<Table Binary Filename>, <Table Definition File>, <Table Name (optional)>)

table_create_report(<Table Binary Filename>, <Table Definition File>, <Table Name (optional)>)

filename, definition, table_name

Parameter	Description
Table Binary File	Path to the table binary file, e.g. INST/tables/bin/ConfigTables.bin
Table Definition File	Path to the table definition file, e.g. INST/tables/config/ConfigTables_def.txt
Table Name	Name of the table to create the report. This only applies if the Table Binary and Table Definition consist of multiple tables. By default the report consists of all tables and is named after the binary file. If the table name is given, the report is just the specified table and is named after the table.

Python Example
Ruby Example

table = table_create_report("INST/tables/bin/ConfigTables.bin", "INST/tables/config/ConfigTables_def.txt") # =>
# {'filename': 'INST/tables/bin/ConfigTables.csv', 'contents': 'MC_CONFIGURATION\nLabel, ...
table = table_create_report("INST/tables/bin/ConfigTables.bin", "INST/tables/config/ConfigTables_def.txt", table_name="MC_CONFIGURATION") # =>
# {'filename': 'INST/tables/bin/ConfigTables.csv', 'contents': 'MC_CONFIGURATION\nLabel, ...

table = table_create_report("INST/tables/bin/ConfigTables.bin", "INST/tables/config/ConfigTables_def.txt") # =>
# {"filename"=>"INST/tables/bin/ConfigTables.csv", "contents"=>"MC_CONFIGURATION\nLabel, ...
table = table_create_report("INST/tables/bin/ConfigTables.bin", "INST/tables/config/ConfigTables_def.txt", table_name: "MC_CONFIGURATION") # =>
# {"filename"=>"INST/tables/bin/McConfiguration.csv", "contents"=>"MC_CONFIGURATION\nLabel, ...

Stashing Data

These methods allow the user to store data into COSMOS and retrieve it. The storage is implemented as a key / value storage (Ruby hash or Python dict). This can be used in scripts to store information that applies across multiple scripts or multiple runs of a single script. As a best practice, use stashes to store transient data, since duplicate keys will be overwritten by the most recent write.

stash_set

Since 5.2.0

Sets a stash item.

Python Syntax
Ruby Syntax

stash_set("<Stash Key>", <Stash Value>)

stash_set("<Stash Key>", <Stash Value>)

Parameter	Description
Stash Key	Name of the stash key to set
Stash Value	Value to set

Python Example
Ruby Example

stash_set('run_count', 5)
stash_set('setpoint', 23.4)

stash_set('run_count', 5)
stash_set('setpoint', 23.4)

stash_get

Since 5.2.0

Returns the specified stash item.

Python Syntax
Ruby Syntax

stash_get("<Stash Key>")

stash_get("<Stash Key>")

Parameter	Description
Stash Key	Name of the stash key to return

Python Example
Ruby Example

stash_get('run_count')  # => 5

stash_get('run_count')  # => 5

stash_all

Since 5.2.0

Returns all the stash items as a Ruby hash or Python dict.

Python Example
Ruby Example

stash_all()  # => ['run_count': 5, 'setpoint': 23.4]

stash_all()  # => ['run_count' => 5, 'setpoint' => 23.4]

stash_keys

Since 5.2.0

Returns all the stash keys.

Python Example
Ruby Example

stash_keys()  # => ['run_count', 'setpoint']

stash_keys()  # => ['run_count', 'setpoint']

stash_delete

Since 5.2.0

Deletes a stash item. Note this actions is permanent!

Python Syntax
Ruby Syntax

stash_delete("<Stash Key>")

stash_delete("<Stash Key>")

Parameter	Description
Stash Key	Name of the stash key to delete

Python Example
Ruby Example

stash_delete("run_count")

stash_delete("run_count")

Telemetry Screens

These methods allow the user to open, close or create unique telemetry screens from within a test procedure.

display_screen

Since 5.6.0

Opens a telemetry screen at the specified position.

Python Syntax
Ruby Syntax

display_screen("<Target Name>", "<Screen Name>", <X Position (optional)>, <Y Position (optional)>)

display_screen("<Target Name>", "<Screen Name>", <X Position (optional)>, <Y Position (optional)>)

Parameter	Description
Target Name	Telemetry screen target name
Screen Name	Screen name within the specified target
X Position	X coordinate for the upper left hand corner of the screen
Y Position	Y coordinate for the upper left hand corner of the screen

Python Example
Ruby Example

display_screen("INST", "ADCS", 100, 200)

display_screen("INST", "ADCS", 100, 200)

clear_screen

Since 5.6.0

Closes an open telemetry screen.

Python Syntax
Ruby Syntax

clear_screen("<Target Name>", "<Screen Name>")

clear_screen("<Target Name>", "<Screen Name>")

Parameter	Description
Target Name	Telemetry screen target name. Note for local screens the target is 'LOCAL'.
Screen Name	Screen name within the specified target

Python Example
Ruby Example

clear_screen("INST", "ADCS")

clear_screen("INST", "ADCS")

clear_all_screens

Since 5.6.0

Closes all open screens.

Python Example
Ruby Example

clear_all_screens()

clear_all_screens()

delete_screen

Since 5.6.0

Deletes an existing Telemetry Viewer screen.

Python Syntax
Ruby Syntax

delete_screen("<Target Name>", "<Screen Name>")

delete_screen("<Target Name>", "<Screen Name>")

Parameter	Description
Target Name	Telemetry screen target name
Screen Name	Screen name within the specified target

Python Example
Ruby Example

delete_screen("INST", "ADCS")

delete_screen("INST", "ADCS")

get_screen_list

Since 5.6.0

Returns a list of available telemetry screens.

Python Example
Ruby Example

get_screen_list() # => ['INST ADCS', 'INST COMMANDING', ...]

get_screen_list() # => ['INST ADCS', 'INST COMMANDING', ...]

get_screen_definition

Since 5.6.0

Returns the text file contents of a telemetry screen definition.

Python Syntax
Ruby Syntax

get_screen_definition("<Target Name>", "<Screen Name>")

get_screen_definition("<Target Name>", "<Screen Name>")

Parameter	Description
Target Name	Telemetry screen target name
Screen Name	Screen name within the specified target

Python Example
Ruby Example

screen_definition = get_screen_definition("INST", "HS")

screen_definition = get_screen_definition("INST", "HS")

create_screen

Since 5.6.0

Allows you to create a screen directly from a script. This screen is saved to Telemetry Viewer for future use in that application.

Python Syntax
Ruby Syntax

create_screen("<Target Name>", "<Screen Name>" "<Definition>")

create_screen("<Target Name>", "<Screen Name>" "<Definition>")

Parameter	Description
Target Name	Telemetry screen target name
Screen Name	Screen name within the specified target
Definition	The entire screen definition as a String

Python Example
Ruby Example

screen_def = """
  SCREEN AUTO AUTO 0.1
  VERTICAL
    TITLE "New Screen"
    VERTICALBOX
      LABELVALUE INST HEALTH_STATUS TEMP1
    END
  END
"""
# Here we pass in the screen definition as a string
create_screen("INST", "LOCAL", screen_def)

screen_def = '
  SCREEN AUTO AUTO 0.1
  VERTICAL
    TITLE "New Screen"
    VERTICALBOX
      LABELVALUE INST HEALTH_STATUS TEMP1
    END
  END
'
# Here we pass in the screen definition as a string
create_screen("INST", "LOCAL", screen_def)

local_screen

Since 5.6.0

Allows you to create a local screen directly from a script which is not permanently saved to the Telemetry Viewer screen list. This is useful for one off screens that help users interact with scripts.

Python Syntax
Ruby Syntax

local_screen("<Screen Name>", "<Definition>", <X Position (optional)>, <Y Position (optional)>)

local_screen("<Screen Name>", "<Definition>", <X Position (optional)>, <Y Position (optional)>)

Parameter	Description
Screen Name	Screen name within the specified target
Definition	The entire screen definition as a String
X Position	X coordinate for the upper left hand corner of the screen
Y Position	Y coordinate for the upper left hand corner of the screen

NOTE: It is possible to specify a X, Y location off the visible display. If you do so and try to re-create the screen it will not display (because it is already displayed). Try issuing a clear_all_screens() first to clear any screens off the visible display space.

Python Example
Ruby Example

screen_def = """
  SCREEN AUTO AUTO 0.1
  VERTICAL
    TITLE "Local Screen"
    VERTICALBOX
      LABELVALUE INST HEALTH_STATUS TEMP1
    END
  END
"""
# Here we pass in the screen definition as a string
local_screen("TESTING", screen_def, 600, 75)
wait(5)
# The local screen 'target' is 'LOCAL'
clear_screen("LOCAL", "TESTING")

screen_def = '
  SCREEN AUTO AUTO 0.1
  VERTICAL
    TITLE "Local Screen"
    VERTICALBOX
      LABELVALUE INST HEALTH_STATUS TEMP1
    END
  END
'
# Here we pass in the screen definition as a string
local_screen("TESTING", screen_def, 600, 75)
wait 5
# The local screen 'target' is 'LOCAL'
clear_screen("LOCAL", "TESTING")

Script Runner Scripts

These methods allow the user to control Script Runner scripts.

start

Since 5.0.0

Starts execution of another high level test procedure. Script Runner will load the file and immediately start executing it before jumping back to the calling procedure. Parameters are not directly given to high level test procedures, though they can use environment variables. If parameters are necessary, consider using a subroutine.

Python Syntax
Ruby Syntax

start("<Procedure Filename>")

start("<Procedure Filename>")

Parameter	Description
Procedure Filename	Name of the test procedure file. These files are normally in the procedures folder but may be anywhere in the Ruby search path. Additionally, absolute paths are supported.

Python Example
Ruby Example

start("test1.rb")

start("test1.rb")

goto

Since 6.4.0

Jumps to a specific line in either the current file or another file. Script context and local variables are retained if jumping in the same file. This method should not be used to create loops or in any other case where normal Python/Ruby functionality could perform the same function. Use of goto increases stack depth and excess use can lead to stack level too deep errors.

Python Syntax
Ruby Syntax

goto(line_number)
goto(filename, line_number)

goto(line_number)
goto(filename, line_number)

Parameter	Description
Line Number or Procedure Filename	If this is the only argument given then it is the line number to goto in the same script. If two arguments are given, then it is the filename to goto
Line Number	If the second argument, it is the line number in the filename given by the first argument to goto

Python Example
Ruby Example

goto(23)
goto("TARGET/procedures/other_script.rb", 5)
goto("TARGET/procedures/other_script.py", 12)

goto(23)
goto("TARGET/procedures/other_script.rb", 5)
goto("TARGET/procedures/other_script.py", 12)

load_utility

Since 5.0.0

Reads in a script file that contains useful subroutines for use in your test procedure. When these subroutines run in ScriptRunner or TestRunner, their lines will be highlighted. If you want to import subroutines but do not want their lines to be highlighted in ScriptRunner or TestRunner, use the standard Ruby 'load' or 'require' statement or Python 'import' statement.

Python Syntax
Ruby Syntax

load_utility("TARGET/lib/<Utility Filename>")

load_utility("TARGET/lib/<Utility Filename>")

Parameter	Description
Utility Filename	Name of the script file containing subroutines including the .rb or .py extension. You need to include the full target name and path such as TARGET/lib/utility.rb

Python Example
Ruby Example

load_utility("TARGET/lib/mode_changes.rb") # Ruby
load_utility("TARGET/lib/mode_changes.py") # Python

load_utility("TARGET/lib/mode_changes.rb") # Ruby
load_utility("TARGET/lib/mode_changes.py") # Python

script_list

Since 5.0.0

Returns all the available files in COSMOS as an array / list. This includes configuration files at every directory level to ensure the user has access to every file. You can filter the list client side to just the 'lib' and or 'procedures' directories if you wish. Note: script names do NOT include '*' to indicate modified.

Python Example
Ruby Example

scripts = script_list()
print(len(scripts))
print(list(script for script in scripts if '/lib/' in script or '/procedures/' in script)) # =>
# [EXAMPLE/lib/example_interface.rb, INST/lib/example_limits_response.rb, ...]

scripts = script_list()
puts scripts.length # => 139
puts scripts.select {|script| script.include?('/lib/') || script.include?('/procedures/')} # =>
# [EXAMPLE/lib/example_interface.rb, INST/lib/example_limits_response.rb, ...]

script_create

Since 5.0.0

Creates a new script with the given contents.

Python Syntax
Ruby Syntax

script_create("<Script Name>", "<Script Contents>")

script_create("<Script Name>", "<Script Contents>")

Parameter	Description
Script Name	Full path name of the script starting with the target
Script Contents	Script contents as text

Python Example
Ruby Example

contents = 'print("Hello from Python")'
script_create("INST2/procedures/new_script.py", contents)

contents = 'puts "Hello from Ruby"'
script_create("INST/procedures/new_script.rb", contents)

script_body

Since 5.0.0

Returns the script contents.

Python Syntax
Ruby Syntax

script_body("<Script Name>")

script_body("<Script Name>")

Parameter	Description
Script Name	Full path name of the script starting with the target

Python Example
Ruby Example

script = script_body("INST2/procedures/checks.py")
print(script) # => # import os\n\n# Display the environment variables ...

script = script_body("INST/procedures/checks.rb")
puts script # => # Display all environment variables\nputs ENV.inspect ...

script_delete

Since 5.0.0

Deletes a script from COSMOS. Note, you can only really delete TEMP scripts and modified scripts. Scripts that are part of an installed COSMOS plugin remain as they were installed.

Python Syntax
Ruby Syntax

script_delete("<Script Name>")

script_delete("<Script Name>")

Parameter	Description
Script Name	Full path name of the script starting with the target

Python Example
Ruby Example

script_delete("INST/procedures/checks.rb")

script_delete("INST/procedures/checks.rb")

script_run

Since 5.0.0

Runs a script in Script Runner. The script will run in the background and can be opened in Script Runner by selecting Script->Execution Status and then connecting to it.

Note: In Enterprise, initialize_offline_access must have been called at least once for the user who calls this method.

Python Syntax
Ruby Syntax

script_run("<Script Name>", disconnect=False, environment=None, suite_runner=None)

script_run("<Script Name>", disconnect: false, environment: nil, suite_runner: nil)

Parameter	Description
Script Name	Full path name of the script starting with the target
disconnect	Whether to run the script in Disconnect mode
environment	Hash / dict of key / value items to set as script environment variables. Note: Do not use `PATH` as it is reserved.
suite_runner	Hash / dict of suite runner options

Python Example
Ruby Example

id = script_run("INST2/procedures/checks.py", environment={ 'USER': 'JASON'})
print(id)
id = script_run("INST2/procedures/my_script_suite.py", suite_runner={ 'suite': 'MySuite', 'group': 'ExampleGroup', 'script': 'script_2' })
print(id)

id = script_run("INST/procedures/checks.rb", environment: { USER: 'JASON'})
puts id
id = script_run("INST/procedures/my_script_suite.rb", suite_runner: { suite: 'MySuite', group: 'ExampleGroup', script: 'script_2' })
puts id

script_lock

Since 5.0.0

Locks a script for editing. Subsequent users that open this script will get a warning that the script is currently locked.

Python Syntax
Ruby Syntax

script_lock("<Script Name>")

script_lock("<Script Name>")

Parameter	Description
Script Name	Full path name of the script starting with the target

Python Example
Ruby Example

script_lock("INST/procedures/checks.rb")

script_lock("INST/procedures/checks.rb")

script_unlock

Since 5.0.0

Unlocks a script for editing. If the script was not previously locked this does nothing.

Python Syntax
Ruby Syntax

script_unlock("<Script Name>")

script_unlock("<Script Name>")

Parameter	Description
Script Name	Full path name of the script starting with the target

Python Example
Ruby Example

script_unlock("INST/procedures/checks.rb")

script_unlock("INST/procedures/checks.rb")

script_syntax_check

Since 5.0.0

Performs a Ruby or Python syntax check on the given script.

Python Syntax
Ruby Syntax

script_syntax_check("<Script Name>")

script_syntax_check("<Script Name>")

Parameter	Description
Script Name	Full path name of the script starting with the target

Python Example
Ruby Example

result = script_syntax_check("INST2/procedures/checks.py")
print(result) # => {'title': 'Syntax Check Successful', 'description': '["Syntax OK"]', 'success': True}

result = script_syntax_check("INST/procedures/checks.rb")
puts result # => {"title"=>"Syntax Check Successful", "description"=>"[\"Syntax OK\\n\"]", "success"=>true}

script_instrumented

Since 5.0.0

Returns the instrumented script which allows COSMOS Script Runner to monitor the execution and provide line by line visualization. This is primarily a low level debugging method used by COSMOS developers.

Python Syntax
Ruby Syntax

script_instrumented("<Script Name>")

script_instrumented("<Script Name>")

Parameter	Description
Script Name	Full path name of the script starting with the target

Python Example
Ruby Example

script = script_instrumented("INST2/procedures/checks.py")
print(script) # => while True:\ntry:\nRunningScript.instance.pre_line_instrumentation ...

script = script_instrumented("INST/procedures/checks.rb")
puts script # => private; __return_val = nil; begin; RunningScript.instance.script_binding = binding(); ...

script_delete_all_breakpoints

Since 5.0.0

Delete all breakpoints associated with all scripts.

Python Example
Ruby Example

script_delete_all_breakpoints()

script_delete_all_breakpoints()

step_mode

Since 5.0.0

Places ScriptRunner into step mode where Go must be hit to proceed to the next line.

Python Example
Ruby Example

step_mode()

step_mode()

run_mode

Since 5.0.0

Places ScriptRunner into run mode where the next line is run automatically.

Python Example
Ruby Example

run_mode()

run_mode()

disconnect_script

Since 5.0.0

Puts scripting into disconnect mode. In disconnect mode, commands are not sent to targets, checks are all successful, and waits expire instantly. Requests for telemetry (tlm()) typically return 0. Disconnect mode is useful for dry-running scripts without having connected targets.

Python Example
Ruby Example

disconnect_script()

disconnect_script()

running_script_list

Since 5.0.0

List the currently running scripts. Note, this will also include the script which is calling this method. Thus the list will never be empty but will always contain at least 1 item. Returns an array of hashes / list of dicts (see script_get for hash / dict contents).

Python Syntax
Ruby Syntax

running_script_list(limit = <limit>, offset = <offset>)

running_script_list(limit: <limit>, offset: <offset>)

Parameter	Description
limit	Max number to return (default 10)
offset	Offset into list to return (default 0)

Python Example
Ruby Example

running_script_list(limit = 20, offset = 10) # =>  [{'name': '372', 'state': 'spawning', 'shard': 0, 'filename': '__TEMP__/2025_05_02_22_38_53_386_temp.py', 'current_filename': '__TEMP__/2025_05_02_22_38_53_386_temp.py', 'line_no': 0, 'start_line_no': 1, 'end_line_no': None, 'username': 'anonymous', 'user_full_name': 'Anonymous', 'start_time': '2025-05-03T14:34:11Z', 'end_time': None, 'disconnect': False, 'environment': '{}', 'suite_runner': None, 'errors': None, 'pid': None, 'log': None, 'report': None, 'updated_at': 1746282851410918174, 'scope': 'DEFAULT'}]

running_script_list(limit: 20, offset: 10) # => [{"name"=>"293", "state"=>"waiting", "shard"=>0, "filename"=>"INST/procedures/collect.rb", "current_filename"=>"INST/procedures/collect.rb", "line_no"=>4, "start_line_no"=>1, "end_line_no"=>nil, "username"=>"anonymous", "user_full_name"=>"Anonymous", "start_time"=>"2025-05-03T04:26:50Z", "end_time"=>nil, "disconnect"=>false, "environment"=>"{}", "suite_runner"=>nil, "errors"=>nil, "pid"=>414, "log"=>nil, "report"=>nil, "updated_at"=>1746246411160414638, "scope"=>"DEFAULT"}]

script_get

Since 5.0.0

Get information on the script with the specified ID. The information returned is the script name (id), state (spawning, init, running, paused, waiting, error, breakpoint, crashed, stopped, completed, completed_errors, killed), shard, filename, current_filename, line_no, start_line_no, end_line_no, username, user_full_name, start_time, end_time, disconnect state, environment variables, suite_runner configuration, errors, pid, log file, report file, update time, and scope.

Possible script states:

spawning - Not running yet
init - Initializing
running - Running
paused - Paused
waiting - Waiting (either for a wait or a prompt)
error - Paused with an error
breakpoint - Paused with a breakpoing
crashed - Complete after crashing with an exception
stopped - Prematurely stopped
completed - Completed successfully
completed_errors - Completed but errors occurred while running
killed - Forcefully killed

Python Syntax
Ruby Syntax

script_get("<Script Id>")

script_get("<Script Id>")

Parameter	Description
Script Id	Script ID returned by script_run

Python Example
Ruby Example

script_get(15) # => {'name': '372', 'state': 'spawning', 'shard': 0, 'filename': '__TEMP__/2025_05_02_22_38_53_386_temp.py', 'current_filename': '__TEMP__/2025_05_02_22_38_53_386_temp.py', 'line_no': 0, 'start_line_no': 1, 'end_line_no': None, 'username': 'anonymous', 'user_full_name': 'Anonymous', 'start_time': '2025-05-03T14:34:11Z', 'end_time': None, 'disconnect': False, 'environment': '{}', 'suite_runner': None, 'errors': None, 'pid': None, 'log': None, 'report': None, 'updated_at': 1746282851410918174, 'scope': 'DEFAULT'}

script_get(15) # => {"name"=>"293", "state"=>"waiting", "shard"=>0, "filename"=>"INST/procedures/collect.rb", "current_filename"=>"INST/procedures/collect.rb", "line_no"=>4, "start_line_no"=>1, "end_line_no"=>nil, "username"=>"anonymous", "user_full_name"=>"Anonymous", "start_time"=>"2025-05-03T04:26:50Z", "end_time"=>nil, "disconnect"=>false, "environment"=>"{}", "suite_runner"=>nil, "errors"=>nil, "pid"=>414, "log"=>nil, "report"=>nil, "updated_at"=>1746246411160414638, "scope"=>"DEFAULT"}

running_script_stop

Since 5.0.0

Stop the running script with the specified ID. This is equivalent to clicking the Stop button in the Script Runner GUI.

Python Syntax
Ruby Syntax

running_script_stop("<Script Id>")

running_script_stop("<Script Id>")

Parameter	Description
Script Id	Script ID returned by script_run

Python Example
Ruby Example

running_script_stop(15)

running_script_stop(15)

running_script_pause

Since 5.0.0

Pause the running script with the specified ID. This is equivalent to clicking the Pause button in the Script Runner GUI.

Python Syntax
Ruby Syntax

running_script_pause("<Script Id>")

running_script_pause("<Script Id>")

Parameter	Description
Script Id	Script ID returned by script_run

Python Example
Ruby Example

running_script_pause(15)

running_script_pause(15)

running_script_retry

Since 5.0.0

Retry the current line of the running script with the specified ID. This is equivalent to clicking the Retry button in the Script Runner GUI.

Python Syntax
Ruby Syntax

running_script_retry("<Script Id>")

running_script_retry("<Script Id>")

Parameter	Description
Script Id	Script ID returned by script_run

Python Example
Ruby Example

running_script_retry(15)

running_script_retry(15)

running_script_go

Since 5.0.0

Unpause the running script with the specified ID. This is equivalent to clicking the Go button in the Script Runner GUI.

Python Syntax
Ruby Syntax

running_script_go("<Script Id>")

running_script_go("<Script Id>")

Parameter	Description
Script Id	Script ID returned by script_run

Python Example
Ruby Example

running_script_go(15)

running_script_go(15)

running_script_execute_while_paused

Since 6.4.0

Perform a goto or execute selection on a running script.

Python Syntax
Ruby Syntax

running_script_execute_while_paused("<Script Id>", "<Script File Path>", <Start Line Number>, <End Line Number>)

running_script_execute_while_paused("<Script Id>", "<Script File Path>", <Start Line Number>, <End Line Number>)

Parameter	Description
Script Id	Script ID returned by script_run
Script File Path	Path to to the script to run ie. "INST/procedures/collect.rb"
Start Line Number	Line Number to Start At
End Line Number	Optional - Line Number to End At. If given then execute selection, else goto.

Python Example
Ruby Example

# Execute Selection
running_script_execute_while_paused("23", "INST/procedures/myprocedure.rb", 2, 4)
# Goto
running_script_execute_while_paused("33", "INST2/procedures/collect.py", 7)

# Execute Selection
running_script_execute_while_paused("23", "INST/procedures/myprocedure.rb", 2, 4)
# Goto
running_script_execute_while_paused("33", "INST2/procedures/collect.py", 7)

running_script_step

Since 5.0.0

Step the running script with the specified ID. This is equivalent to clicking the Step button in the Script Runner GUI's Debug window.

Python Syntax
Ruby Syntax

running_script_step("<Script Id>")

running_script_step("<Script Id>")

Parameter	Description
Script Id	Script ID returned by script_run

Python Example
Ruby Example

running_script_step(15)

running_script_step(15)

running_script_delete

Since 5.0.0

Force quit the running script with the specified ID. This is equivalent to clicking the Delete button under the Running Scripts in the Script Runner GUI's Script -> Execution Status pane. Note, the 'stop' signal is first sent to the specified script and then the script is forcibly removed. Normally you should use the running_script_stop method.

Python Syntax
Ruby Syntax

running_script_delete("<Script Id>")

running_script_delete("<Script Id>")

Parameter	Description
Script Id	Script ID returned by script_run

Python Example
Ruby Example

running_script_delete(15)

running_script_delete(15)

completed_script_list

Since 5.0.0

List the completed scripts. Returns an array of hashes / list of dicts containing the id, username, script name, script log, and start time.

Python Syntax
Ruby Syntax

completed_script_list(limit = <limit>, offset = <offset>)

completed_script_list(limit: <limit>, offset: <offset>)

Parameter	Description
limit	Max number to return (default 10)
offset	Offset into list to return (default 0)

Python Example
Ruby Example

completed_script_list(limit = 10, offset = 0) # => [{'id': 16, 'user': 'Anonymous', 'name': 'INST2/procedures/new_script.py', 'log': 'DEFAULT/tool_logs/sr/20250116/2025_01_16_17_46_22_sr_new_script.txt', 'start': '2025-01-16 17:46:22 +0000'}, ...]

completed_script_list(limit: 10, offset: 0) # => [{"id"=>"15", "user"=>"Anonymous", "name"=>"__TEMP__/2025_01_15_17_07_51_568_temp.rb", "log"=>"DEFAULT/tool_logs/sr/20250116/2025_01_16_00_28_43_sr_2025_01_15_17_07_51_568_temp.txt", "start"=>"2025-01-16 00:28:43 +0000"}, ...]

Script Runner Settings

These methods allow the user to control various Script Runner settings.

set_line_delay

Since 5.0.0

This method sets the line delay in script runner.

Python Syntax
Ruby Syntax

set_line_delay(<Delay>)

set_line_delay(<Delay>)

Parameter	Description
Delay	The amount of time script runner will wait between lines when executing a script, in seconds. Should be ≥ 0.0

Python Example
Ruby Example

set_line_delay(0.0)

set_line_delay(0.0)

get_line_delay

Since 5.0.0

The method gets the line delay that script runner is currently using.

Python Example
Ruby Example

curr_line_delay = get_line_delay()

curr_line_delay = get_line_delay()

set_max_output

Since 5.1.0

This method sets the maximum number of characters to display in Script Runner output before truncating. Default is 50,000 characters.

Python Syntax
Ruby Syntax

set_max_output(<Characters>)

set_max_output(<Characters>)

Parameter	Description
Characters	Number of characters to output before truncating

Python Example
Ruby Example

set_max_output(100)

set_max_output(100)

get_max_output

Since 5.1.0

The method gets the maximum number of characters to display in Script Runner output before truncating. Default is 50,000 characters.

Python Example
Ruby Example

print(get_max_output()) # => 50000

puts get_max_output() # => 50000

disable_instrumentation

Since 5.0.0

Disables instrumentation for a block of code (line highlighting and exception catching). This is especially useful for speeding up loops that are very slow if lines are instrumented. Consider breaking code like this into a separate file and using either require/load to read the file for the same effect while still allowing errors to be caught by your script.

Use with Caution

Disabling instrumentation will cause any error that occurs while disabled to cause your script to completely stop.

Python Example
Ruby Example

with disable_instrumentation():
    for x in range(1000):
        # Don't want this to have to highlight 1000 times
        pass

disable_instrumentation do
  1000.times do
    # Don't want this to have to highlight 1000 times
  end
end

Script Runner Suites

Creating Script Runner suites utilizes APIs to add groups to the defined suites. For more information please see running script suites.

add_group, add_group_setup, add_group_teardown, add_script

Since 5.0.0

Adds a group's methods to the suite. The add_group method adds all the group methods including setup, teardown, and all the methods starting with 'script_' or 'test_'. The add_group_setup method adds just the setup method defined in the group class. The add_group_teardown method adds just the teardown method defined in the group class. The add_script method adds an individual method to the suite. NOTE: add_script can add any method including those not named with 'script_' or 'test_'.

Python Syntax
Ruby Syntax

add_group(<Group Class>)
add_group_setup(<Group Class>)
add_group_teardown(<Group Class>)
add_script(<Group Class>, <Method>)

add_group(<Group Class>)
add_group_setup(<Group Class>)
add_group_teardown(<Group Class>)
add_script(<Group Class>, <Method>)

Parameter	Description
Group Class	Name of the previously defined class which inherits from the OpenC3 Group class. The Ruby API passes a String with the name of the group. The Python API passes the Group class directly.
Method	Name of the method in the OpenC3 Group class. The Ruby API passes a String with the name of the method. The Python API passes the Group class directly.

Python Example
Ruby Example

from openc3.script import *
from openc3.script.suite import Group, Suite

class ExampleGroup(Group):
    def script_1(self):
        # Insert test code here ...
        pass
class WrapperGroup(Group):
    def setup(self):
        # Insert test code here ...
        pass
    def my_method(self):
        # Insert test code here ...
        pass
    def teardown(self):
        # Insert test code here ...
        pass
class MySuite(Suite):
    def __init__(self):
        super().__init__()
        self.add_group(ExampleGroup)
        self.add_group_setup(WrapperGroup)
        self.add_script(WrapperGroup, 'my_method')
        self.add_group_teardown(WrapperGroup)

load 'openc3/script/suite.rb'

class ExampleGroup < OpenC3::Group
  def script_1
    # Insert test code here ...
  end
end
class WrapperGroup < OpenC3::Group
  def setup
    # Insert test code here ...
  end
  def my_method
    # Insert test code here ...
  end
  def teardown
    # Insert test code here ...
  end
end

class MySuite < OpenC3::Suite
  def initialize
    super()
    add_group('ExampleGroup')
    add_group_setup('WrapperGroup')
    add_script('WrapperGroup', 'my_method')
    add_group_teardown('WrapperGroup')
  end
end

Timelines

The Timelines API allows you to manipulate Calendar timelines. Calendar is a COSMOS Enterprise tool.

list_timelines

Since 5.12.0

Returns all the timelines in an array of hashes / list of dicts.

Python Example
Ruby Example

timelihes = list_timelines() # =>
# [{'name': 'Mine', 'color': '#e67643', 'execute': True, 'shard': 0, 'scope': 'DEFAULT', 'updated_at': 1737124024123643504}]

timelines = list_timelines() # =>
# [{"name"=>"Mine", "color"=>"#e67643", "execute"=>true, "shard"=>0, "scope"=>"DEFAULT", "updated_at"=>1737124024123643504}]

create_timeline

Since 5.12.0

Create a new timeline in Calendar which can hold activities.

Python Syntax
Ruby Syntax

create_timeline(name, color=None)

create_timeline(name, color: nil)

Parameter	Description
name	Name of the timeline
color	Color of the timeline. Must be given as a hex value, e.g. #FF0000. Default is a random color.

Python Example
Ruby Example

tl = create_timeline("Other", color="#FF0000") # =>
# {'name': 'Other', 'color': '#FF0000', 'execute': True, 'shard': 0, 'scope': 'DEFAULT', 'updated_at': 1737126348971941923}

tl = create_timeline("Mine") # =>
# {"name"=>"Mine", "color"=>"#e67643", "execute"=>true, "shard"=>0, "scope"=>"DEFAULT", "updated_at"=>1737124024123643504}

get_timeline

Since 5.12.0

Get information about an existing timeline.

Python Syntax
Ruby Syntax

get_timeline(name)

get_timeline(name)

Parameter	Description
name	Name of the timeline

Python Example
Ruby Example

tl = get_timeline("Other") # =>
# {'name': 'Other', 'color': '#FF0000', 'execute': True, 'shard': 0, 'scope': 'DEFAULT', 'updated_at': 1737126348971941923}

tl = get_timeline("Mine") # =>
# {"name"=>"Mine", "color"=>"#e67643", "execute"=>true, "shard"=>0, "scope"=>"DEFAULT", "updated_at"=>1737124024123643504}

set_timeline_color

Since 5.12.0

Set the displayed color for an existing timeline.

Python Syntax
Ruby Syntax

set_timeline_color(name, color)

set_timeline_color(name, color)

Parameter	Description
name	Name of the timeline
color	Color of the timeline. Must be given as a hex value, e.g. #FF0000.

Python Example
Ruby Example

set_timeline_color("Mine", "#4287f5")

set_timeline_color("Mine", "#4287f5")

delete_timeline

Since 5.12.0

Delete an existing timeline. Timelines with activities can only be deleted by passing force = true.

Python Syntax
Ruby Syntax

delete_timeline(name, force=False)

delete_timeline(name, force: false)

Parameter	Description
name	Name of the timeline
force	Whether to delete the timeline if it has activities. Default is false.

Python Example
Ruby Example

delete_timeline("Other", force=True)

delete_timeline("Mine", force: true)

create_timeline_activity

Since 5.12.0

Create an activity on an existing timeline. Activities can be one of COMMAND, SCRIPT, or RESERVE. Activities have a start and stop time and commands and scripts take data on the command or script to execute.

Python Syntax
Ruby Syntax

create_timeline_activity(name, kind, start, stop, data={})

create_timeline_activity(name, kind:, start:, stop:, data: {})

Parameter	Description
name	Name of the timeline
kind	Type of the activity. One of COMMAND, SCRIPT, or RESERVE.
start	Start time of the activity. Time / datetime instance.
stop	Stop time of the activity. Time / datetime instance.
data	Hash / dict of data for COMMAND or SCRIPT type. Default is empty hash / dict. Valid keys are described below.
scope	Scope of the activity. Default is the OPENC3_SCOPE, usually "DEFAULT". Must be the containing scope of the timeline specified by the `name` parameter.

create_timeline_activity data parameter

Key	Value
username	Username to display as the creator of the activity. Default is "operator".
customTitle	Custom title to display for the activity. Default is empty string which results in no custom title being shown.
notes	Notes to display for the activity. Default is empty string, which results in no notes being shown.
command	Command to execute for COMMAND type activities.
script	Script to execute for SCRIPT type activities. Should be given as the path to the script file to run, starting with the target name, e.g. "INST/procedures/collect.rb".
environment	Array of environment variable key/value pairs to set for SCRIPT type activities, e.g. `[{key: "USER", value: "JASON"}]`

Python Example
Ruby Example

now = datetime.now(timezone.utc)
start = now + timedelta(hours=1)
stop = start + timedelta(hours=1)
act = create_timeline_activity("PythonTL", kind="RESERVE", start=start, stop=stop) # =>
# {'name': 'PythonTL', 'updated_at': 1737129305507111708, 'start': 1737132902, 'stop': 1737136502,
#  'kind': 'reserve', 'data': {'username': 'operator'},
#  'scope': 'DEFAULT', 'fulfillment': False, 'uuid': '46328378-ed78-4719-ad70-e84951a196fd',
#  'events': [{'time': 1737129305, 'event': 'created'}], 'recurring': {}}
act = create_timeline_activity("PythonTL", kind="COMMAND", start=start, stop=stop,
    data={'command': "INST COLLECT with TYPE NORMAL, DURATION 5, TEMP 10"}) # =>
# {'name': 'PythonTL', 'updated_at': 1737129508886643928, 'start': 1737133108, 'stop': 1737136708,
#  'kind': 'command', 'data': {'command': 'INST COLLECT with TYPE NORMAL, DURATION 5, TEMP 10', 'username': 'operator'},
#  'scope': 'DEFAULT', 'fulfillment': False, 'uuid': 'cddbf034-ccdd-4c36-91c2-2653a39b06a5',
#  'events': [{'time': 1737129508, 'event': 'created'}], 'recurring': {}}
start = now + timedelta(hours=2)
stop = start + timedelta(hours=1)
act = create_timeline_activity("PythonTL", kind="SCRIPT", start=start, stop=stop,
  data={'environment': [{'key': "USER", 'value': "JASON"}], 'script': "INST2/procedures/checks.py"}) # =>
# {'name': 'PythonTL', 'updated_at': 1737129509288571345, 'start': 1737136708, 'stop': 1737140308,
#  'kind': 'script', 'data': {'environment': [{'key': 'USER', 'value': 'JASON'}], 'script': 'INST2/procedures/checks.py', 'username': 'operator'},
#  'scope': 'DEFAULT', 'fulfillment': False, 'uuid': '4f8d791b-b138-4383-b5ec-85c28b2bea20',
#  'events': [{'time': 1737129509, 'event': 'created'}], 'recurring': {}}

now = Time.now()
start = now + 3600
stop = start + 3600
act = create_timeline_activity("RubyTL", kind: "RESERVE", start: start, stop: stop) # =>
# { "name"=>"RubyTL", "updated_at"=>1737128705034982375, "start"=>1737132303, "stop"=>1737135903,
#   "kind"=>"reserve", "data"=>{"username"=>"operator"},
#   "scope"=>"DEFAULT", "fulfillment"=>false, "uuid"=>"5f373846-eb6c-43cd-97bd-cca19a8ffb04",
#   "events"=>[{"time"=>1737128705, "event"=>"created"}], "recurring"=>{}}
act = create_timeline_activity("RubyTL", kind: "COMMAND", start: start, stop: stop,
    data: {command: "INST COLLECT with TYPE NORMAL, DURATION 5, TEMP 10"}) # =>
# { "name"=>"RubyTL", "updated_at"=>1737128761316084471, "start"=>1737132303, "stop"=>1737135903,
#   "kind"=>"command", "data"=>{"command"=>"INST COLLECT with TYPE NORMAL, DURATION 5, TEMP 10", "username"=>"operator"},
#   "scope"=>"DEFAULT", "fulfillment"=>false, "uuid"=>"cdb661b4-a65b-44e7-95e2-5e1dba80c782",
#   "events"=>[{"time"=>1737128761, "event"=>"created"}], "recurring"=>{}}
act = create_timeline_activity("RubyTL", kind: "SCRIPT", start: start, stop: stop,
  data: {environment: [{key: "USER", value: "JASON"}], script: "INST/procedures/checks.rb"}) # =>
# { "name"=>"RubyTL", "updated_at"=>1737128791047885970, "start"=>1737135903, "stop"=>1737139503,
#   "kind"=>"script", "data"=>{"environment"=>[{"key"=>"USER", "value"=>"JASON"}], "script"=>"INST/procedures/checks.rb", "username"=>"operator"},
#   "scope"=>"DEFAULT", "fulfillment"=>false, "uuid"=>"70426e3d-6313-4897-b159-6e5cd94ace1d",
#   "events"=>[{"time"=>1737128791, "event"=>"created"}], "recurring"=>{}}

update_timeline_activity

Update an existing timeline activity. The activity is identified by its timeline name and current start time (id). All fields (kind, start, stop, data) are replaced with the provided values.

Python Syntax
Ruby Syntax

update_timeline_activity(name, id, kind, start, stop, uuid, data={})

update_timeline_activity(name, id:, kind:, start:, stop:, uuid:, data: {})

Parameter	Description
name	Name of the timeline
id	The current start time / score of the activity to update (integer, Unix seconds).
kind	Type of the activity. One of COMMAND, SCRIPT, or RESERVE.
start	New start time of the activity. Time / datetime instance.
stop	New stop time of the activity. Time / datetime instance.
uuid	UUID of the activity.
data	Hash / dict of data for the activity. Default is empty hash / dict. Valid keys are described above.
scope	Scope of the activity. Must be the containing scope of the timeline specified by the `name` parameter.

Python Example
Ruby Example

# First create an activity
now = datetime.now(timezone.utc)
start = now + timedelta(hours=1)
stop = start + timedelta(hours=1)
act = create_timeline_activity("PythonTL", kind="COMMAND", start=start, stop=stop,
    data={'command': "INST COLLECT with TYPE NORMAL, DURATION 5"})

# Update the activity with a new custom title, notes, and extended stop time
new_stop = stop + timedelta(minutes=30)
updated = update_timeline_activity("PythonTL",
    id=act['start'],
    kind="COMMAND", start=start, stop=new_stop,
    uuid=act['uuid'],
    data={'command': "INST COLLECT with TYPE NORMAL, DURATION 10",
          'customTitle': "Extended Collection",
          'notes': "Duration extended per ops request"})

# First create an activity
now = Time.now()
start = now + 3600
stop = start + 3600
act = create_timeline_activity("RubyTL", kind: "COMMAND", start: start, stop: stop,
  data: {command: "INST COLLECT with TYPE NORMAL, DURATION 5"})

# Update the activity with a new custom title, notes, and extended stop time
new_stop = stop + 1800
updated = update_timeline_activity("RubyTL",
  id: act['start'],
  kind: "COMMAND", start: start, stop: new_stop,
  uuid: act['uuid'],
  data: {command: "INST COLLECT with TYPE NORMAL, DURATION 10",
         customTitle: "Extended Collection",
         notes: "Duration extended per ops request"})

get_timeline_activity

Since 5.12.0

Get an existing timeline activity.

Python Syntax
Ruby Syntax

get_timeline_activity(name, start, uuid)

get_timeline_activity(name, start, uuid)

Parameter	Description
name	Name of the timeline
start	Start time of the activity. Time / datetime instance.
uuid	UUID of the activity

Python Example
Ruby Example

act = get_timeline_activity("PythonTL", 1737133108, "cddbf034-ccdd-4c36-91c2-2653a39b06a5") # =>
# {'name': 'PythonTL', 'updated_at': 1737129508886643928, 'start': 1737133108, 'stop': 1737136708,
#  'kind': 'command', 'data': {'command': 'INST COLLECT with TYPE NORMAL, DURATION 5, TEMP 10', 'username': 'operator'},
#  'scope': 'DEFAULT', 'fulfillment': False, 'uuid': 'cddbf034-ccdd-4c36-91c2-2653a39b06a5',
#  'events': [{'time': 1737129508, 'event': 'created'}], 'recurring': {}}

act = get_timeline_activity("RubyTL", 1737132303, "cdb661b4-a65b-44e7-95e2-5e1dba80c782") # =>
# { "name"=>"RubyTL", "updated_at"=>1737128761316084471, "start"=>1737132303, "stop"=>1737135903,
#   "kind"=>"command", "data"=>{"command"=>"INST COLLECT with TYPE NORMAL, DURATION 5, TEMP 10", "username"=>"operator"},
#   "scope"=>"DEFAULT", "fulfillment"=>false, "uuid"=>"cdb661b4-a65b-44e7-95e2-5e1dba80c782",
#   "events"=>[{"time"=>1737128761, "event"=>"created"}], "recurring"=>{}}

get_timeline_activities

Since 5.12.0

Get a range of timeline activities between start and stop time. If called without a start / stop time it defaults to 1 week before "now" up to 1 week from "now" (2 weeks total).

Python Syntax
Ruby Syntax

get_timeline_activities(name, start=None, stop=None, limit=None)

get_timeline_activities(name, start: nil, stop: nil, limit: nil)

Parameter	Description
name	Name of the timeline
start	Start time of the activities. Time / datetime instance. Defaults to 7 days ago.
stop	Stop time of the activities. Time / datetime instance. Defaults to 7 days from now.
limit	Maximum number of activities to return. Default is 1 per minute of the time range.

Python Example
Ruby Example

now = datetime.now(timezone.utc)
acts = get_timeline_activities("PythonTL", start=now - timedelta(hours=2), stop=now, limit=1000) # =>
# [{ "name"=>"PythonTL", ... }, { "name"=>"PythonTL", ... }]

acts = get_timeline_activities("RubyTL", start: Time.now() - 3600, stop: Time.now(), limit: 1000) # =>
# [{ "name"=>"RubyTL", ... }, { "name"=>"RubyTL", ... }]

delete_timeline_activity

Since 5.12.0

Delete an existing timeline activity.

Python Syntax
Ruby Syntax

delete_timeline_activity(name, start, uuid)

delete_timeline_activity(name, start, uuid)

Parameter	Description
name	Name of the timeline
start	Start time of the activity. Time / datetime instance.
uuid	UUID of the activity

Python Example
Ruby Example

delete_timeline_activity("PythonTL", 1737133108, "cddbf034-ccdd-4c36-91c2-2653a39b06a5")

delete_timeline_activity("RubyTL", 1737132303, "cdb661b4-a65b-44e7-95e2-5e1dba80c782")

Metadata

Metadata allows you to mark the regular target / packet data logged in COSMOS with your own fields. This metadata can then be searched and used to filter data when using other COSMOS tools.

metadata_all

Since 5.2.0

Returns all the metadata that was previously set

Python Syntax
Ruby Syntax

metadata_all()

metadata_all()

Parameter	Description
limit	Amount of metadata items to return. Default is 100.

Python Example
Ruby Example

metadata_all(limit='500')

metadata_all(limit: 500)

metadata_get

Since 5.2.0

Returns metadata that was previously set

Python Syntax
Ruby Syntax

metadata_get(start)

metadata_get(start)

Parameter	Description
start	Named parameter, time at which to retrieve metadata as integer seconds from epoch

Python Example
Ruby Example

metadata_get(start='500')

metadata_get(start: 500)

metadata_set

Since 5.2.0

Sets metadata which appears on the Calendar and can be retried by metadata_get.

Python Syntax
Ruby Syntax

metadata_set(<Metadata>, start, color)

metadata_set(<Metadata>, start, color)

Parameter	Description
Metadata	Hash or dict of key value pairs to store as metadata.
start	Named parameter, time at which to store metadata. Default is now.
color	Named parameter, color to display metadata in the calendar. Default is #003784.

Python Example
Ruby Example

metadata_set({ 'key': 'value' })
metadata_set({ 'key': 'value' }, color='ff5252')

metadata_set({ 'key' => 'value' })
metadata_set({ 'key' => 'value' }, color: '#ff5252')

metadata_update

Since 5.2.0

Updates metadata that was previously set

Python Syntax
Ruby Syntax

metadata_update(<Metadata>, start, color)

metadata_update(<Metadata>, start, color)

Parameter	Description
Metadata	Hash or dict of key value pairs to update as metadata.
start	Named parameter, time at which to update metadata. Default is latest metadata.
color	Named parameter, color to display metadata in the calendar. Default is #003784.

Python Example
Ruby Example

metadata_update({ 'key': 'value' })

metadata_update({ 'key' => 'value' })

metadata_input

Since 5.2.0

Prompts the user to set existing metadata values or create new a new one.

Python Example
Ruby Example

metadata_input()

metadata_input()

Settings

COSMOS has several settings typically accessed through the Admin Settings tab. These APIs allow programmatic access to those same settings.

list_settings

Since 5.0.0

Return all the current COSMOS setting name. These are the names that should be used in the other APIs.

Python Example
Ruby Example

print(list_settings()) # => ['pypi_url', 'rubygems_url', 'source_url', 'version']

puts list_settings() # => ["pypi_url", "rubygems_url", "source_url", "version"]

get_all_settings

Since 5.0.0

Return all the current COSMOS settings along with their values.

Python Example
Ruby Example

settings = get_all_settings() # =>
# { 'version': {'name': 'version', 'data': '5.11.4-beta0', 'updated_at': 1698074299509456507},
#   'pypi_url': {'name': 'pypi_url', 'data': 'https://pypi.org/simple', 'updated_at': 1698026776574347007},
#   'rubygems_url': {'name': 'rubygems_url', 'data': 'https://rubygems.org', 'updated_at': 1698026776574105465},
#   'source_url': {'name': 'source_url', 'data': 'https://github.com/OpenC3/cosmos', 'updated_at': 1698026776573904132} }

settings = get_all_settings() # =>
# { "version"=>{"name"=>"version", "data"=>"5.11.4-beta0", "updated_at"=>1698074299509456507},
#   "pypi_url"=>{"name"=>"pypi_url", "data"=>"https://pypi.org/simple", "updated_at"=>1698026776574347007},
#   "rubygems_url"=>{"name"=>"rubygems_url", "data"=>"https://rubygems.org", "updated_at"=>1698026776574105465},
#   "source_url"=>{"name"=>"source_url", "data"=>"https://github.com/OpenC3/cosmos", "updated_at"=>1698026776573904132} }

get_setting, get_settings

Since 5.0.0

Return the data from the given COSMOS setting. Returns nil (Ruby) or None (Python) if the setting does not exist.

Python Syntax
Ruby Syntax

get_setting(<Setting Name>)
get_settings(<Setting Name1>, <Setting Name2>, ...)

get_setting(<Setting Name>)
get_settings(<Setting Name1>, <Setting Name2>, ...)

Parameter	Description
Setting Name	Name of the setting to return

Python Example
Ruby Example

setting = get_setting('version') # => '5.11.4-beta0'
setting = get_setting('version', 'rubygems_url') # => ['5.11.4-beta0', 'https://rubygems.org']

setting = get_setting('version') # => "5.11.4-beta0"
setting = get_settings('version', 'rubygems_url') # => ["5.11.4-beta0", "https://rubygems.org"]

set_setting

Since 5.0.0

Sets the given setting value.

Admin Passwork Required

This API is only accessible externally (not within Script Runner) and requires the admin password.

Python Syntax
Ruby Syntax

set_setting(<Setting Name>, <Setting Value>)

set_setting(<Setting Name>, <Setting Value>)

Parameter	Description
Setting Name	Name of the setting to change
Setting Value	Setting value to set

Python Example
Ruby Example

set_setting('pypi_url', 'https://mypypiserver')

set_setting('rubygems_url', 'https://mygemserver')

Configuration

Many COSMOS tools have the ability to load and save a configuration. These APIs allow you to programmatically load and save the configuration.

config_tool_names

Since 5.12.0

List all the configuration tool names which are used as the first parameter in the other APIs.

Python Example
Ruby Example

names = config_tool_names() # => ['telemetry_grapher', 'data_viewer']

names = config_tool_names() # => ["telemetry_grapher", "data_viewer"]

list_configs

Since 5.0.0

List all the saved configuration names under the given tool name.

Python Syntax
Ruby Syntax

list_configs(<Tool Name>)

list_configs(<Tool Name>)

Parameter	Description
Tool Name	Name of the tool to retrieve configuration names from

Python Example
Ruby Example

configs = list_configs('telemetry_grapher') # => ['adcs', 'temps']

configs = list_configs('telemetry_grapher') # => ['adcs', 'temps']

load_config

Since 5.0.0

Load a particular tool configuration.

Tool Configuration

Tool configurations are not fully documented and subject to change between releases. Only modify values returned by load_config and do not change any keys.

Python Syntax
Ruby Syntax

load_config(<Tool Name>, <Configuration Name>)

load_config(<Tool Name>, <Configuration Name>)

Parameter	Description
Tool Name	Name of the tool
Configuration Name	Name of the configuration

Python Example
Ruby Example

config = load_config('telemetry_grapher', 'adcs') # =>
# [ {
#   "items": [
#     {
#       "targetName": "INST",
#       "packetName": "ADCS",
#       "itemName": "CCSDSVER",
# ...

config = load_config('telemetry_grapher', 'adcs') # =>
# [ {
#   "items": [
#     {
#       "targetName": "INST",
#       "packetName": "ADCS",
#       "itemName": "CCSDSVER",
# ...

save_config

Since 5.0.0

Save a particular tool configuration.

Python Syntax
Ruby Syntax

save_config(<Tool Name>, <Configuration Name>, local_mode)

save_config(<Tool Name>, <Configuration Name>, local_mode)

Parameter	Description
Tool Name	Name of the tool
Configuration Name	Name of the configuration
local_mode	Whether to save the configuration in local mode

Python Example
Ruby Example

save_config('telemetry_grapher', 'adcs', config)

save_config('telemetry_grapher', 'adcs', config)

delete_config

Since 5.0.0

Delete a particular tool configuration.

Python Syntax
Ruby Syntax

delete_config(<Tool Name>, <Configuration Name>, local_mode)

delete_config(<Tool Name>, <Configuration Name>, local_mode)

Parameter	Description
Tool Name	Name of the tool
Configuration Name	Name of the configuration
local_mode	Whether to delete the configuration in local mode

Python Example
Ruby Example

delete_config('telemetry_grapher', 'adcs')

delete_config('telemetry_grapher', 'adcs')

Offline Access

An offline access token is required to execute scripts in COSMOS Enterprise. These methods support client side creation, testing, and setting of the offline_access_token.

initialize_offline_access

Since 6.3.0

Creates and sets the offline access token for the user. Note: calling this method is required before executing any api methods that require an offline access token like script_run (Enterprise Only). This method must be called OUTSIDE of ScriptRunner as it is needed in order to start a script in the first place.

In Enterprise, the OPENC3_API_USER and OPENC3_API_PASSWORD environment variables must be set for the initialize_offline_access to generate a token. This API user must also be a valid user with the respective permissions setup in Keycloak. These two variables are not in the .env by default, and should not be as they contain sensitive information.

Depending on your deployment environment, there are several ways Secrets can be managed. In a Kubernetes deployment, Secretes can be configured, or dynamically managed by a separate secrets management tool like HashiCorp Vault or AWS Secrets Manager.

Python Example
Ruby Example

# First setup environment variables. See examples/external_script.py
initialize_offline_access()
script_run("INST2/procedures/collect.py")

# First setup environment variables. See examples/external_script.rb
initialize_offline_access()
script_run("INST/procedures/collect.rb")

offline_access_needed

Since 5.2.0

Returns true if the user needs to generate an offline access token. Note this will only be true if the user is at least authorized to view scripts, otherwise it will always be false if script_view permission is not available for the user.

Python Example
Ruby Example

result = offline_access_needed() # => False

result = offline_access_needed() # => true

set_offline_access

Since 5.2.0

Sets the offline access token in the backend. Note: You probably don't need to call this method directly, as it will be called by initialize_offline_access().

Python Syntax
Ruby Syntax

set_offline_access(offline_access_token)

set_offline_access(offline_access_token)

Parameter	Description
offline_access_token	Keycloak generated refresh token that contains the offline_access openid scope

Python Example
Ruby Example

set_offline_access(offline_access_token)

set_offline_access(offline_access_token)

Autonomic

Autonomic provides automated reactions to telemetry conditions through triggers and reactions. These methods allow you to manage autonomic groups, triggers, and reactions programmatically.

autonomic_group_list

Since 6.4.2

Returns a list of all autonomic groups.

Python Syntax
Ruby Syntax

autonomic_group_list(scope=None)

autonomic_group_list(scope: $openc3_scope)

Parameter	Description
scope	Scope to operate in (optional)

Python Example
Ruby Example

groups = autonomic_group_list()

groups = autonomic_group_list()

autonomic_group_create

Since 6.4.2

Creates a new autonomic group.

Python Syntax
Ruby Syntax

autonomic_group_create(name, scope=None)

autonomic_group_create(name, scope: $openc3_scope)

Parameter	Description
name	Name of the group to create
scope	Scope to operate in (optional)

Python Example
Ruby Example

group = autonomic_group_create("SAFETY")

group = autonomic_group_create("SAFETY")

autonomic_group_show

Since 6.4.2

Shows details about a specific autonomic group.

Python Syntax
Ruby Syntax

autonomic_group_show(name, scope=None)

autonomic_group_show(name, scope: $openc3_scope)

Parameter	Description
name	Name of the group
scope	Scope to operate in (optional)

Python Example
Ruby Example

group_info = autonomic_group_show("SAFETY")

group_info = autonomic_group_show("SAFETY")

autonomic_group_destroy

Since 6.4.2

Destroys an autonomic group.

Python Syntax
Ruby Syntax

autonomic_group_destroy(name, scope=None)

autonomic_group_destroy(name, scope: $openc3_scope)

Parameter	Description
name	Name of the group to destroy
scope	Scope to operate in (optional)

Python Example
Ruby Example

autonomic_group_destroy("SAFETY")

autonomic_group_destroy("SAFETY")

autonomic_trigger_list

Since 6.4.2

Returns a list of triggers in a specific group.

Python Syntax
Ruby Syntax

autonomic_trigger_list(group='DEFAULT', scope=None)

autonomic_trigger_list(group: 'DEFAULT', scope: $openc3_scope)

Parameter	Description
group	Group to list triggers from (default: 'DEFAULT')
scope	Scope to operate in (optional)

Python Example
Ruby Example

triggers = autonomic_trigger_list(group="SAFETY")

triggers = autonomic_trigger_list(group: "SAFETY")

autonomic_trigger_create

Since 6.4.2

Creates a new trigger with the specified condition.

Python Syntax
Ruby Syntax

autonomic_trigger_create(left, operator, right, group='DEFAULT', scope=None)

autonomic_trigger_create(left:, operator:, right:, group: 'DEFAULT', scope: $openc3_scope)

Parameter	Description
left	Left side of the trigger condition
operator	Comparison operator (e.g. >, <, ==, !=, >=, <=)
right	Right side of the trigger condition
group	Group to create the trigger in (default: 'DEFAULT')
scope	Scope to operate in (optional)

Python Example
Ruby Example

left = {
    "type": "item",
    "target": "INST",
    "packet": "HEALTH_STATUS",
    "item": "TEMP1",
    "valueType": "CONVERTED",
}
operator = ">"
right = {
    "type": "float",
    "float": 0,
}
trigger = autonomic_trigger_create(left=left, operator=operator, right=right, group="SAFETY")

# Create a test trigger
left = {
  type: "item",
  target: "INST",
  packet: "HEALTH_STATUS",
  item: "TEMP1",
  valueType: "CONVERTED",
}
operator = ">"
right = {
  type: "float",
  float: 0,
}
trigger = autonomic_trigger_create(left: left, operator: operator, right: right, group: "SAFETY")

autonomic_trigger_show

Since 6.4.2

Shows details about a specific trigger.

Python Syntax
Ruby Syntax

autonomic_trigger_show(name, group='DEFAULT', scope=None)

autonomic_trigger_show(name, group: 'DEFAULT', scope: $openc3_scope)

Parameter	Description
name	Name of the trigger
group	Group the trigger belongs to (default: 'DEFAULT')
scope	Scope to operate in (optional)

Python Example
Ruby Example

trigger_info = autonomic_trigger_show("TRIG1", group="SAFETY")

trigger_info = autonomic_trigger_show("TRIG1", group: "SAFETY")

autonomic_trigger_enable

Since 6.4.2

Enables a trigger.

Python Syntax
Ruby Syntax

autonomic_trigger_enable(name, group='DEFAULT', scope=None)

autonomic_trigger_enable(name, group: 'DEFAULT', scope: $openc3_scope)

Parameter	Description
name	Name of the trigger to enable
group	Group the trigger belongs to (default: 'DEFAULT')
scope	Scope to operate in (optional)

Python Example
Ruby Example

autonomic_trigger_enable("TRIG1", group="SAFETY")

autonomic_trigger_enable("TRIG1", group: "SAFETY")

autonomic_trigger_disable

Since 6.4.2

Disables a trigger.

Python Syntax
Ruby Syntax

autonomic_trigger_disable(name, group='DEFAULT', scope=None)

autonomic_trigger_disable(name, group: 'DEFAULT', scope: $openc3_scope)

Parameter	Description
name	Name of the trigger to disable
group	Group the trigger belongs to (default: 'DEFAULT')
scope	Scope to operate in (optional)

Python Example
Ruby Example

autonomic_trigger_disable("TRIG1", group="SAFETY")

autonomic_trigger_disable("TRIG1", group: "SAFETY")

autonomic_trigger_update

Since 6.4.2

Updates an existing trigger with new parameters.

Python Syntax
Ruby Syntax

autonomic_trigger_update(name, group='DEFAULT', left=left, operator=operator, right=right, scope=None)

autonomic_trigger_update(name, group: 'DEFAULT', left: left, operator: operator, right: right, scope: $openc3_scope)

Parameter	Description
name	Name of the trigger to update
group	Group the trigger belongs to (default: 'DEFAULT')
left	New left side of the trigger condition (optional)
operator	New comparison operator (optional)
right	New right side of the trigger condition (optional)
scope	Scope to operate in (optional)

Python Example
Ruby Example

right = {
    "type": "float",
    "float": 100,
}
updated_trigger = autonomic_trigger_update(
    "TRIG1",
    group="SAFETY",
    right=right
)

right = {
  type: "float",
  float: 100,
}
updated_trigger = autonomic_trigger_update(
  "TRIG1",
  group: "SAFETY",
  right: right
)

autonomic_trigger_destroy

Since 6.4.2

Destroys a trigger.

Python Syntax
Ruby Syntax

autonomic_trigger_destroy(name, group='DEFAULT', scope=None)

autonomic_trigger_destroy(name, group: 'DEFAULT', scope: $openc3_scope)

Parameter	Description
name	Name of the trigger to destroy
group	Group the trigger belongs to (default: 'DEFAULT')
scope	Scope to operate in (optional)

Python Example
Ruby Example

autonomic_trigger_destroy("TRIG1", group="SAFETY")

autonomic_trigger_destroy("TRIG1", group: "SAFETY")

autonomic_reaction_list

Since 6.4.2

Returns a list of all reactions.

Python Syntax
Ruby Syntax

autonomic_reaction_list(scope=None)

autonomic_reaction_list(scope: $openc3_scope)

Parameter	Description
scope	Scope to operate in (optional)

Python Example
Ruby Example

reactions = autonomic_reaction_list()

reactions = autonomic_reaction_list()

autonomic_reaction_create

Since 6.4.2

Creates a new reaction that executes actions when triggers are activated.

Python Syntax
Ruby Syntax

autonomic_reaction_create(triggers, actions, trigger_level='EDGE', snooze=0, scope=None)

autonomic_reaction_create(triggers:, actions:, trigger_level: 'EDGE', snooze: 0, scope: $openc3_scope)

Parameter	Description
triggers	List of trigger names that activate this reaction
actions	List of actions to perform when triggered
trigger_level	Trigger level: 'EDGE' or 'LEVEL' (default: 'EDGE')
snooze	Snooze time in seconds between activations (default: 0)
scope	Scope to operate in (optional)

Python Example
Ruby Example

triggers = [{
    'name': 'TRIG1',
    'group': 'SAFETY',
}]
actions = [{
    'type': 'command',
    'value': 'INST ABORT'
}]
reaction = autonomic_reaction_create(
  triggers=triggers,
  actions=actions,
  trigger_level='EDGE',
  snooze=300
)

triggers = [{
  'name' => 'TRIG1',
  'group' => 'SAFETY',
}]
actions = [{
  'type' => 'command',
  'value' => 'INST ABORT'
}]
reaction = autonomic_reaction_create(
  triggers: triggers,
  actions: actions,
  trigger_level: 'EDGE',
  snooze: 300
)

autonomic_reaction_show

Since 6.4.2

Shows details about a specific reaction.

Python Syntax
Ruby Syntax

autonomic_reaction_show(name, scope=None)

autonomic_reaction_show(name, scope: $openc3_scope)

Parameter	Description
name	Name of the reaction
scope	Scope to operate in (optional)

Python Example
Ruby Example

reaction_info = autonomic_reaction_show("REACT1")

reaction_info = autonomic_reaction_show("REACT1")

autonomic_reaction_enable

Since 6.4.2

Enables a reaction.

Python Syntax
Ruby Syntax

autonomic_reaction_enable(name, scope=None)

autonomic_reaction_enable(name, scope: $openc3_scope)

Parameter	Description
name	Name of the reaction to enable
scope	Scope to operate in (optional)

Python Example
Ruby Example

autonomic_reaction_enable("REACT1")

autonomic_reaction_enable("REACT1")

autonomic_reaction_disable

Since 6.4.2

Disables a reaction.

Python Syntax
Ruby Syntax

autonomic_reaction_disable(name, scope=None)

autonomic_reaction_disable(name, scope: $openc3_scope)

Parameter	Description
name	Name of the reaction to disable
scope	Scope to operate in (optional)

Python Example
Ruby Example

autonomic_reaction_disable("REACT1")

autonomic_reaction_disable("REACT1")

autonomic_reaction_execute

Since 6.4.2

Manually executes a reaction's actions.

Python Syntax
Ruby Syntax

autonomic_reaction_execute(name, scope=None)

autonomic_reaction_execute(name, scope: $openc3_scope)

Parameter	Description
name	Name of the reaction to execute
scope	Scope to operate in (optional)

Python Example
Ruby Example

autonomic_reaction_execute("REACT1")

autonomic_reaction_execute("REACT1")

autonomic_reaction_update

Since 6.4.2

Updates an existing reaction with new parameters.

Python Syntax
Ruby Syntax

autonomic_reaction_update(name, triggers=None, actions=None, trigger_level=None, snooze=None, scope=None)

autonomic_reaction_update(name, triggers: nil, actions: nil, trigger_level: nil, snooze: nil, scope: $openc3_scope)

Parameter	Description
name	Name of the reaction to update
triggers	New list of trigger names (optional)
actions	New list of actions (optional)
trigger_level	New trigger level (optional)
snooze	New snooze time in seconds (optional)
scope	Scope to operate in (optional)

Python Example
Ruby Example

updated_reaction = autonomic_reaction_update(
  "REACT1",
  snooze=600
)

updated_reaction = autonomic_reaction_update(
  "REACT1",
  snooze: 600
)

autonomic_reaction_destroy

Since 6.4.2

Destroys a reaction.

Python Syntax
Ruby Syntax

autonomic_reaction_destroy(name, scope=None)

autonomic_reaction_destroy(name, scope: $openc3_scope)

Parameter	Description
name	Name of the reaction to destroy
scope	Scope to operate in (optional)

Python Example
Ruby Example

autonomic_reaction_destroy("REACT1")

autonomic_reaction_destroy("REACT1")

Utilities

Various utilities that can be used in scripts.

open_tab

Since 7.0.0

Opens a new tab in the browser.

Python Syntax
Ruby Syntax

open_tab(url)

open_tab(url)

Parameter	Description
url	URL to open in a new tab

Python Example
Ruby Example

open_tab("https://github.com/OpenC3/cosmos")

open_tab("https://github.com/OpenC3/cosmos")

Concepts​

Programming Languages​

Using Script Runner​

Telemetry Types​

Script Runner API​

Migration from COSMOS v6 to v7​

Migration from COSMOS v5 to v6​

Migration from COSMOS v4 to v5​

Retrieving User Input​

ask​

ask_string​

message_box​

vertical_message_box​

combo_box​

check_box​

open_file_dialog​

open_files_dialog​

open_bucket_dialog​

File Manipulation​

get_target_file​

put_target_file​

delete_target_file​

download_file​

Providing information to the user​

prompt​

Commands​

cmd​

cmd_no_range_check​

cmd_no_hazardous_check​

cmd_no_checks​

cmd_raw​

cmd_raw_no_range_check​

cmd_raw_no_hazardous_check​

cmd_raw_no_checks​

build_cmd​

enable_cmd​

disable_cmd​

send_raw​

get_all_cmds​

get_all_cmd_names​

get_cmd​

get_param​

get_cmd_buffer​

get_cmd_hazardous​

get_cmd_value​

get_cmd_time​

get_cmd_cnt​

get_cmd_cnts​

critical_cmd_status​

critical_cmd_approve​

critical_cmd_reject​

critical_cmd_can_approve​

Command Queues​

queue_create​

queue_get​

queue_all​

queue_list​

queue_hold​

queue_release​

queue_disable​

queue_exec​

queue_remove​

queue_delete​

Handling Telemetry​

check, check_raw, check_formatted​

check_tolerance​

check_expression​

check_exception​

tlm, tlm_raw, tlm_formatted​

get_tlm_buffer​

get_tlm_packet​

get_tlm_available​

get_tlm_values​

get_all_tlm​

get_all_tlm_names​

get_all_tlm_item_names​

get_tlm​

get_item​

get_tlm_cnt​

set_tlm​

Concepts

Programming Languages

Using Script Runner

Telemetry Types

Script Runner API

Migration from COSMOS v6 to v7

Migration from COSMOS v5 to v6

Migration from COSMOS v4 to v5

Retrieving User Input

ask

ask_string

message_box

vertical_message_box

combo_box

check_box

open_file_dialog

open_files_dialog

open_bucket_dialog

File Manipulation

get_target_file

put_target_file

delete_target_file

download_file

Providing information to the user

prompt

Commands

cmd

cmd_no_range_check

cmd_no_hazardous_check

cmd_no_checks

cmd_raw

cmd_raw_no_range_check

cmd_raw_no_hazardous_check

cmd_raw_no_checks

build_cmd

enable_cmd

disable_cmd

send_raw

get_all_cmds

get_all_cmd_names

get_cmd

get_param

get_cmd_buffer

get_cmd_hazardous

get_cmd_value

get_cmd_time

get_cmd_cnt

get_cmd_cnts

critical_cmd_status

critical_cmd_approve

critical_cmd_reject

critical_cmd_can_approve

Command Queues

queue_create

queue_get

queue_all

queue_list

queue_hold

queue_release

queue_disable

queue_exec

queue_remove

queue_delete

Handling Telemetry

check, check_raw, check_formatted

check_tolerance

check_expression

check_exception

tlm, tlm_raw, tlm_formatted

get_tlm_buffer

get_tlm_packet

get_tlm_available

get_tlm_values

get_all_tlm

get_all_tlm_names

get_all_tlm_item_names

get_tlm

get_item

get_tlm_cnt

set_tlm