Module: OpenC3::Api

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

Methods included from CmdLog

#_build_cmd_output_string

Instance Method Details

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

NOTE: When adding new keywords to this method, make sure to update script/commands.rb



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

def _cmd_implementation(method_name, *args, range_check:, hazardous_check:, raw:, timeout: nil, log_message: nil, manual: false, validate: true, queue: 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)
  user = authorize(permission: 'cmd', target_name: target_name, packet_name: cmd_name, manual: manual, scope: scope, token: token)
  if user.nil?
    user = {}
    user['username'] = ENV['OPENC3_MICROSERVICE_NAME']

    # Get the caller stack trace to determine the point in the code where the command was called
    # This code works but ultimately we didn't want to overload 'username' and take a performance hit
    # caller.each do |frame|
    #   # Look for the following line in the stack trace which indicates custom code
    #   # /tmp/d20240827-62-8e57pf/targets/INST/lib/example_limits_response.rb:31:in `call'
    #   if frame.include?("/targets/#{target_name}")
    #     user = {}
    #     # username is the name of the custom code file
    #     user['username'] = frame.split("/targets/")[-1].split(':')[0]
    #     break
    #   end
    # end
  end

  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
  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 { |find_item| find_item['name'] == key.to_s }
      if item && item['states'] && item['states'][value] && item['states'][value]["messages_disabled"]
        log_message = false
      end
    end
  end
  cmd_string = _build_cmd_output_string(method_name, target_name, cmd_name, cmd_params, packet)
  username = user && user['username'] ? user['username'] : 'anonymous'
  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,
    'cmd_string' => cmd_string,
    'username' => username,
    'validate' => validate.to_s,
    'manual' => manual.to_s,
    'log_message' => log_message.to_s,
    'obfuscated_items' => packet['obfuscated_items'].to_s
  }
  # Users have to explicitly opt into a default queue by setting the OPENC3_DEFAULT_QUEUE
  # At which point ALL commands will go to that queue unless they specifically opt out with queue: false
  if ENV['OPENC3_DEFAULT_QUEUE'] && queue.nil?
    queue = ENV['OPENC3_DEFAULT_QUEUE']
  end
  if queue
    # Pass the command components separately for the queue microservice to use the 3-parameter cmd() method
    QueueModel.queue_command(queue,
      target_name: target_name,
      cmd_name: cmd_name,
      cmd_params: cmd_params,
      validate: validate,
      timeout: timeout,
      username: username,
      scope: scope)
  else
    CommandTopic.send_command(command, timeout: timeout, scope: scope)
  end
  return command
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 



550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
 
# File 'lib/openc3/api/tlm_api.rb', line 550

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



531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
 
# File 'lib/openc3/api/tlm_api.rb', line 531

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, manual:, scope:, token:) ⇒ Object

Helper method for disable_cmd / enable_cmd



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

def _get_and_set_cmd(method, *args, manual:, scope:, token:)
  target_name, command_name = _extract_target_command_names(method, *args)
  authorize(permission: 'admin', target_name: target_name, packet_name: command_name, manual: manual, 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



372
373
374
375
376
 
# File 'lib/openc3/api/limits_api.rb', line 372

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:, manual:, scope:, token:) ⇒ Object

Enables or disables a limits group



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

def _limits_group(group_name, action:, manual:, scope:, token:)
  authorize(permission: 'tlm_set', manual: manual, 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']['enabled'] = false
          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, cache_timeout: nil, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
 
# File 'lib/openc3/api/tlm_api.rb', line 610

def _set_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, 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

  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, value]
end

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



584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
 
# File 'lib/openc3/api/tlm_api.rb', line 584

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 



571
572
573
574
575
576
577
578
579
580
581
582
 
# File 'lib/openc3/api/tlm_api.rb', line 571

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

#build_cmd(*args, range_check: true, raw: false, manual: false, timeout: 5, scope: $openc3_scope, token: $openc3_token, **kwargs) ⇒ Object Also known as: build_command

Build a command binary

Since:

  • 5.8.0



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

def build_cmd(*args, range_check: true, raw: false, manual: false, timeout: 5, 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, manual: manual, scope: scope, token: token)
  DecomInterfaceTopic.build_cmd(target_name, cmd_name, cmd_params, range_check, raw, timeout: timeout, 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.



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

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.



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

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.



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

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.



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

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 



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

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 



105
106
107
 
# File 'lib/openc3/api/cmd_api.rb', line 105

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 



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

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 



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

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(manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



31
32
33
34
 
# File 'lib/openc3/api/config_api.rb', line 31

def config_tool_names(manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', manual: manual, scope: scope, token: token)
  ToolConfigModel.config_tool_names(scope: scope)
end

#connect_interface(interface_name, *interface_params, manual: false, 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



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

def connect_interface(interface_name, *interface_params, manual: false, scope: $openc3_scope, token: $openc3_token)
  # TODO: Check if they have command authority for the targets mapped to this interface
  authorize(permission: 'system_set', interface_name: interface_name, manual: manual, scope: scope, token: token)
  InterfaceTopic.connect_interface(interface_name, *interface_params, scope: scope)
end

#connect_router(router_name, *router_params, manual: false, 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
68
 
# File 'lib/openc3/api/router_api.rb', line 64

def connect_router(router_name, *router_params, manual: false, scope: $openc3_scope, token: $openc3_token)
  # TODO: Check if they have command authority for the targets mapped to this router
  authorize(permission: 'system_set', router_name: router_name, manual: manual, scope: scope, token: token)
  RouterTopic.connect_router(router_name, *router_params, scope: scope)
end

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



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

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

#disable_cmd(*args, manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Since:

  • 5.15.1



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

def disable_cmd(*args, manual: false, scope: $openc3_scope, token: $openc3_token)
  _get_and_set_cmd('disable_cmd', *args, manual: manual, scope: scope, token: token) do |command|
    command['disabled'] = true
    command
  end
end

#disable_limits(*args, manual: false, 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:



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/openc3/api/limits_api.rb', line 155

def disable_limits(*args, manual: false, 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, manual: manual, 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'] = false
      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, manual: false, 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



272
273
274
 
# File 'lib/openc3/api/limits_api.rb', line 272

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

#disconnect_interface(interface_name, manual: false, 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
78
 
# File 'lib/openc3/api/interface_api.rb', line 74

def disconnect_interface(interface_name, manual: false, scope: $openc3_scope, token: $openc3_token)
  # TODO: Check if they have command authority for the targets mapped to this interface
  authorize(permission: 'system_set', interface_name: interface_name, manual: manual, scope: scope, token: token)
  InterfaceTopic.disconnect_interface(interface_name, scope: scope)
end

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

Disconnects a router and kills its command gathering thread

Parameters:

  • router_name (String) —

    Name of router



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

def disconnect_router(router_name, manual: false, scope: $openc3_scope, token: $openc3_token)
  # TODO: Check if they have command authority for the targets mapped to this router
  authorize(permission: 'system_set', router_name: router_name, manual: manual, scope: scope, token: token)
  RouterTopic.disconnect_router(router_name, scope: scope)
end

#enable_cmd(*args, manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Since:

  • 5.15.1



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

def enable_cmd(*args, manual: false, scope: $openc3_scope, token: $openc3_token)
  _get_and_set_cmd('enable_cmd', *args, manual: manual, scope: scope, token: token) do |command|
    command['disabled'] = false
    command
  end
end

#enable_limits(*args, manual: false, 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:



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/openc3/api/limits_api.rb', line 122

def enable_limits(*args, manual: false, 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, manual: manual, 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, manual: false, 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



265
266
267
 
# File 'lib/openc3/api/limits_api.rb', line 265

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

#get_all_cmd_names(target_name, hidden: false, manual: 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



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/openc3/api/cmd_api.rb', line 213

def get_all_cmd_names(target_name, hidden: false, manual: 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, manual: false, 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



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

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

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

Get information about all interfaces

Returns:



116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/openc3/api/interface_api.rb', line 116

def get_all_interface_info(manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', manual: manual, scope: scope, token: token)
  info = []
  InterfaceStatusModel.all(scope: scope).each do |int_name, int|
    # Get the interface configuration to access disable_disconnect
    interface_model = InterfaceModel.get(name: int_name, scope: scope)
    disable_disconnect = interface_model && interface_model['disable_disconnect'] ? true : false

    info << [int['name'], int['state'], int['clients'], int['txsize'], int['rxsize'],
             int['txbytes'], int['rxbytes'], int['txcnt'], int['rxcnt'], disable_disconnect]
  end
  info.sort! { |a, b| a[0] <=> b[0] }
  info
end

#get_all_router_info(manual: false, 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:



115
116
117
118
119
120
121
122
123
124
 
# File 'lib/openc3/api/router_api.rb', line 115

def get_all_router_info(manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', manual: manual, 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(manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



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

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

#get_all_tlm(target_name, manual: false, 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



358
359
360
361
362
 
# File 'lib/openc3/api/tlm_api.rb', line 358

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

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

Returns an array of all the item names for every packet in a target

Parameters:

  • target_name (String) —

    Name of the taret

Returns:

  • (Array<String>) —

    Array of all telemetry item names



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

def get_all_tlm_item_names(target_name, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm', target_name: target_name, manual: manual, scope: scope, token: token)
  begin
    items = TargetModel.all_item_names(target_name, scope: scope)
  rescue RuntimeError
    items = []
  end
  return items
end

#get_all_tlm_names(target_name, hidden: false, manual: 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



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

def get_all_tlm_names(target_name, hidden: false, manual: false, scope: $openc3_scope, token: $openc3_token)
  begin
    packets = get_all_tlm(target_name, manual: manual, 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, manual: false, 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



236
237
238
239
240
 
# File 'lib/openc3/api/cmd_api.rb', line 236

def get_cmd(*args, manual: false, 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, manual: manual, scope: scope, token: token)
  TargetModel.packet(target_name, command_name, type: :CMD, scope: scope)
end

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



181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/openc3/api/cmd_api.rb', line 181

def get_cmd_buffer(*args, manual: false, 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, manual: manual, scope: scope, token: token)
  TargetModel.packet(target_name, command_name, type: :CMD, scope: scope)
  topic = "#{scope}__COMMAND__{#{target_name}}__#{command_name}"
  db_shard = Store.db_shard_for_target(target_name, scope: scope)
  msg_id, msg_hash = Topic.get_newest_message(topic, db_shard: db_shard)
  if msg_id
    msg_hash['buffer'] = msg_hash['buffer'].b
    return msg_hash
  end
  return nil
end

#get_cmd_cnt(*args, manual: false, 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



388
389
390
391
392
393
 
# File 'lib/openc3/api/cmd_api.rb', line 388

def get_cmd_cnt(*args, manual: false, 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, manual: manual, scope: scope, token: token)
  TargetModel.packet(target_name, command_name, type: :CMD, scope: scope)
  return TargetModel.get_command_count(target_name, command_name, scope: scope)
end

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

Get the transmit counts for command packets

Parameters:

Returns:

  • (Numeric) —

    Transmit count for the command



399
400
401
402
403
404
405
 
# File 'lib/openc3/api/cmd_api.rb', line 399

def get_cmd_cnts(target_commands, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', manual: manual, 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
  return TargetModel.get_command_counts(target_commands, scope: scope)
end

#get_cmd_hazardous(*args, manual: false, 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



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
304
305
306
307
308
309
 
# File 'lib/openc3/api/cmd_api.rb', line 267

def get_cmd_hazardous(*args, manual: false, 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, manual: manual, 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, manual: false, 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:



350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
 
# File 'lib/openc3/api/cmd_api.rb', line 350

def get_cmd_time(target_name = nil, command_name = nil, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'cmd_info', target_name: target_name, packet_name: command_name, manual: manual, 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, manual: false, 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



316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
 
# File 'lib/openc3/api/cmd_api.rb', line 316

def get_cmd_value(*args, type: :CONVERTED, manual: false, 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, manual: manual, scope: scope, token: token)
  CommandDecomTopic.get_cmd_item(target_name, command_name, parameter_name, type: type, scope: scope)
end

#get_interface(interface_name, manual: false, 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



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

def get_interface(interface_name, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', interface_name: interface_name, manual: manual, 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(manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Array<String>

Returns All the interface names.

Returns:



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

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

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



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

def get_item(*args, manual: false, scope: $openc3_scope, token: $openc3_token, cache_timeout: nil)
  target_name, packet_name, item_name = _extract_target_packet_item_names('get_item', *args)
  if packet_name == 'LATEST'
    packet_name = CvtModel.determine_latest_packet_for_item(target_name, item_name, cache_timeout: cache_timeout, scope: scope)
  end
  authorize(permission: 'tlm', target_name: target_name, packet_name: packet_name, manual: manual, 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, manual: false, 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:



188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/openc3/api/limits_api.rb', line 188

def get_limits(target_name, packet_name, item_name, cache_timeout: nil, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm', target_name: target_name, packet_name: packet_name, manual: manual, 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, manual: false, 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.



311
312
313
314
 
# File 'lib/openc3/api/limits_api.rb', line 311

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

#get_limits_groups(manual: false, 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



257
258
259
260
 
# File 'lib/openc3/api/limits_api.rb', line 257

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

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

Returns the active limits set that applies to all telemetry

Returns:

  • (String) —

    The current limits set



298
299
300
301
 
# File 'lib/openc3/api/limits_api.rb', line 298

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

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

Returns all defined limits sets

Returns:



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

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

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



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

def get_metrics(manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', manual: manual, 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)

  redis_metrics = MetricModel.redis_metrics
  redis_metrics.each do |_db_shard, values|
    values.each do |key, value|
      existing = result[key]
      result[key] = value if existing.nil? or value > existing
    end
  end

  return result
end

#get_out_of_limits(manual: false, 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:



45
46
47
48
 
# File 'lib/openc3/api/limits_api.rb', line 45

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

#get_overall_limits_state(ignored_items = nil, manual: false, 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'



57
58
59
60
61
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
 
# File 'lib/openc3/api/limits_api.rb', line 57

def get_overall_limits_state(ignored_items = nil, manual: false, 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(manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Get the list of CVT overrides



185
186
187
188
 
# File 'lib/openc3/api/tlm_api.rb', line 185

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

#get_packet_derived_items(*args, manual: false, 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.



522
523
524
525
526
527
 
# File 'lib/openc3/api/tlm_api.rb', line 522

def get_packet_derived_items(*args, manual: false, 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, manual: manual, 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, manual: false, 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



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
 
# File 'lib/openc3/api/tlm_api.rb', line 464

def get_packets(id, block: nil, count: 1000, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm', manual: manual, 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)]
  # Group topics by db_shard for multi-shard support
  db_shard_groups = {}
  lookup.each do |topic, offset|
    target_name = topic.match(/__\{?([^}_]+)\}?__/)[1] rescue nil
    db_shard = Store.db_shard_for_target(target_name, scope: scope)
    db_shard_groups[db_shard] ||= { topics: [], offsets: [] }
    db_shard_groups[db_shard][:topics] << topic
    db_shard_groups[db_shard][:offsets] << offset
  end
  xread = {}
  db_shard_groups.each do |db_shard, group|
    result = Topic.read_topics(group[:topics], group[:offsets], nil, count, db_shard: db_shard) # Always don't block
    xread.merge!(result) if result
  end
  # 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, manual: false, 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



251
252
253
254
255
 
# File 'lib/openc3/api/cmd_api.rb', line 251

def get_param(*args, manual: false, 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, manual: manual, scope: scope, token: token)
  TargetModel.packet_item(target_name, command_name, parameter_name, type: :CMD, scope: scope)
end

#get_router(router_name, manual: false, 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, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', router_name: router_name, manual: manual, 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(manual: false, 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(manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', manual: manual, scope: scope, token: token)
  RouterModel.names(scope: scope)
end

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



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

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

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



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

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

#get_target(target_name, manual: false, 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



45
46
47
48
 
# File 'lib/openc3/api/target_api.rb', line 45

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

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

Get all targets and their interfaces

Returns:



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/openc3/api/target_api.rb', line 53

def get_target_interfaces(manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', manual: manual, 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(manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Array<String> Also known as: get_target_list

Returns the list of all target names

Returns:



33
34
35
36
 
# File 'lib/openc3/api/target_api.rb', line 33

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

#get_tlm(*args, manual: false, 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



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

def get_tlm(*args, manual: false, 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, manual: manual, scope: scope, token: token)
  TargetModel.packet(target_name, packet_name, scope: scope)
end

#get_tlm_available(items, manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Returns the available items from a list of requested screen items This does the packet introspection to determine what is actually available Like if you ask for FORMATTED but only RAW is available



259
260
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
304
305
306
307
308
309
310
311
312
313
 
# File 'lib/openc3/api/tlm_api.rb', line 259

def get_tlm_available(items, manual: false, scope: $openc3_scope, token: $openc3_token)
  results = []
  items.each do |item|
    item_upcase = item.to_s.upcase
    target_name, orig_packet_name, item_name, value_type = item_upcase.split('__')
    packet_name = orig_packet_name
    raise ArgumentError, "items must be formatted as TGT__PKT__ITEM__TYPE" if target_name.nil? || packet_name.nil? || item_name.nil? || value_type.nil?
    if orig_packet_name == 'LATEST'
      # TODO: Do we need to lookup ALL the possible packets for this item?
      # We can have a large cache_timeout of 1 because all we're trying to do is lookup a packet
      packet_name = CvtModel.determine_latest_packet_for_item(target_name, item_name, cache_timeout: 1, scope: scope)
    end
    authorize(permission: 'tlm', target_name: target_name, packet_name: packet_name, scope: scope, token: token)
    begin
      item = TargetModel.packet_item(target_name, packet_name, item_name, scope: scope)
      if Packet::RESERVED_ITEM_NAMES.include?(item_name)
        value_type = 'RAW' # Must request the raw value when dealing with the reserved items
      end

      # Arrays must be accessed as RAW since there's no conversion
      if item['array_size']
        value_type = 'RAW'
      end

      case value_type
      when 'FORMATTED', 'WITH_UNITS'
        if item['format_string'] or item['units']
          results << [target_name, orig_packet_name, item_name, 'FORMATTED'].join('__')
        # This logic must match the logic in Packet#decom
        elsif item['states'] or (item['read_conversion'] and item['data_type'] != 'DERIVED')
          results << [target_name, orig_packet_name, item_name, 'CONVERTED'].join('__')
        else
          results << [target_name, orig_packet_name, item_name, 'RAW'].join('__')
        end
      when 'CONVERTED'
        # This logic must match the logic in Packet#decom
        if item['states'] or (item['read_conversion'] and item['data_type'] != 'DERIVED')
          results << [target_name, orig_packet_name, item_name, 'CONVERTED'].join('__')
        else
          results << [target_name, orig_packet_name, item_name, 'RAW'].join('__')
        end
      else # RAW or unknown
        results << [target_name, orig_packet_name, item_name, 'RAW'].join('__')
      end

      # Tack on __LIMITS to notify that we have an available limits value
      if item['limits']['DEFAULT']
        results[-1] += '__LIMITS'
      end
    rescue RuntimeError
      results << nil
    end
  end
  results
end

#get_tlm_buffer(*args, manual: false, scope: $openc3_scope, token: $openc3_token, timeout: 5) ⇒ 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



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
 
# File 'lib/openc3/api/tlm_api.rb', line 214

def get_tlm_buffer(*args, manual: false, scope: $openc3_scope, token: $openc3_token, timeout: 5)
  target_name, packet_name = _extract_target_packet_names('get_tlm_buffer', *args)
  authorize(permission: 'tlm', target_name: target_name, packet_name: packet_name, manual: manual, scope: scope, token: token)
  model = TargetModel.packet(target_name, packet_name, scope: scope)
  if model["subpacket"]
    msg_hash = DecomInterfaceTopic.get_tlm_buffer(target_name, packet_name, timeout: timeout, scope: scope)
    msg_hash['buffer'] = msg_hash['buffer'].b
    return msg_hash
  else
    topic = "#{scope}__TELEMETRY__{#{target_name}}__#{packet_name}"
    db_shard = Store.db_shard_for_target(target_name, scope: scope)
    msg_id, msg_hash = Topic.get_newest_message(topic, db_shard: db_shard)
    if msg_id
      msg_hash['buffer'] = msg_hash['buffer'].b
      return msg_hash
    end
  end
  return nil
end

#get_tlm_cnt(*args, manual: false, 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



501
502
503
504
505
506
 
# File 'lib/openc3/api/tlm_api.rb', line 501

def get_tlm_cnt(*args, manual: false, 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, manual: manual, scope: scope, token: token)
  TargetModel.packet(target_name, packet_name, scope: scope)
  return TargetModel.get_telemetry_count(target_name, packet_name, scope: scope)
end

#get_tlm_cnts(target_packets, manual: false, 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



512
513
514
515
 
# File 'lib/openc3/api/tlm_api.rb', line 512

def get_tlm_cnts(target_packets, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', manual: manual, scope: scope, token: token)
  return TargetModel.get_telemetry_counts(target_packets, scope: scope)
end

#get_tlm_packet(*args, stale_time: 30, type: :CONVERTED, cache_timeout: nil, manual: false, 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

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) 


243
244
245
246
247
248
249
250
251
252
253
254
 
# File 'lib/openc3/api/tlm_api.rb', line 243

def get_tlm_packet(*args, stale_time: 30, type: :CONVERTED, cache_timeout: nil, manual: false, 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, manual: manual, 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"].reject { | item | item["hidden"] }
  items = 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, manual: false, start_time: nil, end_time: 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



325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
 
# File 'lib/openc3/api/tlm_api.rb', line 325

def get_tlm_values(items, stale_time: 30, cache_timeout: nil, manual: false, start_time: nil, end_time: nil, scope: $openc3_scope, token: $openc3_token)
  if !items.is_a?(Array)
    raise ArgumentError, "items must be array of strings: ['TGT__PKT__ITEM__TYPE', ...]"
  end
  packets = []
  cvt_items = []
  items.each_with_index do |item, index|
    if item.nil?
      # null items mean that it doesn't exist
      cvt_items[index] = nil
    else
      item_upcase = item.to_s.upcase
      target_name, packet_name, item_name, value_type, limits = 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?
      if packet_name == 'LATEST' # Lookup packet_name in case of LATEST
        packet_name = CvtModel.determine_latest_packet_for_item(target_name, item_name, cache_timeout: cache_timeout, scope: scope)
      end
    end
    cvt_items[index] = [target_name, packet_name, item_name, value_type, limits]
    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, manual: manual, scope: scope, token: token)
  end
  CvtModel.get_tlm_values(cvt_items, stale_time: stale_time, cache_timeout: cache_timeout, start_time: start_time, end_time: end_time, scope: scope)
end

#inject_tlm(target_name, packet_name, item_hash = nil, type: :CONVERTED, stored: false, manual: false, 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



120
121
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
156
157
158
159
160
161
162
 
# File 'lib/openc3/api/tlm_api.rb', line 120

def inject_tlm(target_name, packet_name, item_hash = nil, type: :CONVERTED, stored: false, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm_set', target_name: target_name, packet_name: packet_name, manual: manual, 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
    items = TargetModel.packet_items(target_name, packet_name, item_hash.keys, scope: scope)
    if type == :CONVERTED
      # If the type is converted, check that the item states are valid
      item_hash.each do |item_name, item_value|
        item = items.find { |i| i['name'] == item_name.to_s.upcase }
        if item['states'] && !item['states'][item_value]
          raise "Unknown state '#{item_value}' for #{item['name']}, must be one of #{item['states'].keys.join(', ')}"
        end
      end
    end
  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, stored: stored, scope: scope)
  else
    DecomInterfaceTopic.inject_tlm(target_name, packet_name, item_hash, type: type, stored: stored, scope: scope)
  end
end

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



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

def interface_cmd(interface_name, cmd_name, *cmd_params, manual: false, scope: $openc3_scope, token: $openc3_token)
  # TODO: Check if they have command authority for the targets mapped to this interface
  authorize(permission: 'system_set', interface_name: interface_name, manual: manual, scope: scope, token: token)
  InterfaceTopic.interface_cmd(interface_name, cmd_name, *cmd_params, scope: scope)
end

#interface_details(interface_name, manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



223
224
225
226
 
# File 'lib/openc3/api/interface_api.rb', line 223

def interface_details(interface_name, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', interface_name: interface_name, manual: manual, scope: scope, token: token)
  InterfaceTopic.interface_details(interface_name, scope: scope)
end

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



183
184
185
186
187
 
# File 'lib/openc3/api/interface_api.rb', line 183

def interface_protocol_cmd(interface_name, cmd_name, *cmd_params, read_write: :READ_WRITE, index: -1, manual: false, scope: $openc3_scope, token: $openc3_token)
  # TODO: Check if they have command authority for the targets mapped to this interface
  authorize(permission: 'system_set', interface_name: interface_name, manual: manual, scope: scope, token: token)
  InterfaceTopic.protocol_cmd(interface_name, cmd_name, *cmd_params, read_write: read_write, index: index, scope: scope)
end

#interface_target_disable(interface_name, target_name, cmd_only: false, tlm_only: false, manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



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

def interface_target_disable(interface_name, target_name, cmd_only: false, tlm_only: false, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', interface_name: interface_name, manual: manual, scope: scope, token: token)
  interface = InterfaceModel.get_model(name: interface_name, scope: scope)
  if cmd_only and tlm_only
    cmd_only = false
    tlm_only = false
  end
  if not tlm_only
    interface.cmd_target_enabled[target_name.upcase] = false
  end
  if not cmd_only
    interface.tlm_target_enabled[target_name.upcase] = false
  end
  interface.update
  InterfaceTopic.interface_target_disable(interface_name, target_name, cmd_only: cmd_only, tlm_only: tlm_only, scope: scope)
end

#interface_target_enable(interface_name, target_name, cmd_only: false, tlm_only: false, manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/openc3/api/interface_api.rb', line 189

def interface_target_enable(interface_name, target_name, cmd_only: false, tlm_only: false, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', interface_name: interface_name, manual: manual, scope: scope, token: token)
  interface = InterfaceModel.get_model(name: interface_name, scope: scope)
  if cmd_only and tlm_only
    cmd_only = false
    tlm_only = false
  end
  if not tlm_only
    interface.cmd_target_enabled[target_name.upcase] = true
  end
  if not cmd_only
    interface.tlm_target_enabled[target_name.upcase] = true
  end
  interface.update
  InterfaceTopic.interface_target_enable(interface_name, target_name, cmd_only: cmd_only, tlm_only: tlm_only, scope: scope)
end

#limits_enabled?(*args, manual: false, 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 item



106
107
108
109
110
 
# File 'lib/openc3/api/limits_api.rb', line 106

def limits_enabled?(*args, manual: false, 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, manual: manual, scope: scope, token: token)
  return TargetModel.packet_item(target_name, packet_name, item_name, scope: scope)['limits']['enabled'] ? true : false
end

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



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

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

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



45
46
47
48
 
# File 'lib/openc3/api/settings_api.rb', line 45

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

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



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

def load_config(tool, name, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', manual: manual, 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, manual: false, 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



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/openc3/api/interface_api.rb', line 137

def map_target_to_interface(target_name, interface_name, cmd_only: false, tlm_only: false, unmap_old: true, manual: false, scope: $openc3_scope, token: $openc3_token)
  # TODO: Check if they have command authority for the targets mapped to this interface
  authorize(permission: 'system_set', interface_name: interface_name, manual: manual, scope: scope, token: token)
  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|
    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

#map_target_to_router(target_name, router_name, cmd_only: false, tlm_only: false, unmap_old: true, manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Associates a target and all its commands and telemetry with a particular router.

Parameters:

  • target_name (String/Array) —

    The name of the target(s)

  • router_name (String) —

    Name of router



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

def map_target_to_router(target_name, router_name, cmd_only: false, tlm_only: false, unmap_old: true, manual: false, scope: $openc3_scope, token: $openc3_token)
  # TODO: Check if they have command authority for the targets mapped to this router
  authorize(permission: 'system_set', router_name: router_name, manual: manual, scope: scope, token: token)
  router = RouterModel.get_model(name: router_name, scope: scope)
  raise "Router '#{router_name}' does not exist" unless router

  if Array === target_name
    target_names = target_name
  else
    target_names = [target_name]
  end
  target_names.each do |name|
    router.map_target(name, cmd_only: cmd_only, tlm_only: tlm_only, unmap_old: unmap_old)
    Logger.info("Target #{name} mapped to Router #{router_name}", scope: scope)
  end
  nil
end

#normalize_tlm(*args, type: :ALL, manual: false, 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 Also takes :ALL which means to normalize all telemetry types



203
204
205
206
207
 
# File 'lib/openc3/api/tlm_api.rb', line 203

def normalize_tlm(*args, type: :ALL, manual: false, 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, manual: manual, scope: scope, token: token)
  CvtModel.normalize(target_name, packet_name, item_name, type: type.intern, scope: scope)
end

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



25
26
27
28
29
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
 
# File 'lib/openc3/api/offline_access_api.rb', line 25

def offline_access_needed(manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', manual: manual, scope: scope, token: token)
  begin
    authorize(permission: 'script_view', manual: manual, 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, manual: false, 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



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

def override_tlm(*args, type: :ALL, manual: false, 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, manual: manual, 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, manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



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

def router_cmd(router_name, cmd_name, *cmd_params, manual: false, scope: $openc3_scope, token: $openc3_token)
  # TODO: Check if they have command authority for the targets mapped to this router
  authorize(permission: 'system_set', router_name: router_name, manual: manual, scope: scope, token: token)
  RouterTopic.router_cmd(router_name, cmd_name, *cmd_params, scope: scope)
end

#router_details(router_name, manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



218
219
220
221
 
# File 'lib/openc3/api/router_api.rb', line 218

def router_details(router_name, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system', router_name: router_name, manual: manual, scope: scope, token: token)
  RouterTopic.router_details(router_name, scope: scope)
end

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



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

def router_protocol_cmd(router_name, cmd_name, *cmd_params, read_write: :READ_WRITE, index: -1, manual: false, scope: $openc3_scope, token: $openc3_token)
  # TODO: Check if they have command authority for the targets mapped to this router
  authorize(permission: 'system_set', router_name: router_name, manual: manual, scope: scope, token: token)
  RouterTopic.protocol_cmd(router_name, cmd_name, *cmd_params, read_write: read_write, index: index, scope: scope)
end

#router_target_disable(router_name, target_name, cmd_only: false, tlm_only: false, manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/openc3/api/router_api.rb', line 201

def router_target_disable(router_name, target_name, cmd_only: false, tlm_only: false, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', router_name: router_name, manual: manual, scope: scope, token: token)
  router = RouterModel.get_model(name: router_name, scope: scope)
  if cmd_only and tlm_only
    cmd_only = false
    tlm_only = false
  end
  if not tlm_only
    router.cmd_target_enabled[target_name.upcase] = false
  end
  if not cmd_only
    router.tlm_target_enabled[target_name.upcase] = false
  end
  router.update
  RouterTopic.router_target_disable(router_name, target_name, cmd_only: cmd_only, tlm_only: tlm_only, scope: scope)
end

#router_target_enable(router_name, target_name, cmd_only: false, tlm_only: false, manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/openc3/api/router_api.rb', line 184

def router_target_enable(router_name, target_name, cmd_only: false, tlm_only: false, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'system_set', router_name: router_name, manual: manual, scope: scope, token: token)
  router = RouterModel.get_model(name: router_name, scope: scope)
  if cmd_only and tlm_only
    cmd_only = false
    tlm_only = false
  end
  if not tlm_only
    router.cmd_target_enabled[target_name.upcase] = true
  end
  if not cmd_only
    router.tlm_target_enabled[target_name.upcase] = true
  end
  router.update
  RouterTopic.router_target_enable(router_name, target_name, cmd_only: cmd_only, tlm_only: tlm_only, scope: scope)
end

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



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

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

#send_raw(interface_name, data, manual: false, 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



166
167
168
169
170
171
172
173
174
 
# File 'lib/openc3/api/cmd_api.rb', line 166

def send_raw(interface_name, data, manual: false, scope: $openc3_scope, token: $openc3_token)
  interface_name = interface_name.upcase
  interface = get_interface(interface_name, scope: scope, token: token)
  # Verify we have command authority on all the targets mapped to this interface
  interface['cmd_target_names'].each do |target_name|
    authorize(permission: 'cmd_raw', interface_name: interface_name, target_name: target_name, manual: manual, scope: scope, token: token)
  end
  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, manual: false, 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.



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

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,
               manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm_set', target_name: target_name, packet_name: packet_name, manual: manual, 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']['enabled'] = false
        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, manual: false, 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



287
288
289
290
291
292
293
 
# File 'lib/openc3/api/limits_api.rb', line 287

def set_limits_set(limits_set, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'tlm_set', manual: manual, 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, manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



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

def set_offline_access(offline_access_token, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'script_view', manual: manual, 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, manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object Also known as: save_setting 



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

def set_setting(name, data, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'admin', manual: manual, scope: scope, token: token)
  SettingModel.set({ name: name, data: data }, scope: scope)
  LocalMode.save_setting(scope, name, data)
  username = (token)['username'] || 'Anonymous'
  Logger.info("User #{username} saved setting '#{name}': #{data}", scope: scope, user: username)
end

#set_tlm(*args, type: :CONVERTED, manual: false, cache_timeout: nil, 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



108
109
110
111
112
 
# File 'lib/openc3/api/tlm_api.rb', line 108

def set_tlm(*args, type: :CONVERTED, manual: false, cache_timeout: nil, scope: $openc3_scope, token: $openc3_token)
  target_name, packet_name, item_name, value = _set_tlm_process_args(args, __method__, cache_timeout: cache_timeout, scope: scope)
  authorize(permission: 'tlm_set', target_name: target_name, packet_name: packet_name, manual: manual, 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', manual: false, 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



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

def start_raw_logging_interface(interface_name = 'ALL', manual: false, scope: $openc3_scope, token: $openc3_token)
  # TODO: Check if they have command authority for the targets mapped to this interface
  authorize(permission: 'system_set', interface_name: interface_name, manual: manual, 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', manual: false, 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



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

def start_raw_logging_router(router_name = 'ALL', manual: false, scope: $openc3_scope, token: $openc3_token)
  # TODO: Check if they have command authority for the targets mapped to this router
  authorize(permission: 'system_set', router_name: router_name, manual: manual, 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(manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



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

def stash_all(manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'script_view', manual: manual, 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, manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



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

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

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



32
33
34
35
36
37
38
39
40
 
# File 'lib/openc3/api/stash_api.rb', line 32

def stash_get(key, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'script_view', manual: manual, 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(manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object 



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

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

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



27
28
29
30
 
# File 'lib/openc3/api/stash_api.rb', line 27

def stash_set(key, value, manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'script_run', manual: manual, 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', manual: false, 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



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

def stop_raw_logging_interface(interface_name = 'ALL', manual: false, scope: $openc3_scope, token: $openc3_token)
  # TODO: Check if they have command authority for the targets mapped to this interface
  authorize(permission: 'system_set', interface_name: interface_name, manual: manual, 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', manual: false, 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



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

def stop_raw_logging_router(router_name = 'ALL', manual: false, scope: $openc3_scope, token: $openc3_token)
  # TODO: Check if they have command authority for the targets mapped to this router
  authorize(permission: 'system_set', router_name: router_name, manual: manual, 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, manual: false, 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



439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
 
# File 'lib/openc3/api/tlm_api.rb', line 439

def subscribe_packets(packets, manual: false, 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

  results = {}
  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, manual: manual, scope: scope, token: token)
    topic = "#{scope}__DECOM__{#{target_name}}__#{packet_name}"
    db_shard = Store.db_shard_for_target(target_name, scope: scope)
    id, = Topic.get_newest_message(topic, db_shard: db_shard)
    results[topic] = id ? id : '0-0'
  end
  results.to_a.join(SUBSCRIPTION_DELIMITER)
end

#tlm(*args, type: :CONVERTED, cache_timeout: nil, manual: false, 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

Returns:

  • (Object) —

    The telemetry value formatted as requested



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

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



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

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

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



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

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

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

Deprecated.

Use tlm_formatted



89
90
91
 
# File 'lib/openc3/api/tlm_api.rb', line 89

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

#unmap_target_from_interface(target_name, interface_name, cmd_only: false, tlm_only: false, manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Removes association of a target and all its commands and telemetry with a particular interface. No commands will go out over and no telemetry be received from that interface for the target.

Parameters:

  • target_name (String/Array) —

    The name of the target(s)

  • interface_name (String) —

    The name of the interface



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/openc3/api/interface_api.rb', line 159

def unmap_target_from_interface(target_name, interface_name, cmd_only: false, tlm_only: false, manual: false, scope: $openc3_scope, token: $openc3_token)
  # TODO: Check if they have command authority for the targets mapped to this interface
  authorize(permission: 'system_set', interface_name: interface_name, manual: manual, scope: scope, token: token)
  interface = InterfaceModel.get_model(name: interface_name, scope: scope)
  raise "Interface '#{interface_name}' does not exist" unless interface

  if Array === target_name
    target_names = target_name
  else
    target_names = [target_name]
  end
  target_names.each do |name|
    interface.unmap_target(name, cmd_only: cmd_only, tlm_only: tlm_only)
    Logger.info("Target #{name} unmapped from Interface #{interface_name}", scope: scope)
  end
  nil
end

#unmap_target_from_router(target_name, router_name, cmd_only: false, tlm_only: false, manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Removes association of a target and all its commands and telemetry with a particular router.

Parameters:

  • target_name (String/Array) —

    The name of the target(s)

  • router_name (String) —

    Name of router



166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/openc3/api/router_api.rb', line 166

def unmap_target_from_router(target_name, router_name, cmd_only: false, tlm_only: false, manual: false, scope: $openc3_scope, token: $openc3_token)
  # TODO: Check if they have command authority for the targets mapped to this router
  authorize(permission: 'system_set', router_name: router_name, manual: manual, scope: scope, token: token)
  router = RouterModel.get_model(name: router_name, scope: scope)
  raise "Router '#{router_name}' does not exist" unless router

  if Array === target_name
    target_names = target_name
  else
    target_names = [target_name]
  end
  target_names.each do |name|
    router.unmap_target(name, cmd_only: cmd_only, tlm_only: tlm_only)
    Logger.info("Target #{name} unmapped from Router #{router_name}", scope: scope)
  end
  nil
end

#update_news(manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Update the news feed on demand to respond to frontend setting changes



83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/openc3/api/settings_api.rb', line 83

def update_news(manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'admin', manual: manual, scope: scope, token: token)
  conn = Faraday.new(
    url: 'https://news.openc3.com',
    params: {version: VERSION, enterprise: ENTERPRISE},
  )
  response = conn.get('/news')
  if response.success?
    NewsModel.set(response.body)
  else
    NewsModel.news_error("Error contacting OpenC3 news feed (status: #{response.status})")
  end

  # Test code to update the news feed with a dummy message
  # data = NewsModel.all()
  # json = JSON.parse(data)
  # json.unshift( { date: Time.now.utc.iso8601, title: "News at #{Time.now}", body: "The news feed has been updated at #{Time.now}." })
  # json.pop if json.length > 5
  # NewsModel.set(json.to_json)
rescue Exception => e
  NewsModel.news_error("Error contacting OpenC3 news feed. #{e.message})")
end

#update_plugin_store(manual: false, scope: $openc3_scope, token: $openc3_token) ⇒ Object

Update the local copy of the plugin store data



107
108
109
110
 
# File 'lib/openc3/api/settings_api.rb', line 107

def update_plugin_store(manual: false, scope: $openc3_scope, token: $openc3_token)
  authorize(permission: 'admin', manual: manual, scope: scope, token: token)
  PluginStoreModel.update()
end