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.
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.
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.
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.
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.
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.