Module: OpenC3::Api

Includes:
Authorization, ApiShared, Extract
Included in:
AuthorizedApi, GemModel, Interface, LimitsResponse, PluginModel, PythonPackageModel
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

#_build_cmd_output_string(method_name, target_name, cmd_name, cmd_params, packet) ⇒ Object 



518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
 
# File 'lib/openc3/api/cmd_api.rb', line 518

def _build_cmd_output_string(method_name, target_name, cmd_name, cmd_params, packet)
  output_string = "#{method_name}(\""
  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

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



451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
 
# File 'lib/openc3/api/cmd_api.rb', line 451

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)
  if packet['disabled']
    error = DisabledError.new
    error.target_name = target_name
    error.cmd_name = cmd_name
    raise error
  end

  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(method_name, target_name, cmd_name, cmd_params, packet), scope: scope)
  end
  CommandTopic.send_command(command, timeout: timeout, scope: scope)
end

#_extract_target_command_names(method_name, *args) ⇒ Object

PRIVATE implementation details



411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
 
# File 'lib/openc3/api/cmd_api.rb', line 411

def _extract_target_command_names(method_name, *args)
  target_name = nil
  command_name = nil
  case args.length
  when 1
    target_name, command_name = args[0].upcase.split
  when 2
    target_name = args[0].upcase
    command_name = args[1].upcase
  else
    # Invalid number of arguments
    raise "ERROR: Invalid number of arguments (#{args.length}) passed to #{method_name}()"
  end
  if target_name.nil? or command_name.nil?
    raise "ERROR: Target name and command name required. Usage: #{method_name}(\"TGT CMD\") or #{method_name}(\"TGT\", \"CMD\")"
  end
  return [target_name, command_name]
end

#_extract_target_command_parameter_names(method_name, *args) ⇒ Object 



430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
 
# File 'lib/openc3/api/cmd_api.rb', line 430

def _extract_target_command_parameter_names(method_name, *args)
  target_name = nil
  command_name = nil
  parameter_name = nil
  case args.length
  when 1
    target_name, command_name, parameter_name = args[0].upcase.split
  when 3
    target_name = args[0].upcase
    command_name = args[1].upcase
    parameter_name = args[2].upcase
  else
    # Invalid number of arguments
    raise "ERROR: Invalid number of arguments (#{args.length}) passed to #{method_name}()"
  end
  if target_name.nil? or command_name.nil? or parameter_name.nil?
    raise "ERROR: Target name, command name and parameter name required. Usage: #{method_name}(\"TGT CMD PARAM\") or #{method_name}(\"TGT\", \"CMD\", \"PARAM\")"
  end
  return [target_name, command_name, parameter_name]
end

#_extract_target_packet_item_names(method_name, *args) ⇒ Object 



445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
 
# File 'lib/openc3/api/tlm_api.rb', line 445

def _extract_target_packet_item_names(method_name, *args)
  target_name = nil
  packet_name = nil
  item_name = nil
  case args.length
  when 1
    target_name, packet_name, item_name = args[0].upcase.split
  when 3
    target_name = args[0].upcase
    packet_name = args[1].upcase
    item_name = args[2].upcase
  else
    # Invalid number of arguments
    raise "ERROR: Invalid number of arguments (#{args.length}) passed to #{method_name}()"
  end
  if target_name.nil? or packet_name.nil? or item_name.nil?
    raise "ERROR: Target name, packet name and item name are required. Usage: #{method_name}(\"TGT PKT ITEM\") or #{method_name}(\"TGT\", \"PKT\", \"ITEM\")"
  end
  return [target_name, packet_name, item_name]
end

#_extract_target_packet_names(method_name, *args) ⇒ Object

PRIVATE



426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
 
# File 'lib/openc3/api/tlm_api.rb', line 426

def _extract_target_packet_names(method_name, *args)
  target_name = nil
  packet_name = nil
  case args.length
  when 1
    target_name, packet_name = args[0].upcase.split
  when 2
    target_name = args[0].upcase
    packet_name = args[1].upcase
  else
    # Invalid number of arguments
    raise "ERROR: Invalid number of arguments (#{args.length}) passed to #{method_name}()"
  end
  if target_name.nil? or packet_name.nil?
    raise "ERROR: Both target name and packet name required. Usage: #{method_name}(\"TGT PKT\") or #{method_name}(\"TGT\", \"PKT\")"
  end
  return [target_name, packet_name]
end

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

Helper method for disable_cmd / enable_cmd



137
138
139
140
141
142
 
# File 'lib/openc3/api/cmd_api.rb', line 137

def _get_and_set_cmd(method, *args, scope: $openc3_scope, token: $openc3_token)
  target_name, command_name = _extract_target_command_names(method, *args)
  authorize(permission: 'admin', target_name: target_name, packet_name: command_name, scope: scope, token: token)
  command = yield TargetModel.packet(target_name, command_name, type: :CMD, scope: scope)
  TargetModel.set_packet(target_name, command_name, command, type: :CMD, scope: scope)
end

#_get_item(target_name, packet_name, item_name, cache_timeout: nil, 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



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

def _get_item(target_name, packet_name, item_name, cache_timeout: nil, 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



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
368
 
# File 'lib/openc3/api/limits_api.rb', line 326

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

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



506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
 
# File 'lib/openc3/api/tlm_api.rb', line 506

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

#_tlm_process_args(args, method_name, cache_timeout: nil, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
 
# File 'lib/openc3/api/tlm_api.rb', line 480

def _tlm_process_args(args, method_name, cache_timeout: nil, 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

#_validate_tlm_type(type) ⇒ Object 



466
467
468
469
470
471
472
473
474
475
476
477
478
 
# File 'lib/openc3/api/tlm_api.rb', line 466

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(*args, range_check: true, raw: false, scope: $openc3_scope, token: $openc3_token, **kwargs) ⇒ Object Also known as: build_command

Build a command binary

Since:

  • 5.8.0



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/openc3/api/cmd_api.rb', line 110

def build_cmd(*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.



71
72
73
 
# File 'lib/openc3/api/cmd_api.rb', line 71

def cmd(*args, **kwargs)
  _cmd_implementation('cmd', *args, range_check: true, hazardous_check: true, raw: false, **kwargs)
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.



100
101
102
 
# File 'lib/openc3/api/cmd_api.rb', line 100

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.



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

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.



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

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 



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

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 



103
104
105
 
# File 'lib/openc3/api/cmd_api.rb', line 103

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 



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

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 



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

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

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



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

def config_tool_names(scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)
  ToolConfigModel.config_tool_names(scope: scope)
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_cmd(*args, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Since:

  • 5.15.1



153
154
155
156
157
158
 
# File 'lib/openc3/api/cmd_api.rb', line 153

def disable_cmd(*args, scope: $openc3_scope, token: $openc3_token)
  _get_and_set_cmd('disable_cmd', *args, scope: scope, token: token) do |command|
    command['disabled'] = true
    command
  end
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:



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

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



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

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_cmd(*args, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Since:

  • 5.15.1



145
146
147
148
149
150
 
# File 'lib/openc3/api/cmd_api.rb', line 145

def enable_cmd(*args, scope: $openc3_scope, token: $openc3_token)
  _get_and_set_cmd('enable_cmd', *args, scope: scope, token: token) do |command|
    command['disabled'] = false
    command
  end
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:



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

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



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

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_cmd_names(target_name, hidden: false, scope: $openc3_scope, token: $openc3_token) ⇒ Array<String> Also known as: get_all_command_names

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



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

def get_all_cmd_names(target_name, hidden: false, scope: $openc3_scope, token: $openc3_token)
  begin
    packets = get_all_cmds(target_name, scope: scope, token: token)
  rescue RuntimeError
    packets = []
  end
  names = []
  packets.each do |packet|
    if hidden
      names << packet['packet_name']
    else
      names << packet['packet_name'] unless packet['hidden']
    end
  end
  return names
end

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

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



194
195
196
197
198
 
# File 'lib/openc3/api/cmd_api.rb', line 194

def get_all_cmds(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 



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

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_tlm(target_name, scope: $openc3_scope, token: $openc3_token) ⇒ Array<Hash> Also known as: get_all_telemetry

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



278
279
280
281
282
 
# File 'lib/openc3/api/tlm_api.rb', line 278

def get_all_tlm(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_tlm_names(target_name, hidden: false, scope: $openc3_scope, token: $openc3_token) ⇒ Array<String> Also known as: get_all_telemetry_names

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



290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
 
# File 'lib/openc3/api/tlm_api.rb', line 290

def get_all_tlm_names(target_name, hidden: false, scope: $openc3_scope, token: $openc3_token)
  begin
    packets = get_all_tlm(target_name, scope: scope, token: token)
  rescue RuntimeError
    packets = []
  end
  names = []
  packets.each do |packet|
    if hidden
      names << packet['packet_name']
    else
      names << packet['packet_name'] unless packet['hidden']
    end
  end
  return names
end

#get_cmd(*args, scope: $openc3_scope, token: $openc3_token) ⇒ Hash Also known as: get_command

Returns a hash of the given command

Returns:

  • (Hash) —

    Command as a hash

Since:

  • 5.0.0



230
231
232
233
234
 
# File 'lib/openc3/api/cmd_api.rb', line 230

def get_cmd(*args, scope: $openc3_scope, token: $openc3_token)
  target_name, command_name = _extract_target_command_names('get_cmd', *args)
  authorize(permission: 'cmd_info', target_name: target_name, scope: scope, token: token)
  TargetModel.packet(target_name, command_name, type: :CMD, scope: scope)
end

#get_cmd_buffer(*args, 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



176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/openc3/api/cmd_api.rb', line 176

def get_cmd_buffer(*args, scope: $openc3_scope, token: $openc3_token)
  target_name, command_name = _extract_target_command_names('get_cmd_buffer', *args)
  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(*args, 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



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

def get_cmd_cnt(*args, scope: $openc3_scope, token: $openc3_token)
  target_name, command_name = _extract_target_command_names('get_cmd_cnt', *args)
  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



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

def get_cmd_cnts(target_commands, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', scope: scope, token: token)
  unless target_commands.is_a?(Array) and target_commands[0].is_a?(Array)
    raise "get_cmd_cnts takes an array of arrays containing target, packet_name, e.g. [['INST', 'COLLECT'], ['INST', 'ABORT']]"
  end
  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



261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/openc3/api/cmd_api.rb', line 261

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:



344
345
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
 
# File 'lib/openc3/api/cmd_api.rb', line 344

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)
    return [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
    time = 0
    command_name = nil
    targets.each do |cur_target|
      TargetModel.packets(cur_target, type: :CMD, scope: scope).each do |packet|
        cur_time = CommandDecomTopic.get_cmd_item(cur_target, 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"]
          target_name = cur_target
        end
      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

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

Returns a value from the specified command Supports the following call syntax:

get_cmd_value("TGT PKT ITEM", type: :RAW)
get_cmd_value("TGT", "PKT", "ITEM", type: :RAW)
get_cmd_value("TGT", "PKT", "ITEM", :RAW) # DEPRECATED



310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
 
# File 'lib/openc3/api/cmd_api.rb', line 310

def get_cmd_value(*args, type: :CONVERTED, scope: $openc3_scope, token: $openc3_token)
  target_name = nil
  command_name = nil
  parameter_name = nil
  case args.length
  when 1
    target_name, command_name, parameter_name = args[0].upcase.split
  when 3
    target_name = args[0].upcase
    command_name = args[1].upcase
    parameter_name = args[2].upcase
  when 4
    target_name = args[0].upcase
    command_name = args[1].upcase
    parameter_name = args[2].upcase
    type = args[3].upcase
  else
    # Invalid number of arguments
    raise "ERROR: Invalid number of arguments (#{args.length}) passed to get_cmd_value()"
  end
  if target_name.nil? or command_name.nil? or parameter_name.nil?
    raise "ERROR: Target name, command name and parameter name required. Usage: get_cmd_value(\"TGT CMD PARAM\") or #{method_name}(\"TGT\", \"CMD\", \"PARAM\")"
  end
  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: type, 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(*args, 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



328
329
330
331
332
 
# File 'lib/openc3/api/tlm_api.rb', line 328

def get_item(*args, scope: $openc3_scope, token: $openc3_token)
  target_name, packet_name, item_name = _extract_target_packet_item_names('get_item', *args)
  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, cache_timeout: nil, 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:



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

def get_limits(target_name, packet_name, item_name, cache_timeout: nil, 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, cache_timeout: cache_timeout, 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.



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

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



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

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



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

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:



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

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 



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
100
101
102
 
# File 'lib/openc3/api/metrics_api.rb', line 69

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(*args, 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.



417
418
419
420
421
422
 
# File 'lib/openc3/api/tlm_api.rb', line 417

def get_packet_derived_items(*args, scope: $openc3_scope, token: $openc3_token)
  target_name, packet_name = _extract_target_packet_names('get_packet_derived_items', *args)
  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



366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
 
# File 'lib/openc3/api/tlm_api.rb', line 366

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_param(*args, scope: $openc3_scope, token: $openc3_token) ⇒ Hash Also known as: get_parameter

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



245
246
247
248
249
 
# File 'lib/openc3/api/cmd_api.rb', line 245

def get_param(*args, scope: $openc3_scope, token: $openc3_token)
  target_name, command_name, parameter_name = _extract_target_command_parameter_names('get_param', *args)
  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_setting(name, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



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

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 



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

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_tlm(*args, scope: $openc3_scope, token: $openc3_token) ⇒ Hash Also known as: get_telemetry

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



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

def get_tlm(*args, scope: $openc3_scope, token: $openc3_token)
  target_name, packet_name = _extract_target_packet_names('get_tlm', *args)
  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(*args, 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
 
# File 'lib/openc3/api/tlm_api.rb', line 207

def get_tlm_buffer(*args, scope: $openc3_scope, token: $openc3_token)
  target_name, packet_name = _extract_target_packet_names('get_tlm_buffer', *args)
  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(*args, 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



390
391
392
393
394
395
 
# File 'lib/openc3/api/tlm_api.rb', line 390

def get_tlm_cnt(*args, scope: $openc3_scope, token: $openc3_token)
  target_name, packet_name = _extract_target_packet_names('get_tlm_cnt', *args)
  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) ⇒ Array<Numeric>

Get the transmit counts for telemetry packets

Parameters:

Returns:

  • (Array<Numeric>) —

    Receive count for the telemetry packets



401
402
403
404
405
406
407
408
409
410
 
# File 'lib/openc3/api/tlm_api.rb', line 401

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(*args, stale_time: 30, type: :CONVERTED, cache_timeout: nil, 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) 


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

def get_tlm_packet(*args, stale_time: 30, type: :CONVERTED, cache_timeout: nil, scope: $openc3_scope, token: $openc3_token)
  target_name, packet_name = _extract_target_packet_names('get_tlm_packet', *args)
  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: nil, 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



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

def get_tlm_values(items, stale_time: 30, cache_timeout: nil, 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 Also known as: limits_enabled

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 



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

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

#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



164
165
166
167
168
169
 
# File 'lib/openc3/api/cmd_api.rb', line 164

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.



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
257
 
# File 'lib/openc3/api/limits_api.rb', line 208

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



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

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_setting(name, data, scope: $openc3_scope, token: $openc3_token) ⇒ Object Also known as: save_setting 



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

def set_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

#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

#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



342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
 
# File 'lib/openc3/api/tlm_api.rb', line 342

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: nil, 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



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

def tlm(*args, type: :CONVERTED, cache_timeout: nil, 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: nil, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



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

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

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



78
79
80
 
# File 'lib/openc3/api/tlm_api.rb', line 78

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

#tlm_variable(*args, cache_timeout: nil, 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: nil, 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: nil, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



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

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