ISOBUS Guidance API

The guidance API is an interface for sending and receiving ISOBUS guidance messages. These messages are used to steer ISOBUS compliant machines, steering valves, and implements in general.

Warning

Please use extreme care if you try to steer a machine with this interface! Remember that this library is licensed under The MIT License, and that by obtaining a copy of this library and of course by attempting to steer a machine with it, you are agreeing to our license.

Note

These messages are expected to be deprecated or at least made redundant in favor of Tractor Implement Management (TIM) at some point by the AEF, though the timeline on that is not known at the time of writing this, and it’s likely that many machines will continue to support this interface going forward due to its simplicity over TIM. This project is not affiliated with the AEF, and the AEF has not endorsed this project.

class AgriculturalGuidanceInterface

An interface for sending and receiving ISOBUS guidance messages.

Public Functions

AgriculturalGuidanceInterface(std::shared_ptr<InternalControlFunction> source, std::shared_ptr<ControlFunction> destination, bool enableSendingSystemCommandPeriodically = false, bool enableSendingMachineInfoPeriodically = false)

Constructor for a AgriculturalGuidanceInterface.

Parameters:

source – [in] The internal control function to use when sending messages, or nullptr for listen only
destination – [in] The destination control function for transmitted messages, or nullptr for broadcasts
enableSendingSystemCommandPeriodically – [in] If true, the system command message will be sent periodically. This should (only) be used by an guidance application trying to steer a machine.
enableSendingMachineInfoPeriodically – [in] If true, the machine info message will be sent periodically. This should (only) be used by the steering controller itself.

~AgriculturalGuidanceInterface(): Destructor for the AgriculturalGuidanceInterface.

void initialize(): Sets up the class and registers it to receive callbacks from the network manager for processing guidance 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

std::size_t get_number_received_guidance_system_command_sources() const

Returns the number of received, unique guidance system command sources.

Returns:: The number of CFs sending the guidance system command either as a broadcast, or to our internal control function

std::size_t get_number_received_guidance_machine_info_message_sources() const

Returns the number of received, unique guidance machine info message sources.

Returns:: The number of CFs sending the guidance machine info message either as a broadcast, or to our internal control function

std::shared_ptr<GuidanceMachineInfo> get_received_guidance_machine_info(std::size_t index)

Returns the content of the agricultural guidance machine info message based on the index of the sender. Use this to read the received messages’ content.

Note

Only one device on the bus will send this normally, but we provide a generic way to get an arbitrary number of these commands. So generally using only index 0 will be acceptable.

Parameters:: index – [in] An index of senders of the agricultural guidance machine info message
Returns:: The content of the agricultural guidance machine info message

std::shared_ptr<GuidanceSystemCommand> get_received_guidance_system_command(std::size_t index)

Returns the content of the agricultural guidance curvature command message based on the index of the sender. Use this to read the received messages’ content.

Note

Only one device on the bus will send this normally, but we provide a generic way to get an arbitrary number of these commands. So generally using only index 0 will be acceptable.

Parameters:: index – [in] An index of senders of the agricultural guidance curvature command message
Returns:: The content of the agricultural guidance curvature command message

EventDispatcher<const std::shared_ptr<GuidanceMachineInfo>, bool> &get_guidance_machine_info_event_publisher()

Returns an event dispatcher which you can use to get callbacks when new/updated guidance machine info messages are received.

Returns:: The event publisher for guidance machine info messages

EventDispatcher<const std::shared_ptr<GuidanceSystemCommand>, bool> &get_guidance_system_command_event_publisher()

Returns an event dispatcher which you can use to get callbacks when new/updated guidance system command messages are received.

Returns:: The event publisher for guidance system command messages

void update(): Call this cyclically to update the interface. Transmits messages if needed and processes timeouts for received messages.

Public Members

GuidanceMachineInfo guidanceMachineInfoTransmitData: Use this to configure the transmission of the guidance machine info message from your application. If you pass in an internal control function to the constructor of this class, then this message is available to be sent.

GuidanceSystemCommand guidanceSystemCommandTransmitData: Use this to configure transmission the guidance system command message from your application. If you pass in an internal control function to the constructor of this class, then this message is available to be sent.

class GuidanceMachineInfo

An interface for sending and receiving the ISOBUS agricultural guidance machine message.

Public Types

enum class MechanicalSystemLockout : std::uint8_t

State of a lockout switch that allows operators to disable automatic steering system functions.

https://www.isobus.net/isobus/pGNAndSPN/1221?type=SPN

Values:

enumerator NotActive

enumerator Active

enumerator Error

enumerator NotAvailable

enum class RequestResetCommandStatus : std::uint8_t

Machine steering system request to the automatic guidance system to change Curvature Command Status state from “Intended to steer” to “Not intended to steer”.

Values:

enumerator ResetNotRequired

enumerator ResetRequired

enumerator Error

enumerator NotAvailable

enum class GenericSAEbs02SlotValue : std::uint8_t

A typical, generic 2 bit value in J1939 with no superseding definition in ISO 11783.

Values:

enumerator DisabledOffPassive

enumerator EnabledOnActive

enumerator ErrorIndication

enumerator NotAvailableTakeNoAction

enum class GuidanceLimitStatus : std::uint8_t

This parameter is used to report the steering system’s present limit status associated with guidance commands that are persistent (i.e. not transient/temporary/one-shot).

Values:

enumerator NotLimited: Not limited.

enumerator OperatorLimitedControlled: Request cannot be implemented.

enumerator LimitedHigh: Only lower command values result in a change.

enumerator LimitedLow: Only higher command values result in a change.

enumerator Reserved_1: Reserved.

enumerator Reserved_2: Reserved.

enumerator NonRecoverableFault: Non-recoverable fault.

enumerator NotAvailable: Parameter not supported.

enum class GuidanceSystemCommandExitReasonCode

This parameter is used to indicate why the guidance system cannot currently accept remote commands or has most recently stopped accepting remote commands.

Values:

enumerator NoReasonAllClear

enumerator RequiredLevelOfOperatorPresenceAwarenessNotDetected

enumerator ImplementReleasedControlOfFunction

enumerator OperatorOverrideOfFunction

enumerator OperatorControlNotInValidPosition

enumerator RemoteCommandTimeout

enumerator RemoteCommandOutOfRangeInvalid

enumerator FunctionNotCalibrated

enumerator OperatorControlFault

enumerator FunctionFault

enumerator HydraulicOilLevelTooLow

enumerator HydraulicOilTemperatureTooLow

enumerator VehicleTransmissionGearDoesNotAllowRemoteCommands: park, etc.

enumerator VehicleSpeedTooLow

enumerator VehicleSpeedTooHigh

enumerator AlternateGuidanceSystemActive

enumerator ControlUnitInDiagnosticMode

enumerator Error

enumerator NotAvailable: Parameter not supported.

Public Functions

explicit GuidanceMachineInfo(std::shared_ptr<ControlFunction> sender)

Constructor for a GuidanceMachineInfo.

Parameters:: sender – [in] The control function that is sending this message

bool set_estimated_curvature(float curvature)

Sets the estimated course curvature over ground for the machine.

Parameters:: curvature – [in] The curvature in km^-1 (inverse kilometers). Range is -8032 to 8031.75 km-1
Returns:: True if the curvature changed, false otherwise

float get_estimated_curvature() const

Returns the estimated curvature that was previously set with set_estimated_curvature.

Returns:: The estimated curvature in km^-1 (inverse kilometers). Range is -8032 to 8031.75 km-1

bool set_mechanical_system_lockout_state(MechanicalSystemLockout state)

Sets the mechanical system lockout state.

Parameters:: state – [in] The mechanical system lockout state to report
Returns:: True if the mechanical system lockout state changed, false otherwise

MechanicalSystemLockout get_mechanical_system_lockout() const

Returns the mechanical system lockout state.

Returns:: The mechanical system lockout state being reported

bool set_guidance_steering_system_readiness_state(GenericSAEbs02SlotValue state)

Sets the guidance system’s readiness state to report.

Parameters:: state – [in] The state to report. See definition of GenericSAEbs02SlotValue
Returns:: True if the guidance steering system readiness state changed, false otherwise

GenericSAEbs02SlotValue get_guidance_steering_system_readiness_state() const

Returns the guidance system’s readiness state for steering.

Returns:: The guidance system’s readiness state for steering

bool set_guidance_steering_input_position_status(GenericSAEbs02SlotValue state)

Sets the guidance steering input position state.

Parameters:: state – [in] The state to set for the guidance steering input position
Returns:: True if the guidance steering input position status changed, false otherwise

GenericSAEbs02SlotValue get_guidance_steering_input_position_status() const

Returns the guidance steering input position state.

Returns:: Guidance steering input position state

bool set_request_reset_command_status(RequestResetCommandStatus state)

Sets the request reset command to report.

Machine steering system request to the automatic guidance system to change Curvature Command Status state from “Intended to steer” to “Not intended to steer”.

Parameters:: state – [in] The request reset command state to report
Returns:: True if the request reset command status changed, false otherwise

RequestResetCommandStatus get_request_reset_command_status() const

Returns the reported request reset command.

Machine steering system request to the automatic guidance system to change Curvature Command Status state from “Intended to steer” to “Not intended to steer”.

Returns:: The reported request reset command

bool set_guidance_limit_status(GuidanceLimitStatus status)

Sets the reported guidance limit status.

This parameter is used to report the steering system’s present limit status associated with guidance commands that are persistent (i.e. not transient/temporary/one-shot).

Parameters:: status – [in] The limit status to report
Returns:: True if the guidance limit status changed, false otherwise

GuidanceLimitStatus get_guidance_limit_status() const

Returns the reported guidance limit status.

This parameter is used to report the steering system’s present limit status associated with guidance commands that are persistent (i.e. not transient/temporary/one-shot).

Returns:: The reported guidance limit status

bool set_guidance_system_command_exit_reason_code(std::uint8_t exitCode)

Sets the exit code for the guidance system.

This parameter is used to indicate why the guidance system cannot currently accept remote commands or has most recently stopped accepting remote commands.

Parameters:: exitCode – [in] The exit code for the guidance system to report
Returns:: The exit code for the guidance system

std::uint8_t get_guidance_system_command_exit_reason_code() const

Returns the exit code for the guidance system.

This parameter is used to indicate why the guidance system cannot currently accept remote commands or has most recently stopped accepting remote commands.

Returns:: The exit code for the guidance system

bool set_guidance_system_remote_engage_switch_status(GenericSAEbs02SlotValue switchStatus)

Sets the state for the steering engage switch.

Parameters:: switchStatus – [in] The engage switch state to report
Returns:: True if the engage switch state changed, false otherwise

GenericSAEbs02SlotValue get_guidance_system_remote_engage_switch_status() const

Returns the state for the steering engage switch.

Returns:: The state for the steering engage switch

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.

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

class GuidanceSystemCommand

An interface for sending the agricultural guidance system command message.

This message is sent by an automatic guidance control system to the machine steering system. It provides steering commands and serves as heartbeat between guidance system and steering control system.

Public Types

enum class CurvatureCommandStatus : std::uint8_t

This parameter indicates whether the guidance system is attempting to control steering with this command.

Values:

enumerator NotIntendedToSteer: Steering Disengaged.

enumerator IntendedToSteer: Steering Engaged.

enumerator Error

enumerator NotAvailable

Public Functions

explicit GuidanceSystemCommand(std::shared_ptr<ControlFunction> sender)

Constructor for a GuidanceSystemCommand.

Parameters:: sender – [in] The control function that is sending this message

bool set_status(CurvatureCommandStatus newStatus)

Sets the curvature command status that will be encoded into the CAN message. This parameter indicates whether the guidance system is attempting to control steering with this command.

Parameters:: newStatus – [in] The status to encode into the message
Returns:: True if the status changed, false otherwise

CurvatureCommandStatus get_status() const

Returns the curvature command status that is active in the guidance system.

Returns:: The curvature command status

bool set_curvature(float curvature)

Desired course curvature over ground that a machine’s steering system is required to achieve.

The value you set here will be encoded into the guidance curvature command message.

The desired path is determined by the automatic guidance system expressed as the inverse of the instantaneous radius of curvature of the turn. Curvature is positive when the vehicle is moving forward and turning to the driver’s right

Parameters:: curvature – [in] Commanded curvature in km^-1 (inverse kilometers). Range is -8032 to 8031.75 km-1
Returns:: True if the curvature changed, false otherwise

float get_curvature() const

Returns the curvature value that is currently be trying to be achieved by the guidance system.

Returns:: Commanded curvature in km^-1 (inverse kilometers). Range is -8032 to 8031.75 km-1

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.

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