Maintain Power API
This interface provides a way to manage sending and receiving the “maintain power” message. This message is sent by any control function connected to the implement bus and requests that the Tractor ECU (TECU) not switch off the power for 2 s after it has received the wheel-based speed and distance message indicating that the ignition has been switched off. The message also includes the connected implement(s) operating state. You can choose if the TECU maintains actuator power independently of ECU power as well, as an option.
Note
If you are using the library for implement section control, you might want to maintain actuator power using this interface to ensure your section valves close when keyed off.
-
class MaintainPowerInterface
Manages sending and receiving the maintain power message (PGN 65095)
Public Functions
Constructor for a MaintainPowerInterface.
- Parameters:
sourceControlFunction – [in] The control function to send the message from, or nullptr to listen only
-
~MaintainPowerInterface()
Destructor for a MaintainPowerInterface.
-
void initialize()
Sets up the class and registers it to receive callbacks from the network manager for processing messages. The class will not receive messages if this is not called.
-
bool get_initialized() const
Returns if the interface has been initialized.
- Returns:
true if initialize has been called for this interface, otherwise false
-
void set_maintain_power_time(std::uint32_t timeToMaintainPower)
Use this to tell the interface how long it should transmit the maintain power message after it detects a key state transition to off. The interface will use whatever you have set in maintainPowerTransmitData when performing automatic transmission of the message.
- Attention
The interface will always send the message at least once with what you have configured in maintainPowerTransmitData if it was set up with an internal control function, but you should take care to configure maintainPowerTransmitData with the parameters that will ensure you have enough time to safely stop your section control and shutdown your application, because when we stop sending this message the TECU may kill power to your device or the actuators without warning.
- Parameters:
timeToMaintainPower – [in] The amount of time in milliseconds that the interface will send the maintain power message when the key transitions to off.
-
std::uint32_t get_maintain_power_time() const
Returns the amount of time that the interface will continue to send the maintain power message after it detects a key transition to off.
- Returns:
The amount of time in milliseconds that the interface will send the maintain power message for.
-
std::size_t get_number_received_maintain_power_sources() const
Returns the number of unique senders of the maintain power message.
- Returns:
The number of unique senders of the maintain power message
-
std::shared_ptr<MaintainPowerData> get_received_maintain_power(std::size_t index)
Returns the content of a received maintain power message based on the index of the sender. Use this to read the received messages’ content.
- Parameters:
index – [in] An index of senders of the maintain power message
- Returns:
A pointer to the maintain power message data, or nullptr if the index is out of range
-
EventDispatcher<const std::shared_ptr<MaintainPowerData>, bool> &get_maintain_power_data_event_publisher()
Returns an event dispatcher which you can use to get callbacks when new/updated maintain power messages are received.
- Returns:
The event publisher for maintain power messages
-
EventDispatcher &get_key_switch_transition_off_event_publisher()
Returns an event dispatcher which you can use to get callbacks when the key switch transitions from the not-off state to the off state. When you get this callback, you can then shutdown your application safely.
Note
You can get more comprehensive key switch events by using the wheel-selected speed events in the SpeedMessagesInterface file.
- Returns:
The event publisher for key switch off transitions
-
void update()
Call this cyclically to update the interface. Transmits messages if needed and processes timeouts for received messages.
Public Members
-
MaintainPowerData maintainPowerTransmitData
Use this to configure the transmission of the maintain power message.
-
class MaintainPowerData
Stores information sent/received in a maintain power message.
Public Types
-
enum class ImplementInWorkState : std::uint8_t
Signal that indicates that an implement is connected to a tractor or power unit and is in work state.
SPN 7447
Values:
-
enumerator ImplementNotInWorkState
-
enumerator ImplementInWorkState
-
enumerator ErrorIndication
-
enumerator NotAvailable
-
enumerator ImplementNotInWorkState
-
enum class ImplementReadyToWorkState
Signal that indicates that an implement is connected to a tractor or power unit and is ready for work.
SPN 1871
Values:
-
enumerator ImplementNotReadyForFieldWork
-
enumerator ImplementReadyForFieldWork
-
enumerator ErrorIndication
-
enumerator NotAvailable
-
enumerator ImplementNotReadyForFieldWork
-
enum class ImplementParkState
Indicates the state of an implement where it may be disconnected from a tractor or power unit.
SPN 1870
Values:
-
enumerator ImplementMayNotBeDisconnected
-
enumerator ImplementMayBeDisconnected
-
enumerator ErrorIndication
-
enumerator NotAvailable
-
enumerator ImplementMayNotBeDisconnected
-
enum class ImplementTransportState
Indicates the transport state of an implement connected to a tractor or power unit.
SPN 1869
Values:
-
enumerator ImplementMayNotBeTransported
-
enumerator ImplementMayBeTransported
-
enumerator ErrorIndication
-
enumerator NotAvailable
-
enumerator ImplementMayNotBeTransported
Public Functions
Constructor for a MaintainPowerData object, which stores information sent/received in a maintain power message.
- Parameters:
sendingControlFunction – [in] The control function to use if sending the message
-
bool set_implement_in_work_state(ImplementInWorkState inWorkState)
Sets the reported implement in-work state.
- Parameters:
inWorkState – [in] The reported implement in-work state to set
- Returns:
True if the set value was different from the stored value, otherwise false.
-
ImplementInWorkState get_implement_in_work_state() const
Returns the reported implement in-work state.
- Returns:
The reported implement in-work state
-
bool set_implement_ready_to_work_state(ImplementReadyToWorkState readyToWorkState)
Sets the reported implement ready to work state.
- Parameters:
readyToWorkState – [in] The reported implement ready to work state
- Returns:
True if the set value was different from the stored value, otherwise false.
-
ImplementReadyToWorkState get_implement_ready_to_work_state() const
Returns the reported implement ready to work state.
- Returns:
The reported implement ready to work state
-
bool set_implement_park_state(ImplementParkState parkState)
Sets the reported implement park state.
- Parameters:
parkState – [in] The reported implement park state to set
- Returns:
True if the set value was different from the stored value, otherwise false.
-
ImplementParkState get_implement_park_state() const
Returns the reported implement park state.
- Returns:
The reported implement park state
-
bool set_implement_transport_state(ImplementTransportState transportState)
Sets the reported implement transport state.
- Parameters:
transportState – [in] The reported implement transport state to set
- Returns:
True if the set value was different from the stored value, otherwise false.
-
ImplementTransportState get_implement_transport_state() const
Returns the reported implement transport state.
- Returns:
The reported implement transport state
-
bool set_maintain_actuator_power(MaintainActuatorPower maintainState)
Sets the reported maintain actuator power state.
- Parameters:
maintainState – [in] The reported maintain actuator power state
- Returns:
True if the set value was different from the stored value, otherwise false.
-
MaintainActuatorPower get_maintain_actuator_power() const
Returns the reported maintain actuator power state.
- Returns:
The reported maintain actuator power state
-
bool set_maintain_ecu_power(MaintainECUPower maintainState)
Sets the reported maintain ECU power state.
- Parameters:
maintainState – [in] The reported maintain ECU power state
- Returns:
True if the set value was different from the stored value, otherwise false.
-
MaintainECUPower get_maintain_ecu_power() const
Returns the reported maintain ECU power state.
- Returns:
The reported maintain ECU power state
-
std::shared_ptr<ControlFunction> get_sender_control_function() const
Returns a pointer to the sender of the message. If an ICF is the sender, returns the ICF being used to transmit from.
- Attention
The only way you could get an invalid pointer here is if you register a partner, it sends this message, then you delete the partner and call this function, as that is the only time the stack deletes a control function. That would be abnormal program flow, but at some point the stack will be updated to return a shared or weak pointer instead, but for now please be aware of that limitation. Eventually though the message will time-out normally and you can get a new pointer for the external CF that replaces the deleted partner.
- Returns:
The control function sending this instance of the guidance system command message
-
void set_timestamp_ms(std::uint32_t timestamp)
Sets the timestamp for when the message was received or sent.
- Parameters:
timestamp – [in] The timestamp, in milliseconds, when the message was sent or received
-
std::uint32_t get_timestamp_ms() const
Returns the timestamp for when the message was received, in milliseconds.
- Returns:
The timestamp for when the message was received, in milliseconds
-
enum class ImplementInWorkState : std::uint8_t