Main Page | Modules | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members | Related Pages

DC_PUSDataReportingPacket Class Reference

#include <DC_PUSDataReportingPacket.h>

Inheritance diagram for DC_PUSDataReportingPacket:

PUSTelemetryPacket TelemetryPacket CC_RootObject List of all members.

Detailed Description

PUS telemetry data reporting packet with no filtering.

A PUS data reporting packet is used to hold the data associated to a housekeeping and diagnostic data reporting definition (PUS service type 3). This class assumes that no filtering is performed on the reported data. The following types of service reports of the housekeeping and diagnostic data reporting service are modelled:<ul> The housekeeping parameter report (PUS service subtype 25) The diagnostic parameter report (PUS service subtype 26) A data reporting packet is characterized by the following attributes:

The SID is an integer that uniquely identifies the data reporting packet.

The collection interval defines the interval between successive dispatches of the packet content to the telemetry stream. The collection interval is expressed as a positive integer representing a number of activations of the data update service (see method update in the base class TelemetryPacket). Thus, for instance, a collection interval of 3 indicates that the data in the reporting packets are made available for dispatch to the telemetry stream every third activation of the data update service.

The parameter identifiers identify the parameters whose values have to be included in the reporting packet. Only parameters in the system data pool can be included in a data reporting packet. As parameter identifier, the data pool item identifier must be used (see class DataPool).

A fixed length array identifies a set of parameters that must be sampled with the frequency. The fixed length array specifies the sampling frequency through the the repetition count, namely the number of times that the parameters must be sampled in a collection interval. If C is the collection interval for the data reporting packet and NREP is the repetition count, then C must be a multiple of NREP. The value of the parameters is acquired every C/NREP activations of the data update service.

The mode flag determines whether the "mode" field should be included in the generated packet. If it is to be included, its value is always zero. The mode flag is a static attribute that is defined as a constant PUS_DATA_REP_MODE in file Constants.h.

The enabled flag determines whether the data reporting packet is enabled or disabled. If a data reporting packet is disabled, then its update service takes no action and its data acquisition service reports: "no telemetry data to be acquired".

An instance of this class is first configured after being created by performing the following operations:

The packet definition buffer is an internal buffer that holds a copy of the application data of the PUS telecommand that defined the housekeeping or diagnostic packet report. The packet value buffer is an internal buffer that holds an image of telemetry data associated to this telemetry packet. In particular, it hols the values of the parameters as they are acquired in a collection interval.

Instances of this class will normally undergo a second configuration process at run time when the housekeeping or diagnostic report definition is loaded. This configuration procedure is performed by loading the packet definition buffer byte by byte using method setDefinitionBuffer.

The PUS specifies that the SID, the collection interval, the number of parameters, the number of repetitions, and the number of fixed-length arrays, should be of "unsigned integer" type but it does not specify the implementation of this type. This class uses typedef type definitions for the SID, the collection interval, and the number of parameters and it implements the number of repetitions and the number of fixed length arrays as "unsigned char". Similarly, the PUS specifies that the mode of packet generation should be of "enumerated" type but it does not elaborate on the exact nature of this type. This class implements the mode indicator as an "unsigned char".

This class retrieves the data to be stored in the PUS reporting packet from the system data pool. In order to copy them to the packet, information about the type of the data is required. This information is retrieved by using the type checking service of the data pool (see methods isFloat and isInteger in class DataPool). This class therefore assumes that the type checking service is fully implemented by the system data pool.

This class implements the fast version of the data acquisition service. This is useful when the amount of telemetry data is very large.

Description of Internal Data Structures The internal data structures of this class do not differentiate between the paramaters that are sampled only once per collection interval and the fixed-length arrays that describe oversampled paramaters. To the parameters that are sampled only once per collection interval, a fictitious fixed-length array is associated with a repetition count of 1.

The internal array F holds the descriptors of the fixed length arrays. Element F[0] describes the parameters that are to be sampled only once per collection interval. Element F[i] with i>0 describes the i-th fixed length array.

The definition of the PUS packet is kept in the packet definition buffer that is a byte-by-byte copy of the application data in the PUS telecommand defining the housekeeping or diagnostic parameter report. This buffer is loaded byte by byte and it is interpreted as it is loaded. The objective of the interpretation is to set up a "map" of the buffer. This map consists of variables that point to locations in the buffer where certain information is held. Thus, for instance, internal variable indNFA points to the location in the buffer where the NFA field is stored. The most important mapping variable is the array indFA. Element indFA[i] with i>0 holds the location of the NREP value of the i-th fixed-length array.

The packet value buffer is organized as an array of unsigned char. Its first locations hold the SID and, depending on the value of flag PUS_DATA_REP_MODE, the reporting mode. Successive locations hold the collected parameter values stored in consecutive locations.

See also:
DataPool
Author:
Alessandro Pasetti (P&P Software GmbH)
Version:
1.0

Definition at line 137 of file DC_PUSDataReportingPacket.h.

Public Member Functions

 DC_PUSDataReportingPacket (void)
 Instantiate a PUS data report packet.

void setEnabled (bool enabledStatus)
 Set the enable status of the data reporting packet.

bool isEnabled () const
 Return the enable status of the data reporting packet.

TD_PUSCollectionInterval getCollectionInterval ()
 Getter method for the collection interval.

TD_PUSNumberOfParameters getNPAR1 ()
 Getter method for the number of parameters to be sampled once per collection interval.

unsigned char getNFA ()
 Getter method for the number of fixed-length arrays.

TD_SID getSID ()
 Getter method for the structure identifier (SID) of the data reporting packet.

void setDefinitionBuffer (unsigned int i, unsigned char val)
 Load the i-the byte of the packet definition buffer.

unsigned char getDefinitionBuffer (unsigned int i)
 Return the i-th byte of the packet definition buffer.

unsigned int getDefinitionBufferLength (void)
 Return the number of bytes in the packet definition buffer that were loaded with the last set of consecutive calls to method setDefinitionBuffer.

virtual void update ()
 Implement the data update service.

void reset ()
 Reset the internal state of the data reporting packet.

virtual unsigned int getNumberOfBytes (void)
 Return the number of bytes that this data reporting packet will provide at the next call of the data acquisition service.

virtual unsigned char getUnsignedByte (unsigned int n)
 Return the n-th byte of this data reporting packet.

virtual unsigned char * getStartAddress (void)
 Return a pointer to start address of the packet value buffer.

virtual bool isFastAcquisitionImplemented (void)
 Return true to signify that the fast version of the data acquisition service is implemented.

void setDefinitionBufferSize (unsigned int size)
 Set the maximum size of the packet definition buffer.

unsigned int getDefinitionBufferSize ()
 Get the maximum size of the packet definition buffer.

void setMaxNumberFA (unsigned int n)
 Set the maximum number of fixed-length arrays that are allowed in a data reporting packet.

unsigned int getMaxNumberFA (void)
 Return the maximum number of fixed-length arrays that are allowed in a data reporting packet.

void setValueBufferSize (unsigned int size)
 Set the maximum size of the packet value buffer.

unsigned int getValueBufferSize (void)
 Return the maximum size of the packet value buffer.

virtual bool isObjectConfigured (void)
 Perform a class-specific configuration check on the telemetry packet: verify that:.


Protected Member Functions

TD_DataPoolId getParameterId (unsigned int faIndex, unsigned int parPos)
 Get the parameter id of the parPos-th parameter in the faIndex-th fixed length array.

Constructor & Destructor Documentation

DC_PUSDataReportingPacket::DC_PUSDataReportingPacket (  void   ) 
 

Instantiate a PUS data report packet.

The size of the internal buffers are set to illegal values to signify that the data report packet is not yet configured. The class identifier is set. The packet type is set to: PUS_TYPE_DATA_REP. The enable status is set to "disabled". The "in use" status is set to: "packet not in use".

See also:
PUS_TYPE_DATA_REP

Definition at line 21 of file DC_PUSDataReportingPacket.cpp.

Member Function Documentation

TD_PUSCollectionInterval DC_PUSDataReportingPacket::getCollectionInterval (   ) 
 

Getter method for the collection interval.

Returns:
the collection interval

Definition at line 44 of file DC_PUSDataReportingPacket.cpp.

unsigned char DC_PUSDataReportingPacket::getDefinitionBuffer (  unsigned int  i  ) 
 

Return the i-th byte of the packet definition buffer.

The values that are returned are those that were set with the last set of consecutive calls to method setDefinitionBuffer. This method should be used in conjunction with method getDefinitionBufferLength. The legal range of the index i is [0,N-1] where N is the return value of getDefinitionBufferLength.

See also:
getDefinitionBufferLength

setDefinitionBuffer

Parameters:
i the index of the byte in the packet definition buffer to be returned
Returns:
the value of the byte

Definition at line 197 of file DC_PUSDataReportingPacket.cpp.

unsigned int DC_PUSDataReportingPacket::getDefinitionBufferLength (  void   ) 
 

Return the number of bytes in the packet definition buffer that were loaded with the last set of consecutive calls to method setDefinitionBuffer.

Returns:
the number of loaded bytes in the packet definition buffer

Definition at line 192 of file DC_PUSDataReportingPacket.cpp.

unsigned int DC_PUSDataReportingPacket::getDefinitionBufferSize (   ) 
 

Get the maximum size of the packet definition buffer.

Returns:
the size of the packet definition buffer

Definition at line 314 of file DC_PUSDataReportingPacket.cpp.

unsigned int DC_PUSDataReportingPacket::getMaxNumberFA (  void   ) 
 

Return the maximum number of fixed-length arrays that are allowed in a data reporting packet.

Returns:
the maximum number of Ffixed-length arrays

Definition at line 349 of file DC_PUSDataReportingPacket.cpp.

unsigned char DC_PUSDataReportingPacket::getNFA (   ) 
 

Getter method for the number of fixed-length arrays.

Returns:
the number of fixed-length arrays

Definition at line 58 of file DC_PUSDataReportingPacket.cpp.

TD_PUSNumberOfParameters DC_PUSDataReportingPacket::getNPAR1 (   ) 
 

Getter method for the number of parameters to be sampled once per collection interval.

Returns:
the number of parameters

Definition at line 51 of file DC_PUSDataReportingPacket.cpp.

unsigned int DC_PUSDataReportingPacket::getNumberOfBytes (  void   )  [virtual]
 

Return the number of bytes that this data reporting packet will provide at the next call of the data acquisition service.

If this method is called at a time other than the end of a collection interval, then its return value is zero. The end of a collection interval is detected by looking at the value of the main counter defined in method update. At the end of a collection interval, this counter has value zero. A return value of zero for this method indicates that the data reporting packet is not providing any data for the telemetry stream. A PUS data reporting packet is only intended to provide telemetry data at the end of its collection interval.

If this method is called at the end of a collection interval (i.e. at a time when the main counter defined in method updatey is equal to zero), then its return value is equal to the number of bytes in the data reporting packet. This is computed as follows: 

      n1 = sizeof(TD_SID);
      if (PUS_DATA_REP_MODE)
          n2 = 1;
      else
          n2 = 0;
      n3 = 0;
      for (all parameters p in the packet)
          if (p is of type TD_Float)
              n3 += (repetition count of p) * sizeof(TD_Float);
          else
              n3 += (repetition count of p) * sizeof(TD_Integer);
      return (n1+n2+n3);
The "repetition count" of a parameter is 1 for parameters that are collected only once per cycle and it is as specified by the relevant fixed-length array for over-sampled parameters.

If the packet is disabled, then this method returns zero to signify that a disabled packet should not provide any telemetry data.

See also:
update
Returns:
the number of bytes in this data reporting packet at the end of a collection interval or zero at other times

Implements TelemetryPacket.

Definition at line 271 of file DC_PUSDataReportingPacket.cpp.

TD_DataPoolId DC_PUSDataReportingPacket::getParameterId (  unsigned int  faIndex,
unsigned int  parPos
)  [protected]
 

Get the parameter id of the parPos-th parameter in the faIndex-th fixed length array.

The parameter id is read from the packet definition buffer. The value of faIndex should lie in the interval [0,N] where N is the number of fixed length arrays in the packet. A value of faIndex equal to zero is taken to refer to the paramaters that are sampled only once per collection interval. The value of parPos should lie in the interval [0,M-1] where M is the total number of parameters in the fixed-length array (or the total number of parameters to be sampled only once per collection interval).

Parameters:
faIndex the fixed length array index
parPos the position of the parameter in the fixed length array
Returns:
the paramater identifier

Definition at line 202 of file DC_PUSDataReportingPacket.cpp.

TD_SID DC_PUSDataReportingPacket::getSID (   ) 
 

Getter method for the structure identifier (SID) of the data reporting packet.

Returns:
the SID of the packet

Definition at line 63 of file DC_PUSDataReportingPacket.cpp.

unsigned char * DC_PUSDataReportingPacket::getStartAddress (  void   )  [virtual]
 

Return a pointer to start address of the packet value buffer.

This method implements the fast version of the data acquisition service. This may be useful (if potentially unsafe) in the case of large packets.

Returns:
the start address of the packet value buffer

Reimplemented from TelemetryPacket.

Definition at line 295 of file DC_PUSDataReportingPacket.cpp.

unsigned char DC_PUSDataReportingPacket::getUnsignedByte (  unsigned int  n  )  [virtual]
 

Return the n-th byte of this data reporting packet.

The image of this packet is stored in the packet value buffer. This method therefore simply returns the value of the n-th element of the packet value buffer. Note that this method is independent of whether or not the packet is enabled.

Parameters:
n the byte to be returned

Implements TelemetryPacket.

Definition at line 286 of file DC_PUSDataReportingPacket.cpp.

unsigned int DC_PUSDataReportingPacket::getValueBufferSize (  void   ) 
 

Return the maximum size of the packet value buffer.

Returns:
the size of the packet definition buffer

Definition at line 328 of file DC_PUSDataReportingPacket.cpp.

bool DC_PUSDataReportingPacket::isEnabled (   )  const
 

Return the enable status of the data reporting packet.

Returns:
true if the data reporting packet is enabled, false otherwise

Definition at line 74 of file DC_PUSDataReportingPacket.cpp.

bool DC_PUSDataReportingPacket::isFastAcquisitionImplemented (  void   )  [virtual]
 

Return true to signify that the fast version of the data acquisition service is implemented.

See also:
getStartAddress
Returns:
this method always returns true

Reimplemented from TelemetryPacket.

Definition at line 300 of file DC_PUSDataReportingPacket.cpp.

bool DC_PUSDataReportingPacket::isObjectConfigured (  void   )  [virtual]
 

Perform a class-specific configuration check on the telemetry packet: verify that:.

  • The maximum size of the packet definition buffer has a legal value
  • The maximum size of the packet value buffer has a legal value
  • The maximum number of fixed-length arrays has a legal value
Returns:
true if the component is configured, false otherwise.

Reimplemented from PUSTelemetryPacket.

Definition at line 354 of file DC_PUSDataReportingPacket.cpp.

void DC_PUSDataReportingPacket::reset (   ) 
 

Reset the internal state of the data reporting packet.

The main counter is initialized to the value of the collection interval. The FA counters are initialized to the value of the repetition counter of their fixed-length array. The component is disabled.

See also:
update

Definition at line 78 of file DC_PUSDataReportingPacket.cpp.

void DC_PUSDataReportingPacket::setDefinitionBuffer (  unsigned int  i,
unsigned char  val
) 
 

Load the i-the byte of the packet definition buffer.

As the packet bytes are loaded, they are interpreted and the internal map of the packet is constructed. This method assumes that the bytes are loaded in sequence starting from the most significant byte of the SID and ending with the least significant byte of the last parameter identifier in the last fixed-length array of the packet.

The index i must lie in the interval [0,N-1] where N is the size of the packet definition buffer. If this is not the case, then the method generates an event report EVT_ILLEGAL_PUS_REP_PACKET and returns without taking any further action.

This method, among other things, maintains a counter that keeps track of the number of fixed length arrays that have been loaded. If the number of fixed length arrays exceeds the maximum value set with method setMaxNumberFA, then an event report EVT_ILLEGAL_PUS_REP_PACKET is generated.

See also:
setDefinitionBufferSize
Parameters:
i the byte to be loaded
val the value of the byte

Definition at line 90 of file DC_PUSDataReportingPacket.cpp.

void DC_PUSDataReportingPacket::setDefinitionBufferSize (  unsigned int  size  ) 
 

Set the maximum size of the packet definition buffer.

This is an initialization method. It should be called only once as part of the component configuration during the application initialization phase. The maximum size should be smaller than 0xFF.

Todo:
Clarify the reason for the 0xFF limit on the buffer size. This seems to be obsolete.
Parameters:
size the size of the packet definition buffer

Definition at line 304 of file DC_PUSDataReportingPacket.cpp.

void DC_PUSDataReportingPacket::setEnabled (  bool  enabledStatus  ) 
 

Set the enable status of the data reporting packet.

Parameters:
enabledStatus the new enabled status

Definition at line 70 of file DC_PUSDataReportingPacket.cpp.

void DC_PUSDataReportingPacket::setMaxNumberFA (  unsigned int  n  ) 
 

Set the maximum number of fixed-length arrays that are allowed in a data reporting packet.

This is an initialization method. It should be called only once as part of the component configuration during the application initialization phase.

Parameters:
n the maximum number of fixed-length arrays

Definition at line 332 of file DC_PUSDataReportingPacket.cpp.

void DC_PUSDataReportingPacket::setValueBufferSize (  unsigned int  size  ) 
 

Set the maximum size of the packet value buffer.

This is an initialization method. It should be called only once as part of the component configuration during the application initialization phase.

Parameters:
size the size of the packet definition buffer

Definition at line 318 of file DC_PUSDataReportingPacket.cpp.

void DC_PUSDataReportingPacket::update (   )  [virtual]
 

Implement the data update service.

This class maintains a main counter and a a set of FA counters, one for each fixed-length array. After a reset (call to method reset). The main counter is initialized to the value of the collection interval. The FA counters are initialized to the value of the repetition count of their fixed-length array. If the component is enabled, then every time this method is called, the counters are decremented by one. When an FA counter reaches the value of zero, the following actions are performed:

  • The values of the parameters in the fixed-length array are acquired from the system database and are stored in the parameter buffer
  • The FA counter is reset to its initial value
When the main counter reaches zero, then all the parameter values are acquired. In all cases, the time attribute of the telemetry packet is set to the current time.

Implements TelemetryPacket.

Definition at line 212 of file DC_PUSDataReportingPacket.cpp.

The documentation for this class was generated from the following files:
Copyright 2003 P&P Software GmbH - All Rights Reserved