Module: OpenC3::Api

Includes:
Authorization, ApiShared, Extract
Included in:
AuthorizedApi, Interface, LimitsResponse
Defined in:
lib/openc3/api/api.rb,
lib/openc3/api/cmd_api.rb,
lib/openc3/api/tlm_api.rb,
lib/openc3/api/stash_api.rb,
lib/openc3/api/config_api.rb,
lib/openc3/api/limits_api.rb,
lib/openc3/api/router_api.rb,
lib/openc3/api/target_api.rb,
lib/openc3/api/metrics_api.rb,
lib/openc3/api/settings_api.rb,
lib/openc3/api/interface_api.rb,
lib/openc3/api/offline_access_api.rb

Constant Summary collapse

SUBSCRIPTION_DELIMITER =

2x double underscore since __ is reserved

'____'
DELAY_METRICS = 
{}
DURATION_METRICS = 
{}
SUM_METRICS = 
{}

Constants included from ApiShared

OpenC3::ApiShared::DEFAULT_TLM_POLLING_RATE

Constants included from Extract

Extract::SCANNING_REGULAR_EXPRESSION

Instance Method Summary collapse

Instance Method Details

#_get_item(target_name, packet_name, item_name, cache_timeout: 0.1, scope:) ⇒ Object

Gets an item. The code below is mostly duplicated from tlm_process_args in tlm_api.rb.

Parameters:

  • target_name (String) —

    target name

  • packet_name (String) —

    packet name

  • item_name (String) —

    item name

  • scope (String) —

    scope

Returns:

  • Hash The requested item based on the packet name



376
377
378
379
380
 
# File 'lib/openc3/api/limits_api.rb', line 376

def _get_item(target_name, packet_name, item_name, cache_timeout: 0.1, scope:)
  # Determine if this item exists, it will raise appropriate errors if not
  packet_name = CvtModel.determine_latest_packet_for_item(target_name, item_name, cache_timeout: cache_timeout, scope: $openc3_scope) if packet_name == 'LATEST'
  return TargetModel.packet_item(target_name, packet_name, item_name, scope: scope)
end

#_limits_group(group_name, action:, scope:, token:) ⇒ Object

Enables or disables a limits group



325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
 
# File 'lib/openc3/api/limits_api.rb', line 325

def _limits_group(group_name, action:, scope:, token:)
  authorize(permission: 'tlm_set', scope: scope, token: token)
  group_name.upcase!
  group = get_limits_groups(scope: scope, token: token)[group_name]
  raise "LIMITS_GROUP #{group_name} undefined. Ensure your telemetry definition contains the line: LIMITS_GROUP #{group_name}" unless group

  Logger.info("#{action.to_s.capitalize} Limits Group: #{group_name}", scope: scope)
  last_target_name = nil
  last_packet_name = nil
  packet = nil
  group.sort.each do |target_name, packet_name, item_name|
    if last_target_name != target_name || last_packet_name != packet_name
      if last_target_name && last_packet_name
        TargetModel.set_packet(last_target_name, last_packet_name, packet, scope: scope)
      end
      packet = TargetModel.packet(target_name, packet_name, scope: scope)
    end
    packet['items'].each do |item|
      if item['name'] == item_name
        if action == :enable
          enabled = true
          item['limits']['enabled'] = true
          message = "Enabling Limits For '#{target_name} #{packet_name} #{item_name}'"
        elsif action == :disable
          enabled = false
          item['limits'].delete('enabled')
          message = "Disabling Limits For '#{target_name} #{packet_name} #{item_name}'"
        end
        Logger.info(message, scope: scope)

        event = { type: :LIMITS_ENABLE_STATE, target_name: target_name, packet_name: packet_name,
                  item_name: item_name, enabled: enabled, time_nsec: Time.now.to_nsec_from_epoch, message: message }
        LimitsEventTopic.write(event, scope: scope)
        break
      end
    end
    last_target_name = target_name
    last_packet_name = packet_name
  end
  if last_target_name && last_packet_name
    TargetModel.set_packet(last_target_name, last_packet_name, packet, scope: scope)
  end
end

#_validate_tlm_type(type) ⇒ Object

PRIVATE



419
420
421
422
423
424
425
426
427
428
429
430
431
 
# File 'lib/openc3/api/tlm_api.rb', line 419

def _validate_tlm_type(type)
  case type.intern
  when :RAW
    return ''
  when :CONVERTED
    return 'C'
  when :FORMATTED
    return 'F'
  when :WITH_UNITS
    return 'U'
  end
  return nil
end

#build_cmd_output_string(target_name, cmd_name, cmd_params, packet, raw) ⇒ Object 



407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
 
# File 'lib/openc3/api/cmd_api.rb', line 407

def build_cmd_output_string(target_name, cmd_name, cmd_params, packet, raw)
  if raw
    output_string = 'cmd_raw("'
  else
    output_string = 'cmd("'
  end
  output_string << target_name + ' ' + cmd_name
  if cmd_params.nil? or cmd_params.empty?
    output_string << '")'
  else
    params = []
    cmd_params.each do |key, value|
      next if Packet::RESERVED_ITEM_NAMES.include?(key)

      item = packet['items'].find { |item| item['name'] == key.to_s }

      begin
        item_type = item['data_type'].intern
      rescue
        item_type = nil
      end

      if value.is_a?(String)
        value = value.dup
        if item_type == :BLOCK or item_type == :STRING
          if !value.is_printable?
            value = "0x" + value.simple_formatted
          else
            value = value.inspect
          end
        else
          value = value.convert_to_value.to_s
        end
        if value.length > 256
          value = value[0..255] + "...'"
        end
        value.tr!('"', "'")
      elsif value.is_a?(Array)
        value = "[#{value.join(", ")}]"
      end
      params << "#{key} #{value}"
    end
    params = params.join(", ")
    output_string << ' with ' + params + '")'
  end
  return output_string
end

#build_command(*args, range_check: true, raw: false, scope: $openc3_scope, token: $openc3_token, **kwargs) ⇒ Object

Build a command binary

Since:

  • 5.8.0



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/openc3/api/cmd_api.rb', line 103

def build_command(*args, range_check: true, raw: false, scope: $openc3_scope, token: $openc3_token, **kwargs)
  extract_string_kwargs_to_args(args, kwargs)
  case args.length
  when 1
    target_name, cmd_name, cmd_params = extract_fields_from_cmd_text(args[0], scope: scope)
  when 2, 3
    target_name  = args[0]
    cmd_name     = args[1]
    if args.length == 2
      cmd_params = {}
    else
      cmd_params = args[2]
    end
  else
    # Invalid number of arguments
    raise "ERROR: Invalid number of arguments (#{args.length}) passed to build_command()"
  end
  target_name = target_name.upcase
  cmd_name = cmd_name.upcase
  cmd_params = cmd_params.transform_keys(&:upcase)
  authorize(permission: 'cmd_info', target_name: target_name, scope: scope, token: token)
  DecomInterfaceTopic.build_cmd(target_name, cmd_name, cmd_params, range_check, raw, scope: scope)
end

#cmd(*args, **kwargs) ⇒ Object

The following methods send a command packet to a target. The ‘raw’ version of the equivalent command methods do not perform command parameter conversions.

Accepts two different calling styles:

cmd("TGT CMD with PARAM1 val, PARAM2 val")
cmd('TGT','CMD','PARAM1'=>val,'PARAM2'=>val)

Favor the first syntax where possible as it is more succinct.



64
65
66
 
# File 'lib/openc3/api/cmd_api.rb', line 64

def cmd(*args, **kwargs)
  cmd_implementation('cmd', *args, range_check: true, hazardous_check: true, raw: false, **kwargs)
end

#cmd_implementation(method_name, *args, range_check:, hazardous_check:, raw:, timeout: nil, log_message: nil, scope: $openc3_scope, token: $openc3_token, **kwargs) ⇒ Object

PRIVATE implementation details



346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
 
# File 'lib/openc3/api/cmd_api.rb', line 346

def cmd_implementation(method_name, *args, range_check:, hazardous_check:, raw:, timeout: nil, log_message: nil,
                       scope: $openc3_scope, token: $openc3_token, **kwargs)
  extract_string_kwargs_to_args(args, kwargs)
  unless [nil, true, false].include?(log_message)
    raise "Invalid log_message parameter: #{log_message}. Must be true or false."
  end
  unless timeout.nil?
    begin
      Float(timeout)
    rescue ArgumentError, TypeError
      raise "Invalid timeout parameter: #{timeout}. Must be numeric."
    end
  end

  case args.length
  when 1
    target_name, cmd_name, cmd_params = extract_fields_from_cmd_text(args[0], scope: scope)
  when 2, 3
    target_name  = args[0]
    cmd_name     = args[1]
    if args.length == 2
      cmd_params = {}
    else
      cmd_params = args[2]
    end
  else
    # Invalid number of arguments
    raise "ERROR: Invalid number of arguments (#{args.length}) passed to #{method_name}()"
  end
  target_name = target_name.upcase
  cmd_name = cmd_name.upcase
  cmd_params = cmd_params.transform_keys(&:upcase)
  authorize(permission: 'cmd', target_name: target_name, packet_name: cmd_name, scope: scope, token: token)
  packet = TargetModel.packet(target_name, cmd_name, type: :CMD, scope: scope)

  command = {
    'target_name' => target_name,
    'cmd_name' => cmd_name,
    'cmd_params' => cmd_params,
    'range_check' => range_check.to_s,
    'hazardous_check' => hazardous_check.to_s,
    'raw' => raw.to_s
  }
  if log_message.nil? # This means the default was used, no argument was passed
    log_message = true # Default is true
    # If the packet has the DISABLE_MESSAGES keyword then no messages by default
    log_message = false if packet["messages_disabled"]
    # Check if any of the parameters have DISABLE_MESSAGES
    cmd_params.each do |key, value|
      item = packet['items'].find { |item| item['name'] == key.to_s }
      if item && item['states'] && item['states'][value] && item['states'][value]["messages_disabled"]
        log_message = false
      end
    end
  end
  if log_message
    Logger.info(build_cmd_output_string(target_name, cmd_name, cmd_params, packet, raw), scope: scope)
  end
  CommandTopic.send_command(command, timeout: timeout, scope: scope)
end

#cmd_no_checks(*args, **kwargs) ⇒ Object

Send a command packet to a target without performing any value range checks or hazardous checks both on the command itself and its parameters.



93
94
95
 
# File 'lib/openc3/api/cmd_api.rb', line 93

def cmd_no_checks(*args, **kwargs)
  cmd_implementation('cmd_no_checks', *args, range_check: false, hazardous_check: false, raw: false, **kwargs)
end

#cmd_no_hazardous_check(*args, **kwargs) ⇒ Object

Send a command packet to a target without performing any hazardous checks both on the command itself and its parameters. Useful in scripts to prevent popping up warnings to the user.



84
85
86
 
# File 'lib/openc3/api/cmd_api.rb', line 84

def cmd_no_hazardous_check(*args, **kwargs)
  cmd_implementation('cmd_no_hazardous_check', *args, range_check: true, hazardous_check: false, raw: false, **kwargs)
end

#cmd_no_range_check(*args, **kwargs) ⇒ Object

Send a command packet to a target without performing any value range checks on the parameters. Useful for testing to allow sending command parameters outside the allowable range as defined in the configuration.



74
75
76
 
# File 'lib/openc3/api/cmd_api.rb', line 74

def cmd_no_range_check(*args, **kwargs)
  cmd_implementation('cmd_no_range_check', *args, range_check: false, hazardous_check: true, raw: false, **kwargs)
end

#cmd_raw(*args, **kwargs) ⇒ Object 



67
68
69
 
# File 'lib/openc3/api/cmd_api.rb', line 67

def cmd_raw(*args, **kwargs)
  cmd_implementation('cmd_raw', *args, range_check: true, hazardous_check: true, raw: true, **kwargs)
end

#cmd_raw_no_checks(*args, **kwargs) ⇒ Object 



96
97
98
 
# File 'lib/openc3/api/cmd_api.rb', line 96

def cmd_raw_no_checks(*args, **kwargs)
  cmd_implementation('cmd_raw_no_checks', *args, range_check: false, hazardous_check: false, raw: true, **kwargs)
end

#cmd_raw_no_hazardous_check(*args, **kwargs) ⇒ Object 



87
88
89
 
# File 'lib/openc3/api/cmd_api.rb', line 87

def cmd_raw_no_hazardous_check(*args, **kwargs)
  cmd_implementation('cmd_raw_no_hazardous_check', *args, range_check: true, hazardous_check: false, raw: true, **kwargs)
end

#cmd_raw_no_range_check(*args, **kwargs) ⇒ Object 



77
78
79
 
# File 'lib/openc3/api/cmd_api.rb', line 77

def cmd_raw_no_range_check(*args, **kwargs)
  cmd_implementation('cmd_raw_no_range_check', *args, range_check: false, hazardous_check: true, raw: true, **kwargs)
end

#connect_interface(interface_name, *interface_params, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Connects an interface and starts its telemetry gathering thread

Parameters:

  • interface_name (String) —

    The name of the interface

  • interface_params (Array) —

    Optional parameters to pass to the interface



66
67
68
69
 
# File 'lib/openc3/api/interface_api.rb', line 66

def connect_interface(interface_name, *interface_params, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', interface_name: interface_name, scope: scope, token: token)
  InterfaceTopic.connect_interface(interface_name, *interface_params, scope: scope)
end

#connect_router(router_name, *router_params, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Connects a router and starts its command gathering thread

Parameters:

  • router_name (String) —

    Name of router

  • router_params (Array) —

    Optional parameters to pass to the router



64
65
66
67
 
# File 'lib/openc3/api/router_api.rb', line 64

def connect_router(router_name, *router_params, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', router_name: router_name, scope: scope, token: token)
  RouterTopic.connect_router(router_name, *router_params, scope: scope)
end

#delete_config(tool, name, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



56
57
58
59
 
# File 'lib/openc3/api/config_api.rb', line 56

def delete_config(tool, name, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', scope: scope, token: token)
  ToolConfigModel.delete_config(tool, name, scope: scope)
end

#disable_limits(*args, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Disable limit checking for a telemetry item

Accepts two different calling styles:

disable_limits("TGT PKT ITEM")
disable_limits('TGT','PKT','ITEM')

Favor the first syntax where possible as it is more succinct.

Parameters:



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/openc3/api/limits_api.rb', line 159

def disable_limits(*args, scope: $openc3_scope, token: $openc3_token)
  target_name, packet_name, item_name = tlm_process_args(args, 'disable_limits', scope: scope)
  authorize(permission: 'tlm_set', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
  packet = TargetModel.packet(target_name, packet_name, scope: scope)
  found_item = nil
  packet['items'].each do |item|
    if item['name'] == item_name
      item['limits'].delete('enabled')
      found_item = item
      break
    end
  end
  raise "Item '#{target_name} #{packet_name} #{item_name}' does not exist" unless found_item

  TargetModel.set_packet(target_name, packet_name, packet, scope: scope)

  message = "Disabling Limits For '#{target_name} #{packet_name} #{item_name}'"
  Logger.info(message, scope: scope)

  event = { type: :LIMITS_ENABLE_STATE, target_name: target_name, packet_name: packet_name,
            item_name: item_name, enabled: false, time_nsec: Time.now.to_nsec_from_epoch, message: message }
  LimitsEventTopic.write(event, scope: scope)
end

#disable_limits_group(group_name, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Disables limits for all the items in the group

Parameters:

  • group_name (String) —

    Name of the group to disable



276
277
278
 
# File 'lib/openc3/api/limits_api.rb', line 276

def disable_limits_group(group_name, scope: $openc3_scope, token: $openc3_token)
  _limits_group(group_name, action: :disable, scope: scope, token: token)
end

#disconnect_interface(interface_name, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Disconnects from an interface and kills its telemetry gathering thread

Parameters:

  • interface_name (String) —

    The name of the interface



74
75
76
77
 
# File 'lib/openc3/api/interface_api.rb', line 74

def disconnect_interface(interface_name, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', interface_name: interface_name, scope: scope, token: token)
  InterfaceTopic.disconnect_interface(interface_name, scope: scope)
end

#disconnect_router(router_name, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Disconnects a router and kills its command gathering thread

Parameters:

  • router_name (String) —

    Name of router



72
73
74
75
 
# File 'lib/openc3/api/router_api.rb', line 72

def disconnect_router(router_name, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', router_name: router_name, scope: scope, token: token)
  RouterTopic.disconnect_router(router_name, scope: scope)
end

#enable_limits(*args, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Enable limits checking for a telemetry item

Accepts two different calling styles:

enable_limits("TGT PKT ITEM")
enable_limits('TGT','PKT','ITEM')

Favor the first syntax where possible as it is more succinct.

Parameters:



126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/openc3/api/limits_api.rb', line 126

def enable_limits(*args, scope: $openc3_scope, token: $openc3_token)
  target_name, packet_name, item_name = tlm_process_args(args, 'enable_limits', scope: scope)
  authorize(permission: 'tlm_set', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
  packet = TargetModel.packet(target_name, packet_name, scope: scope)
  found_item = nil
  packet['items'].each do |item|
    if item['name'] == item_name
      item['limits']['enabled'] = true
      found_item = item
      break
    end
  end
  raise "Item '#{target_name} #{packet_name} #{item_name}' does not exist" unless found_item

  TargetModel.set_packet(target_name, packet_name, packet, scope: scope)

  message = "Enabling Limits For '#{target_name} #{packet_name} #{item_name}'"
  Logger.info(message, scope: scope)

  event = { type: :LIMITS_ENABLE_STATE, target_name: target_name, packet_name: packet_name,
            item_name: item_name, enabled: true, time_nsec: Time.now.to_nsec_from_epoch, message: message }
  LimitsEventTopic.write(event, scope: scope)
end

#enable_limits_group(group_name, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Enables limits for all the items in the group

Parameters:

  • group_name (String) —

    Name of the group to enable



269
270
271
 
# File 'lib/openc3/api/limits_api.rb', line 269

def enable_limits_group(group_name, scope: $openc3_scope, token: $openc3_token)
  _limits_group(group_name, action: :enable, scope: scope, token: token)
end

#get_all_command_names(target_name, scope: $openc3_scope, token: $openc3_token) ⇒ Array<String>

Returns an array of all the command packet names

Parameters:

  • target_name (String) —

    Name of the target

Returns:

  • (Array<String>) —

    Array of all command packet names

Since:

  • 5.0.6



173
174
175
176
177
 
# File 'lib/openc3/api/cmd_api.rb', line 173

def get_all_command_names(target_name, scope: $openc3_scope, token: $openc3_token)
  target_name = target_name.upcase
  authorize(permission: 'cmd_info', target_name: target_name, scope: scope, token: token)
  TargetModel.packet_names(target_name, type: :CMD, scope: scope)
end

#get_all_commands(target_name, scope: $openc3_scope, token: $openc3_token) ⇒ Array<Hash>

Returns an array of all the commands as a hash

Parameters:

  • target_name (String) —

    Name of the target

Returns:

  • (Array<Hash>) —

    Array of all commands as a hash

Since:

  • 5.0.0



162
163
164
165
166
 
# File 'lib/openc3/api/cmd_api.rb', line 162

def get_all_commands(target_name, scope: $openc3_scope, token: $openc3_token)
  target_name = target_name.upcase
  authorize(permission: 'cmd_info', target_name: target_name, scope: scope, token: token)
  TargetModel.packets(target_name, type: :CMD, scope: scope)
end

#get_all_interface_info(scope: $openc3_scope, token: $openc3_token) ⇒ Array<Array<String, Numeric, Numeric, Numeric, Numeric, Numeric, Numeric, Numeric>>

Get information about all interfaces

Returns:



113
114
115
116
117
118
119
120
121
122
 
# File 'lib/openc3/api/interface_api.rb', line 113

def get_all_interface_info(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)
  info = []
  InterfaceStatusModel.all(scope: scope).each do |int_name, int|
    info << [int['name'], int['state'], int['clients'], int['txsize'], int['rxsize'],
             int['txbytes'], int['rxbytes'], int['txcnt'], int['rxcnt']]
  end
  info.sort! { |a, b| a[0] <=> b[0] }
  info
end

#get_all_router_info(scope: $openc3_scope, token: $openc3_token) ⇒ Array<Array<String, Numeric, Numeric, Numeric, Numeric, Numeric, Numeric, Numeric>>

Consolidate all router info into a single API call

Returns:



111
112
113
114
115
116
117
118
119
120
 
# File 'lib/openc3/api/router_api.rb', line 111

def get_all_router_info(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)
  info = []
  RouterStatusModel.all(scope: scope).each do |router_name, router|
    info << [router['name'], router['state'], router['clients'], router['txsize'], router['rxsize'],\
             router['txbytes'], router['rxbytes'], router['rxcnt'], router['txcnt']]
  end
  info.sort! { |a, b| a[0] <=> b[0] }
  info
end

#get_all_settings(scope: $openc3_scope, token: $openc3_token) ⇒ Object 



41
42
43
44
 
# File 'lib/openc3/api/settings_api.rb', line 41

def get_all_settings(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)
  SettingModel.all(scope: scope)
end

#get_all_target_info(scope: $openc3_scope, token: $openc3_token) ⇒ Array<Array<String, String, Numeric, Numeric>] Array of Arrays \[name, interface, cmd_cnt, tlm_cnt]

DEPRECATED: Get information about all targets Warning this call can take a long time with many defined packets

Returns:

  • (Array<Array<String, String, Numeric, Numeric>] Array of Arrays \[name, interface, cmd_cnt, tlm_cnt]) —

    Array<Array<String, String, Numeric, Numeric>] Array of Arrays [name, interface, cmd_cnt, tlm_cnt]



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/openc3/api/target_api.rb', line 79

def get_all_target_info(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)
  info = []
  get_target_names(scope: scope, token: token).each do |target_name|
    cmd_cnt = 0
    packets = TargetModel.packets(target_name, type: :CMD, scope: scope)
    packets.each do |packet|
      cmd_cnt += Topic.get_cnt("#{scope}__COMMAND__{#{target_name}}__#{packet['packet_name']}")
    end
    tlm_cnt = 0
    packets = TargetModel.packets(target_name, type: :TLM, scope: scope)
    packets.each do |packet|
      tlm_cnt += Topic.get_cnt("#{scope}__TELEMETRY__{#{target_name}}__#{packet['packet_name']}")
    end
    interface_names = []
    InterfaceModel.all(scope: scope).each do |name, interface|
      if interface['target_names'].include? target_name
        interface_names << interface['name']
      end
    end
    info << [target_name, interface_names.join(","), cmd_cnt, tlm_cnt]
  end
  info
end

#get_all_telemetry(target_name, scope: $openc3_scope, token: $openc3_token) ⇒ Array<Hash>

Returns an array of all the telemetry packet hashes

Parameters:

  • target_name (String) —

    Name of the target

Returns:

  • (Array<Hash>) —

    Array of all telemetry packet hashes

Since:

  • 5.0.0



280
281
282
283
284
 
# File 'lib/openc3/api/tlm_api.rb', line 280

def get_all_telemetry(target_name, scope: $openc3_scope, token: $openc3_token)
  target_name = target_name.upcase
  authorize(permission: 'tlm', target_name: target_name, scope: scope, token: token)
  TargetModel.packets(target_name, type: :TLM, scope: scope)
end

#get_all_telemetry_names(target_name, scope: $openc3_scope, token: $openc3_token) ⇒ Array<String>

Returns an array of all the telemetry packet names

Parameters:

  • target_name (String) —

    Name of the target

Returns:

  • (Array<String>) —

    Array of all telemetry packet names

Since:

  • 5.0.6



291
292
293
294
295
 
# File 'lib/openc3/api/tlm_api.rb', line 291

def get_all_telemetry_names(target_name, scope: $openc3_scope, token: $openc3_token)
  target_name = target_name.upcase
  authorize(permission: 'cmd_info', target_name: target_name, scope: scope, token: token)
  TargetModel.packet_names(target_name, type: :TLM, scope: scope)
end

#get_cmd_buffer(target_name, command_name, scope: $openc3_scope, token: $openc3_token) ⇒ Hash

Returns the raw buffer from the most recent specified command packet.

Parameters:

  • target_name (String) —

    Target name of the command

  • command_name (String) —

    Packet name of the command

Returns:

  • (Hash) —

    command hash with last command buffer



143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/openc3/api/cmd_api.rb', line 143

def get_cmd_buffer(target_name, command_name, scope: $openc3_scope, token: $openc3_token)
  target_name = target_name.upcase
  command_name = command_name.upcase
  authorize(permission: 'cmd_info', target_name: target_name, packet_name: command_name, scope: scope, token: token)
  TargetModel.packet(target_name, command_name, type: :CMD, scope: scope)
  topic = "#{scope}__COMMAND__{#{target_name}}__#{command_name}"
  msg_id, msg_hash = Topic.get_newest_message(topic)
  if msg_id
    msg_hash['buffer'] = msg_hash['buffer'].b
    return msg_hash
  end
  return nil
end

#get_cmd_cnt(target_name, command_name, scope: $openc3_scope, token: $openc3_token) ⇒ Numeric

Get the transmit count for a command packet

Parameters:

  • target_name (String) —

    Target name of the command

  • command_name (String) —

    Packet name of the command

Returns:

  • (Numeric) —

    Transmit count for the command



319
320
321
322
323
324
325
 
# File 'lib/openc3/api/cmd_api.rb', line 319

def get_cmd_cnt(target_name, command_name, scope: $openc3_scope, token: $openc3_token)
  target_name = target_name.upcase
  command_name = command_name.upcase
  authorize(permission: 'system', target_name: target_name, packet_name: command_name, scope: scope, token: token)
  TargetModel.packet(target_name, command_name, type: :CMD, scope: scope)
  Topic.get_cnt("#{scope}__COMMAND__{#{target_name}}__#{command_name}")
end

#get_cmd_cnts(target_commands, scope: $openc3_scope, token: $openc3_token) ⇒ Numeric

Get the transmit counts for command packets

Parameters:

Returns:

  • (Numeric) —

    Transmit count for the command



331
332
333
334
335
336
337
338
339
340
 
# File 'lib/openc3/api/cmd_api.rb', line 331

def get_cmd_cnts(target_commands, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)
  counts = []
  target_commands.each do |target_name, command_name|
    target_name = target_name.upcase
    command_name = command_name.upcase
    counts << Topic.get_cnt("#{scope}__COMMAND__{#{target_name}}__#{command_name}")
  end
  counts
end

#get_cmd_hazardous(*args, scope: $openc3_scope, token: $openc3_token, **kwargs) ⇒ Boolean

Returns whether the specified command is hazardous

Accepts two different calling styles:

get_cmd_hazardous("TGT CMD with PARAM1 val, PARAM2 val")
get_cmd_hazardous('TGT','CMD',{'PARAM1'=>val,'PARAM2'=>val})

Parameters:

Returns:

  • (Boolean) —

    Whether the command is hazardous



215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/openc3/api/cmd_api.rb', line 215

def get_cmd_hazardous(*args, scope: $openc3_scope, token: $openc3_token, **kwargs)
  extract_string_kwargs_to_args(args, kwargs)
  case args.length
  when 1
    target_name, command_name, parameters = extract_fields_from_cmd_text(args[0], scope: scope)
  when 2, 3
    target_name = args[0]
    command_name = args[1]
    if args.length == 2
      parameters = {}
    else
      parameters = args[2]
    end
  else
    # Invalid number of arguments
    raise "ERROR: Invalid number of arguments (#{args.length}) passed to get_cmd_hazardous()"
  end
  target_name = target_name.upcase
  command_name = command_name.upcase
  parameters = parameters.transform_keys(&:upcase)

  authorize(permission: 'cmd_info', target_name: target_name, packet_name: command_name, scope: scope, token: token)
  packet = TargetModel.packet(target_name, command_name, type: :CMD, scope: scope)
  return true if packet['hazardous']

  packet['items'].each do |item|
    next unless parameters.keys.include?(item['name']) && item['states']

    # States are an array of the name followed by a hash of 'value' and sometimes 'hazardous'
    item['states'].each do |name, hash|
      parameter_name = parameters[item['name']]
      # Remove quotes from string parameters
      parameter_name = parameter_name.gsub('"', '').gsub("'", '') if parameter_name.is_a?(String)
      # To be hazardous the state must be marked hazardous
      # Check if either the state name or value matches the param passed
      if hash['hazardous'] && (name == parameter_name || hash['value'] == parameter_name)
        return true
      end
    end
  end

  false
end

#get_cmd_time(target_name = nil, command_name = nil, scope: $openc3_scope, token: $openc3_token) ⇒ Array<Target Name, Command Name, Time Seconds, Time Microseconds>

Returns the time the most recent command was sent

Parameters:

  • target_name (String) (defaults to: nil) —

    Target name of the command. If not given then the most recent time from all commands will be returned

  • command_name (String) (defaults to: nil) —

    Packet name of the command. If not given then then most recent time from the given target will be returned.

Returns:



282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
 
# File 'lib/openc3/api/cmd_api.rb', line 282

def get_cmd_time(target_name = nil, command_name = nil, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'cmd_info', target_name: target_name, packet_name: command_name, scope: scope, token: token)
  if target_name and command_name
    target_name = target_name.upcase
    command_name = command_name.upcase
    time = CommandDecomTopic.get_cmd_item(target_name, command_name, 'RECEIVED_TIMESECONDS', type: :CONVERTED, scope: scope)
    [target_name, command_name, time.to_i, ((time.to_f - time.to_i) * 1_000_000).to_i]
  else
    if target_name.nil?
      targets = TargetModel.names(scope: scope)
    else
      target_name = target_name.upcase
      targets = [target_name]
    end
    targets.each do |target_name|
      time = 0
      command_name = nil
      TargetModel.packets(target_name, type: :CMD, scope: scope).each do |packet|
        cur_time = CommandDecomTopic.get_cmd_item(target_name, packet["packet_name"], 'RECEIVED_TIMESECONDS', type: :CONVERTED, scope: scope)
        next unless cur_time

        if cur_time > time
          time = cur_time
          command_name = packet["packet_name"]
        end
      end
      target_name = nil unless command_name
      return [target_name, command_name, time.to_i, ((time.to_f - time.to_i) * 1_000_000).to_i]
    end
  end
end

#get_cmd_value(target_name, command_name, parameter_name, value_type = :CONVERTED, scope: $openc3_scope, token: $openc3_token) ⇒ Varies

Returns a value from the specified command

Parameters:

  • target_name (String) —

    Target name of the command

  • command_name (String) —

    Packet name of the command

  • parameter_name (String) —

    Parameter name in the command

  • value_type (Symbol) (defaults to: :CONVERTED) —

    How the values should be converted. Must be one of Packet::VALUE_TYPES

Returns:

  • (Varies) —

    value



267
268
269
270
271
272
273
 
# File 'lib/openc3/api/cmd_api.rb', line 267

def get_cmd_value(target_name, command_name, parameter_name, value_type = :CONVERTED, scope: $openc3_scope, token: $openc3_token)
  target_name = target_name.upcase
  command_name = command_name.upcase
  parameter_name = parameter_name.upcase
  authorize(permission: 'cmd_info', target_name: target_name, packet_name: command_name, scope: scope, token: token)
  CommandDecomTopic.get_cmd_item(target_name, command_name, parameter_name, type: value_type, scope: scope)
end

#get_command(target_name, command_name, scope: $openc3_scope, token: $openc3_token) ⇒ Hash

Returns a hash of the given command

Parameters:

  • target_name (String) —

    Name of the target

  • command_name (String) —

    Name of the packet

Returns:

  • (Hash) —

    Command as a hash

Since:

  • 5.0.0



185
186
187
188
189
190
 
# File 'lib/openc3/api/cmd_api.rb', line 185

def get_command(target_name, command_name, scope: $openc3_scope, token: $openc3_token)
  target_name = target_name.upcase
  command_name = command_name.upcase
  authorize(permission: 'cmd_info', target_name: target_name, scope: scope, token: token)
  TargetModel.packet(target_name, command_name, type: :CMD, scope: scope)
end

#get_interface(interface_name, scope: $openc3_scope, token: $openc3_token) ⇒ Hash

Get information about an interface

Parameters:

  • interface_name (String) —

    Interface name

Returns:

  • (Hash) —

    Hash of all the interface information

Since:

  • 5.0.0



48
49
50
51
52
53
54
 
# File 'lib/openc3/api/interface_api.rb', line 48

def get_interface(interface_name, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', interface_name: interface_name, scope: scope, token: token)
  interface = InterfaceModel.get(name: interface_name, scope: scope)
  raise "Interface '#{interface_name}' does not exist" unless interface

  interface.merge(InterfaceStatusModel.get(name: interface_name, scope: scope))
end

#get_interface_names(scope: $openc3_scope, token: $openc3_token) ⇒ Array<String>

Returns All the interface names.

Returns:



57
58
59
60
 
# File 'lib/openc3/api/interface_api.rb', line 57

def get_interface_names(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)
  InterfaceModel.names(scope: scope)
end

#get_item(target_name, packet_name, item_name, scope: $openc3_scope, token: $openc3_token) ⇒ Hash

Returns a telemetry packet item hash

Parameters:

  • target_name (String) —

    Name of the target

  • packet_name (String) —

    Name of the packet

  • item_name (String) —

    Name of the packet

Returns:

  • (Hash) —

    Telemetry packet item hash

Since:

  • 5.0.0



317
318
319
320
321
322
323
 
# File 'lib/openc3/api/tlm_api.rb', line 317

def get_item(target_name, packet_name, item_name, scope: $openc3_scope, token: $openc3_token)
  target_name = target_name.upcase
  packet_name = packet_name.upcase
  item_name = item_name.upcase
  authorize(permission: 'tlm', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
  TargetModel.packet_item(target_name, packet_name, item_name, scope: scope)
end

#get_limits(target_name, packet_name, item_name, scope: $openc3_scope, token: $openc3_token) ⇒ Hash{String => Array<Number, Number, Number, Number, Number, Number>}

Get a Hash of all the limits sets defined for an item. Hash keys are the limit set name in uppercase (note there is always a DEFAULT) and the value is an array of limit values: red low, yellow low, yellow high, red high, <green low, green high>. Green low and green high are optional.

For example: {‘DEFAULT’ => [-80, -70, 60, 80, -20, 20],

'TVAC' => [-25, -10, 50, 55] }

Returns:



192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/openc3/api/limits_api.rb', line 192

def get_limits(target_name, packet_name, item_name, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
  limits = {}
  item = _get_item(target_name, packet_name, item_name, scope: scope)
  item['limits'].each do |key, vals|
    next unless vals.is_a?(Hash)

    limits[key] = [vals['red_low'], vals['yellow_low'], vals['yellow_high'], vals['red_high']]
    limits[key].concat([vals['green_low'], vals['green_high']]) if vals['green_low']
  end
  return limits
end

#get_limits_events(offset = nil, count: 100, scope: $openc3_scope, token: $openc3_token) ⇒ Hash, Integer

Returns limits events starting at the provided offset. Passing nil for an offset will return the last received limits event and associated offset.

Parameters:

  • offset (Integer) (defaults to: nil) —

    Offset to start reading limits events. Nil to return the last received limits event (if any).

  • count (Integer) (defaults to: 100) —

    The total number of events returned. Default is 100.

Returns:

  • (Hash, Integer) —

    Event hash followed by the offset. The offset can be used in subsequent calls to return events from where the last call left off.



315
316
317
318
 
# File 'lib/openc3/api/limits_api.rb', line 315

def get_limits_events(offset = nil, count: 100, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm', scope: scope, token: token)
  LimitsEventTopic.read(offset, count: count, scope: scope)
end

#get_limits_groups(scope: $openc3_scope, token: $openc3_token) ⇒ Hash{String => Array<Array<String, String, String>>]

Returns all limits_groups and their members

Returns:

Since:

  • 5.0.0 Returns hash with values



261
262
263
264
 
# File 'lib/openc3/api/limits_api.rb', line 261

def get_limits_groups(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm', scope: scope, token: token)
  TargetModel.limits_groups(scope: scope)
end

#get_limits_set(scope: $openc3_scope, token: $openc3_token) ⇒ String

Returns the active limits set that applies to all telemetry

Returns:

  • (String) —

    The current limits set



302
303
304
305
 
# File 'lib/openc3/api/limits_api.rb', line 302

def get_limits_set(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm', scope: scope, token: token)
  LimitsEventTopic.current_set(scope: scope)
end

#get_limits_sets(scope: $openc3_scope, token: $openc3_token) ⇒ Array<String>

Returns all defined limits sets

Returns:



283
284
285
286
 
# File 'lib/openc3/api/limits_api.rb', line 283

def get_limits_sets(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm', scope: scope, token: token)
  LimitsEventTopic.sets(scope: scope).keys
end

#get_metrics(scope: $openc3_scope, token: $openc3_token) ⇒ Object 



62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/openc3/api/metrics_api.rb', line 62

def get_metrics(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)

  sum_metrics = SUM_METRICS.dup
  duration_metrics = DURATION_METRICS.dup
  delay_metrics = DELAY_METRICS.dup

  metrics = MetricModel.all(scope: scope)
  metrics.each do |microservice_name, metrics|
    next unless metrics and metrics['values']
    metrics['values'].each do |metric_name, data|
      value = data['value']
      if sum_metrics[metric_name]
        sum_metrics[metric_name] += value
      elsif duration_metrics[metric_name]
        previous = duration_metrics[metric_name]
        duration_metrics[metric_name] = value if value > previous
      elsif delay_metrics.include?(metric_name)
        previous = delay_metrics[metric_name]
        delay_metrics[metric_name] = value if value > previous
      else
        # Ignore other metrics for now
      end
    end
  end

  result = delay_metrics
  result.merge!(duration_metrics)
  result.merge!(sum_metrics)

  result.merge!(MetricModel.redis_metrics)

  return result
end

#get_out_of_limits(scope: $openc3_scope, token: $openc3_token) ⇒ Array<Array<String, String, String, String>>

Return an array of arrays indicating all items in the packet that are out of limits

[[target name, packet name, item name, item limits state], ...]

Returns:



50
51
52
53
 
# File 'lib/openc3/api/limits_api.rb', line 50

def get_out_of_limits(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm', scope: scope, token: token)
  LimitsEventTopic.out_of_limits(scope: scope)
end

#get_overall_limits_state(ignored_items = nil, scope: $openc3_scope, token: $openc3_token) ⇒ String

Get the overall limits state which is the worse case of all limits items. For example if any limits are YELLOW_LOW or YELLOW_HIGH then the overall limits state is YELLOW. If a single limit item then turns RED_HIGH the overall limits state is RED.

Parameters:

  • ignored_items (Array<Array<String, String, String|nil>>) (defaults to: nil) —

    Array of [TGT, PKT, ITEM] strings to ignore when determining overall state. Note, ITEM can be nil to indicate to ignore entire packet.

Returns:

  • (String) —

    The overall limits state for the system, one of 'GREEN', 'YELLOW', 'RED'



62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/openc3/api/limits_api.rb', line 62

def get_overall_limits_state(ignored_items = nil, scope: $openc3_scope, token: $openc3_token)
  # We only need to check out of limits items so call get_out_of_limits() which authorizes
  out_of_limits = get_out_of_limits(scope: scope, token: token)
  overall = 'GREEN'

  # Build easily matchable ignore list
  if ignored_items
    ignored_items.map! do |item|
      raise "Invalid ignored item: #{item}. Must be [TGT, PKT, ITEM] where ITEM can be nil." if item.length != 3

      item.join('__')
    end
  else
    ignored_items = []
  end

  out_of_limits.each do |target_name, packet_name, item_name, limits_state|
    # Ignore this item if we match one of the ignored items. Checking against /^#{item}/
    # allows us to detect matches against a TGT__PKT__ with no item defined.
    next if ignored_items.detect { |item| "#{target_name}__#{packet_name}__#{item_name}" =~ /^#{item}/ }

    if limits_state == 'RED' || limits_state == 'RED_HIGH' || limits_state == 'RED_LOW'
      overall = limits_state
      break # Red is as high as we go so no need to look for more
    end

    case overall
      # If our overall state is currently blue or green we can go to any state
    when 'BLUE', 'GREEN', 'GREEN_HIGH', 'GREEN_LOW'
      overall = limits_state
    # else YELLOW - Stay at YELLOW until we find a red
    end
  end
  overall = 'GREEN' if overall == 'GREEN_HIGH' || overall == 'GREEN_LOW' || overall == 'BLUE'
  overall = 'YELLOW' if overall == 'YELLOW_HIGH' || overall == 'YELLOW_LOW'
  overall = 'RED' if overall == 'RED_HIGH' || overall == 'RED_LOW'
  return overall
end

#get_overrides(scope: $openc3_scope, token: $openc3_token) ⇒ Object

Get the list of CVT overrides



178
179
180
181
 
# File 'lib/openc3/api/tlm_api.rb', line 178

def get_overrides(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm', scope: scope, token: token)
  CvtModel.overrides(scope: scope)
end

#get_packet_derived_items(target_name, packet_name, scope: $openc3_scope, token: $openc3_token) ⇒ Array<String>

Get the list of derived telemetry items for a packet

Parameters:

  • target_name (String) —

    Target name

  • packet_name (String) —

    Packet name

Returns:

  • (Array<String>) —

    All of the ignored telemetry items for a packet.



409
410
411
412
413
414
415
 
# File 'lib/openc3/api/tlm_api.rb', line 409

def get_packet_derived_items(target_name, packet_name, scope: $openc3_scope, token: $openc3_token)
  target_name = target_name.upcase
  packet_name = packet_name.upcase
  authorize(permission: 'tlm', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
  packet = TargetModel.packet(target_name, packet_name, scope: scope)
  return packet['items'].select { |item| item['data_type'] == 'DERIVED' }.map { |item| item['name'] }
end

#get_packets(id, block: nil, count: 1000, scope: $openc3_scope, token: $openc3_token) ⇒ Array<String, Array<Hash>] Array of the ID and array of all packets found

Get packets based on ID returned from subscribe_packet.

Parameters:

  • id (String) —

    ID returned from subscribe_packets or last call to get_packets

  • block (Integer) (defaults to: nil) —

    Unused - Blocking must be implemented at the client

  • count (Integer) (defaults to: 1000) —

    Maximum number of packets to return from EACH packet stream

Returns:

  • (Array<String, Array<Hash>] Array of the ID and array of all packets found) —

    Array<String, Array<Hash>] Array of the ID and array of all packets found



357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
 
# File 'lib/openc3/api/tlm_api.rb', line 357

def get_packets(id, block: nil, count: 1000, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm', scope: scope, token: token)
  # Split the list of topic, ID values and turn it into a hash for easy updates
  lookup = Hash[*id.split(SUBSCRIPTION_DELIMITER)]
  xread = Topic.read_topics(lookup.keys, lookup.values, nil, count) # Always don't block
  # Return the original ID and and empty array if we didn't get anything
  packets = []
  return [id, packets] if xread.empty?
  xread.each do |topic, data|
    data.each do |id, msg_hash|
      lookup[topic] = id # save the new ID
      json_hash = JSON.parse(msg_hash['json_data'], :allow_nan => true, :create_additions => true)
      msg_hash.delete('json_data')
      packets << msg_hash.merge(json_hash)
    end
  end
  return lookup.to_a.join(SUBSCRIPTION_DELIMITER), packets
end

#get_parameter(target_name, command_name, parameter_name, scope: $openc3_scope, token: $openc3_token) ⇒ Hash

Returns a hash of the given command parameter

Parameters:

  • target_name (String) —

    Name of the target

  • command_name (String) —

    Name of the packet

  • parameter_name (String) —

    Name of the parameter

Returns:

  • (Hash) —

    Command parameter as a hash

Since:

  • 5.0.0



199
200
201
202
203
204
205
 
# File 'lib/openc3/api/cmd_api.rb', line 199

def get_parameter(target_name, command_name, parameter_name, scope: $openc3_scope, token: $openc3_token)
  target_name = target_name.upcase
  command_name = command_name.upcase
  parameter_name = parameter_name.upcase
  authorize(permission: 'cmd_info', target_name: target_name, packet_name: command_name, scope: scope, token: token)
  TargetModel.packet_item(target_name, command_name, parameter_name, type: :CMD, scope: scope)
end

#get_router(router_name, scope: $openc3_scope, token: $openc3_token) ⇒ Hash

Get information about a router

Parameters:

  • router_name (String) —

    Router name

Returns:

  • (Hash) —

    Hash of all the router information



46
47
48
49
50
51
52
 
# File 'lib/openc3/api/router_api.rb', line 46

def get_router(router_name, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', router_name: router_name, scope: scope, token: token)
  router = RouterModel.get(name: router_name, scope: scope)
  raise "Router '#{router_name}' does not exist" unless router

  router.merge(RouterStatusModel.get(name: router_name, scope: scope))
end

#get_router_names(scope: $openc3_scope, token: $openc3_token) ⇒ Array<String>

Returns All the router names.

Returns:



55
56
57
58
 
# File 'lib/openc3/api/router_api.rb', line 55

def get_router_names(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)
  RouterModel.names(scope: scope)
end

#get_saved_config(configuration_name = nil, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Get a saved configuration zip file



37
38
39
 
# File 'lib/openc3/api/config_api.rb', line 37

def get_saved_config(configuration_name = nil, scope: $openc3_scope, token: $openc3_token)
  raise "Not supported by OpenC3 5"
end

#get_setting(name, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



46
47
48
49
50
51
52
53
54
 
# File 'lib/openc3/api/settings_api.rb', line 46

def get_setting(name, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)
  setting = SettingModel.get(name: name, scope: scope)
  if setting
    setting['data']
  else
    nil
  end
end

#get_settings(*settings, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



56
57
58
59
60
61
 
# File 'lib/openc3/api/settings_api.rb', line 56

def get_settings(*settings, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)
  result = []
  settings.each { |name| result << get_setting(name, scope: scope, token: token) }
  result
end

#get_target(target_name, scope: $openc3_scope, token: $openc3_token) ⇒ Hash

Gets the full target hash

Parameters:

  • target_name (String) —

    Target name

Returns:

  • (Hash) —

    Hash of all the target properties

Since:

  • 5.0.0



51
52
53
54
 
# File 'lib/openc3/api/target_api.rb', line 51

def get_target(target_name, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', target_name: target_name, scope: scope, token: token)
  TargetModel.get(name: target_name, scope: scope)
end

#get_target_interfaces(scope: $openc3_scope, token: $openc3_token) ⇒ Array<Array<String, String] Array of Arrays \[name, interfaces]

Get all targets and their interfaces

Returns:



59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/openc3/api/target_api.rb', line 59

def get_target_interfaces(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)
  info = []
  interfaces = InterfaceModel.all(scope: scope)
  get_target_names(scope: scope, token: token).each do |target_name|
    interface_names = []
    interfaces.each do |name, interface|
      if interface['target_names'].include? target_name
        interface_names << interface['name']
      end
    end
    info << [target_name, interface_names.join(",")]
  end
  info
end

#get_target_names(scope: $openc3_scope, token: $openc3_token) ⇒ Array<String> Also known as: get_target_list

Returns the list of all target names

Returns:



39
40
41
42
 
# File 'lib/openc3/api/target_api.rb', line 39

def get_target_names(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm', scope: scope, token: token)
  TargetModel.names(scope: scope)
end

#get_telemetry(target_name, packet_name, scope: $openc3_scope, token: $openc3_token) ⇒ Hash

Returns a telemetry packet hash

Parameters:

  • target_name (String) —

    Name of the target

  • packet_name (String) —

    Name of the packet

Returns:

  • (Hash) —

    Telemetry packet hash

Since:

  • 5.0.0



303
304
305
306
307
308
 
# File 'lib/openc3/api/tlm_api.rb', line 303

def get_telemetry(target_name, packet_name, scope: $openc3_scope, token: $openc3_token)
  target_name = target_name.upcase
  packet_name = packet_name.upcase
  authorize(permission: 'tlm', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
  TargetModel.packet(target_name, packet_name, scope: scope)
end

#get_tlm_buffer(target_name, packet_name, scope: $openc3_scope, token: $openc3_token) ⇒ Hash

Returns the raw buffer for a telemetry packet.

Parameters:

  • target_name (String) —

    Name of the target

  • packet_name (String) —

    Name of the packet

Returns:

  • (Hash) —

    telemetry hash with last telemetry buffer



207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/openc3/api/tlm_api.rb', line 207

def get_tlm_buffer(target_name, packet_name, scope: $openc3_scope, token: $openc3_token)
  target_name = target_name.upcase
  packet_name = packet_name.upcase
  authorize(permission: 'tlm', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
  TargetModel.packet(target_name, packet_name, scope: scope)
  topic = "#{scope}__TELEMETRY__{#{target_name}}__#{packet_name}"
  msg_id, msg_hash = Topic.get_newest_message(topic)
  if msg_id
    msg_hash['buffer'] = msg_hash['buffer'].b
    return msg_hash
  end
  return nil
end

#get_tlm_cnt(target_name, packet_name, scope: $openc3_scope, token: $openc3_token) ⇒ Numeric

Get the receive count for a telemetry packet

Parameters:

  • target_name (String) —

    Name of the target

  • packet_name (String) —

    Name of the packet

Returns:

  • (Numeric) —

    Receive count for the telemetry packet



381
382
383
384
385
386
387
 
# File 'lib/openc3/api/tlm_api.rb', line 381

def get_tlm_cnt(target_name, packet_name, scope: $openc3_scope, token: $openc3_token)
  target_name = target_name.upcase
  packet_name = packet_name.upcase
  authorize(permission: 'system', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
  TargetModel.packet(target_name, packet_name, scope: scope)
  Topic.get_cnt("#{scope}__TELEMETRY__{#{target_name}}__#{packet_name}")
end

#get_tlm_cnts(target_packets, scope: $openc3_scope, token: $openc3_token) ⇒ Numeric

Get the transmit counts for telemetry packets

Parameters:

Returns:

  • (Numeric) —

    Transmit count for the command



393
394
395
396
397
398
399
400
401
402
 
# File 'lib/openc3/api/tlm_api.rb', line 393

def get_tlm_cnts(target_packets, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)
  counts = []
  target_packets.each do |target_name, packet_name|
    target_name = target_name.upcase
    packet_name = packet_name.upcase
    counts << Topic.get_cnt("#{scope}__TELEMETRY__{#{target_name}}__#{packet_name}")
  end
  counts
end

#get_tlm_packet(target_name, packet_name, stale_time: 30, type: :CONVERTED, cache_timeout: 0.1, scope: $openc3_scope, token: $openc3_token) ⇒ Array<String, Object, Symbol|nil>

Returns all the values (along with their limits state) for a packet.

Parameters:

  • target_name (String) —

    Name of the target

  • packet_name (String) —

    Name of the packet

  • stale_time (Integer) (defaults to: 30) —

    Time in seconds from Time.now that packet will be marked stale

  • type (Symbol) (defaults to: :CONVERTED) —

    Types returned, :RAW, :CONVERTED (default), :FORMATTED, or :WITH_UNITS

Returns:

  • (Array<String, Object, Symbol|nil>) —

    Returns an Array consisting of [item name, item value, item limits state] where the item limits state can be one of Limits::LIMITS_STATES

Raises:

  • (ArgumentError) 


230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/openc3/api/tlm_api.rb', line 230

def get_tlm_packet(target_name, packet_name, stale_time: 30, type: :CONVERTED, cache_timeout: 0.1, scope: $openc3_scope, token: $openc3_token)
  target_name = target_name.upcase
  packet_name = packet_name.upcase
  authorize(permission: 'tlm', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
  packet = TargetModel.packet(target_name, packet_name, scope: scope)
  t = _validate_tlm_type(type)
  raise ArgumentError, "Unknown type '#{type}' for #{target_name} #{packet_name}" if t.nil?
  items = packet['items'].map { | item | item['name'].upcase }
  cvt_items = items.map { | item | [target_name, packet_name, item, type] }
  current_values = CvtModel.get_tlm_values(cvt_items, stale_time: stale_time, cache_timeout: cache_timeout, scope: scope)
  items.zip(current_values).map { | item , values | [item, values[0], values[1]]}
end

#get_tlm_values(items, stale_time: 30, cache_timeout: 0.1, scope: $openc3_scope, token: $openc3_token) ⇒ Array<Object, Symbol>

Returns all the item values (along with their limits state). The items can be from any target and packet and thus must be fully qualified with their target and packet names.

Parameters:

  • items (Array<String>) —

    Array of items consisting of 'tgt__pkt__item__type'

  • stale_time (Integer) (defaults to: 30) —

    Time in seconds from Time.now that data will be marked stale

Returns:

  • (Array<Object, Symbol>) —

    Array consisting of the item value and limits state given as symbols such as :RED, :YELLOW, :STALE

Since:

  • 5.0.0



253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/openc3/api/tlm_api.rb', line 253

def get_tlm_values(items, stale_time: 30, cache_timeout: 0.1, scope: $openc3_scope, token: $openc3_token)
  if !items.is_a?(Array) || !items[0].is_a?(String)
    raise ArgumentError, "items must be array of strings: ['TGT__PKT__ITEM__TYPE', ...]"
  end
  packets = []
  cvt_items = []
  items.each_with_index do |item, index|
    item_upcase = item.to_s.upcase
    target_name, packet_name, item_name, value_type = item_upcase.split('__')
    raise ArgumentError, "items must be formatted as TGT__PKT__ITEM__TYPE" if target_name.nil? || packet_name.nil? || item_name.nil? || value_type.nil?
    packet_name = CvtModel.determine_latest_packet_for_item(target_name, item_name, cache_timeout: cache_timeout, scope: scope) if packet_name == 'LATEST'
    # Change packet_name in case of LATEST and ensure upcase
    cvt_items[index] = [target_name, packet_name, item_name, value_type]
    packets << [target_name, packet_name]
  end
  packets.uniq!
  packets.each do |target_name, packet_name|
    authorize(permission: 'tlm', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
  end
  CvtModel.get_tlm_values(cvt_items, stale_time: stale_time, cache_timeout: cache_timeout, scope: scope)
end

#inject_tlm(target_name, packet_name, item_hash = nil, type: :CONVERTED, scope: $openc3_scope, token: $openc3_token) ⇒ Object

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

Parameters:

  • target_name (String) —

    Target name of the packet

  • packet_name (String) —

    Packet name of the packet

  • item_hash (Hash) (defaults to: nil) —

    Hash of item_name and value for each item you want to change from the current value table

  • type (Symbol) (defaults to: :CONVERTED) —

    Telemetry type, :RAW, :CONVERTED (default), :FORMATTED, or :WITH_UNITS



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/openc3/api/tlm_api.rb', line 122

def inject_tlm(target_name, packet_name, item_hash = nil, type: :CONVERTED, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm_set', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
  type = type.to_s.intern
  target_name = target_name.upcase
  packet_name = packet_name.upcase
  unless CvtModel::VALUE_TYPES.include?(type)
    raise "Unknown type '#{type}' for #{target_name} #{packet_name}"
  end

  if item_hash
    item_hash = item_hash.transform_keys(&:upcase)
    # Check that the items exist ... exceptions are raised if not
    TargetModel.packet_items(target_name, packet_name, item_hash.keys, scope: scope)
  else
    # Check that the packet exists ... exceptions are raised if not
    TargetModel.packet(target_name, packet_name, scope: scope)
  end

  # See if this target has a tlm interface
  interface_name = nil
  InterfaceModel.all(scope: scope).each do |name, interface|
    if interface['tlm_target_names'].include? target_name
      interface_name = interface['name']
      break
    end
  end

  # Use an interface microservice if it exists, other use the decom microservice
  if interface_name
    InterfaceTopic.inject_tlm(interface_name, target_name, packet_name, item_hash, type: type, scope: scope)
  else
    DecomInterfaceTopic.inject_tlm(target_name, packet_name, item_hash, type: type, scope: scope)
  end
end

#interface_cmd(interface_name, cmd_name, *cmd_params, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



145
146
147
148
 
# File 'lib/openc3/api/interface_api.rb', line 145

def interface_cmd(interface_name, cmd_name, *cmd_params, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', interface_name: interface_name, scope: scope, token: token)
  InterfaceTopic.interface_cmd(interface_name, cmd_name, *cmd_params, scope: scope)
end

#interface_protocol_cmd(interface_name, cmd_name, *cmd_params, read_write: :READ_WRITE, index: -1,, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



150
151
152
153
 
# File 'lib/openc3/api/interface_api.rb', line 150

def interface_protocol_cmd(interface_name, cmd_name, *cmd_params, read_write: :READ_WRITE, index: -1, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', interface_name: interface_name, scope: scope, token: token)
  InterfaceTopic.protocol_cmd(interface_name, cmd_name, *cmd_params, read_write: read_write, index: index, scope: scope)
end

#limits_enabled?(*args, scope: $openc3_scope, token: $openc3_token) ⇒ Boolean

Whether the limits are enabled for the given item

Accepts two different calling styles:

limits_enabled?("TGT PKT ITEM")
limits_enabled?('TGT','PKT','ITEM')

Favor the first syntax where possible as it is more succinct.

Parameters:

Returns:

  • (Boolean) —

    Whether limits are enable for the itme



111
112
113
114
115
 
# File 'lib/openc3/api/limits_api.rb', line 111

def limits_enabled?(*args, scope: $openc3_scope, token: $openc3_token)
  target_name, packet_name, item_name = tlm_process_args(args, 'limits_enabled?', scope: scope)
  authorize(permission: 'tlm', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
  return TargetModel.packet_item(target_name, packet_name, item_name, scope: scope)['limits']['enabled'] ? true : false
end

#list_configs(tool, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



41
42
43
44
 
# File 'lib/openc3/api/config_api.rb', line 41

def list_configs(tool, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)
  ToolConfigModel.list_configs(tool, scope: scope)
end

#list_settings(scope: $openc3_scope, token: $openc3_token) ⇒ Object 



36
37
38
39
 
# File 'lib/openc3/api/settings_api.rb', line 36

def list_settings(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)
  SettingModel.names(scope: scope)
end

#load_config(tool, name, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



46
47
48
49
 
# File 'lib/openc3/api/config_api.rb', line 46

def load_config(tool, name, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)
  ToolConfigModel.load_config(tool, name, scope: scope)
end

#map_target_to_interface(target_name, interface_name, cmd_only: false, tlm_only: false, unmap_old: true, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Associates a target and all its commands and telemetry with a particular interface. All the commands will go out over and telemetry be received from that interface.

Parameters:

  • target_name (String/Array) —

    The name of the target(s)

  • interface_name (String) —

    The name of the interface



130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/openc3/api/interface_api.rb', line 130

def map_target_to_interface(target_name, interface_name, cmd_only: false, tlm_only: false, unmap_old: true, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', interface_name: interface_name, scope: scope, token: token)
  new_interface = InterfaceModel.get_model(name: interface_name, scope: scope)
  if Array === target_name
    target_names = target_name
  else
    target_names = [target_name]
  end
  target_names.each do |name|
    new_interface.map_target(name, cmd_only: cmd_only, tlm_only: tlm_only, unmap_old: unmap_old)
    Logger.info("Target #{name} mapped to Interface #{interface_name}", scope: scope)
  end
  nil
end

#normalize_tlm(*args, type: :ALL, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Normalize a telemetry item in a packet to its default behavior. Called after override_tlm to restore standard processing.

Accepts two different calling styles:

normalize_tlm("TGT PKT ITEM")
normalize_tlm('TGT','PKT','ITEM')

Favor the first syntax where possible as it is more succinct.

Parameters:

  • args —

    The args must either be a string or three strings (see the calling style in the description).

  • type (Symbol) (defaults to: :ALL) —

    Telemetry type, :ALL (default), :RAW, :CONVERTED, :FORMATTED, :WITH_UNITS Also takes :ALL which means to normalize all telemetry types



196
197
198
199
200
 
# File 'lib/openc3/api/tlm_api.rb', line 196

def normalize_tlm(*args, type: :ALL, scope: $openc3_scope, token: $openc3_token)
  target_name, packet_name, item_name = tlm_process_args(args, __method__, scope: scope)
  authorize(permission: 'tlm_set', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
  CvtModel.normalize(target_name, packet_name, item_name, type: type.intern, scope: scope)
end

#offline_access_needed(scope: $openc3_scope, token: $openc3_token) ⇒ Object 



30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/openc3/api/offline_access_api.rb', line 30

def offline_access_needed(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)
  begin
    authorize(permission: 'script_run', scope: scope, token: token)
  rescue
    # Not needed if can't run scripts
    return false
  end
  info = (token)
  if info['roles'].to_s.include?("offline_access")
    username = info['username']
    if username and username != ''
      model = OfflineAccessModel.get_model(name: username, scope: scope)
      if model and model.offline_access_token
        auth = OpenC3KeycloakAuthentication.new(ENV['OPENC3_KEYCLOAK_URL'])
        valid_token = auth.get_token_from_refresh_token(model.offline_access_token)
        if valid_token
          return false
        else
          model.offline_access_token = nil
          model.update
          return true
        end
      end
      return true
    else
      return false
    end
  else
    return false
  end
end

#override_tlm(*args, type: :ALL, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Override the current value table such that a particular item always returns the same value (for a given type) even when new telemetry packets are received from the target.

Accepts two different calling styles:

override_tlm("TGT PKT ITEM = 1.0")
override_tlm('TGT','PKT','ITEM', 10.0)

Favor the first syntax where possible as it is more succinct.

Parameters:

  • args —

    The args must either be a string followed by a value or three strings followed by a value (see the calling style in the description).

  • type (Symbol) (defaults to: :ALL) —

    Telemetry type, :ALL (default), :RAW, :CONVERTED, :FORMATTED, :WITH_UNITS



171
172
173
174
175
 
# File 'lib/openc3/api/tlm_api.rb', line 171

def override_tlm(*args, type: :ALL, scope: $openc3_scope, token: $openc3_token)
  target_name, packet_name, item_name, value = set_tlm_process_args(args, __method__, scope: scope)
  authorize(permission: 'tlm_set', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
  CvtModel.override(target_name, packet_name, item_name, value, type: type.intern, scope: scope)
end

#router_cmd(router_name, cmd_name, *cmd_params, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



122
123
124
125
 
# File 'lib/openc3/api/router_api.rb', line 122

def router_cmd(router_name, cmd_name, *cmd_params, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', router_name: router_name, scope: scope, token: token)
  RouterTopic.router_cmd(router_name, cmd_name, *cmd_params, scope: scope)
end

#router_protocol_cmd(router_name, cmd_name, *cmd_params, read_write: :READ_WRITE, index: -1,, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



127
128
129
130
 
# File 'lib/openc3/api/router_api.rb', line 127

def router_protocol_cmd(router_name, cmd_name, *cmd_params, read_write: :READ_WRITE, index: -1, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', router_name: router_name, scope: scope, token: token)
  RouterTopic.protocol_cmd(router_name, cmd_name, *cmd_params, read_write: read_write, index: index, scope: scope)
end

#save_config(tool, name, data, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



51
52
53
54
 
# File 'lib/openc3/api/config_api.rb', line 51

def save_config(tool, name, data, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', scope: scope, token: token)
  ToolConfigModel.save_config(tool, name, data, scope: scope)
end

#save_setting(name, data, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



63
64
65
66
67
 
# File 'lib/openc3/api/settings_api.rb', line 63

def save_setting(name, data, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'admin', scope: scope, token: token)
  SettingModel.set({ name: name, data: data }, scope: scope)
  LocalMode.save_setting(scope, name, data)
end

#send_raw(interface_name, data, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Send a raw binary string to the specified interface.

Parameters:

  • interface_name (String) —

    The interface to send the raw binary

  • data (String) —

    The raw binary data



131
132
133
134
135
136
 
# File 'lib/openc3/api/cmd_api.rb', line 131

def send_raw(interface_name, data, scope: $openc3_scope, token: $openc3_token)
  interface_name = interface_name.upcase
  authorize(permission: 'cmd_raw', interface_name: interface_name, scope: scope, token: token)
  get_interface(interface_name, scope: scope, token: token) # Check to make sure the interface exists
  InterfaceTopic.write_raw(interface_name, data, scope: scope)
end

#set_limits(target_name, packet_name, item_name, red_low, yellow_low, yellow_high, red_high, green_low = nil, green_high = nil, limits_set = 'CUSTOM', persistence = nil, enabled = true, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Change the limits settings for a given item. By default, a new limits set called ‘CUSTOM’ is created to avoid overriding existing limits.



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/openc3/api/limits_api.rb', line 207

def set_limits(target_name, packet_name, item_name, red_low, yellow_low, yellow_high, red_high,
               green_low = nil, green_high = nil, limits_set = 'CUSTOM', persistence = nil, enabled = true,
               scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm_set', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
  if (red_low > yellow_low) || (yellow_low >= yellow_high) || (yellow_high > red_high)
    raise "Invalid limits specified. Ensure yellow limits are within red limits."
  end
  if (green_low && green_high) && ((yellow_low > green_low) || (green_low >= green_high) || (green_high > yellow_high))
    raise "Invalid limits specified. Ensure green limits are within yellow limits."
  end
  packet = TargetModel.packet(target_name, packet_name, scope: scope)
  found_item = nil
  packet['items'].each do |item|
    if item['name'] == item_name
      if item['limits']
        item['limits']['persistence_setting'] = persistence if persistence
        if enabled
          item['limits']['enabled'] = true
        else
          item['limits'].delete('enabled')
        end
        limits = {}
        limits['red_low'] = red_low
        limits['yellow_low'] = yellow_low
        limits['yellow_high'] = yellow_high
        limits['red_high'] = red_high
        limits['green_low'] = green_low if green_low && green_high
        limits['green_high'] = green_high if green_low && green_high
        item['limits'][limits_set] = limits
        found_item = item
        break
      else
        raise "Cannot set_limits on item without any limits"
      end
    end
  end
  raise "Item '#{target_name} #{packet_name} #{item_name}' does not exist" unless found_item
  message = "Setting '#{target_name} #{packet_name} #{item_name}' limits to #{red_low} #{yellow_low} #{yellow_high} #{red_high}"
  message << " #{green_low} #{green_high}" if green_low && green_high
  message << " in set #{limits_set} with persistence #{persistence} as enabled #{enabled}"
  Logger.info(message, scope: scope)

  TargetModel.set_packet(target_name, packet_name, packet, scope: scope)

  event = { type: :LIMITS_SETTINGS, target_name: target_name, packet_name: packet_name,
            item_name: item_name, red_low: red_low, yellow_low: yellow_low, yellow_high: yellow_high, red_high: red_high,
            green_low: green_low, green_high: green_high, limits_set: limits_set, persistence: persistence, enabled: enabled,
            time_nsec: Time.now.to_nsec_from_epoch, message: message }
  LimitsEventTopic.write(event, scope: scope)
end

#set_limits_set(limits_set, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Changes the active limits set that applies to all telemetry

Parameters:

  • limits_set (String) —

    The name of the limits set



291
292
293
294
295
296
297
 
# File 'lib/openc3/api/limits_api.rb', line 291

def set_limits_set(limits_set, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm_set', scope: scope, token: token)
  message = "Setting Limits Set: #{limits_set}"
  Logger.info(message, scope: scope)
  LimitsEventTopic.write({ type: :LIMITS_SET, set: limits_set.to_s,
    time_nsec: Time.now.to_nsec_from_epoch, message: message }, scope: scope)
end

#set_offline_access(offline_access_token, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/openc3/api/offline_access_api.rb', line 63

def set_offline_access(offline_access_token, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'script_run', scope: scope, token: token)
  info = (token)
  username = info['username']
  raise "Invalid username" if not username or username == ''
  model = OfflineAccessModel.get_model(name: username, scope: scope)
  if model
    model.offline_access_token = offline_access_token
    model.update
  else
    model = OfflineAccessModel.new(name: username, offline_access_token: offline_access_token, scope: scope)
    model.create
  end
end

#set_tlm(*args, type: :CONVERTED, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Set a telemetry item in the current value table.

Note: If this is done while OpenC3 is currently receiving telemetry, this value could get overwritten at any time. Thus this capability is best used for testing or for telemetry items that are not received regularly through the target interface.

Accepts two different calling styles:

set_tlm("TGT PKT ITEM = 1.0")
set_tlm('TGT','PKT','ITEM', 10.0)

Favor the first syntax where possible as it is more succinct.

Parameters:

  • args (String|Array<String>) —

    See the description for calling style

  • type (Symbol) (defaults to: :CONVERTED) —

    Telemetry type, :RAW, :CONVERTED (default), :FORMATTED, or :WITH_UNITS



110
111
112
113
114
 
# File 'lib/openc3/api/tlm_api.rb', line 110

def set_tlm(*args, type: :CONVERTED, scope: $openc3_scope, token: $openc3_token)
  target_name, packet_name, item_name, value = set_tlm_process_args(args, __method__, scope: scope)
  authorize(permission: 'tlm_set', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
  CvtModel.set_item(target_name, packet_name, item_name, value, type: type.intern, scope: scope)
end

#set_tlm_process_args(args, method_name, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
 
# File 'lib/openc3/api/tlm_api.rb', line 459

def set_tlm_process_args(args, method_name, scope: $openc3_scope, token: $openc3_token)
  case args.length
  when 1
    target_name, packet_name, item_name, value = extract_fields_from_set_tlm_text(args[0])
  when 4
    target_name = args[0]
    packet_name = args[1]
    item_name = args[2]
    value = args[3]
  else
    # Invalid number of arguments
    raise "ERROR: Invalid number of arguments (#{args.length}) passed to #{method_name}()"
  end
  target_name = target_name.upcase
  packet_name = packet_name.upcase
  item_name = item_name.upcase
  # Determine if this item exists, it will raise appropriate errors if not
  TargetModel.packet_item(target_name, packet_name, item_name, scope: scope)

  return [target_name, packet_name, item_name, value]
end

#start_raw_logging_interface(interface_name = 'ALL', scope: $openc3_scope, token: $openc3_token) ⇒ Object

Starts raw logging for an interface

Parameters:

  • interface_name (String) (defaults to: 'ALL') —

    The name of the interface



82
83
84
85
86
87
88
89
90
91
 
# File 'lib/openc3/api/interface_api.rb', line 82

def start_raw_logging_interface(interface_name = 'ALL', scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', interface_name: interface_name, scope: scope, token: token)
  if interface_name == 'ALL'
    get_interface_names().each do |interface_name|
      InterfaceTopic.start_raw_logging(interface_name, scope: scope)
    end
  else
    InterfaceTopic.start_raw_logging(interface_name, scope: scope)
  end
end

#start_raw_logging_router(router_name = 'ALL', scope: $openc3_scope, token: $openc3_token) ⇒ Object

Starts raw logging for a router

Parameters:

  • router_name (String) (defaults to: 'ALL') —

    The name of the router



80
81
82
83
84
85
86
87
88
89
 
# File 'lib/openc3/api/router_api.rb', line 80

def start_raw_logging_router(router_name = 'ALL', scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', router_name: router_name, scope: scope, token: token)
  if router_name == 'ALL'
    get_router_names().each do |router_name|
      RouterTopic.start_raw_logging(router_name, scope: scope)
    end
  else
    RouterTopic.start_raw_logging(router_name, scope: scope)
  end
end

#stash_all(scope: $openc3_scope, token: $openc3_token) ⇒ Object 



47
48
49
50
 
# File 'lib/openc3/api/stash_api.rb', line 47

def stash_all(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'script_view', scope: scope, token: token)
  StashModel.all(scope: scope).transform_values { |hash| JSON.parse(hash["value"], :allow_nan => true, :create_additions => true) }
end

#stash_delete(key, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



57
58
59
60
61
 
# File 'lib/openc3/api/stash_api.rb', line 57

def stash_delete(key, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'script_run', scope: scope, token: token)
  model = StashModel.get_model(name: key, scope: scope)
  model.destroy if model
end

#stash_get(key, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



37
38
39
40
41
42
43
44
45
 
# File 'lib/openc3/api/stash_api.rb', line 37

def stash_get(key, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'script_view', scope: scope, token: token)
  result = StashModel.get(name: key, scope: scope)
  if result
    JSON.parse(result['value'], :allow_nan => true, :create_additions => true)
  else
    nil
  end
end

#stash_keys(scope: $openc3_scope, token: $openc3_token) ⇒ Object 



52
53
54
55
 
# File 'lib/openc3/api/stash_api.rb', line 52

def stash_keys(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'script_view', scope: scope, token: token)
  StashModel.names(scope: scope)
end

#stash_set(key, value, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



32
33
34
35
 
# File 'lib/openc3/api/stash_api.rb', line 32

def stash_set(key, value, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'script_run', scope: scope, token: token)
  StashModel.set( {name: key, value: JSON.generate(value.as_json(:allow_nan => true)) }, scope: scope)
end

#stop_raw_logging_interface(interface_name = 'ALL', scope: $openc3_scope, token: $openc3_token) ⇒ Object

Stop raw logging for an interface

Parameters:

  • interface_name (String) (defaults to: 'ALL') —

    The name of the interface



96
97
98
99
100
101
102
103
104
105
 
# File 'lib/openc3/api/interface_api.rb', line 96

def stop_raw_logging_interface(interface_name = 'ALL', scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', interface_name: interface_name, scope: scope, token: token)
  if interface_name == 'ALL'
    get_interface_names().each do |interface_name|
      InterfaceTopic.stop_raw_logging(interface_name, scope: scope)
    end
  else
    InterfaceTopic.stop_raw_logging(interface_name, scope: scope)
  end
end

#stop_raw_logging_router(router_name = 'ALL', scope: $openc3_scope, token: $openc3_token) ⇒ Object

Stop raw logging for a router

Parameters:

  • router_name (String) (defaults to: 'ALL') —

    The name of the router



94
95
96
97
98
99
100
101
102
103
 
# File 'lib/openc3/api/router_api.rb', line 94

def stop_raw_logging_router(router_name = 'ALL', scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', router_name: router_name, scope: scope, token: token)
  if router_name == 'ALL'
    get_router_names().each do |router_name|
      RouterTopic.stop_raw_logging(router_name, scope: scope)
    end
  else
    RouterTopic.stop_raw_logging(router_name, scope: scope)
  end
end

#subscribe_packets(packets, scope: $openc3_scope, token: $openc3_token) ⇒ String Also known as: subscribe_packet

Subscribe to a list of packets. An ID is returned which is passed to get_packets(id) to return packets.

Parameters:

Returns:

  • (String) —

    ID which should be passed to get_packets



333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
 
# File 'lib/openc3/api/tlm_api.rb', line 333

def subscribe_packets(packets, scope: $openc3_scope, token: $openc3_token)
  if !packets.is_a?(Array) || !packets[0].is_a?(Array)
    raise ArgumentError, "packets must be nested array: [['TGT','PKT'],...]"
  end

  result = {}
  packets.each do |target_name, packet_name|
    target_name = target_name.upcase
    packet_name = packet_name.upcase
    authorize(permission: 'tlm', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
    topic = "#{scope}__DECOM__{#{target_name}}__#{packet_name}"
    id, _ = Topic.get_newest_message(topic)
    result[topic] = id ? id : '0-0'
  end
  result.to_a.join(SUBSCRIPTION_DELIMITER)
end

#tlm(*args, type: :CONVERTED, cache_timeout: 0.1, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Request a telemetry item from a packet.

Accepts two different calling styles:

tlm("TGT PKT ITEM")
tlm('TGT','PKT','ITEM')

Favor the first syntax where possible as it is more succinct.

Parameters:

  • args (String|Array<String>) —

    See the description for calling style

  • type (Symbol) (defaults to: :CONVERTED) —

    Telemetry type, :RAW, :CONVERTED (default), :FORMATTED, or :WITH_UNITS

Returns:

  • (Object) —

    The telemetry value formatted as requested



69
70
71
72
73
 
# File 'lib/openc3/api/tlm_api.rb', line 69

def tlm(*args, type: :CONVERTED, cache_timeout: 0.1, scope: $openc3_scope, token: $openc3_token)
  target_name, packet_name, item_name = tlm_process_args(args, 'tlm', cache_timeout: cache_timeout, scope: scope)
  authorize(permission: 'tlm', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
  CvtModel.get_item(target_name, packet_name, item_name, type: type.intern, cache_timeout: cache_timeout, scope: scope)
end

#tlm_formatted(*args, cache_timeout: 0.1, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Deprecated.

Use tlm with type: :FORMATTED



81
82
83
 
# File 'lib/openc3/api/tlm_api.rb', line 81

def tlm_formatted(*args, cache_timeout: 0.1, scope: $openc3_scope, token: $openc3_token)
  tlm(*args, type: :FORMATTED, cache_timeout: cache_timeout, scope: scope, token: token)
end

#tlm_process_args(args, method_name, cache_timeout: 0.1, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
 
# File 'lib/openc3/api/tlm_api.rb', line 433

def tlm_process_args(args, method_name, cache_timeout: 0.1, scope: $openc3_scope, token: $openc3_token)
  case args.length
  when 1
    target_name, packet_name, item_name = extract_fields_from_tlm_text(args[0])
  when 3
    target_name = args[0]
    packet_name = args[1]
    item_name = args[2]
  else
    # Invalid number of arguments
    raise "ERROR: Invalid number of arguments (#{args.length}) passed to #{method_name}()"
  end
  target_name = target_name.upcase
  packet_name = packet_name.upcase
  item_name = item_name.upcase

  if packet_name == 'LATEST'
    packet_name = CvtModel.determine_latest_packet_for_item(target_name, item_name, cache_timeout: cache_timeout, scope: scope)
  else
    # Determine if this item exists, it will raise appropriate errors if not
    TargetModel.packet_item(target_name, packet_name, item_name, scope: scope)
  end

  return [target_name, packet_name, item_name]
end

#tlm_raw(*args, cache_timeout: 0.1, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Deprecated.

Use tlm with type: :RAW



76
77
78
 
# File 'lib/openc3/api/tlm_api.rb', line 76

def tlm_raw(*args, cache_timeout: 0.1, scope: $openc3_scope, token: $openc3_token)
  tlm(*args, type: :RAW, cache_timeout: cache_timeout, scope: scope, token: token)
end

#tlm_variable(*args, cache_timeout: 0.1, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Deprecated.

Use tlm with type:



91
92
93
 
# File 'lib/openc3/api/tlm_api.rb', line 91

def tlm_variable(*args, cache_timeout: 0.1, scope: $openc3_scope, token: $openc3_token)
  tlm(*args[0..-2], type: args[-1].intern, cache_timeout: cache_timeout, scope: scope, token: token)
end

#tlm_with_units(*args, cache_timeout: 0.1, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Deprecated.

Use tlm with type: :WITH_UNITS



86
87
88
 
# File 'lib/openc3/api/tlm_api.rb', line 86

def tlm_with_units(*args, cache_timeout: 0.1, scope: $openc3_scope, token: $openc3_token)
  tlm(*args, type: :WITH_UNITS, cache_timeout: cache_timeout, scope: scope, token: token)
end