Class: OpenC3::Packet
- Defined in:
- lib/openc3/packets/packet.rb,
lib/openc3/utilities/simulated_target.rb,
ext/openc3/ext/packet/packet.c
Overview
Adds features common to all OpenC3 packets of data to the Structure class. This includes the additional attributes listed below. The primary behavior Packet adds is the ability to apply formatting to PacketItem values as well as managing PacketItem’s limit states.
Direct Known Subclasses
Constant Summary collapse
- RESERVED_ITEM_NAMES =
['PACKET_TIMESECONDS'.freeze, 'PACKET_TIMEFORMATTED'.freeze, 'RECEIVED_TIMESECONDS'.freeze, 'RECEIVED_TIMEFORMATTED'.freeze, 'RECEIVED_COUNT'.freeze]
- ANY_STATE =
'ANY'
- VALUE_TYPES =
Valid format types
[:RAW, :CONVERTED, :FORMATTED, :WITH_UNITS]
Instance Attribute Summary collapse
-
#abstract ⇒ Boolean
Whether or not this is a ‘abstract’ packet.
-
#cmd_or_tlm ⇒ Symbol
:CMD or :TLM.
-
#description ⇒ String
Description of the packet.
-
#disabled ⇒ Boolean
Whether or not this is a ‘disabled’ packet.
-
#error_response ⇒ Array<Target Name, Packet Name>
Related error response packet.
-
#extra ⇒ Hash
Extra data to be logged/transferred with packet.
-
#given_values ⇒ Hash<Item Name, Value>
Contains the values given by the user for a command (distinguished from defaults) These values should be used within command conversions if present because the order that values are written into the actual packet can vary.
-
#hazardous ⇒ Boolean
Flag indicating if the packet is hazardous (typically for commands).
-
#hazardous_description ⇒ String
Description of why the packet is hazardous.
-
#hidden ⇒ Boolean
Whether or not this is a ‘hidden’ packet.
-
#ignore_overlap ⇒ Boolean
Whether to ignore overlapping items.
-
#messages_disabled ⇒ Boolean
Whether or not messages should be printed for this packet.
-
#packet_name ⇒ String
Name of the packet.
-
#packet_rate ⇒ Object
Returns the value of attribute packet_rate.
-
#raw ⇒ Boolean
Whether or not this is a ‘raw’ packet.
-
#received_count ⇒ Integer
Number of times the packet has been received.
-
#received_time ⇒ Time
Time at which the packet was received.
-
#related_items ⇒ Array<Array<Target Name, Packet Name, Item Name>>
Related items.
-
#response ⇒ Array<Target Name, Packet Name>
Related response packet.
-
#screen ⇒ Array<Target Name, Screen Name>
Related telemetry screen.
-
#stored ⇒ Boolean
Whether or not this was a stored packet.
-
#target_name ⇒ String
Name of the target this packet is associated with.
-
#template ⇒ String
Base data for building packet.
-
#virtual ⇒ Boolean
If this packet should be used for identification.
Class Method Summary collapse
- .from_json(hash) ⇒ Object
-
.next_bit_offset(item) ⇒ Integer
Returns the bit offset of the next item after the current item if items are packed.
Instance Method Summary collapse
-
#append_item(name, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR, format_string = nil, read_conversion = nil, write_conversion = nil, id_value = nil) ⇒ PacketItem
Define an item at the end of the packet.
- #as_json(*a) ⇒ Object
-
#buffer=(buffer) ⇒ Object
Set the buffer to be used by the structure.
-
#check_bit_offsets ⇒ Array<String>
Review bit offset to look for overlapping definitions.
-
#check_limits(limits_set = :DEFAULT, ignore_persistence = false) ⇒ Object
Check all the items in the packet against their defined limits.
-
#clear_all_non_derived_items ⇒ Object
Reset the packet to just derived items.
- #clear_config_name ⇒ Object
-
#clone ⇒ Packet
(also: #dup)
Make a light weight clone of this packet.
-
#config_name ⇒ Object
Calculates a unique hashing sum that changes if the parts of the packet configuration change that could affect the “shape” of the packet.
- #decom ⇒ Object
-
#define(item) ⇒ PacketItem
Add an item to the packet by adding it to the items hash.
-
#define_item(name, bit_offset, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR, format_string = nil, read_conversion = nil, write_conversion = nil, id_value = nil) ⇒ PacketItem
Define an item in the packet.
-
#define_reserved_items ⇒ Object
Define the reserved items on the current telemetry packet.
-
#disable_limits(name) ⇒ Object
Disable limits on an item by name.
-
#enable_limits(name) ⇒ Object
Enable limits on an item by name.
-
#formatted(value_type = :CONVERTED, indent = 0, buffer = @buffer, ignored = nil) ⇒ String
Create a string that shows the name and value of each item in the packet.
-
#get_item(name) ⇒ StructureItem
StructureItem or one of its subclasses.
-
#id_items ⇒ Array<PacketItem>
Id items are used by the identify? method to determine if a raw buffer of data represents this packet.
-
#identified? ⇒ TrueClass or FalseClass
Indicates if the packet has been identified.
-
#identify?(buffer) ⇒ Boolean
Tries to identify if a buffer represents the currently defined packet.
-
#initialize(*args) ⇒ Object
constructor
Creates a new packet by initalizing the attributes.
-
#limits_change_callback=(limits_change_callback) ⇒ Object
Sets the callback object called when a limits state changes.
-
#limits_items ⇒ Array<PacketItem>
All items with defined limits.
-
#meta ⇒ Hash<Meta Name, Meta Values>
Returns packet specific metadata.
-
#meta=(meta) ⇒ Object
Sets packet specific metadata.
-
#out_of_limits ⇒ Array<Array<String, String, String, Symbol>>
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], …].
-
#packed? ⇒ Boolean
Checks if the packet has any gaps or overlapped items.
-
#packet_time ⇒ Object
Returns @received_time unless a packet item called PACKET_TIME exists that returns a Ruby Time object that represents a different timestamp for the packet.
- #packet_time=(time) ⇒ Object
-
#process(buffer = @buffer) ⇒ Object
Performs packet specific processing on the packet.
-
#processors ⇒ Hash
Hash of processors associated with this packet.
-
#read(name, value_type = :CONVERTED, buffer = @buffer) ⇒ Object
Read an item in the packet by name.
-
#read_all(value_type = :CONVERTED, buffer = @buffer, top = true) ⇒ Array<Array>
Read all items in the packet into an array of arrays [[item name, item value], …].
-
#read_all_with_limits_states(value_type = :CONVERTED, buffer = @buffer) ⇒ Array<String, Object, Symbol|nil>
Read all items in the packet into an array of arrays [[item name, item value], [item limits state], …].
-
#read_id_values(buffer) ⇒ Array
Reads the values from a buffer at the position of each id_item defined in the packet.
-
#read_item(item, value_type = :CONVERTED, buffer = @buffer, given_raw = nil) ⇒ Object
Read an item in the packet.
-
#read_items(items, value_type = :RAW, buffer = @buffer, _raw_value = nil) ⇒ Object
Read a list of items in the structure.
-
#reset ⇒ Object
Reset temporary packet data This includes packet received time, received count, and processor state.
-
#restore_defaults(buffer = @buffer, skip_item_names = nil, use_template = true) ⇒ Object
Restore all items in the packet to their default value.
-
#set_received_time_fast(received_time) ⇒ Object
Sets the received time of the packet (without cloning).
- #to_config(cmd_or_tlm) ⇒ Object
- #update_id_items(item) ⇒ Object
-
#update_limits_items_cache(item) ⇒ Object
Add an item to the limits items cache if necessary.
-
#write(name, value, value_type = :CONVERTED, buffer = @buffer) ⇒ Object
Write an item in the packet by name.
-
#write_item(item, value, value_type = :CONVERTED, buffer = @buffer) ⇒ Object
Write an item in the packet.
-
#write_items(items, values, value_type = :RAW, buffer = @buffer) ⇒ Object
Write values to the buffer based on the item definitions.
Constructor Details
#initialize(*args) ⇒ Object
Creates a new packet by initalizing the attributes.
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 |
# File 'lib/openc3/packets/packet.rb', line 123 def initialize(target_name = nil, packet_name = nil, default_endianness = :BIG_ENDIAN, description = nil, buffer = nil, item_class = PacketItem) super(default_endianness, buffer, item_class) # Explictly call the defined setter methods self.target_name = target_name self.packet_name = packet_name self.description = description self.received_time = nil self.received_count = 0 @id_items = nil @hazardous = false @hazardous_description = nil @given_values = nil @limits_items = nil @processors = nil @limits_change_callback = nil @read_conversion_cache = nil @raw = nil @messages_disabled = false @meta = nil @hidden = false @disabled = false @stored = false @extra = nil @cmd_or_tlm = nil @template = nil @packet_time = nil @ignore_overlap = false @virtual = false end |
Instance Attribute Details
#abstract ⇒ Boolean
Returns Whether or not this is a ‘abstract’ packet.
78 79 80 |
# File 'lib/openc3/packets/packet.rb', line 78 def abstract @abstract end |
#cmd_or_tlm ⇒ Symbol
Returns :CMD or :TLM.
87 88 89 |
# File 'lib/openc3/packets/packet.rb', line 87 def cmd_or_tlm @cmd_or_tlm end |
#description ⇒ String
Returns Description of the packet.
45 46 47 |
# File 'lib/openc3/packets/packet.rb', line 45 def description @description end |
#disabled ⇒ Boolean
Returns Whether or not this is a ‘disabled’ packet.
72 73 74 |
# File 'lib/openc3/packets/packet.rb', line 72 def disabled @disabled end |
#error_response ⇒ Array<Target Name, Packet Name>
Returns Related error response packet.
96 97 98 |
# File 'lib/openc3/packets/packet.rb', line 96 def error_response @error_response end |
#extra ⇒ Hash
Returns Extra data to be logged/transferred with packet.
84 85 86 |
# File 'lib/openc3/packets/packet.rb', line 84 def extra @extra end |
#given_values ⇒ Hash<Item Name, Value>
Contains the values given by the user for a command (distinguished from defaults) These values should be used within command conversions if present because the order that values are written into the actual packet can vary
63 64 65 |
# File 'lib/openc3/packets/packet.rb', line 63 def given_values @given_values end |
#hazardous ⇒ Boolean
Returns Flag indicating if the packet is hazardous (typically for commands).
54 55 56 |
# File 'lib/openc3/packets/packet.rb', line 54 def hazardous @hazardous end |
#hazardous_description ⇒ String
Returns Description of why the packet is hazardous.
57 58 59 |
# File 'lib/openc3/packets/packet.rb', line 57 def hazardous_description @hazardous_description end |
#hidden ⇒ Boolean
Returns Whether or not this is a ‘hidden’ packet.
69 70 71 |
# File 'lib/openc3/packets/packet.rb', line 69 def hidden @hidden end |
#ignore_overlap ⇒ Boolean
Returns Whether to ignore overlapping items.
105 106 107 |
# File 'lib/openc3/packets/packet.rb', line 105 def ignore_overlap @ignore_overlap end |
#messages_disabled ⇒ Boolean
Returns Whether or not messages should be printed for this packet.
75 76 77 |
# File 'lib/openc3/packets/packet.rb', line 75 def @messages_disabled end |
#packet_name ⇒ String
Returns Name of the packet.
42 43 44 |
# File 'lib/openc3/packets/packet.rb', line 42 def packet_name @packet_name end |
#packet_rate ⇒ Object
Returns the value of attribute packet_rate.
29 30 31 |
# File 'lib/openc3/utilities/simulated_target.rb', line 29 def packet_rate @packet_rate end |
#raw ⇒ Boolean
Returns Whether or not this is a ‘raw’ packet.
66 67 68 |
# File 'lib/openc3/packets/packet.rb', line 66 def raw @raw end |
#received_count ⇒ Integer
Returns Number of times the packet has been received.
51 52 53 |
# File 'lib/openc3/packets/packet.rb', line 51 def received_count @received_count end |
#received_time ⇒ Time
Returns Time at which the packet was received.
48 49 50 |
# File 'lib/openc3/packets/packet.rb', line 48 def received_time @received_time end |
#related_items ⇒ Array<Array<Target Name, Packet Name, Item Name>>
Returns Related items.
102 103 104 |
# File 'lib/openc3/packets/packet.rb', line 102 def @related_items end |
#response ⇒ Array<Target Name, Packet Name>
Returns Related response packet.
93 94 95 |
# File 'lib/openc3/packets/packet.rb', line 93 def response @response end |
#screen ⇒ Array<Target Name, Screen Name>
Returns Related telemetry screen.
99 100 101 |
# File 'lib/openc3/packets/packet.rb', line 99 def screen @screen end |
#stored ⇒ Boolean
Returns Whether or not this was a stored packet.
81 82 83 |
# File 'lib/openc3/packets/packet.rb', line 81 def stored @stored end |
#target_name ⇒ String
Returns Name of the target this packet is associated with.
39 40 41 |
# File 'lib/openc3/packets/packet.rb', line 39 def target_name @target_name end |
#template ⇒ String
Returns Base data for building packet.
90 91 92 |
# File 'lib/openc3/packets/packet.rb', line 90 def template @template end |
#virtual ⇒ Boolean
Returns If this packet should be used for identification.
108 109 110 |
# File 'lib/openc3/packets/packet.rb', line 108 def virtual @virtual end |
Class Method Details
.from_json(hash) ⇒ Object
1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 |
# File 'lib/openc3/packets/packet.rb', line 1186 def self.from_json(hash) endianness = hash['endianness'] ? hash['endianness'].intern : nil # Convert to symbol packet = Packet.new(hash['target_name'], hash['packet_name'], endianness, hash['description']) packet.short_buffer_allowed = hash['short_buffer_allowed'] packet.hazardous = hash['hazardous'] packet.hazardous_description = hash['hazardous_description'] packet. = hash['messages_disabled'] packet.disabled = hash['disabled'] packet.hidden = hash['hidden'] packet.virtual = hash['virtual'] if hash['accessor'] begin accessor = OpenC3::const_get(hash['accessor']) if hash['accessor_args'] and hash['accessor_args'].length > 0 packet.accessor = accessor.new(packet, *hash['accessor_args']) else packet.accessor = accessor.new(packet) end rescue => e Logger.instance.error "#{packet.target_name} #{packet.packet_name} accessor of #{hash['accessor']} could not be found due to #{e}" end end packet.template = Base64.decode64(hash['template']) if hash['template'] packet. = hash['meta'] # Can't convert processors hash['items'].each do |item| packet.define(PacketItem.from_json(item)) end if hash['response'] packet.response = hash['response'] end if hash['error_response'] packet.error_response = hash['error_response'] end if hash['screen'] packet.screen = hash['screen'] end if hash['related_items'] packet. = hash['related_items'] end packet.ignore_overlap = hash['ignore_overlap'] packet end |
.next_bit_offset(item) ⇒ Integer
Returns the bit offset of the next item after the current item if items are packed
449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 |
# File 'lib/openc3/packets/packet.rb', line 449 def self.next_bit_offset(item) if item.array_size if item.array_size > 0 next_offset = item.bit_offset + item.array_size else next_offset = item.array_size end else next_offset = nil if item.bit_offset > 0 if item.little_endian_bit_field? # Bit offset always refers to the most significant bit of a bitfield bits_remaining_in_last_byte = 8 - (item.bit_offset % 8) if item.bit_size > bits_remaining_in_last_byte next_offset = item.bit_offset + bits_remaining_in_last_byte end end end unless next_offset if item.bit_size > 0 next_offset = item.bit_offset + item.bit_size else next_offset = item.bit_size end end end next_offset end |
Instance Method Details
#append_item(name, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR, format_string = nil, read_conversion = nil, write_conversion = nil, id_value = nil) ⇒ PacketItem
Define an item at the end of the packet. This creates a new instance of the item_class as given in the constructor and adds it to the items hash. It also resizes the buffer to accomodate the new item.
569 570 571 572 |
# File 'lib/openc3/packets/packet.rb', line 569 def append_item(name, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR, format_string = nil, read_conversion = nil, write_conversion = nil, id_value = nil) item = super(name, bit_size, data_type, array_size, endianness, overflow) packet_define_item(item, format_string, read_conversion, write_conversion, id_value) end |
#as_json(*a) ⇒ Object
1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 |
# File 'lib/openc3/packets/packet.rb', line 1128 def as_json(*a) config = {} config['target_name'] = @target_name.to_s config['packet_name'] = @packet_name.to_s config['endianness'] = @default_endianness.to_s config['description'] = @description config['short_buffer_allowed'] = true if @short_buffer_allowed config['hazardous'] = true if @hazardous config['hazardous_description'] = @hazardous_description.to_s if @hazardous_description config['messages_disabled'] = true if @messages_disabled config['disabled'] = true if @disabled config['hidden'] = true if @hidden config['virtual'] = true if @virtual config['accessor'] = @accessor.class.to_s config['accessor_args'] = @accessor.args config['template'] = Base64.encode64(@template) if @template config['config_name'] = self.config_name if @processors processors = [] @processors.each do |_processor_name, processor| processors << processor.as_json(*a) end config['processors'] = processors end config['meta'] = @meta if @meta items = [] config['items'] = items # Items with derived items last @sorted_items.each do |item| if item.data_type != :DERIVED items << item.as_json(*a) end end @sorted_items.each do |item| if item.data_type == :DERIVED items << item.as_json(*a) end end if @response config['response'] = @response end if @error_response config['error_response'] = @error_response end if @screen config['screen'] = @screen end if @related_items config['related_items'] = @related_items end config['ignore_overlap'] = true if @ignore_overlap config end |
#buffer=(buffer) ⇒ Object
Set the buffer to be used by the structure. The buffer is copied and thus further modifications to the buffer have no effect on the structure items.
324 325 326 327 328 329 330 331 332 333 |
# File 'lib/openc3/packets/packet.rb', line 324 def buffer=(buffer) synchronize() do begin internal_buffer_equals(buffer) rescue RuntimeError Logger.instance.error "#{@target_name} #{@packet_name} received with actual packet length of #{buffer.length} but defined length of #{@defined_length}" end @read_conversion_cache.clear if @read_conversion_cache end end |
#check_bit_offsets ⇒ Array<String>
Review bit offset to look for overlapping definitions. This will allow gaps in the packet, but not allow the same bits to be used for multiple variables.
410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 |
# File 'lib/openc3/packets/packet.rb', line 410 def check_bit_offsets if @ignore_overlap Logger.instance.debug("#{@target_name} #{@packet_name} has IGNORE_OVERLAP so bit overlaps ignored") return [] end expected_next_offset = nil previous_item = nil warnings = [] @sorted_items.each do |item| if expected_next_offset and (item.bit_offset < expected_next_offset) and !item.overlap msg = "Bit definition overlap at bit offset #{item.bit_offset} for packet #{@target_name} #{@packet_name} items #{item.name} and #{previous_item.name}" Logger.instance.warn(msg) warnings << msg end expected_next_offset = Packet.next_bit_offset(item) previous_item = item end warnings end |
#check_limits(limits_set = :DEFAULT, ignore_persistence = false) ⇒ Object
Check all the items in the packet against their defined limits. Update their internal limits state and persistence and call the limits_change_callback as necessary.
977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 |
# File 'lib/openc3/packets/packet.rb', line 977 def check_limits(limits_set = :DEFAULT, ignore_persistence = false) return unless @limits_items @limits_items.each do |item| # Verify limits monitoring is enabled for this item if item.limits.enabled value = read_item(item) # Handle state monitoring and value monitoring differently if item.states handle_limits_states(item, value) elsif item.limits.values handle_limits_values(item, value, limits_set, ignore_persistence) end end end end |
#clear_all_non_derived_items ⇒ Object
Reset the packet to just derived items
891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 |
# File 'lib/openc3/packets/packet.rb', line 891 def clear_all_non_derived_items @defined_length = 0 @defined_length_bits = 0 @pos_bit_size = 0 @neg_bit_size = 0 @fixed_size = true @short_buffer_allowed = false @id_items = nil @limits_items = nil new_items = {} new_sorted_items = [] @items.each do |name, item| if item.data_type == :DERIVED new_items[name] = item end end @sorted_items.each do |item| if item.data_type == :DERIVED new_sorted_items << item end end @items = new_items @sorted_items = new_sorted_items clear_config_name() end |
#clear_config_name ⇒ Object
319 320 321 |
# File 'lib/openc3/packets/packet.rb', line 319 def clear_config_name @config_name = nil end |
#clone ⇒ Packet Also known as: dup
Make a light weight clone of this packet. This only creates a new buffer of data and clones the processors. The defined packet items are the same.
1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 |
# File 'lib/openc3/packets/packet.rb', line 1022 def clone packet = super() if packet.instance_variable_get("@processors".freeze) packet.instance_variable_set("@processors".freeze, packet.processors.clone) packet.processors.each do |processor_name, processor| packet.processors[processor_name] = processor.clone end end packet.instance_variable_set("@read_conversion_cache".freeze, nil) packet.extra = JSON.parse(packet.extra.as_json(:allow_nan => true).to_json(:allow_nan => true), :allow_nan => true, :create_additions => true) if packet.extra # Deep copy using JSON packet end |
#config_name ⇒ Object
Calculates a unique hashing sum that changes if the parts of the packet configuration change that could affect the “shape” of the packet. This value is cached and that packet should not be changed if this method is being used
304 305 306 307 308 309 310 311 312 313 314 315 316 317 |
# File 'lib/openc3/packets/packet.rb', line 304 def config_name return @config_name if @config_name string = "#{@target_name} #{@packet_name}" @sorted_items.each do |item| string << " ITEM #{item.name} #{item.bit_offset} #{item.bit_size} #{item.data_type} #{item.array_size} #{item.endianness} #{item.overflow} #{item.states} #{item.read_conversion ? item.read_conversion.class : 'NO_CONVERSION'}" end # Use the hashing algorithm established by OpenC3::System digest = Digest::SHA256.new digest << string @config_name = digest.hexdigest @config_name end |
#decom ⇒ Object
1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 |
# File 'lib/openc3/packets/packet.rb', line 1231 def decom # Read all the RAW at once because this could be optimized by the accessor json_hash = read_items(@sorted_items) # Decom extra into the values (all raw) if @extra @extra.each do |key, value| json_hash[key.upcase] = value end end # Now read all other value types - no accessor required @sorted_items.each do |item| given_raw = json_hash[item.name] json_hash["#{item.name}__C"] = read_item(item, :CONVERTED, @buffer, given_raw) if item.states or (item.read_conversion and item.data_type != :DERIVED) json_hash["#{item.name}__F"] = read_item(item, :FORMATTED, @buffer, given_raw) if item.format_string json_hash["#{item.name}__U"] = read_item(item, :WITH_UNITS, @buffer, given_raw) if item.units limits_state = item.limits.state json_hash["#{item.name}__L"] = limits_state if limits_state end json_hash end |
#define(item) ⇒ PacketItem
Add an item to the packet by adding it to the items hash. It also resizes the buffer to accomodate the new item.
547 548 549 550 551 552 |
# File 'lib/openc3/packets/packet.rb', line 547 def define(item) item = super(item) update_id_items(item) update_limits_items_cache(item) item end |
#define_item(name, bit_offset, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR, format_string = nil, read_conversion = nil, write_conversion = nil, id_value = nil) ⇒ PacketItem
Define an item in the packet. This creates a new instance of the item_class as given in the constructor and adds it to the items hash. It also resizes the buffer to accomodate the new item.
537 538 539 540 |
# File 'lib/openc3/packets/packet.rb', line 537 def define_item(name, bit_offset, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR, format_string = nil, read_conversion = nil, write_conversion = nil, id_value = nil) item = super(name, bit_offset, bit_size, data_type, array_size, endianness, overflow) packet_define_item(item, format_string, read_conversion, write_conversion, id_value) end |
#define_reserved_items ⇒ Object
Define the reserved items on the current telemetry packet
872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 |
# File 'lib/openc3/packets/packet.rb', line 872 def define_reserved_items item = define_item('PACKET_TIMESECONDS', 0, 0, :DERIVED, nil, @default_endianness, :ERROR, '%0.6f', PacketTimeSecondsConversion.new) item.description = 'OpenC3 Packet Time (UTC, Floating point, Unix epoch)' item = define_item('PACKET_TIMEFORMATTED', 0, 0, :DERIVED, nil, @default_endianness, :ERROR, nil, PacketTimeFormattedConversion.new) item.description = 'OpenC3 Packet Time (Local time zone, Formatted string)' item = define_item('RECEIVED_TIMESECONDS', 0, 0, :DERIVED, nil, @default_endianness, :ERROR, '%0.6f', ReceivedTimeSecondsConversion.new) item.description = 'OpenC3 Received Time (UTC, Floating point, Unix epoch)' item = define_item('RECEIVED_TIMEFORMATTED', 0, 0, :DERIVED, nil, @default_endianness, :ERROR, nil, ReceivedTimeFormattedConversion.new) item.description = 'OpenC3 Received Time (Local time zone, Formatted string)' item = define_item('RECEIVED_COUNT', 0, 0, :DERIVED, nil, @default_endianness, :ERROR, nil, ReceivedCountConversion.new) item.description = 'OpenC3 packet received count' end |
#disable_limits(name) ⇒ Object
Disable limits on an item by name
927 928 929 930 931 932 933 934 935 |
# File 'lib/openc3/packets/packet.rb', line 927 def disable_limits(name) item = get_item(name) item.limits.enabled = false unless item.limits.state == :STALE old_limits_state = item.limits.state item.limits.state = nil @limits_change_callback.call(self, item, old_limits_state, nil, false) if @limits_change_callback end end |
#enable_limits(name) ⇒ Object
Enable limits on an item by name
920 921 922 |
# File 'lib/openc3/packets/packet.rb', line 920 def enable_limits(name) get_item(name).limits.enabled = true end |
#formatted(value_type = :CONVERTED, indent = 0, buffer = @buffer, ignored = nil) ⇒ String
Create a string that shows the name and value of each item in the packet
849 850 851 |
# File 'lib/openc3/packets/packet.rb', line 849 def formatted(value_type = :CONVERTED, indent = 0, buffer = @buffer, ignored = nil) return super(value_type, indent, buffer, ignored) end |
#get_item(name) ⇒ StructureItem
Returns StructureItem or one of its subclasses.
575 576 577 578 579 |
# File 'lib/openc3/packets/packet.rb', line 575 def get_item(name) return super(name) rescue ArgumentError raise "Packet item '#{@target_name} #{@packet_name} #{name.upcase}' does not exist" end |
#id_items ⇒ Array<PacketItem>
Id items are used by the identify? method to determine if a raw buffer of data represents this packet.
481 482 483 |
# File 'lib/openc3/packets/packet.rb', line 481 def id_items @id_items ||= [] end |
#identified? ⇒ TrueClass or FalseClass
Indicates if the packet has been identified
508 509 510 |
# File 'lib/openc3/packets/packet.rb', line 508 def identified? !@target_name.nil? && !@packet_name.nil? end |
#identify?(buffer) ⇒ Boolean
Tries to identify if a buffer represents the currently defined packet. It does this by iterating over all the packet items that were created with an ID value and checking whether that ID value is present at the correct location in the buffer.
Incorrectly sized buffers will still positively identify if there is enough data to match the ID values. This is to allow incorrectly sized packets to still be processed as well as possible given the incorrectly sized data.
238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 |
# File 'lib/openc3/packets/packet.rb', line 238 def identify?(buffer) return false unless buffer return false if @virtual return true unless @id_items @id_items.each do |item| begin value = read_item(item, :RAW, buffer) rescue Exception value = nil end return false if item.id_value != value end true end |
#limits_change_callback=(limits_change_callback) ⇒ Object
Sets the callback object called when a limits state changes
381 382 383 384 385 386 387 388 389 |
# File 'lib/openc3/packets/packet.rb', line 381 def limits_change_callback=(limits_change_callback) if limits_change_callback raise ArgumentError, "limits_change_callback must respond to call" unless limits_change_callback.respond_to?(:call) @limits_change_callback = limits_change_callback else @limits_change_callback = nil end end |
#limits_items ⇒ Array<PacketItem>
Returns All items with defined limits.
486 487 488 |
# File 'lib/openc3/packets/packet.rb', line 486 def limits_items @limits_items ||= [] end |
#meta ⇒ Hash<Meta Name, Meta Values>
Returns packet specific metadata
497 498 499 |
# File 'lib/openc3/packets/packet.rb', line 497 def @meta ||= {} end |
#meta=(meta) ⇒ Object
Sets packet specific metadata
502 503 504 |
# File 'lib/openc3/packets/packet.rb', line 502 def () @meta = end |
#out_of_limits ⇒ Array<Array<String, String, String, Symbol>>
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], ...]
956 957 958 959 960 961 962 963 964 965 966 967 |
# File 'lib/openc3/packets/packet.rb', line 956 def out_of_limits items = [] return items unless @limits_items @limits_items.each do |item| if item.limits.enabled && item.limits.state && PacketItemLimits::OUT_OF_LIMITS_STATES.include?(item.limits.state) items << [@target_name, @packet_name, item.name, item.limits.state] end end return items end |
#packed? ⇒ Boolean
Checks if the packet has any gaps or overlapped items
433 434 435 436 437 438 439 440 441 442 443 |
# File 'lib/openc3/packets/packet.rb', line 433 def packed? expected_next_offset = nil @sorted_items.each do |item| if expected_next_offset and item.bit_offset != expected_next_offset return false end expected_next_offset = Packet.next_bit_offset(item) end true end |
#packet_time ⇒ Object
Returns @received_time unless a packet item called PACKET_TIME exists that returns a Ruby Time object that represents a different timestamp for the packet
277 278 279 280 281 282 283 284 285 286 287 288 |
# File 'lib/openc3/packets/packet.rb', line 277 def packet_time item = @items['PACKET_TIME'.freeze] if item return read_item(item, :CONVERTED, @buffer) else if @packet_time return @packet_time else return @received_time end end end |
#packet_time=(time) ⇒ Object
290 291 292 |
# File 'lib/openc3/packets/packet.rb', line 290 def packet_time=(time) @packet_time = time end |
#process(buffer = @buffer) ⇒ Object
Performs packet specific processing on the packet. Intended to only be run once for each packet received
1257 1258 1259 1260 1261 1262 1263 |
# File 'lib/openc3/packets/packet.rb', line 1257 def process(buffer = @buffer) return unless @processors @processors.each do |_processor_name, processor| processor.call(self, buffer) end end |
#processors ⇒ Hash
Returns Hash of processors associated with this packet.
491 492 493 |
# File 'lib/openc3/packets/packet.rb', line 491 def processors @processors ||= {} end |
#read(name, value_type = :CONVERTED, buffer = @buffer) ⇒ Object
Read an item in the packet by name
799 800 801 |
# File 'lib/openc3/packets/packet.rb', line 799 def read(name, value_type = :CONVERTED, buffer = @buffer) return super(name, value_type, buffer) end |
#read_all(value_type = :CONVERTED, buffer = @buffer, top = true) ⇒ Array<Array>
Read all items in the packet into an array of arrays
[[item name, item value], ...]
820 821 822 |
# File 'lib/openc3/packets/packet.rb', line 820 def read_all(value_type = :CONVERTED, buffer = @buffer, top = true) return super(value_type, buffer, top) end |
#read_all_with_limits_states(value_type = :CONVERTED, buffer = @buffer) ⇒ Array<String, Object, Symbol|nil>
Read all items in the packet into an array of arrays
[[item name, item value], [item limits state], ...]
832 833 834 835 836 837 838 839 840 |
# File 'lib/openc3/packets/packet.rb', line 832 def read_all_with_limits_states(value_type = :CONVERTED, buffer = @buffer) result = nil synchronize_allow_reads(true) do result = read_all(value_type, buffer, false).map! do |array| array << @items[array[0]].limits.state end end return result end |
#read_id_values(buffer) ⇒ Array
Reads the values from a buffer at the position of each id_item defined in the packet.
260 261 262 263 264 265 266 267 268 269 270 271 272 273 |
# File 'lib/openc3/packets/packet.rb', line 260 def read_id_values(buffer) return [] unless buffer return [] unless @id_items values = [] @id_items.each do |item| values << read_item(item, :RAW, buffer) rescue Exception values << nil end values end |
#read_item(item, value_type = :CONVERTED, buffer = @buffer, given_raw = nil) ⇒ Object
Read an item in the packet
591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 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 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 |
# File 'lib/openc3/packets/packet.rb', line 591 def read_item(item, value_type = :CONVERTED, buffer = @buffer, given_raw = nil) if given_raw # Must clone this since value is returned value = given_raw.clone else value = super(item, :RAW, buffer) end derived_raw = false if item.data_type == :DERIVED && value_type == :RAW value_type = :CONVERTED derived_raw = true end case value_type when :RAW # Done above when :CONVERTED, :FORMATTED, :WITH_UNITS if item.read_conversion using_cached_value = false check_cache = buffer.equal?(@buffer) if check_cache and @read_conversion_cache synchronize_allow_reads() do if @read_conversion_cache[item] value = @read_conversion_cache[item] # Make sure cached value is not modified by anyone by creating # a deep copy if String === value value = value.clone elsif Array === value value = Marshal.load(Marshal.dump(value)) end using_cached_value = true end end end unless using_cached_value if item.array_size value.map! do |val, _index| item.read_conversion.call(val, self, buffer) end else value = item.read_conversion.call(value, self, buffer) end if check_cache synchronize_allow_reads() do @read_conversion_cache ||= {} @read_conversion_cache[item] = value # Make sure cached value is not modified by anyone by creating # a deep copy if String === value value = value.clone elsif Array === value value = Marshal.load(Marshal.dump(value)) end end end end end # Derived raw values perform read_conversions but nothing else return value if derived_raw # Convert from value to state if possible if item.states if Array === value value = value.map do |val, _index| if item.states.key(val) item.states.key(val) elsif item.states.values.include?(ANY_STATE) item.states.key(ANY_STATE) else apply_format_string_and_units(item, val, value_type) end end else state_value = item.states.key(value) if state_value value = state_value elsif item.states.values.include?(ANY_STATE) value = item.states.key(ANY_STATE) else value = apply_format_string_and_units(item, value, value_type) end end else if Array === value value = value.map do |val, _index| apply_format_string_and_units(item, val, value_type) end else value = apply_format_string_and_units(item, value, value_type) end end else # Trim a potentially long string (like if they accidentally pass buffer as value_type) if value_type.to_s.length > 10 value_type = value_type.to_s[0...10] # Ensure we're not trying to output binary value_type = value_type.simple_formatted unless value_type.is_printable? value_type += '...' end raise ArgumentError, "Unknown value type '#{value_type}', must be :RAW, :CONVERTED, :FORMATTED, or :WITH_UNITS" end return value end |
#read_items(items, value_type = :RAW, buffer = @buffer, _raw_value = nil) ⇒ Object
Read a list of items in the structure
707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 |
# File 'lib/openc3/packets/packet.rb', line 707 def read_items(items, value_type = :RAW, buffer = @buffer, _raw_value = nil) buffer = allocate_buffer_if_needed() unless buffer if value_type == :RAW result = super(items, value_type, buffer) # Must handle DERIVED special items.each do |item| if item.data_type == :DERIVED result[item.name] = read_item(item, value_type, buffer) end end else result = {} items.each do |item| result[item.name] = read_item(item, value_type, buffer) end end return result end |
#reset ⇒ Object
Reset temporary packet data This includes packet received time, received count, and processor state
997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 |
# File 'lib/openc3/packets/packet.rb', line 997 def reset # The SYSTEM META packet is a special case that does not get reset return if @target_name == 'SYSTEM' && @packet_name == 'META' @received_time = nil @received_count = 0 @stored = false @extra = nil if @read_conversion_cache synchronize() do @read_conversion_cache.clear end end return unless @processors @processors.each do |_processor_name, processor| processor.reset end end |
#restore_defaults(buffer = @buffer, skip_item_names = nil, use_template = true) ⇒ Object
Restore all items in the packet to their default value
858 859 860 861 862 863 864 865 866 867 868 869 |
# File 'lib/openc3/packets/packet.rb', line 858 def restore_defaults(buffer = @buffer, skip_item_names = nil, use_template = true) buffer = allocate_buffer_if_needed() unless buffer upcase_skip_item_names = skip_item_names.map(&:upcase) if skip_item_names buffer.replace(@template) if @template and use_template @sorted_items.each do |item| next if RESERVED_ITEM_NAMES.include?(item.name) unless item.default.nil? write_item(item, item.default, :CONVERTED, buffer) unless skip_item_names and upcase_skip_item_names.include?(item.name) end end end |
#set_received_time_fast(received_time) ⇒ Object
Sets the received time of the packet (without cloning)
338 339 340 341 342 343 344 345 346 |
# File 'lib/openc3/packets/packet.rb', line 338 def set_received_time_fast(received_time) @received_time = received_time @received_time.freeze if @received_time if @read_conversion_cache synchronize() do @read_conversion_cache.clear end end end |
#to_config(cmd_or_tlm) ⇒ Object
1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 |
# File 'lib/openc3/packets/packet.rb', line 1056 def to_config(cmd_or_tlm) config = '' if cmd_or_tlm == :TELEMETRY config << "TELEMETRY #{@target_name.to_s.quote_if_necessary} #{@packet_name.to_s.quote_if_necessary} #{@default_endianness} \"#{@description}\"\n" else config << "COMMAND #{@target_name.to_s.quote_if_necessary} #{@packet_name.to_s.quote_if_necessary} #{@default_endianness} \"#{@description}\"\n" end if @accessor.class.to_s != 'OpenC3::BinaryAccessor' config << " ACCESSOR #{@accessor.class} #{@accessor.args.map { |a| a.to_s.quote_if_necessary }.join(" ")}\n" end # TODO: Add TEMPLATE_ENCODED so this can always be done inline regardless of content if @template config << " TEMPLATE '#{@template}'" end config << " ALLOW_SHORT\n" if @short_buffer_allowed config << " HAZARDOUS #{@hazardous_description.to_s.quote_if_necessary}\n" if @hazardous config << " DISABLE_MESSAGES\n" if @messages_disabled if @virtual config << " VIRTUAL\n" elsif @disabled config << " DISABLED\n" elsif @hidden config << " HIDDEN\n" end if @processors @processors.each do |_processor_name, processor| config << processor.to_config end end if @meta @meta.each do |key, values| config << " META #{key.to_s.quote_if_necessary} #{values.map { |a| a.to_s.quote_if_necessary }.join(" ")}\n" end end # Items with derived items last @sorted_items.each do |item| if item.data_type != :DERIVED config << item.to_config(cmd_or_tlm, @default_endianness) end end @sorted_items.each do |item| if item.data_type == :DERIVED unless RESERVED_ITEM_NAMES.include?(item.name) config << item.to_config(cmd_or_tlm, @default_endianness) end end end if @response config << " RESPONSE #{@response[0].to_s.quote_if_necessary} #{@response[1].to_s.quote_if_necessary}" end if @error_response config << " ERROR_RESPONSE #{@error_response[0].to_s.quote_if_necessary} #{@error_response[1].to_s.quote_if_necessary}" end if @screen config << " SCREEN #{@screen[0].to_s.quote_if_necessary} #{@screen[1].to_s.quote_if_necessary}" end if @related_items @related_items.each do |target_name, packet_name, item_name| config << " RELATED_ITEM #{target_name.to_s.quote_if_necessary} #{packet_name.to_s.quote_if_necessary} #{item_name.to_s.quote_if_necessary}" end end if @ignore_overlap config << " IGNORE_OVERLAP" end config end |
#update_id_items(item) ⇒ Object
1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 |
# File 'lib/openc3/packets/packet.rb', line 1036 def update_id_items(item) if item.id_value @id_items ||= [] # Add to Id Items unless @id_items.empty? last_item = @id_items[-1] @id_items << item # If the current item or last item have a negative offset then we have # to re-sort. We also re-sort if the current item is less than the last # item because we are inserting. if last_item.bit_offset <= 0 or item.bit_offset <= 0 or item.bit_offset < last_item.bit_offset @id_items = @id_items.sort end else @id_items << item end end item end |
#update_limits_items_cache(item) ⇒ Object
Add an item to the limits items cache if necessary. You MUST call this after adding limits to an item This is an optimization so we don’t have to iterate through all the items when checking for limits.
941 942 943 944 945 946 947 948 949 950 |
# File 'lib/openc3/packets/packet.rb', line 941 def update_limits_items_cache(item) if item.limits.values || item.state_colors @limits_items ||= [] @limits_items_hash ||= {} unless @limits_items_hash[item] @limits_items << item @limits_items_hash[item] = true end end end |
#write(name, value, value_type = :CONVERTED, buffer = @buffer) ⇒ Object
Write an item in the packet by name
809 810 811 |
# File 'lib/openc3/packets/packet.rb', line 809 def write(name, value, value_type = :CONVERTED, buffer = @buffer) super(name, value, value_type, buffer) end |
#write_item(item, value, value_type = :CONVERTED, buffer = @buffer) ⇒ Object
Write an item in the packet
732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 |
# File 'lib/openc3/packets/packet.rb', line 732 def write_item(item, value, value_type = :CONVERTED, buffer = @buffer) case value_type when :RAW super(item, value, value_type, buffer) when :CONVERTED if item.states # Convert from state to value if possible state_value = item.states[value.to_s.upcase] value = state_value if state_value end if item.write_conversion value = item.write_conversion.call(value, self, buffer) else raise "Cannot write DERIVED item #{item.name} without a write conversion" if item.data_type == :DERIVED and @accessor.enforce_derived_write_conversion(item) end begin super(item, value, :RAW, buffer) rescue ArgumentError => e if item.states and String === value and e. =~ /invalid value for/ raise "Unknown state #{value} for #{item.name}" else raise e end end when :FORMATTED, :WITH_UNITS raise ArgumentError, "Invalid value type on write: #{value_type}" else # Trim potentially long string (like if they accidentally pass buffer as value_type) if value_type.to_s.length > 10 value_type = value_type.to_s[0...10] # Ensure we're not trying to output binary value_type = value_type.simple_formatted unless value_type.is_printable? value_type += '...' end raise ArgumentError, "Unknown value type '#{value_type}', must be :RAW, :CONVERTED, :FORMATTED, or :WITH_UNITS" end if @read_conversion_cache synchronize() do @read_conversion_cache.clear end end end |
#write_items(items, values, value_type = :RAW, buffer = @buffer) ⇒ Object
Write values to the buffer based on the item definitions
781 782 783 784 785 786 787 788 789 790 791 |
# File 'lib/openc3/packets/packet.rb', line 781 def write_items(items, values, value_type = :RAW, buffer = @buffer) buffer = allocate_buffer_if_needed() unless buffer if value_type == :RAW return super(items, values, value_type, buffer) else items.each_with_index do |item, index| write_item(item, values[index], value_type, buffer) end end return buffer end |