Svc/Ccsds/TmFramer/docs/sdd.md
The Svc::Ccsds::TmFramer is an implementation of the FramerInterface for the CCSDS TM Space Data Link Protocol.
It receives payload data (such as a Space Packet or a VCA_SDU) on input and produces a TM frame on its output port as a result. Please refer to the CCSDS TM specification (CCSDS 132.0-B-3) for details on the frame format and protocol.
The Svc::Ccsds::TmFramer is designed to work in the common F Prime telemetry stack, receiving data from an upstream Svc::ComQueue and passing frames to a Communications Adapter, such as a Radio manager component or Svc::ComStub, for transmission on the wire. It is commonly coupled with the Svc::Ccsds::SpacePacketFramer to wrap CCSDS Space Packets into TM frames.
The TM protocol specifies a fixed frame size. This can be configured in the config/ComCfg.fpp file.
The Svc::Ccsds::TmFramer uses an internal (member) buffer to hold the fixed size frame. The buffer must be returned to the TmFramer via the dataReturnIn port once it has been used or consumed. When the buffer returns to the TmFramer it will reuse the buffer for the next frame. Should a component want to use the frame data past the time it is returned to the TmFramer, data should be copied before the original buffer is returned to the TmFramer via the dataReturnIn port.
The Svc::Ccsds::TmFramer component, as well as the rest of the CCSDS communications stack, is used in the Ref/ example application. It is also generated by the fprime-util new --deployment command.
For each frame generated, the Svc::Ccsds::TmFramer will populate the CCSDS TM Primary Header fields as follows:
| Field | Value | Notes |
|---|---|---|
| Transfer Frame Version Number | 0 | As per protocol 4.1.2.2 |
| Spacecraft ID | Configured in config/ComCfg.fpp | Set in the project configuration |
| Virtual Channel ID | Uses value passed in the context argument (defaults to 0) | Set by an upstream component |
| Operational Control Field Flag | 0 | Unsupported |
| Master Channel Frame Count | Incremented for each frame | Managed internally by TmFramer |
| Virtual Channel Frame Count | Incremented for each frame | Managed internally by TmFramer. One TmFramer instance can only keep count of a single VCID. |
| Transfer Frame Secondary Header Flag | 0 | F Prime does not formally use secondary headers |
| Synchronization Flag | 0 | 0 as Packets are inserted |
| Packet Order Flag | 0 | As per protocol 4.1.2.7.4 |
| Segment Length Identifier | 0b11 | As per protocol 4.1.2.7.5 |
| First Header Pointer | 0 | F Prime packets are limited in length and always sent in a single frame, aligned to the start of the frame. |
| Kind | Name | Port Type | Description |
|---|---|---|---|
| sync input | dataIn | Svc.ComDataWithContext | Receives data to frame, in a Fw::Buffer with optional context |
| output | dataOut | Svc.ComDataWithContext | Outputs framed data with optional context |
| output | dataReturnOut | Svc.ComDataWithContext | Returns ownership of the incoming Fw::Buffer to its sender once framing is handled |
| sync input | dataReturnIn | Svc.ComDataWithContext | Receives buffer from a deallocate call in a ComDriver component |
| sync input | comStatusIn | Fw.SuccessCondition | Receives general status from downstream component indicating readiness for more input |
| output | comStatusOut | Fw.SuccessCondition | Indicates the status of framer for receiving more data |
| Name | Description | Validation |
|---|---|---|
| SVC-Ccsds-TM-FRAMER-001 | The TmFramer shall implement the Svc.FramerInterface. | Inspection, Unit Test |
| SVC-Ccsds-TM-FRAMER-002 | The TmFramer shall construct CCSDS Telemetry (TM) Transfer Frames compliant with the CCSDS 132.0-B-3 standard. | Unit Test, Inspection |
| SVC-Ccsds-TM-FRAMER-002 | The TmFramer shall use a fixed frame size that is configurable by the project. | Unit Test, Inspection |
| SVC-Ccsds-TM-FRAMER-003 | The TmFramer shall accept payload data (Space Packets or VCA_SDU) to be framed via its dataIn port. | Unit Test |
| SVC-Ccsds-TM-FRAMER-004 | The TmFramer shall output the constructed TM Transfer Frame via its dataOut port. | Unit Test |
| SVC-Ccsds-TM-FRAMER-005 | The TmFramer shall return ownership of the input buffer via the dataReturnOut port after the framing process is complete. | Unit Test |
| SVC-Ccsds-TM-FRAMER-006 | The TmFramer shall accept returned buffers (previously sent via dataOut) through the dataReturnIn port for deallocation or reuse. | Unit Test |
| SVC-Ccsds-TM-FRAMER-007 | The TmFramer shall receive communication status from downstream components via the comStatusIn port, and pass it through to comStatusOut | Unit Test, Integration Test |
| SVC-Ccsds-TM-FRAMER-008 | The TmFramer shall use exactly one Virtual Channel. | Unit Test, Integration Test |
| SVC-Ccsds-TM-FRAMER-009 | The TmFramer shall correctly populate all mandatory fields of the TM Transfer Frame Primary Header, including Transfer Frame Version Number, Spacecraft Identifier, Virtual Channel Identifier, Operational Control Field Flag, Master Channel Frame Count, Virtual Channel Frame Count, Transfer Frame Secondary Header Flag, Synchronization Flag, Packet Order Flag, Segment Length Identifier, and First Header Pointer. | Unit Test, Inspection |
| SVC-Ccsds-TM-FRAMER-010 | The TmFramer shall be configurable with a Spacecraft Identifier. | Inspection, Unit Test |
| SVC-Ccsds-TM-FRAMER-011 | The TmFramer shall use the Virtual Channel Identifier passed in the context object on dataIn. | Unit Test |
| SVC-Ccsds-TM-FRAMER-012 | The TmFramer shall manage Master Channel Frame Count and Virtual Channel Frame Count. | Unit Test |
| SVC-Ccsds-TM-FRAMER-013 | The TmFramer shall fill the data field of the TM Transfer Frame with the payload data received on dataIn, and fill up the rest of the fixed-size frame with a single Idle Packet as defined by the protocol. | Unit Test |