UnpackingInterface
A custom extendable cosmos interface that unpacks aggregate packets (packets with many granules/datapoints) into many simple packets (packets with a single granule/datapoint). This way we can use all the cosmos niceties without having to send packets for individual measurements. Essentially we unpack an aggregate packet into many packets that are stored in a queue that is read from. When the queue is empty we look for new aggregate packets
For more information about cosmos interfaces look here
Installation
Add this line to your application's Gemfile:
gem 'cosmos-unpacking_interface'
And then execute:
$ bundle
Or install it yourself as:
$ gem install cosmos-unpacking_interface
Usage
You will likely need to define your own custom PacketMapper. A PacketMapper handles mapping a cosmos packet into our internal representation, a BaseNameMap
. As an example you can look at the Rdoc generated docs in the docs
folder of this repository. An example is given here:
require 'cosmos/unpacking_interface'
##
# Example AggregatePacketMapper. This class encapsulates specific assumptions
# that can be made in mapping an aggregate packet into a BaseNameMap
module Cosmos
class MyPacketMapper < AggregatePacketMapper
##
# Maps an item name like 'VALUE_A_42' => 'VALUE_A'
def _get_normalized_key(str)
match = /(.+)_\d+/.match(str)
return str if match.nil?
m = match[1]
if m.nil?
str
else
m
end end
##
# Builds a BaseNameMap from an aggregate packet
def build_map(packet)
all_item_names = packet.items.keys
map = all_item_names.reduce({}) do |acc, raw_key|
value = packet.read(raw_key)
key = _get_normalized_key(raw_key)
if(_should_write(key))
acc[key] = [] if(acc[key].nil?)
acc[key] << value
end
acc
end
BaseNameMap.new(map, packet.packet_name)
end
##
# List of fields not to be included in BaseNameMap. These are mostly cosmos auto generated derived
# fields
def _should_write(k)
not_allowed = [
'RECEIVED_TIMESECONDS',
'RECEIVED_TIMEFORMATTED',
'RECEIVED_COUNT',
'PACKET_TIMESECONDS',
'PACKET_TIMEFORMATTED'
]
!not_allowed.include?(k)
end
end
end
A target is typically configured to use a specific interface in the cmd_tlm_server.txt
file. In order to use the unpacking interface, you must add a ruby file lib/my_interface
your cosmos project. It should define a class that extends UnpackingInterface
. Then in your cmd_tlm_server.txt
you should reference your file lib/my_interface
. As an example:
require 'cosmos'
require 'cosmos/unpacking_interface'
module Cosmos
##
# Maps aggregate packets (packets with many granules/readings) to simple packets (packets with a single granule/readings)
# should have the form 'AggregatePacket' => 'SimplePacket'
# For example: 'Science' => 'Science2'
AGG_PKT_MAP = {
'AGGREGATE_PACKET_NAME' => 'SIMPLE_PACKET_NAME'
}
##
# Transformations defined on an item in a simple packet. Entries should be of the
# form: "<TARGET>-<PACKET_NAME>-<ITEM_NAME>" => Proc
# where the proc can accept the following parameters TargetName, ItemName, key, value, index
# index is the index of the granule in the aggregate packet that was transformed into the simple packet
# More info about procs can be found here: https://ruby-doc.org/core-2.4.1/Proc.html
TRANSFORMS = {
'MYTARGET-PACKET-VALUE_A' => Proc.new do |target, item, key, value, index|
value # modify and return value
end
}
TARGET = 'MYTARGET'
class MyInterface < UnpackingInterface
def transforms
TRANSFORMS
end
def agg_pkt_map
AGG_PKT_MAP
end
def target
TARGET
end
def packet_mapper
MyPacketMapper.new
end
end
end
Development
Run rake test
to run the tests.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/nick-benoit14/cosmos-unpacking_interface
License
The gem is available as open source under the terms of the MIT License.