Document Subpackets by ryanmelt · Pull Request #2661 · OpenC3/cosmos

ryanmelt · 2025-12-20T17:00:01Z

No description provided.

codecov · 2025-12-20T17:00:53Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.25%. Comparing base (497ae9e) to head (72d90e5).
⚠️ Report is 54 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2661      +/-   ##
==========================================
+ Coverage   79.24%   79.25%   +0.01%     
==========================================
  Files         662      662              
  Lines       52401    52420      +19     
  Branches      734      734              
==========================================
+ Hits        41523    41545      +22     
+ Misses      10798    10795       -3     
  Partials       80       80

Flag	Coverage Δ
python	`81.25% <ø> (+0.02%)`	⬆️
ruby-api	`84.43% <ø> (+<0.01%)`	⬆️
ruby-backend	`82.22% <ø> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

jmthomas

I'd like to see links in the packet-types.md to all the keywords. At least when they're first mentioned.

For example: [VIRTUAL](/docs/configuration/telemetry#virtual) packets are used ...

jmthomas · 2025-12-21T05:52:01Z

docs.openc3.com/docs/guides/packet-types.md

+
+## Subpackets
+
+Subpackets are marked with the keyword SUBPACKET. Subpackets exist inside of regular packets and are identified and broken out during decom processing by a SUBPACKETIZER Python/Ruby class. Subpackets are used for channelized telemetry and for multi-sampled telemetry points in a regular packet. They can also be used for any content that may or may not be present in the parent packet. Note: because subpackets exist inside of regular packets, their is no "raw" version of a subpacket ie. the raw subpacket is part of its parent regular packet.


their is no "raw" -> there is no "raw"

jmthomas · 2025-12-21T06:01:05Z

docs.openc3.com/docs/guides/subpackets.md

+
+Packets are also the unit of data that COSMOS keeps track of with timestamps. Each packet has a received time (the time that COSMOS received the packet), and a packet time (the real time that the packet data was generated which is usually derived from the packet's own data). If no packet time is available then packet time is set to the received time.
+
+Each packet item therefore is part of a time-series with one sample per packet which can be graphed in TlmGrapher, extracted by DataExtractor or played back in TlmViewer.


We refer to the COSMOS tools in the docs using their full names: Telemetry Grapher, Data Extractor, Telemetry Viewer.

jmthomas · 2025-12-21T06:03:12Z

docs.openc3.com/docs/guides/subpackets.md

+
+Systems that produce channelized telemetry generally send down a single packet of telemetry that has variable content. The content within these packets are called channels.
+
+Each channel has some form of id field that let's you know what the rest of the channel's data is. Sometimes each channel has its own timestamp and sometimes the packet timestamp is applied to each channel.


field that let's you know what the rest of the channel's data is -> field that allows you to identify the channel data.

jmthomas · 2025-12-21T06:04:33Z

docs.openc3.com/docs/guides/subpackets.md

+
+The other use case for subpackets is when you have a single packet that has a lot of samples of the same data point in the same packet. Historically COSMOS would put all of these samples into an array item but that has several downsides.
+
+The primary downside is that you couldn't graph the data like a time series in TlmGrapher. Each of the samples generally has its own timestamp (generally derived from a known data rate), but that wasn't usable in TlmGrapher, because it only knows about the one packet timestamp per packet.


TlmGrapher -> Telemetry Grapher
(generally derived -> (typically derived
because it only knows about the one packet timestamp per packet -> because there is only one timestamp per packet.

jmthomas · 2025-12-21T06:07:47Z

docs.openc3.com/docs/guides/subpackets.md

+
+The primary downside is that you couldn't graph the data like a time series in TlmGrapher. Each of the samples generally has its own timestamp (generally derived from a known data rate), but that wasn't usable in TlmGrapher, because it only knows about the one packet timestamp per packet.
+
+Using a SUBPACKETIZER to breakup each sample into its own SUBPACKET solves this problem, and makes the entire series of subpackets available to TlmGrapher to graph.


TlmGrapher -> Telemetry Grapher

jmthomas · 2025-12-21T06:10:01Z

docs.openc3.com/docs/guides/subpackets.md

+
+## Defining a Subpacketizer
+
+A subpacketizer is added to the parent packet with the code necessary to break up it up into any internal subpackets.


up it up -> it up

jmthomas · 2025-12-21T06:11:52Z

docs.openc3.com/docs/guides/subpackets.md

+
+A subpacketizer is added to the parent packet with the code necessary to break up it up into any internal subpackets.
+
+Subpackets receive the parent packet as input and return an array of packets and subpackets as output. They can return 0 to as many subpackets as necessary. Note that if the parent packet is not returned, then it will not be processed.


They can return 0 to as many subpackets as necessary ... <= This needs more explanation. Return 0 as part of the array? What does that mean?

This meant that you can return zero subpackets. Reworded

jmthomas · 2025-12-21T06:12:25Z

docs.openc3.com/docs/guides/subpackets.md

+
+Subpackets receive the parent packet as input and return an array of packets and subpackets as output. They can return 0 to as many subpackets as necessary. Note that if the parent packet is not returned, then it will not be processed.
+
+The following show an example Subpacketizer class that works with the F-Prime Flight Software. Note that this is just one example. A Subpacketizer can contain whatever code necessary to break the packet into subpackets.


The following show an example -> The following is an example

jmthomas · 2025-12-21T06:18:47Z

docs.openc3.com/docs/guides/subpackets.md

+  APPEND_ITEM FPRIME_TIME_USEC 32 UINT
+  APPEND_ITEM RgMaxTime 32 UINT "Max execution time rate group"
+  ITEM PACKET_TIME 0 0 DERIVED "Python time based on FPRIME_TIME_SEC and FPRIME_TIME_USEC"
+    READ_CONVERSION openc3/conversions/unix_time_conversion.py FPRIME_TIME_SEC FPRIME_TIME_USEC


I imagine you'll have a bunch of these SUBPACKET blocks where the only difference is the packet name (ServerDeployment.rateGroup3.RgMaxTime) ID item value (1024) and the item name (RgMaxTime). Seems like a good choice for a partial where you pass those values in. Not sure if that's worth mentioning here or not. Are you going to publish your FPrime example and does that use partials?

FPrime example is autogenerated and does not use partials. Will be published eventually.

jmthomas · 2025-12-21T06:19:58Z

docs.openc3.com/docs/guides/subpackets.md

+                break
+
+        # Append the parent packet so it gets processed too
+        packets.append(packet)


Maybe somewhere in here describe your "return 0" comment with an example

Reworded this earlier. It means you could return an empty array to basically not decom anything.

clayandgen · 2025-12-22T16:45:55Z

docs.openc3.com/docs/guides/packet-types.md

+
+## Restricted Packets
+
+Restricted command packets require additional approval if critical commanding is enabled in COSMOS Enterprise.


I think a link to Critical Commanding for this and above would be helpful!

clayandgen · 2025-12-22T16:46:22Z

docs.openc3.com/docs/guides/subpackets.md

+  myEmoji: 🧩
+---
+
+The unit of processing within COSMOS is a packet. Telemetry packets coming into COSMOS are deliniated and identified in Interfaces, and sometimes the same is done for commands being received by Routers.


sp, delineated

Document Subpackets

3f56593

ryanmelt requested review from EmilyRagan, clayandgen, jmthomas, mcosgriff and ryan-pratt December 20, 2025 17:00

jmthomas requested changes Dec 21, 2025

View reviewed changes

clayandgen reviewed Dec 22, 2025

View reviewed changes

Incorporate review comments

72d90e5

clayandgen approved these changes Dec 23, 2025

View reviewed changes

ryan-pratt approved these changes Dec 24, 2025

View reviewed changes

ryanmelt merged commit 3becf52 into main Dec 26, 2025
28 checks passed

ryanmelt deleted the document_subpackets branch December 26, 2025 20:18


		## Subpackets

		Subpackets are marked with the keyword SUBPACKET. Subpackets exist inside of regular packets and are identified and broken out during decom processing by a SUBPACKETIZER Python/Ruby class. Subpackets are used for channelized telemetry and for multi-sampled telemetry points in a regular packet. They can also be used for any content that may or may not be present in the parent packet. Note: because subpackets exist inside of regular packets, their is no "raw" version of a subpacket ie. the raw subpacket is part of its parent regular packet.


		Packets are also the unit of data that COSMOS keeps track of with timestamps. Each packet has a received time (the time that COSMOS received the packet), and a packet time (the real time that the packet data was generated which is usually derived from the packet's own data). If no packet time is available then packet time is set to the received time.

		Each packet item therefore is part of a time-series with one sample per packet which can be graphed in TlmGrapher, extracted by DataExtractor or played back in TlmViewer.


		Systems that produce channelized telemetry generally send down a single packet of telemetry that has variable content. The content within these packets are called channels.

		Each channel has some form of id field that let's you know what the rest of the channel's data is. Sometimes each channel has its own timestamp and sometimes the packet timestamp is applied to each channel.


		The other use case for subpackets is when you have a single packet that has a lot of samples of the same data point in the same packet. Historically COSMOS would put all of these samples into an array item but that has several downsides.

		The primary downside is that you couldn't graph the data like a time series in TlmGrapher. Each of the samples generally has its own timestamp (generally derived from a known data rate), but that wasn't usable in TlmGrapher, because it only knows about the one packet timestamp per packet.


		The primary downside is that you couldn't graph the data like a time series in TlmGrapher. Each of the samples generally has its own timestamp (generally derived from a known data rate), but that wasn't usable in TlmGrapher, because it only knows about the one packet timestamp per packet.

		Using a SUBPACKETIZER to breakup each sample into its own SUBPACKET solves this problem, and makes the entire series of subpackets available to TlmGrapher to graph.


		## Defining a Subpacketizer

		A subpacketizer is added to the parent packet with the code necessary to break up it up into any internal subpackets.


		A subpacketizer is added to the parent packet with the code necessary to break up it up into any internal subpackets.

		Subpackets receive the parent packet as input and return an array of packets and subpackets as output. They can return 0 to as many subpackets as necessary. Note that if the parent packet is not returned, then it will not be processed.


		Subpackets receive the parent packet as input and return an array of packets and subpackets as output. They can return 0 to as many subpackets as necessary. Note that if the parent packet is not returned, then it will not be processed.

		The following show an example Subpacketizer class that works with the F-Prime Flight Software. Note that this is just one example. A Subpacketizer can contain whatever code necessary to break the packet into subpackets.


		## Restricted Packets

		Restricted command packets require additional approval if critical commanding is enabled in COSMOS Enterprise.

Conversation

ryanmelt commented Dec 20, 2025

Uh oh!

codecov bot commented Dec 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

jmthomas left a comment

Choose a reason for hiding this comment

Uh oh!

jmthomas Dec 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jmthomas Dec 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov bot commented Dec 20, 2025 •

edited

Loading

jmthomas Dec 21, 2025 •

edited

Loading

jmthomas Dec 21, 2025 •

edited

Loading