Loading Packet Definitions from a CSV File

Overview

Fixed Length Packets can be loaded from a CSV (comma separated value) file. This is an alternative method for defining packet layouts which may be desirable to some users, and is currently undergoing development. The syntax for loading a FixedLength packet from a CSV file is:

import ccsdspy
pkt = ccsdspy.FixedLength.from_file('packet_definition.csv')

The syntax is the same for VariableLength packets:

import ccsdspy
pkt = ccsdspy.VariableLength.from_file('packet_definition.csv')

The only requirement is that the CSV is structured as either the Basic Layout (Three Columns) or Extended Layout (Four Columns).

Basic Layout (Three Columns)

The basic CSV layout has columns for name, data_type, and bit_length. The first row of the CSV should be a header line where the columns are named. Subsequent rows encode packet fields. This format is appropriate if the CSV defines all the packets one after another without skipping any. The three column format automatically calculates the bit offsets assuming that the packet order is correct. See the Extended Layout (Four Columns) format for more flexibility.

Basic Layout CSV

name	data_type	bit_length
SHCOARSE	uint	32
SHFINE	uint	20
OPMODE	uint	3
SPACER	fill	1
VOLTAGE	int	8

When the example above is loaded, five PacketField objects are defined with varying names, data types, and bit lengths. To create a PacketArray instead, define the data type with both the type and array shape.

Basic Layout CSV with PacketArray

name	data_type	bit_length
SHCOARSE	uint	32
SHFINE	uint	20
OPMODE	uint	3
SPACER	fill	1
VOLTAGE	int(12, 24)	8

In the example above, VOLTAGE would instead be a PacketArray of type int with shape (12, 24).

For Variable Length Packets, the array shape string can be specified either as expand or as the name of another field.

Basic Layout CSV with PacketArray for Variable Length Packets

name	data_type	bit_length
SHCOARSE	uint	32
SHFINE	uint(expand)	20
OPMODE	uint(SHFINE)	3
SPACER	fill	1
VOLTAGE	int(12, 24)	8

Extended Layout (Four Columns)

The extended CSV layout has columns for name, data_type, bit_length, and bit_offset. The first row of the CSV should be a header line where the columns are named. Subsequent rows encode packet fields. This format allows more flexibility than the basic layout because bit offsets are explicitly defined instead of automatically calculated. Due to this, some packet fields can be skipped since the bit offset indicates exactly where the packet begins.

Extended Layout CSV

name	data_type	bit_length	bit_offset
SHCOARSE	uint	32	0
SHFINE	uint	20	32
OPMODE	uint	3	52
SPACER	fill	1	55
VOLTAGE	int	8	56

When the example above is loaded, five PacketField objects are defined with varying names, data types, and bit lengths. To create a PacketArray instead, define the data type with both the type and array shape.

Extended Layout CSV with PacketArray

name	data_type	bit_length	bit_offset
SHCOARSE	uint(4)	32	0
SHFINE	uint	20	128
OPMODE	uint	3	148
SPACER	fill	1	151
VOLTAGE	int	8	152

In the example above, SHSCOARSE would instead be a PacketArray of type uint with shape (4).

Note

Variable Length Packets are not supported in the extended layout since bit_offset cannot be specified for variable length packets.

Limitations of the CSV format

The CSV format is in development and is currently limited. The limitations are:

• the byte order cannot be defined in the CSV.

• the array order cannot be defined in the CSV.