Datagram

__init__(pcdnum=None, numblocks=None, streambits=None, seed=None, payload=None)

Generate a datagram in the ARGOS-3 standard. The datagram format is illustrated in the figure below.

Parameters:

Name	Type	Description	Default
pcdnum	int	PCD number. Required for TX mode.	None
numblocks	int	Number of blocks. Required for TX mode.	None
seed	int	Seed of the random number generator. Optional for TX mode.	None
payload	ndarray	Payload of the datagram. Optional for TX mode.	None
streambits	ndarray	Bitstream of the datagram. Required for RX mode.	None

Raises:

Type	Description
ValueError	If the number of blocks is not between 1 and 8.
ValueError	If the PCD number is not between 0 and 1048575 \((2^{20} - 1)\).
ValueError	If the parameters pcdnum and numblocks or streambits are not provided.
ValueError	If the payload is not provided or if the length of the payload is not the same as the number of blocks.

Examples:

>>> import argos3
>>> datagramTX = argos3.Datagram(pcdnum=123456, numblocks=2, seed=10)
>>> streambits = datagramTX.streambits
>>> print(streambits)
[0 0 1 1 0 0 0 0 0 0 0 0 0 1 0 0 1 1 0 1 0 0 1 0 0 0 0 0 0 1 0 1 0 0 1 1 0
 1 1 0 1 0 0 1 1 1 1 1 1 1 0 1 1 1 0 0 0 0 1 1 0 0 1 0 1 1 1 0 0 0 1 1 1 0
 1 1 0 1 1 0 0 0 1 0 1 0 0 1 0 0 0 0 0 0 0 0]
>>> 
>>> datagramRX = argos3.Datagram(streambits=streambits)
>>> print(datagramRX.parse_datagram())
{
  "msglength": 2,
  "pcdid": 123456,
  "payload": {
    "block_1": {
      "byte_1": 183,
      "byte_2": 108,
      "byte_3": 125
    },
    "block_2": {
      "byte_1": 112,
      "byte_2": 217,
      "byte_3": 78,
      "byte_4": 141
    }
  },
  "tail": 8
}

• Bitstream Plot Example:

Reference:
AS3-SP-516-274-CNES (section 3.1.4.2)

generate_blocks()

Generate simulated data blocks (random values), based on the specified number of blocks.

The number of blocks can be between 1 and 8. The first block has a length of 24 bits, and all other blocks have 32 bits. In this way, the length of the data application is given by the expression below.

\[ L_{app} = 24 + 32 \cdot (n-1) \]

Where

• \(L_{app}\): Data application length in bits
• \(n\): Number of blocks of the datagram, varying from 1 to 8.

Returns:

Name	Type	Description
blocks	ndarray	Bit array representing the data blocks.

Reference:
AS3-SP-516-274-CNES (section 3.1.4.2)

generate_pcdid()

Generate the PCD_ID field from the PCD number (\(PCD_{num}\)), First generate the sequence of 20 bits corresponding to the PCD number.

\[ PCDnum_{10} \mapsto PCDnum_{2} \]

Where

• \(PCDnum_{10}\): Decimal value of the \(PCD_{num}\) field, varying from 0 to 1048575 \((2^{20} - 1)\).
• \(PCDnum_{2}\): Sequence of 20 bits corresponding to the value of \(PCD_{num}\).

Then, the checksum, \(R_{PCD}\), of the \(PCD_{num}\) field is calculated, obtained through the sum of the bits and application of the modulo 256 (\(2^8\)) operation.

\[ \begin{equation} R_{PCD} = \left( \sum_{i=0}^{19} b_i \cdot 2^i \right) \bmod 256 \end{equation} \]

Where

• \(R_{PCD}\): Sequence of 8 bits corresponding to the checksum of the \(PCD_{num}\) field.
• \(i\): Index of the bit of the \(PCD_{num}\) field.
• \(b\): Value of the bit of the \(PCD_{num}\) field.

The \(PCD_{ID}\) field is generated by concatenating the generated parameters, being \(PCD_{ID} = PCD_{num} \oplus R_{PCD}\).

Returns:

Name	Type	Description
pcd_id	ndarray	Bit array containing the PCD ID and checksum.

Reference:
AS3-SP-516-274-CNES (section 3.1.4.2)

generate_msglength()

Generate the value of the message length \(T_{m}\) based on the number of blocks \(n\). First, the sequence of bits \(B_m\) must be calculated. $$ Bm_{10} = (n - 1) \mapsto Bm_{2} $$

Where

• \(B_m\): Sequence of three bits corresponding to the message length.
• \(n\): Number of blocks of the datagram, varying from 1 to 8.

Then, the fourth bit \(P_m\) (parity bit) is calculated.

\[ \begin{equation} P_m = \begin{cases} 1, & \text{se } \left[ \sum_{i=0}^{B_m} b_i = 0 \right]\mod 2 \\ 0, & \text{se } \left[ \sum_{i=0}^{B_m} b_i = 1 \right]\mod 2 \end{cases} \text{.} \end{equation} \]

Where

• \(P_m\): Parity bit.
• \(i\): Index of bit of the \(B_m\) field.

The \(T_{m}\) field is generated by concatenating the generated parameters, being \(T_{m} = B_{m} \oplus P_{m}\).

Returns:

Name	Type	Description
msg_length	ndarray	Bit array representing the Message Length field.

Reference:
AS3-SP-516-274-CNES (section 3.1.4.2)

generate_tail()

Generate the tail of the datagram \(E_m\), used to clear the codifier's register.

\[ E_m = 7 + [(n - 1) \bmod 3] \]

Where

• \(E_m\): Tail of the datagram (zeros) added to the end of the datagram.
• \(n\): Number of blocks of the datagram.

Returns:

Name	Type	Description
tail	ndarray	Bit array of zeros with variable length (7, 8 or 9 bits).

Reference:
AS3-SP-516-274-CNES (section 3.1.4.3)

parse_datagram()

Interprets the bit sequence of the datagram, extracting fields and validating integrity.

Returns:

Name	Type	Description
str	json	JSON object containing the structured representation of the datagram.

Raises:

Type	Description
ValueError	If the parity check of the message length \(T_m\) fails.
ValueError	If the checksum of the \(PCD_{ID}\) field fails.
ValueError	If the application bit sequence does not correspond to the length of \(T_m\).