Data (Packet)

Table of Contents

• Constructing Packets
  • Create Parameter
  • Add to Parameter Collection
  • Adding Collection to Packet

For this tutorial, we will walk through constructing a packet using the Python package classes. Let's start with our packet definition.

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

Constructing Packets

To get started, the basic process to build a packet is bottom up:

1. Create/Configure a Parameter
2. Add defined Parameter to a ParameterCollection
3. Add ParameterCollection to Packet zone.

Create Parameter

From our list above, let's create the first parameter, Version. Version will be the first 4-bits.

In our Python, we import the classes we will need (usually at the top of a pyhon file).

from trek.parameter import Parameter, ParameterDataType

Then, create a Parameter and configure the data.

param = Parameter()
 
# Initialize not required the first time, but it doesn't hurt.
param.initialize()
param.set_name("Version")
param.set_start_bit(0)    
param.set_data_type(ParameterDataType.DT_UNSIGNED_INTEGER, 4)
param.set_modifiable_flag(False)
param.set_value(0)

Add to Parameter Collection

We add our parameter to a collection. Once added to the collection, a copy is made in the collection and we can re-use our instance of the parameter class for the next parameter because the collection class will make it's own copy.

pc = ParameterCollection()   # create a new collection
pc.add_parameter(param)      # Add parameter to collection

Putting it together, below, there are two parameters added to our collection while re-using our Parameter instance after it is added to the collection.

pc = ParameterCollection()
param = Parameter()
 
# Initialize not required the first time, but it doesn't hurt.
param.initialize()
param.set_name("Version")
param.set_start_bit(0)    
param.set_data_type(ParameterDataType.DT_UNSIGNED_INTEGER, 4)
param.set_modifiable_flag(False)
param.set_value(0)
 
pc.add_parameter(param)
 
# Re-use parameter
param.initialize()
param.set_name("PktId")
param.set_start_bit(4)    
param.set_data_type(ParameterDataType.DT_UNSIGNED_INTEGER, 12)
param.set_modifiable_flag(False)
 
pc.add_parameter(param)

We have created two parameters totalling 16 bits. The first 4 bits are the version and the next 12 bits are the packet ID.

Adding Collection to Packet

This same process is used to configure and add each parameter into our collection for a desired zone. Once we step through all the parameters for our zone, we can add the completed collection to our packet's zone.

This could be add_header, add_trailer, or add_data zones.

pkt = Packet()
pkt.add_header(pc)

The example below provides the completed process for the whole packet and saves the packet in XML form to a file. This saved XML Packet constitutes a "packet definition" used for sending / recieving data.

In closing, we have provided three examples to help with defining, building and extracting packets.

• ex_packet_define.py - Follows this tutorials process to create a packet using code.
• ex_packet_build.py - Once you have a packet definition and values stored for each parameter, you can "build" (pack) the values into a binary representation.
• ex_packet_extract.py - Finally, if you have binary ex_packet_define packet, you will want to see hot to reverse the process and deconstruct binary data into it's discrete values.