Unified Space Data Link (USLP) Package
Module
- class spacepackets.uslp.BypassSequenceControlFlag(value)
Bases:
IntEnumAn enumeration.
- EXPEDITED_QOS = 1
- SEQ_CTRLD_QOS = 0
- class spacepackets.uslp.PrimaryHeader(scid: int, src_dest: SourceOrDestField, vcid: int, map_id: int, frame_len: int, bypass_seq_ctrl_flag: BypassSequenceControlFlag = BypassSequenceControlFlag.SEQ_CTRLD_QOS, prot_ctrl_cmd_flag: ProtocolCommandFlag = ProtocolCommandFlag.USER_DATA, op_ctrl_flag: bool = False, vcf_count_len: int = 0, vcf_count: int | None = None)
Bases:
PrimaryHeaderBaseUSLP transfer frame primary header with a length of 4 to 14 bytes. It consists of 13 fields positioned contiguously. For more information, refer to the USLP Blue Book CCSDS 732.1-B-2 p.77
Transfer Frame Version Number or TFVN (4 bits)
Spacecraft ID or SCID (16 bits)
Source or destination identifier (1 bit)
Virtual Channel ID or VCID (6 bits)
Multiplexer Access Point or MAP ID (4 bits)
End of Frame Primary Header (1 bit)
Frame Length (16 bits)
Bypass/Sequence Control Flag (1 bit)
Protocol Control Command Flag (1 bit)
Reserve Spares (2 bits)
OCF flag (1 bit)
VCF count length (3 bits)
VCF count (0 to 56 bits)
- Raises:
ValueError – If the given VCF count is not valid for the given VCF count length.
- classmethod unpack(raw_packet: bytes | bytearray, uslp_version: int = 12) PrimaryHeader
Unpack a regular transfer frame header from a raw bytearray
- Parameters:
raw_packet
uslp_version
- Raises:
ValueError – Given bytearray too short
- Returns:
- class spacepackets.uslp.ProtocolCommandFlag(value)
Bases:
IntEnumAn enumeration.
- PROTOCOL_INFORMATION = 1
- USER_DATA = 0
- class spacepackets.uslp.SourceOrDestField(value)
Bases:
IntEnumAn enumeration.
- DEST = 1
- SOURCE = 0
- class spacepackets.uslp.TfdzConstructionRules(value)
Bases:
IntEnumValues prefixed with FP are applicable to fixed packets, those with VP to variable length packets
- FpContinuingPortionOfMapaSDU = 2
- FpFixedStartOfMapaSDU = 1
- FpPacketSpanningMultipleFrames = 0
- VpContinuingSegment = 5
- VpLastSegment = 6
- VpNoSegmentation = 7
- VpOctetStream = 3
- VpStartingSegment = 4
- class spacepackets.uslp.TransferFrame(header: TruncatedPrimaryHeader | PrimaryHeader, tfdf: TransferFrameDataField, insert_zone: bytes | None = None, op_ctrl_field: bytes | None = None, has_fecf: bool = True)
Bases:
objectRefer to CCSDS 732.1-B-2. p.77 for detailed information on the frame format. This is the format without the SDLS option
- classmethod unpack(raw_frame: bytes | bytearray, frame_type: FrameType, frame_properties: FixedFrameProperties | VarFrameProperties) TransferFrame
Unpack a USLP transfer frame from a raw bytearray. All managed parameters have to be passed explicitly.
- Parameters:
raw_frame
frame_type
frame_properties
- Raises:
UslpInvalidRawFrameLen – Passed raw bytearray too short
UslpTruncatedFrameNotAllowed – Truncated frames only allowed if passed frame type is Variable. This is REALLY confusing but specified in the standard p.161 D1.2
- Returns:
- class spacepackets.uslp.TransferFrameDataField(tfdz_cnstr_rules: TfdzConstructionRules, uslp_ident: UslpProtocolIdentifier, tfdz: bytes | bytearray, fhp_or_lvop: int | None = None)
Bases:
objectUSLP transfer frame data field (TFDF). For datailed information, refer to the USLP Blue Book CCSDS 732.1-B-2. p.86. The TFDP follows the Primary Header or the Transfer Frame Insert Zone, if present.
The data field has a header varying from 1 to 3 bytes as well.
Notes on the FHP or LVOP field. For more details, refer to CCSDS 732.1-B-2. p.92:
If the TFDZ construction rule is equal to ‘000’ (TFDZ spanning multiple frames), this field is designated as FHP. It then contains the offset within the TFDZ to the first octet of the first packet header. If no packet starts nor ends within the TFDZ, this field is set to all ones. Its purpose is to delimit variable-length packets contained within the TFDZ, by pointing directly to the location of the first packet from which its length can be determined. The location of any subsequent packets are determined by using the length field of those packets.
If the TFDZ constructions rule is equal to ‘001’ or ‘010’, this field is designated as LVOP and contains tbe offset to the last octet of the MAPA_SDU being transferred, with the remaining octets composed of a project specific idle data pattern. If the MAPA_SDU does not complete within this fixed-length TFDZ, then the value contained within the LVOP shall be set to binary all ones.
The FHP/LVOP field is only required when the frame type is set to a fixed length.
- Parameters:
tfdz_cnstr_rules – 3 bits, identifies how the protocol organizes data within the TFDZ in order to transport it.
uslp_ident – 5 bits, Identifies the CCSDS recognized protocol, procedure, or type of data contained within the TFDZ.
tfdz – Transfer Frame Data Zone
fhp_or_lvop – Optional First Header Pointer or Last Valid Octet Pointer.
- Raises:
ValueError – TFDZ too large
- classmethod unpack(raw_tfdf: bytes | bytearray, truncated: bool, exact_len: int, frame_type: FrameType | None) TransferFrameDataField
Unpack a TFDF, given a raw bytearray.
- Parameters:
raw_tfdf
truncated – Required to determine whether a TFDF has a FHP or LVOP field
exact_len – Exact length of the TFDP. Needs to be determined externally because the length information of a packet is usually fixed or part of the USLP primary header and can not be determined from the TFDP field alone
frame_type – Can be passed optionally to verify whether the construction rules are valid for the given frame type
- Returns:
- class spacepackets.uslp.TruncatedPrimaryHeader(scid: int, src_dest: SourceOrDestField, vcid: int, map_id: int)
Bases:
PrimaryHeaderBaseTrucated USLP transfer frame primary header with a length of 4 bytes. For more information, refer to the USLP Blue Book CCSDS 732.1-B-2. p.163
Only contains a subset of the regular primary header 1. Transfer Frame Version Number or TFVN (4 bits) 2. Spacecraft ID or SCID (16 bits) 3. Source or destination identifier (1 bit) 4. Virtual Channel ID or VCID (6 bits) 5. Multiplexer Access Point or MAP ID (4 bits) 6. End of Frame Primary Header (1 bit)
- classmethod unpack(raw_packet: bytes | bytearray, uslp_version: int = 12) TruncatedPrimaryHeader
Unpack USLP primary header from raw bytearray.
- Parameters:
raw_packet
uslp_version – Expected USLP version, 0b1100 by default
- Raises:
ValueError – Wrong packet length
UslpVersionMissmatch – Detected USLP version is not 0b1100
UslpTypeMissmatch – End of Frame Primary Header was 0, should be 1 for truncated packets
- Returns:
- class spacepackets.uslp.UslpProtocolIdentifier(value)
Bases:
IntEnumAlso called UPID. Identifies the CCSDS recognized protocol, procedure, or type of data contained within the TFDZ. See list here: https://sanaregistry.org/r/uslp_protocol_id/
- COP_1_CTRL_COMMANDS = 1
- COP_2_CTRL_COMMANDS = 2
- IDLE_DATA = 31
- MISSION_SPECIFIC_INFO_1_MAPA_SDU = 5
- PRIXMITY_1_PSEUDO_PACKET_ID_1 = 6
- PRIXMITY_1_PSEUDO_PACKET_ID_2 = 8
- PROXIMITY_1_SPDUS = 7
- SDLS_CTRL_COMMANDS = 3
- SPACE_PACKETS_ENCAPSULATION_PACKETS = 0
- USER_DEFINED_OCTET_STREAM = 4
Header Submodule
- class spacepackets.uslp.header.BypassSequenceControlFlag(value)
Bases:
IntEnumAn enumeration.
- EXPEDITED_QOS = 1
- SEQ_CTRLD_QOS = 0
- class spacepackets.uslp.header.HeaderType(value)
Bases:
EnumAn enumeration.
- NON_TRUNCATED = 0
- TRUNCATED = 1
- class spacepackets.uslp.header.PrimaryHeader(scid: int, src_dest: SourceOrDestField, vcid: int, map_id: int, frame_len: int, bypass_seq_ctrl_flag: BypassSequenceControlFlag = BypassSequenceControlFlag.SEQ_CTRLD_QOS, prot_ctrl_cmd_flag: ProtocolCommandFlag = ProtocolCommandFlag.USER_DATA, op_ctrl_flag: bool = False, vcf_count_len: int = 0, vcf_count: int | None = None)
Bases:
PrimaryHeaderBaseUSLP transfer frame primary header with a length of 4 to 14 bytes. It consists of 13 fields positioned contiguously. For more information, refer to the USLP Blue Book CCSDS 732.1-B-2 p.77
Transfer Frame Version Number or TFVN (4 bits)
Spacecraft ID or SCID (16 bits)
Source or destination identifier (1 bit)
Virtual Channel ID or VCID (6 bits)
Multiplexer Access Point or MAP ID (4 bits)
End of Frame Primary Header (1 bit)
Frame Length (16 bits)
Bypass/Sequence Control Flag (1 bit)
Protocol Control Command Flag (1 bit)
Reserve Spares (2 bits)
OCF flag (1 bit)
VCF count length (3 bits)
VCF count (0 to 56 bits)
- Raises:
ValueError – If the given VCF count is not valid for the given VCF count length.
- classmethod unpack(raw_packet: bytes | bytearray, uslp_version: int = 12) PrimaryHeader
Unpack a regular transfer frame header from a raw bytearray
- Parameters:
raw_packet
uslp_version
- Raises:
ValueError – Given bytearray too short
- Returns:
- class spacepackets.uslp.header.PrimaryHeaderBase(scid: int, src_dest: SourceOrDestField, vcid: int, map_id: int)
Bases:
object
- class spacepackets.uslp.header.ProtocolCommandFlag(value)
Bases:
IntEnumAn enumeration.
- PROTOCOL_INFORMATION = 1
- USER_DATA = 0
- class spacepackets.uslp.header.SourceOrDestField(value)
Bases:
IntEnumAn enumeration.
- DEST = 1
- SOURCE = 0
- class spacepackets.uslp.header.TruncatedPrimaryHeader(scid: int, src_dest: SourceOrDestField, vcid: int, map_id: int)
Bases:
PrimaryHeaderBaseTrucated USLP transfer frame primary header with a length of 4 bytes. For more information, refer to the USLP Blue Book CCSDS 732.1-B-2. p.163
Only contains a subset of the regular primary header 1. Transfer Frame Version Number or TFVN (4 bits) 2. Spacecraft ID or SCID (16 bits) 3. Source or destination identifier (1 bit) 4. Virtual Channel ID or VCID (6 bits) 5. Multiplexer Access Point or MAP ID (4 bits) 6. End of Frame Primary Header (1 bit)
- classmethod unpack(raw_packet: bytes | bytearray, uslp_version: int = 12) TruncatedPrimaryHeader
Unpack USLP primary header from raw bytearray.
- Parameters:
raw_packet
uslp_version – Expected USLP version, 0b1100 by default
- Raises:
ValueError – Wrong packet length
UslpVersionMissmatch – Detected USLP version is not 0b1100
UslpTypeMissmatch – End of Frame Primary Header was 0, should be 1 for truncated packets
- Returns:
- spacepackets.uslp.header.determine_header_type(header_start: bytes | bytearray) HeaderType
Determine header type from raw header. :param header_start: :raises ValueError: Passed bytearray shorter than minimum length 4 :return:
Frame Submodule
- class spacepackets.uslp.frame.FixedFrameProperties(fixed_len: int, has_insert_zone: bool, has_fecf: bool, insert_zone_len: int | None = None)
Bases:
FramePropertiesBaseContains properties required when unpacking fixed USLP frames. These properties can not be determined by parsing the frame. The standard refers to these properties as managed parameters.
- Parameters:
has_insert_zone
has_fecf
insert_zone_len
fecf_len
- class spacepackets.uslp.frame.FramePropertiesBase(has_insert_zone: bool, has_fecf: bool, insert_zone_len: int | None = None)
Bases:
object
- class spacepackets.uslp.frame.FrameType(value)
Bases:
EnumAn enumeration.
- FIXED = 0
- VARIABLE = 1
- class spacepackets.uslp.frame.TfdzConstructionRules(value)
Bases:
IntEnumValues prefixed with FP are applicable to fixed packets, those with VP to variable length packets
- FpContinuingPortionOfMapaSDU = 2
- FpFixedStartOfMapaSDU = 1
- FpPacketSpanningMultipleFrames = 0
- VpContinuingSegment = 5
- VpLastSegment = 6
- VpNoSegmentation = 7
- VpOctetStream = 3
- VpStartingSegment = 4
- class spacepackets.uslp.frame.TransferFrame(header: TruncatedPrimaryHeader | PrimaryHeader, tfdf: TransferFrameDataField, insert_zone: bytes | None = None, op_ctrl_field: bytes | None = None, has_fecf: bool = True)
Bases:
objectRefer to CCSDS 732.1-B-2. p.77 for detailed information on the frame format. This is the format without the SDLS option
- classmethod unpack(raw_frame: bytes | bytearray, frame_type: FrameType, frame_properties: FixedFrameProperties | VarFrameProperties) TransferFrame
Unpack a USLP transfer frame from a raw bytearray. All managed parameters have to be passed explicitly.
- Parameters:
raw_frame
frame_type
frame_properties
- Raises:
UslpInvalidRawFrameLen – Passed raw bytearray too short
UslpTruncatedFrameNotAllowed – Truncated frames only allowed if passed frame type is Variable. This is REALLY confusing but specified in the standard p.161 D1.2
- Returns:
- class spacepackets.uslp.frame.TransferFrameDataField(tfdz_cnstr_rules: TfdzConstructionRules, uslp_ident: UslpProtocolIdentifier, tfdz: bytes | bytearray, fhp_or_lvop: int | None = None)
Bases:
objectUSLP transfer frame data field (TFDF). For datailed information, refer to the USLP Blue Book CCSDS 732.1-B-2. p.86. The TFDP follows the Primary Header or the Transfer Frame Insert Zone, if present.
The data field has a header varying from 1 to 3 bytes as well.
Notes on the FHP or LVOP field. For more details, refer to CCSDS 732.1-B-2. p.92:
If the TFDZ construction rule is equal to ‘000’ (TFDZ spanning multiple frames), this field is designated as FHP. It then contains the offset within the TFDZ to the first octet of the first packet header. If no packet starts nor ends within the TFDZ, this field is set to all ones. Its purpose is to delimit variable-length packets contained within the TFDZ, by pointing directly to the location of the first packet from which its length can be determined. The location of any subsequent packets are determined by using the length field of those packets.
If the TFDZ constructions rule is equal to ‘001’ or ‘010’, this field is designated as LVOP and contains tbe offset to the last octet of the MAPA_SDU being transferred, with the remaining octets composed of a project specific idle data pattern. If the MAPA_SDU does not complete within this fixed-length TFDZ, then the value contained within the LVOP shall be set to binary all ones.
The FHP/LVOP field is only required when the frame type is set to a fixed length.
- Parameters:
tfdz_cnstr_rules – 3 bits, identifies how the protocol organizes data within the TFDZ in order to transport it.
uslp_ident – 5 bits, Identifies the CCSDS recognized protocol, procedure, or type of data contained within the TFDZ.
tfdz – Transfer Frame Data Zone
fhp_or_lvop – Optional First Header Pointer or Last Valid Octet Pointer.
- Raises:
ValueError – TFDZ too large
- classmethod unpack(raw_tfdf: bytes | bytearray, truncated: bool, exact_len: int, frame_type: FrameType | None) TransferFrameDataField
Unpack a TFDF, given a raw bytearray.
- Parameters:
raw_tfdf
truncated – Required to determine whether a TFDF has a FHP or LVOP field
exact_len – Exact length of the TFDP. Needs to be determined externally because the length information of a packet is usually fixed or part of the USLP primary header and can not be determined from the TFDP field alone
frame_type – Can be passed optionally to verify whether the construction rules are valid for the given frame type
- Returns:
- class spacepackets.uslp.frame.UslpProtocolIdentifier(value)
Bases:
IntEnumAlso called UPID. Identifies the CCSDS recognized protocol, procedure, or type of data contained within the TFDZ. See list here: https://sanaregistry.org/r/uslp_protocol_id/
- COP_1_CTRL_COMMANDS = 1
- COP_2_CTRL_COMMANDS = 2
- IDLE_DATA = 31
- MISSION_SPECIFIC_INFO_1_MAPA_SDU = 5
- PRIXMITY_1_PSEUDO_PACKET_ID_1 = 6
- PRIXMITY_1_PSEUDO_PACKET_ID_2 = 8
- PROXIMITY_1_SPDUS = 7
- SDLS_CTRL_COMMANDS = 3
- SPACE_PACKETS_ENCAPSULATION_PACKETS = 0
- USER_DEFINED_OCTET_STREAM = 4
- class spacepackets.uslp.frame.VarFrameProperties(has_insert_zone: bool, has_fecf: bool, truncated_frame_len: int, insert_zone_len: int | None = None)
Bases:
FramePropertiesBaseContains properties required when unpacking variable USLP frames. These properties can not be determined by parsing the frame. The standard refers to these properties as managed parameters.
- Parameters:
has_insert_zone
has_fecf
truncated_frame_len
insert_zone_len