net_telemetry.h File Reference

Detailed Description

State-of-health telemetry using QCBOR.

This file implements a multipurpose system for reporting state-of-health telemetry, typically over a network interface. All messages in this system are CBOR-encoded as a key-value dictionary. Users can choose to use integer keys (more compact) or string keys (more readable). Classes are provided to send and receive telemetry.

The transmit API can be operated in raw-Ethernet mode (eth::Telemetry) or UDP mode (udp::Telemetry). In both cases, the user must call connect(...) to set the destination address. To begin sending telemetry:

• Instantiate either eth::Telemetry or net::Telemetry.
• Create a user-defined net::TelemetrySource object that overrides telem_event(...) to send key/value data of interest.
• Instantiate net::TelemetryTier, passing the previous objects and the desired reporting interval. (Optionally, this object may be included as part of the user-defined net::TelemetrySource.)
• Call the Telemetry object's connect(...) method.

The transmit API uses the following classes:

• net::TelemetryAggregator This is the parent class that handles encoded data delivery, creation of the CBOR encoder, timer polling, etc. Each TelemetryAggregator object operates a linked list of associated TelemetryTier object(s). Encoded CBOR data is passed to one or more TelemetrySink object(s).
• net::TelemetryTier This class sets the reporting interval for a specific "tier" of data for a given TelemetrySource. Each TelemetrySource may have multiple tiers operating at different rates, identified by an ID number. ID-codes are optional parameters used by sources and sinks to indicate the content and priority of data, for filtering or other purposes. (i.e., Sources with only one tier can simply set the ID to zero.)
• net::TelemetrySink This class accepts encoded telemetry data and sends it to the network, using a user-selected transport protocol. Implementations are provided for raw-Ethernet (eth::Telemetry) and UDP (udp::Telemetry). To add headers or use other protocols, users should inherit from this class and override the telem_ready(...) method.
• net::TelemetrySource This class is a user-defined data source. Users MUST define a class that inherits from the net::TelemetrySource class and overrides the telem_event(...) method. Sources MAY instantiate any number of TelemetryTier member variables as part of their class definition.
• net::TelemetryCbor An ephemeral wrapper passed to the TelemetrySource::telem_event(...) method. Use the provided helper methods (add_*) or call QCBOR functions directly using the provided "EncodeContext" pointer.
• eth::Telemetry Send CBOR telemetry using raw-Ethernet frames. (Combined net::TelemetryAggregator + net::TelemetrySink.)
• udp::Telemetry Send CBOR telemetry using UDP datagrams. (Combined net::TelemetryAggregator + net::TelemetrySink.)

The receive API uses the following classes:

• net::TelemetryWatcher This class receives a callback for each received key/value pair. It should identify information of interest and discard other items.
• net::TelemetryKey Store a pointer to a statically-allocated global string (const char*) and calculate the CRC32 hash for that string.
• net::TelemetryLogger An example implementation of net::TelemetryWatcher. This class logs received key/value pairs, with an optional filter.
• net::TelemetryLoopback This TelemetrySink attaches to an existing interface for outgoing telemetry messages, and echoes their contents to a designated net::TelemetryRx object. This is useful for message-passing systems that may accept messages from internal or external sources.
• net::TelemetryRx Helper-class and parent of eth::TelemetryRx and udp::TelemetryRx. This class parses the incoming CBOR message and notifies registered callbacks (net::TelemetryWatcher). Create a child class to define a custom transport protocol.
• eth::TelemetryRx Receive CBOR telemetry using raw-Ethernet frames.
• udp::TelemetryRx Receive CBOR telemetry using UDP datagrams.

Definition in file net_telemetry.h.

#include <satcat5/eth_socket.h>
#include <satcat5/io_cbor.h>
#include <satcat5/list.h>
#include <satcat5/polling.h>
#include <satcat5/types.h>
#include <satcat5/udp_socket.h>

Include dependency graph for net_telemetry.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	satcat5::net::TelemetryCbor
	Legacy ephemeral wrapper class for the CBOR encoder. More...
class	satcat5::net::TelemetrySink
	User data sinks must inherit from the TelemetrySink class. More...
class	satcat5::net::TelemetrySource
	User data sources must inherit from the TelemetrySource class. More...
class	satcat5::net::TelemetryTier
	Rate control for a particular telemetry "tier". More...
class	satcat5::net::TelemetryAggregator
	Protocol-agnostic handler for one or more TelemetryTier objects. More...
class	satcat5::net::TelemetryWatcher
	Callback API for incoming telemetry items. More...
struct	satcat5::net::TelemetryKey
	String constant, plus the CRC32 hash of that string. More...
class	satcat5::net::TelemetryLogger
	Example TelemetryWatcher that logs received key/value pairs. More...
class	satcat5::net::TelemetryRx
	Parse incoming CBOR telemetry and notify TelemetryWatcher callbacks. More...
class	satcat5::net::TelemetryLoopback
	Loopback adapter for telemetry messages. More...
class	satcat5::eth::Telemetry
	Thin wrapper for sending CBOR telemetry over raw-Ethernet. More...
class	satcat5::eth::TelemetryRx
	Thin wrapper for receiving CBOR telemetry over raw-Ethernet. More...
class	satcat5::udp::Telemetry
	Thin wrapper for sending CBOR telemetry over UDP. More...
class	satcat5::udp::TelemetryRx
	Thin wrapper for receiving CBOR telemetry over UDP. More...