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.