ISOBUS Heartbeat API

The heartbeat message (PGN 61668/0xF0E4) is used to determine the integrity of the communication of messages and parameters being transmitted by a control function. There may be multiple instances of the heartbeat message on the network, and CFs are required transmit the message on request. As long as the heartbeat message is transmitted at the regular time interval and the sequence number increases through the valid range, then the heartbeat message indicates that the data source CF is operational and provides correct data in all its messages.

Note

This interface is enabled by default, but can be disabled if you want to stop your heartbeat(s) or don’t care about the safety-critical path of the machine.

class HeartbeatInterface

This class is used to send and receive ISOBUS heartbeats.

Public Types

enum class HeartBeatError

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

Values:

enumerator InvalidSequenceCounter

The sequence counter is not valid.

enumerator TimedOut

The heartbeat message has not been received within the repetition rate.

Public Functions

HeartbeatInterface(const CANMessageFrameCallback &sendCANFrameCallback)

Constructor for a HeartbeatInterface.

Parameters:

sendCANFrameCallback – [in] A callback used to send CAN frames

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.

Note

The interface is enabled by default.

Parameters:

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

bool 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

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.

Note

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

Parameters:

  • sourceControlFunction – [in] The internal control function to use when sending the request

  • destinationControlFunction – [in] The destination for the request

Returns:

true if the request was transmitted, otherwise false.

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.

Parameters:

newControlFunction – [in] The new internal control function

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.

Parameters:

destroyedControlFunction – [in] The destroyed internal control function

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.

Returns:

An event dispatcher for heartbeat errors

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.

Returns:

An event dispatcher for new tracked heartbeat events

void process_rx_message(const CANMessage &message)

Processes a CAN message, called by the network manager.

Parameters:

message – [in] The CAN message being received

void update()

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