This class is used to send and receive ISOBUS heartbeats. More...

#include <isobus_heartbeat.hpp>

Classes
class	Heartbeat
	This class is used to store information about a tracked heartbeat. More...

Public Types
enum class	HeartBeatError { InvalidSequenceCounter , TimedOut }
	This enum is used to define the possible errors that can occur when receiving a heartbeat. More...

Public Member Functions
	HeartbeatInterface (const CANMessageFrameCallback &sendCANFrameCallback)
	Constructor for a HeartbeatInterface.

void	set_enabled (bool enable)
	This can be used to disable or enable this heartbeat functionality. It's probably best to leave it enabled for most applications, but it's not strictly needed.

bool	is_enabled () const
	Returns if the interface is currently enabled or not.

bool	request_heartbeat (std::shared_ptr< InternalControlFunction > sourceControlFunction, std::shared_ptr< ControlFunction > destinationControlFunction) const
	This method can be used to request that another control function on the bus start sending the heartbeat message. This does not mean the request will be honored. In order to know if your request was accepted, you will need to either register for timeout events, register for heartbeat events, or check to see if your destination control function ever responded at some later time using the various methods available to you on this class' public interface.

void	on_new_internal_control_function (std::shared_ptr< InternalControlFunction > newControlFunction)
	Called by the internal control function class when a new internal control function is added. This allows us to respond to requests for heartbeats from other control functions.

void	on_destroyed_internal_control_function (std::shared_ptr< InternalControlFunction > destroyedControlFunction)
	Called when an internal control function is deleted. Cleans up stale registrations with PGN request protocol.

EventDispatcher< HeartBeatError, std::shared_ptr< ControlFunction > > &	get_heartbeat_error_event_dispatcher ()
	Returns an event dispatcher which can be used to register for heartbeat errors. Heartbeat errors are generated when a heartbeat message is not received within the repetition rate, or when the sequence counter is not valid. The control function that generated the error is passed as an argument to the event.

EventDispatcher< std::shared_ptr< ControlFunction > > &	get_new_tracked_heartbeat_event_dispatcher ()
	Returns an event dispatcher which can be used to register for new tracked heartbeat events. An event will be generated when a new control function is added to the list of CFs sending heartbeats. The control function that generated the error is passed as an argument to the event.

void	process_rx_message (const CANMessage &message)
	Processes a CAN message, called by the network manager.

void	update ()
	Updates the interface. Called by the network manager, so there is no need for you to call it in your application.

Private Types
enum class	SequenceCounterSpecialValue : std::uint8_t { Initial = 251 , Error = 254 , NotAvailable = 255 }
	This enum is used to define special values for the sequence counter. More...

Static Private Member Functions
static bool	process_request_for_heartbeat (std::uint32_t parameterGroupNumber, std::shared_ptr< ControlFunction > requestingControlFunction, std::shared_ptr< ControlFunction > targetControlFunction, std::uint32_t repetitionRate, void *parentPointer)
	Processes a PGN request for a heartbeat.

Private Attributes
const CANMessageFrameCallback	sendCANFrameCallback
	A callback for sending a CAN frame.

EventDispatcher< HeartBeatError, std::shared_ptr< ControlFunction > >	heartbeatErrorEventDispatcher
	Event dispatcher for heartbeat errors.

EventDispatcher< std::shared_ptr< ControlFunction > >	newTrackedHeartbeatEventDispatcher
	Event dispatcher for when a heartbeat message from another control function becomes tracked by this interface.

std::list< Heartbeat >	trackedHeartbeats
	Store tracked heartbeat data, per CF.

bool	enabled = true
	Attribute that specifies if this interface is enabled. When false, the interface does nothing.

Static Private Attributes
static constexpr std::uint32_t	SEQUENCE_TIMEOUT_MS = 300
	If the repetition rate exceeds 300 ms an error in the communication is detected.

static constexpr std::uint32_t	SEQUENCE_INITIAL_RESPONSE_TIMEOUT_MS = 250
	When requesting a heartbeat from another device, If no response for the repetition rate has been received after 250 ms, the requester shall assume that the request was not accepted.

static constexpr std::uint32_t	SEQUENCE_REPETITION_RATE_MS = 100
	A consuming CF shall send a Request for Repetition rate for the heart beat message with a repetition rate of 100 ms.

Detailed Description

This class is used to send and receive ISOBUS heartbeats.

Definition at line 30 of file isobus_heartbeat.hpp.

Member Enumeration Documentation

◆ HeartBeatError

enum class isobus::HeartbeatInterface::HeartBeatError

strong

This enum is used to define the possible errors that can occur when receiving a heartbeat.

Enumerator
InvalidSequenceCounter	The sequence counter is not valid.
TimedOut	The heartbeat message has not been received within the repetition rate.

Definition at line 34 of file isobus_heartbeat.hpp.

◆ SequenceCounterSpecialValue

enum class isobus::HeartbeatInterface::SequenceCounterSpecialValue : std::uint8_t

strongprivate

This enum is used to define special values for the sequence counter.

Enumerator
Initial	The heartbeat sequence number value shall be set to 251 once upon initialization of a CF.
Error	Sequence Number value 254 indicates an error condition.
NotAvailable	This value shall be used when the transmitted CF is in a shutdown status and is gracefully disconnecting from the network.

Definition at line 102 of file isobus_heartbeat.hpp.

Constructor & Destructor Documentation

◆ HeartbeatInterface()

isobus::HeartbeatInterface::HeartbeatInterface ( const CANMessageFrameCallback & sendCANFrameCallback )

Constructor for a HeartbeatInterface.

Parameters

[in] sendCANFrameCallback A callback used to send CAN frames

Definition at line 26 of file isobus_heartbeat.cpp.

Member Function Documentation

◆ get_heartbeat_error_event_dispatcher()

EventDispatcher< HeartbeatInterface::HeartBeatError, std::shared_ptr< ControlFunction > > & isobus::HeartbeatInterface::get_heartbeat_error_event_dispatcher ( )

Returns an event dispatcher which can be used to register for heartbeat errors. Heartbeat errors are generated when a heartbeat message is not received within the repetition rate, or when the sequence counter is not valid. The control function that generated the error is passed as an argument to the event.

Returns: An event dispatcher for heartbeat errors

Definition at line 82 of file isobus_heartbeat.cpp.

◆ get_new_tracked_heartbeat_event_dispatcher()

EventDispatcher< std::shared_ptr< ControlFunction > > & isobus::HeartbeatInterface::get_new_tracked_heartbeat_event_dispatcher ( )

Returns an event dispatcher which can be used to register for new tracked heartbeat events. An event will be generated when a new control function is added to the list of CFs sending heartbeats. The control function that generated the error is passed as an argument to the event.

Returns: An event dispatcher for new tracked heartbeat events

Definition at line 87 of file isobus_heartbeat.cpp.

◆ is_enabled()

bool isobus::HeartbeatInterface::is_enabled ( ) const

Returns if the interface is currently enabled or not.

Note: The interface is enabled by default.

Returns: true if the interface is enabled, false if the interface is disabled

Definition at line 40 of file isobus_heartbeat.cpp.

◆ on_destroyed_internal_control_function()

void isobus::HeartbeatInterface::on_destroyed_internal_control_function ( std::shared_ptr< InternalControlFunction > destroyedControlFunction )

Called when an internal control function is deleted. Cleans up stale registrations with PGN request protocol.

Parameters

[in] destroyedControlFunction The destroyed internal control function

Definition at line 72 of file isobus_heartbeat.cpp.

Here is the call graph for this function:

◆ on_new_internal_control_function()

void isobus::HeartbeatInterface::on_new_internal_control_function ( std::shared_ptr< InternalControlFunction > newControlFunction )

Called by the internal control function class when a new internal control function is added. This allows us to respond to requests for heartbeats from other control functions.

Parameters

[in] newControlFunction The new internal control function

Definition at line 62 of file isobus_heartbeat.cpp.

Here is the call graph for this function:

◆ process_request_for_heartbeat()

bool isobus::HeartbeatInterface::process_request_for_heartbeat	(	std::uint32_t	parameterGroupNumber,
		std::shared_ptr< ControlFunction >	requestingControlFunction,
		std::shared_ptr< ControlFunction >	targetControlFunction,
		std::uint32_t	repetitionRate,
		void *	parentPointer )

staticprivate

Processes a PGN request for a heartbeat.

Parameters

[in]	parameterGroupNumber	The PGN being requested
[in]	requestingControlFunction	The control function that is requesting the heartbeat
[in]	targetControlFunction	The control function that is being requested to send the heartbeat
[in]	repetitionRate	The repetition rate for the heartbeat
[in]	parentPointer	A context variable to find the relevant instance of this class

Returns: True if the request was transmitted, otherwise false.

Definition at line 200 of file isobus_heartbeat.cpp.

Here is the caller graph for this function:

◆ process_rx_message()

void isobus::HeartbeatInterface::process_rx_message ( const CANMessage & message )

Processes a CAN message, called by the network manager.

Parameters

[in] message The CAN message being received

Definition at line 154 of file isobus_heartbeat.cpp.

Here is the call graph for this function:

◆ request_heartbeat()

bool isobus::HeartbeatInterface::request_heartbeat	(	std::shared_ptr< InternalControlFunction >	sourceControlFunction,
		std::shared_ptr< ControlFunction >	destinationControlFunction ) const

This method can be used to request that another control function on the bus start sending the heartbeat message. This does not mean the request will be honored. In order to know if your request was accepted, you will need to either register for timeout events, register for heartbeat events, or check to see if your destination control function ever responded at some later time using the various methods available to you on this class' public interface.

Note: CFs may take up to 250ms to begin sending the heartbeat.

Parameters

[in]	sourceControlFunction	The internal control function to use when sending the request
[in]	destinationControlFunction	The destination for the request

Returns: true if the request was transmitted, otherwise false.

Definition at line 45 of file isobus_heartbeat.cpp.

Here is the call graph for this function:

◆ set_enabled()

void isobus::HeartbeatInterface::set_enabled ( bool enable )

This can be used to disable or enable this heartbeat functionality. It's probably best to leave it enabled for most applications, but it's not strictly needed.

Note: The interface is enabled by default.

Parameters

[in] enable Set to true to enable the interface, or false to disable it.

Definition at line 31 of file isobus_heartbeat.cpp.

◆ update()

void isobus::HeartbeatInterface::update ( )

Updates the interface. Called by the network manager, so there is no need for you to call it in your application.

Definition at line 92 of file isobus_heartbeat.cpp.

Member Data Documentation

◆ enabled

bool isobus::HeartbeatInterface::enabled = true

private

Attribute that specifies if this interface is enabled. When false, the interface does nothing.

Definition at line 150 of file isobus_heartbeat.hpp.

◆ heartbeatErrorEventDispatcher

EventDispatcher<HeartBeatError, std::shared_ptr<ControlFunction> > isobus::HeartbeatInterface::heartbeatErrorEventDispatcher

private

Event dispatcher for heartbeat errors.

Definition at line 147 of file isobus_heartbeat.hpp.

◆ newTrackedHeartbeatEventDispatcher

EventDispatcher<std::shared_ptr<ControlFunction> > isobus::HeartbeatInterface::newTrackedHeartbeatEventDispatcher

private

Event dispatcher for when a heartbeat message from another control function becomes tracked by this interface.

Definition at line 148 of file isobus_heartbeat.hpp.

◆ sendCANFrameCallback

const CANMessageFrameCallback isobus::HeartbeatInterface::sendCANFrameCallback

private

A callback for sending a CAN frame.

Definition at line 146 of file isobus_heartbeat.hpp.

◆ SEQUENCE_INITIAL_RESPONSE_TIMEOUT_MS

constexpr std::uint32_t isobus::HeartbeatInterface::SEQUENCE_INITIAL_RESPONSE_TIMEOUT_MS = 250

staticconstexprprivate

When requesting a heartbeat from another device, If no response for the repetition rate has been received after 250 ms, the requester shall assume that the request was not accepted.

Definition at line 110 of file isobus_heartbeat.hpp.

◆ SEQUENCE_REPETITION_RATE_MS

constexpr std::uint32_t isobus::HeartbeatInterface::SEQUENCE_REPETITION_RATE_MS = 100

staticconstexprprivate

A consuming CF shall send a Request for Repetition rate for the heart beat message with a repetition rate of 100 ms.

Definition at line 111 of file isobus_heartbeat.hpp.

◆ SEQUENCE_TIMEOUT_MS

constexpr std::uint32_t isobus::HeartbeatInterface::SEQUENCE_TIMEOUT_MS = 300

staticconstexprprivate

If the repetition rate exceeds 300 ms an error in the communication is detected.

Definition at line 109 of file isobus_heartbeat.hpp.

◆ trackedHeartbeats

std::list<Heartbeat> isobus::HeartbeatInterface::trackedHeartbeats

private

Store tracked heartbeat data, per CF.

Definition at line 149 of file isobus_heartbeat.hpp.

The documentation for this class was generated from the following files:

isobus/include/isobus/isobus/isobus_heartbeat.hpp
isobus/src/isobus_heartbeat.cpp

Classes

Public Types

Public Member Functions

Private Types

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Enumeration Documentation

◆ HeartBeatError

◆ SequenceCounterSpecialValue

Constructor & Destructor Documentation

◆ HeartbeatInterface()

Member Function Documentation

◆ get_heartbeat_error_event_dispatcher()

◆ get_new_tracked_heartbeat_event_dispatcher()

◆ is_enabled()

◆ on_destroyed_internal_control_function()

◆ on_new_internal_control_function()

◆ process_request_for_heartbeat()

◆ process_rx_message()

◆ request_heartbeat()

◆ set_enabled()

◆ update()

Member Data Documentation

◆ enabled

◆ heartbeatErrorEventDispatcher

◆ newTrackedHeartbeatEventDispatcher

◆ sendCANFrameCallback

◆ SEQUENCE_INITIAL_RESPONSE_TIMEOUT_MS

◆ SEQUENCE_REPETITION_RATE_MS

◆ SEQUENCE_TIMEOUT_MS

◆ trackedHeartbeats