ex_packet_define.py

"""!
This example is for a simple, completely made up packet.  It has a header,
data, and trailer with all of the packet attributes set.  The 'purpose' of
this example is to define the packet and save it to disk.  Other examples
will use the saved packet to build and extract the packet.  There are other
ways to create packet definitializeions in TReK (e.g., simple comma delimited
files).
 
Just for fun here is the packet definitializeion in a small table.  All of the
data is 'big endian' except for a single parameter.  All sizes are listed
in bits. The data is packed (i.e., there are no gaps).  The code below will
set the start location for parameter, but it isn't shown in the table.
Name        Data Type           Size    Notes
Version     unsigned integer    4       Should always be zero
PktId       unsigned integer    12      For this packet, the value is 54
PktLen      unsigned integer    16      Length of packet after this point
PktCnt      unsigned integer    8       Packet counter
Time        system time         32      A.k.a. DT_UNIX_TIME
IntParam    signed integer      16      First data parameter
UintParam   unsigned integer    32      Three consecutive values
FloatParam  double              64      Little-endian floating point
StrParam    string              800     Varible length string
Checksum    unsigned integer    32      CRC-32 checksum
"""
 
import trek
 
 
def main() -> None:
    """
    Main Routine
    """
 
    try:
        #  NOTE: There is only minimal error checking shown in the code below in
        #  order to simplify the example.  In general, only the first time a
        #  method is used will the error handling be in this example.  You should
        #  always check the returned value when one is available to ensure proper
        #  operation of the code.  Error handling for this example is to exit on
        #  error.
        pkt = trek.Packet()
        pc = trek.ParameterCollection()
        p = trek.Parameter()
 
        #  Need to create the 'zones' for the packet and add it to the packet.
        #  The general steps for this are:
        #
        #  1. initializeialize the parameter collection
        #  2. initializeialize the parameter.
        #  3. Set the parameter attributes as needed (data type, name, length,
        #     byte order, start bit, etc.)
        #  4. Add the parameter to the collection.
        #  5. Repeat steps 2, 3, and 4 until all the parameters are in the
        #     parameter collection.
        #  6. Add the parameter collection into the correct zone.
        #
        #  Using the above procedure as a guideline, create the header zone for
        #  the packet.  This will consist of 5 parameters: Version, PktId, PktLen,
        #  PktCnt, and Time.
        pc.initialize()  # this will clear out any data in the collection
        pc.set_name("MyHeader")  # not required, but can be useful
        p.initialize()  # this will clear out any data in the parameter
        p.set_name("Version")
        p.set_start_bit(0)
 
        # There are a lot of exceptions for this method.  The returned error
        # is usually self explanatory, but an attempt at explanation is made
        # throughout the documentation.
        p.set_data_type(trek.ParameterDataType.DT_UNSIGNED_INTEGER, 4)
 
        p.set_modifiable_flag(False)  # don't want this value changed
 
        # If this method fails it is usually because you have a data type
        # mismatch or the value won't fit in the data.  Since this is a 4-bit
        # unsigned integer, any value above 15 will fail.
        p.set_value(0)
 
        # If this fails, it's most likely because you already have a parameter
        # with the same name.
        pc.add_parameter(p)  # add the parameter to the collection
 
        #  Time to add the rest of the header parameters...and without error
        #  checking.
        p.initialize()  # this will clear out any data in the parameter
        p.set_name("PktId")
        p.set_start_bit(4)  # Don't forget to set this!
        p.set_data_type(trek.ParameterDataType.DT_UNSIGNED_INTEGER, 12)
        p.set_modifiable_flag(False)  # don't want this value changed
        pc.add_parameter(p)  # add the parameter to the collection
        p.initialize()
        p.set_name("PktLen")
        p.set_start_bit(16)
        p.set_data_type(trek.ParameterDataType.DT_UNSIGNED_INTEGER, 16)
        p.set_modifiable_flag(True)  # packet length will change
        pc.add_parameter(p)
        p.initialize()  # this will clear out any data in the parameter
        p.set_name("PktCnt")
        p.set_start_bit(32)
        p.set_data_type(trek.ParameterDataType.DT_UNSIGNED_INTEGER, 8)
        p.set_modifiable_flag(True)  # sequence count will change
        pc.add_parameter(p)
        p.initialize()  # this will clear out any data in the parameter
        p.set_name("Time")
        p.set_start_bit(40)
        p.set_data_type(trek.ParameterDataType.DT_UNIX_TIME, 32)
        p.set_modifiable_flag(True)  # time will change
        pc.add_parameter(p)
 
        # Now all of the parameters are in the collection, add the header.  The
        # Packet will make a copy of the input, so feel free to use it again.
        # If it fails, you probably have already added a header.  Use
        # RemoveHeader first if you really want to add a different one.
        pkt.add_header(pc)
 
        #  Time to add the 'data zone' to the packet.  Same basic procedure as the
        #  header.  The start location for each parameter is relative to the
        #  collection so they will restart at zero.  This makes it much easier to
        #  reuse collections and packets within other packets.
        pc.initialize()  # we're going to reuse this, so must initializeialize it again.
        pc.set_name("MyData")
        p.initialize()  # this will clear out any data in the parameter
        p.set_name("IntParam")
        p.set_start_bit(0)  # Don't forget to start over for a new collection
        p.set_data_type(trek.ParameterDataType.DT_TWOS_COMPLEMENT, 16)
        p.set_modifiable_flag(True)
        pc.add_parameter(p)  # add the parameter to the collection
 
        #  This parameter has 3 samples, you should set the number of samples and
        #  also the sample offset.  The sample offset will default to 0 which is
        #  the required value in this case.  The sample offset is the number of
        #  bits that are between each of the samples.
        p.initialize()
        p.set_name("UintParam")
        p.set_start_bit(16)
        p.set_data_type(trek.ParameterDataType.DT_UNSIGNED_INTEGER, 32)
        p.set_number_of_samples(3)  # the default is 1, need 3 samples
        p.set_sample_offset(0)
        p.set_modifiable_flag(True)
        pc.add_parameter(p)  # add the parameter to the collection
 
        #  This parameter has a little endian byte order.  The default byte order
        #  when setting the data type is big endian so you must pass in an extra
        #  parameter here.
        p.initialize()
        p.set_name("FloatParam")
        p.set_start_bit(112)
        p.set_data_type(
            trek.ParameterDataType.DT_IEEE_FLOATING_POINT,
            64,
            trek.ParameterByteOrderType.LITTLE_ENDIAN_BYTE_ORDER,
        )
        p.set_modifiable_flag(True)
        pc.add_parameter(p)  # add the parameter to the collection
 
        #  The last parameter in the data is variable length.  Variable length
        #  data must always be at the end of the container.  You'll need to
        #  specify the parameter is variable length when setting the data type.
        p.initialize()
        p.set_name("StrParam")
        p.set_start_bit(176)
        p.set_data_type(
            trek.ParameterDataType.DT_NULL_TERMINATED_STRING,
            800,  # 100 byte string (as bits)
            trek.ParameterByteOrderType.BIG_ENDIAN_BYTE_ODER,
            True,
        )
        p.set_modifiable_flag(True)
        pc.add_parameter(p)  # add the parameter to the collection
 
        #  Now add the data zone to the packet.
        pkt.add_data(pc)
 
        #  The trailer consists of a single 32-bit parameter that is used for a
        #  checksum.  The type of checksum is specified in the packet attributes.
        #  You just need to create the parameter to hold it here.
        pc.initialize()
        p.initialize()
        p.set_name("Checksum")
        p.set_start_bit(0)
        p.set_data_type(trek.ParameterDataType.DT_UNSIGNED_INTEGER, 32)
        p.set_modifiable_flag(True)  # checksum will change
        p.set_value(0)
        pc.add_parameter(p)
        pkt.add_trailer(pc)
 
        #  Once all of the data is in the packet, create the packet map that will
        #  allow lookup of the parameters in the packet.
        pkt.create_global_packet_map()
 
        #  Now it's time to set the packet attributes.  None of the attributes are
        #  required, but all are used in this example.
 
        #  Add an identifier.  This packet only has one, but you can have any
        #  number of identifiers as required.  The "Version" of the packet could
        #  be used here to ensure that the packet header hasn't changed, but we
        #  won't use it today.
        pkt.add_identifier(
            "PktId",
            trek.IdentifierInfo(
                zone=trek.PacketZoneType.HEADER_ZONE,
                id_type=trek.IdentifierType.CONTENT_IDENTIFIER,
                has_default=False,
                has_expected=True,
                expected=54,
            ),
        )
 
        #  Add the length parameter.  In this case the actual length of the packet
        #  is 4 bytes longer than the value of this field.
        pkt.set_length_parameter(
            "PktLen", trek.LengthParameterInfo(trek.PacketZoneType.HEADER_ZONE, 4)
        )
 
        #  Add the packet counter.  Since it is a simple forward based counter,
        #  the defaults work fine.
        pkt.set_counter_parameter(
            "PktCnt", trek.CounterParameterInfo(zone=trek.PacketZoneType.HEADER_ZONE)
        )
 
        #  Add the time stamp.  There's no offset here, so the defaults will work.
        pkt.set_timestamp_parameter(
            "Time", trek.TimeStampParameterInfo(zone=trek.PacketZoneType.HEADER_ZONE)
        )
 
        #  Add the checksum.  It's a CRC-32 of all of the header and data.
        pkt.set_checksum_parameter(
            "Checksum",
            trek.ChecksumParameterInfo(
                trek.PacketZoneType.TRAILER_ZONE,
                trek.PacketChecksumPointType.START_HEADER,
                0,
                trek.PacketChecksumPointType.END_DATA,
                0,
                trek.PacketChecksumType.CT_CRC32,
            ),
        )
 
        # Saving this packet to a file is easy.
        pkt.save_file("my_file.xml")  # output is XML
 
        #  The definitializeion of the packet now is saved to a file.  You can use this
        #  definitializeion to build a packet to send or extract a packet you receive.
        #  Examples for both are provided.
 
    except trek.TrekError as err:
        # Locate friendly message why it failed.
        print(err.find_error_code())
        print(err)
 
 
if __name__ == "__main__":
    main()