diff --git a/docs/user-guide/fixedlength.rst b/docs/user-guide/fixedlength.rst index 32f5c36..40ba12a 100644 --- a/docs/user-guide/fixedlength.rst +++ b/docs/user-guide/fixedlength.rst @@ -33,16 +33,8 @@ The following code defines a simple fixed length packet ]) Note that the CCSDS header need not be included as it is included by default. -A packet need not be defined in code. -It can also be defined in a text file. -For example, -With this file, it is then possible to define the packet object with - -.. code-block:: python - - import ccsdspy - pkt = ccsdspy.FixedLength.from_file('packet_definition.csv') +Alternatively, fixed length packets can be :ref:`loaded from a CSV file `. Parsing a file ============== diff --git a/docs/user-guide/index.rst b/docs/user-guide/index.rst index 65a19c4..e7c5bbe 100644 --- a/docs/user-guide/index.rst +++ b/docs/user-guide/index.rst @@ -14,5 +14,6 @@ For more details checkout the :ref:`reference`. packetfields fixedlength variablelength + loadfile converters utils diff --git a/docs/user-guide/loadfile.rst b/docs/user-guide/loadfile.rst new file mode 100644 index 0000000..8d61c88 --- /dev/null +++ b/docs/user-guide/loadfile.rst @@ -0,0 +1,86 @@ +.. _loadfile: + +****************************************** +Loading Packet Definitions from a CSV File +****************************************** + +Overview +========= + +:ref:`fixed` 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 from a CSV file is: + +.. code-block:: python + + import ccsdspy + pkt = ccsdspy.FixedLength.from_file('packet_definition.csv') + +The only requirement is that the CSV is structured as either the :ref:`threecolumn` +or :ref:`fourcolumn`. At the moment, :ref:`variable` cannot be loaded from a CSV file. + +.. contents:: + :depth: 2 + +.. _threecolumn: + +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 :ref:`fourcolumn` format +for more flexibility. + +.. csv-table:: Basic Layout CSV + :file: ../../ccsdspy/tests/data/packet_def/simple_csv_3col.csv + :widths: 30, 30, 30 + :header-rows: 1 + +When the example above is loaded, five `~ccsdspy.PacketField` objects are defined +with varying names, data types, and bit lengths. To create a `~ccsdspy.PacketArray` instead, define the data type with +both the type and array shape. + +.. csv-table:: Basic Layout CSV with `~ccsdspy.PacketArray` + :file: ../../ccsdspy/tests/data/packet_def/simple_csv_3col_with_array.csv + :widths: 30, 30, 30 + :header-rows: 1 + +In the example above, `VOLTAGE` would instead be a `~ccsdspy.PacketArray` of type `int` with shape `(12, 24)`. + +.. _fourcolumn: + +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. + +.. csv-table:: Extended Layout CSV + :file: ../../ccsdspy/tests/data/packet_def/simple_csv_4col.csv + :widths: 30, 30, 30, 30 + :header-rows: 1 + +When the example above is loaded, five `~ccsdspy.PacketField` objects are defined +with varying names, data types, and bit lengths. To create a `~ccsdspy.PacketArray` instead, define the data type with +both the type and array shape. + +.. csv-table:: Extended Layout CSV with `~ccsdspy.PacketArray` + :file: ../../ccsdspy/tests/data/packet_def/simple_csv_4col_with_array.csv + :widths: 30, 30, 30, 30 + :header-rows: 1 + +In the example above, `SHSCOARSE` would instead be a `~ccsdspy.PacketArray` of type `uint` with shape `(4)`. + +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 and byte order cannot be defined in the CSV. +* :ref:`variable` cannot currently be loaded from a CSV file.