ex_packet_build.py

"""
Example TReK Building a Packet
 
This example builds the packet described by the define_packet example.  If
that example hasn't run, you will need to do that now.  The file that is
created must be located where this program can find it.
The table below shows what is defined in the packet:
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()
        param_value: float = 0.0
 
        # Read in the packet file.
        pkt.load_file("my_file.xml")
 
        # After loading a packet, you must create the 'map' that allows parameter lookup.
        pkt.create_global_packet_map()
 
        # Since the define_packet example doesn't set all of the parameter
        # values, they must be set here or the build will fail.  You can use
        # GetParameterList or GetSortedParameterList to get a list of the
        # parameter names if needed.  Since the names are already known (check
        # the top of this file) we can set the values without the lookup.
        #
        # HINT: You'll only need to set the values in the "data zone".  The
        # values in the header and trailer were either set in the
        # define_packet example with your code or were set automatically to
        # defaults when setting packet attributes.
        #
        # Must find the parameter before we can set the value.  The pointer that is
        # returned can be saved so you don't have to perform the lookup each time.
        param = pkt.find_parameter("IntParam")
 
        # Now set the value.  This is a 16 bit signed integer.  TReK will check
        # value you pass in to make sure that it is allowed for the parameter.
        # Since there wasn't a high or low range set here, TReK will check that
        # the value passed in is between -32,768 and 32,767 inclusive.  We're
        # using a floating point value so TReK will also check if the value is a
        # fraction.  The value will still be set, but you'll get a return code
        # indicating a 'possible loss of data'.
        param_value = -2
        param.set_value(param_value)
 
        # SetValue calls can fail because of data type mismatches (trying to
        # set a binary value with a float) or many other things.  You can look
        # up the return code in the online documentation to get an idea on
        # what to check.
 
        # Now set the value for the UintParam which has 3 samples.  The set value
        # call takes an optional sample number.  We don't have to use it for the
        # first sample.
        param = pkt.find_parameter("UintParam")
        param.set_value(1024, 1)
        param.set_value(2048, 2)
        param.set_value(4096, 3)
 
        # The floating point parameter needs a value too.
        param = pkt.find_parameter("FloatParam")
        param_value = 1.2345
        param.set_value(param_value)
 
        # The StrParam is variable length.  Only the bytes needed for the value
        # (plus the NULL terminating character) will appear in the packet.
        param = pkt.find_parameter("StrParam")
        param.set_value("Howdy Y'all")
 
        # Now that all of the data is defined, we can build the packet.  You'll
        # need a buffer large enough to hold the maximum length packet.  The
        # packet attributes will automatically be set by the Packet class.  Each
        # identifier will be set, the sequence count will be set and incremented,
        # the time will be set to the current system time, the length will be
        # calculated and set, and finally the checksum (CRC-32) will be
        # calculated and set.
 
        buf = bytearray(1000)
        _ = pkt.build(buf)  # returned last_bit_used not used in example.
 
        # One common reason for a build to fail is that one or more parameters
        # do not have a value.  Another reason is that the build buffer isn't
        # large enough. You should always set the buf_size prior to each call
        # to Build().  The build method will reset the value to the number of
        # bytes that are valid.  If you have a variable length packet, failure
        # to reset the value can cause an error.
 
        # Now that the buffer is set, you could use other functions in TReK to
        # send the data.  Check out the Device Services API if you need to do
        # that.
 
    except trek.TrekError as err:
        # Locate friendly message why it failed.
        print(err.find_error_code())
        print(err)
 
 
if __name__ == "__main__":
    main()