The Data API classes perform telemetry and command data manipulation. These classes are used by TReK for all telemetry and command processing. The Packet class provides the encapsulation of data.
Each packet can have up to three 'zones' of information: header, data, and trailer. The header zone typically has information for packet identification and routing. The data zone usually holds the values that users will be interested in. The trailer zone, if available, often just consists of a single parameter such as a checksum. For a packet to be considered valid, at least one zone must be defined.
The first row in the picture shows a packet with three zones populated. The second row shows the details for each of the zones in the packet. The header zone consists of four parameters (A, B, C, and D). The data zone consists of another packet with just the header and data zones populated. The trailer zone consists of two parameters (N and O). The third row shows that the encapsulated packet breaks down into parameters in the header (E, F, and G) and data (H, I, J, K, L, and M).
The zones in a packet that contain parameters are all ParameterCollection objects. Each ParameterCollection consists of one or more Parameter. There is no limit to the amount of encapsulation allowed for packets.
API Overview
The full list of documented classes can be found in the Class List, but here is a high level summary of some of the most useful / common classes. Each of them can be saved to a file and loaded from a file. The format of the save file is XML.
Parameter
The Parameter encapsulates all the information for a telemetry or command data item. A parameter has a data type, length, byte order, and location to describe how to place it in a packet (build) or remove it from a packet (extract). Each parameter can have ranges set to restrict the valid values allowed. A parameter can also be calibrated with any of the built in TReK calibration options or with a user defined calibration function. An example of how to build a user defined calibrator can be found at the end of this page. The value of the parameter can also be checked for limit violations (high, low, and/or delta).
ParameterCollection
The ParameterCollection class is a set of parameters that are related.
A parameter collection can be used on its own, but most often will be inserted into a trek.Packet as one of the zones. A parameter collection can be created and reused in multiple packets. For example, if a parameter colllection defines the header it can be inserted as the header zone in multiple packets.
Packet
Packet is made up of the header, data, and trailer zones and defines a set of bytes that typically are transferred over an interface such as a socket or serial device. The packet can also have optional attributes defined. The attributes available for each packet are defined in the table below:
| Attribute | Description |
| Checksum | An integrity check for the data. The checksum can be any of the types supported by TReK (currently MD5, 16-bit sum (ISS), and CRC-32). A checksum will usually appear in either the header or trailer zone of a packet. If a checksum is specified, TReK will ensure that the data received matches the checksum. If TReK is building the data, the checksum will be calculated and placed in the packet. |
| Counter | An incrementing or decrementing count used for each packet. When building the packet, TReK will automatically set the counter and increment it to the next available counter value. |
| Identifiers | One or more identifiers can be set for a packet. Currently these are not used when receiving a packet (see packet header processors for that stuff). However, they are set when building a packet. |
| Length | A length for the packet including an optional offset value. For fixed length packets this value can be check to insure that the data is the correct length when received. The length is automatically set when building the packet. |
| Time Stamp | A time to be associated with all data in the packet. When building packets, TReK uses the current system time (with optional offset) to populate this value. Upon receipt, TReK will use this value as the time the packet originated from the source. |
PolynomialCalibrator
The PolynomialCalibrator class performs polynomial calibration on a parameter value using an nth order polynomial equation:
where x is the converted value of the parameter, n is the order of the polynomial, and C are constant values for each term.
SplineCalibrator
The SplineCalibrator class performs calibration using a series of line segments. The graphic below show a calibrator with three line segments.
The calibrated value of a parameter is found using the following equation:
LimitAlarm
The LimitAlarm class holds the high, low, and delta values that cause an alarm.
Multiple limit alarms can be set for a parameter and each one is assigned a 'level'. The higher the level number, the more severe the alarm. Up to 5 levels of alarms may be defined.
ParameterStatus
The ParameterStatus class holds status associated with a telemetry value.
Most of the methods available in the parameter status are not needed by a user program. A typical use of this class would be to set the status values and get the corresponding status string.
Examples
The following examples are provided to show how to use Data API classes:
Define a Packet
Creates a simple packet in code and stores the definition to an XML file. The file created in this example is used for the build and extract packet examples.
Source File: ex_packet_define.py
Build a Packet
Shows how to build a packet into a buffer from the individual parameters found in a packet. Uses the simple packet created in the define packet example.
Source File: ex_packet_build.py
Extract a Packet
Shows how to extract data from a buffer into the individual parameters found in a packet. Uses the simple packet created in the define packet example. Source File: ex_packet_extract.py
Additional Dependencies
The TReK Data API is also dependent on the following libraries. See the Libraries main help page for more information.