Client API

class TaskControllerClient

A class to manage a client connection to a ISOBUS field computer’s task controller or data logger.

Public Types

enum class StateMachineState

Enumerates the different internal state machine states.

Values:

enumerator Disconnected: Not communicating with the TC.

enumerator WaitForStartUpDelay: Client is waiting for the mandatory 6s startup delay.

enumerator WaitForServerStatusMessage: Client is waiting to identify the TC via reception of a valid status message.

enumerator SendWorkingSetMaster: Client initating communication with TC by sending the working set master message.

enumerator SendStatusMessage: Enables sending the status message.

enumerator RequestVersion: Requests the TC version and related data from the TC.

enumerator WaitForRequestVersionResponse: Waiting for the TC to respond to a request for its version.

enumerator WaitForRequestVersionFromServer: Waiting to see if the TC will request our version (optional)

enumerator SendRequestVersionResponse: Sending our response to the TC’s request for out version information.

enumerator RequestLanguage: Client is requesting the language command PGN from the TC.

enumerator WaitForLanguageResponse: Waiting for a response to our request for the language command PGN.

enumerator ProcessDDOP: Client is processing the DDOP into a binary DDOP and validating object IDs in the pool.

enumerator RequestStructureLabel: Client is requesting the DDOP structure label that the TC has (if any)

enumerator WaitForStructureLabelResponse: Client is waiting for the TC to respond to our request for its structure label.

enumerator RequestLocalizationLabel: Client is requesting the DDOP localization label the TC has for us (if any)

enumerator WaitForLocalizationLabelResponse: Waiting for a response to our request for the localization label from the TC.

enumerator SendDeleteObjectPool: Client is sending a request to the TC to delete its current copy of our object pool.

enumerator WaitForDeleteObjectPoolResponse: Waiting for a response to our request to delete our object pool off the TC.

enumerator SendRequestTransferObjectPool: Client is requesting to transfer the DDOP to the TC.

enumerator WaitForRequestTransferObjectPoolResponse: Waiting for a response to our request to transfer the DDOP to the TC.

enumerator BeginTransferDDOP: Client is initiating the DDOP transfer.

enumerator WaitForDDOPTransfer: The DDOP transfer in ongoing. Client is waiting for a callback from the transport layer.

enumerator WaitForObjectPoolTransferResponse: DDOP has transferred. Waiting for a response to our object pool transfer.

enumerator SendObjectPoolActivate: Client is sending the activate object pool message.

enumerator WaitForObjectPoolActivateResponse: Client is waiting for a response to its request to activate the object pool.

enumerator Connected: TC is connected.

enumerator DeactivateObjectPool: Client is shutting down and is therefore sending the deactivate object pool message.

enumerator WaitForObjectPoolDeactivateResponse: Client is waiting for a response to the deactivate object pool message.

enum class Version : std::uint8_t

Enumerates the different task controller versions.

Values:

enumerator DraftInternationalStandard: The version of the DIS (draft International Standard).

enumerator FinalDraftInternationalStandardFirstEdition: The version of the FDIS.1 (final draft International Standard, first edition).

enumerator FirstPublishedEdition: The version of the FDIS.2 and the first edition published ss an International Standard.

enumerator SecondEditionDraft: The version of the second edition published as a draft International Standard(E2.DIS).

enumerator SecondPublishedEdition: The version of the second edition published as the final draft International Standard(E2.FDIS) and as the International Standard(E2.IS)

enumerator Unknown

enum class ServerOptions : std::uint8_t

Enumerates the bits stored in our version data that we send to the TC when handshaking.

Values:

enumerator SupportsDocumentation

enumerator SupportsTCGEOWithoutPositionBasedControl

enumerator SupportsTCGEOWithPositionBasedControl

enumerator SupportsPeerControlAssignment

enumerator SupportsImplementSectionControlFunctionality

enumerator ReservedOption1

enumerator ReservedOption2

enumerator ReservedOption3

using RequestValueCommandCallback = bool (*)(std::uint16_t elementNumber, std::uint16_t DDI, std::int32_t &processVariableValue, void *parentPointer): A callback for handling a value request command from the TC.

using ValueCommandCallback = bool (*)(std::uint16_t elementNumber, std::uint16_t DDI, std::int32_t processVariableValue, void *parentPointer): A callback for handling a set value command from the TC.

Public Functions

TaskControllerClient(std::shared_ptr<PartneredControlFunction> partner, std::shared_ptr<InternalControlFunction> clientSource, std::shared_ptr<PartneredControlFunction> primaryVT)

The constructor for a TaskControllerClient.

Parameters:

partner – [in] The TC server control function
clientSource – [in] The internal control function to communicate from
primaryVT – [in] Pointer to our primary VT. This is optional (can be nullptr), but should be provided if possible to provide the best compatibility to TC < version 4.

~TaskControllerClient(): Destructor for the client.

void initialize(bool spawnThread)

This function starts the state machine. Call this once you have created your DDOP, set up the client capabilities, and are ready to connect.

Parameters:: spawnThread – [in] The client will start a thread to manage itself if this parameter is true. Otherwise you must update it cyclically by calling the update function.

void add_request_value_callback(RequestValueCommandCallback callback, void *parentPointer)

This adds a callback that will be called when the TC requests the value of one of your variables.

The task controller will often send a request for the value of a process data variable. When the stack receives those messages, it will call this callback to request the value from your application. You must provide the value at that time for the associated process data variable identified by its element number and DDI.

Parameters:

callback – [in] The callback to add
parentPointer – [in] A generic context variable that will be passed into the associated callback when it gets called

void add_value_command_callback(ValueCommandCallback callback, void *parentPointer)

Adds a callback that will be called when the TC commands a new value for one of your variables.

The task controller will often send a command to set one of your process data variables to a new value. This callback will get called when that happens, and you will need to set the variable to the commanded value in your application.

Parameters:

callback – [in] The callback to add
parentPointer – [in] A generic context variable that will be passed into the associated callback when it gets called

void remove_request_value_callback(RequestValueCommandCallback callback, void *parentPointer)

Removes the specified callback from the list of value request callbacks.

Parameters:

callback – [in] The callback to remove
parentPointer – [in] parent pointer associated to the callback being removed

void remove_value_command_callback(ValueCommandCallback callback, void *parentPointer)

Removes the specified callback from the list of value command callbacks.

Parameters:

callback – [in] The callback to remove
parentPointer – [in] parent pointer associated to the callback being removed

void configure(std::shared_ptr<DeviceDescriptorObjectPool> DDOP, std::uint8_t maxNumberBoomsSupported, std::uint8_t maxNumberSectionsSupported, std::uint8_t maxNumberChannelsSupportedForPositionBasedControl, bool reportToTCSupportsDocumentation, bool reportToTCSupportsTCGEOWithoutPositionBasedControl, bool reportToTCSupportsTCGEOWithPositionBasedControl, bool reportToTCSupportsPeerControlAssignment, bool reportToTCSupportsImplementSectionControl)

A convenient way to set all client options at once instead of calling the individual setters.

This function sets up the parameters that the client will report to the TC server. These parameters should be tailored to your specific application.

Note

This version of the configure function takes a DeviceDescriptorObjectPool. The other versions of the configure function take various other kinds of DDOP.

Parameters:

DDOP – [in] The device descriptor object pool to upload to the TC
maxNumberBoomsSupported – [in] Configures the max number of booms the client supports
maxNumberSectionsSupported – [in] Configures the max number of sections supported by the client for section control
maxNumberChannelsSupportedForPositionBasedControl – [in] Configures the max number of channels supported by the client for position based control
reportToTCSupportsDocumentation – [in] Denotes if your app supports documentation
reportToTCSupportsTCGEOWithoutPositionBasedControl – [in] Denotes if your app supports TC-GEO without position based control
reportToTCSupportsTCGEOWithPositionBasedControl – [in] Denotes if your app supports TC-GEO with position based control
reportToTCSupportsPeerControlAssignment – [in] Denotes if your app supports peer control assignment
reportToTCSupportsImplementSectionControl – [in] Denotes if your app supports implement section control

void configure(std::uint8_t const *binaryDDOP, std::uint32_t DDOPSize, std::uint8_t maxNumberBoomsSupported, std::uint8_t maxNumberSectionsSupported, std::uint8_t maxNumberChannelsSupportedForPositionBasedControl, bool reportToTCSupportsDocumentation, bool reportToTCSupportsTCGEOWithoutPositionBasedControl, bool reportToTCSupportsTCGEOWithPositionBasedControl, bool reportToTCSupportsPeerControlAssignment, bool reportToTCSupportsImplementSectionControl)

A convenient way to set all client options at once instead of calling the individual setters.

This function sets up the parameters that the client will report to the TC server. These parameters should be tailored to your specific application.

Note

This version of the configure function takes a pointer to an array of bytes. The other versions of the configure function take various other kinds of DDOP.

Parameters:

binaryDDOP – [in] The device descriptor object pool to upload to the TC
DDOPSize – [in] The number of bytes in the binary DDOP that will be uploaded
maxNumberBoomsSupported – [in] Configures the max number of booms the client supports
maxNumberSectionsSupported – [in] Configures the max number of sections supported by the client for section control
maxNumberChannelsSupportedForPositionBasedControl – [in] Configures the max number of channels supported by the client for position based control
reportToTCSupportsDocumentation – [in] Denotes if your app supports documentation
reportToTCSupportsTCGEOWithoutPositionBasedControl – [in] Denotes if your app supports TC-GEO without position based control
reportToTCSupportsTCGEOWithPositionBasedControl – [in] Denotes if your app supports TC-GEO with position based control
reportToTCSupportsPeerControlAssignment – [in] Denotes if your app supports peer control assignment
reportToTCSupportsImplementSectionControl – [in] Denotes if your app supports implement section control

void configure(std::shared_ptr<std::vector<std::uint8_t>> binaryDDOP, std::uint8_t maxNumberBoomsSupported, std::uint8_t maxNumberSectionsSupported, std::uint8_t maxNumberChannelsSupportedForPositionBasedControl, bool reportToTCSupportsDocumentation, bool reportToTCSupportsTCGEOWithoutPositionBasedControl, bool reportToTCSupportsTCGEOWithPositionBasedControl, bool reportToTCSupportsPeerControlAssignment, bool reportToTCSupportsImplementSectionControl)

A convenient way to set all client options at once instead of calling the individual setters.

This function sets up the parameters that the client will report to the TC server. These parameters should be tailored to your specific application.

Note

This version of the configure function takes a vector of bytes, and stores a copy of it. The other versions of the configure function take various other kinds of DDOP.

Parameters:

binaryDDOP – [in] The device descriptor object pool to upload to the TC
maxNumberBoomsSupported – [in] Configures the max number of booms the client supports
maxNumberSectionsSupported – [in] Configures the max number of sections supported by the client for section control
maxNumberChannelsSupportedForPositionBasedControl – [in] Configures the max number of channels supported by the client for position based control
reportToTCSupportsDocumentation – [in] Denotes if your app supports documentation
reportToTCSupportsTCGEOWithoutPositionBasedControl – [in] Denotes if your app supports TC-GEO without position based control
reportToTCSupportsTCGEOWithPositionBasedControl – [in] Denotes if your app supports TC-GEO with position based control
reportToTCSupportsPeerControlAssignment – [in] Denotes if your app supports peer control assignment
reportToTCSupportsImplementSectionControl – [in] Denotes if your app supports implement section control

void restart(): Calling this function will reset the task controller client’s connection with the TC server, and cause it to reconnect after a short delay.

void terminate(): Terminates the client and joins the worker thread if applicable.

std::shared_ptr<InternalControlFunction> get_internal_control_function() const

Returns the internal control function being used by the interface to send messages.

Returns:: The internal control function being used by the interface to send messages

std::shared_ptr<PartneredControlFunction> get_partner_control_function() const

Returns the control function of the TC server with which this TC client communicates.

Returns:: The partner control function for the TC server

std::uint8_t get_number_booms_supported() const

Returns the previously configured number of booms supported by the client.

Returns:: The previously configured number of booms supported by the client

std::uint8_t get_number_sections_supported() const

Returns the previously configured number of section supported by the client.

Returns:: The previously configured number of booms supported by the client

std::uint8_t get_number_channels_supported_for_position_based_control() const

Returns the previously configured number of channels supported for position based control.

Returns:: The previously configured number of channels supported for position based control

bool get_supports_documentation() const

Returns if the client has been configured to report that it supports documentation to the TC.

Returns:: true if the client has been configured to report that it supports documentation, otherwise false

bool get_supports_tcgeo_without_position_based_control() const

Returns if the client has been configured to report that it supports TC-GEO without position based control to the TC.

Returns:: true if the client has been configured to report that it supports TC-GEO without position based control, otherwise false

bool get_supports_tcgeo_with_position_based_control() const

Returns if the client has been configured to report that it supports TC-GEO with position based control to the TC.

Returns:: true if the client has been configured to report that it supports TC-GEO with position based control, otherwise false

bool get_supports_peer_control_assignment() const

Returns if the client has been configured to report that it supports peer control assignment to the TC.

Returns:: true if the client has been configured to report that it supports peer control assignment, otherwise false

bool get_supports_implement_section_control() const

Returns if the client has been configured to report that it supports implement section control to the TC.

Returns:: true if the client has been configured to report that it supports implement section control, otherwise false

bool get_is_initialized() const

Returns if the client has been initialized.

Note

This does not mean that the client is connected to the TC server

Returns:: true if the client has been initialized

bool get_is_connected() const

Check whether the client is connected to the TC server.

Returns:: true if cconnected, false otherwise

bool get_is_task_active() const

Returns if a task is active as indicated by the TC.

Attention: Some TCs will report they are always in a task rather than properly reporting this. For example, John Deere TCs have a bad habit of doing this. Use caution before relying on the TC’s task status.

Returns:: true if the TC is connected and the TC is reporting it is in a task, otherwise false

StateMachineState get_state() const

Returns the current state machine state.

Returns:: The current internal state machine state

std::uint8_t get_connected_tc_number_booms_supported() const

Returns the number of booms that the connected TC supports for section control.

Returns:: Number of booms that the connected TC supports for section control

std::uint8_t get_connected_tc_number_sections_supported() const

Returns the number of sections that the connected TC supports for section control.

Returns:: Number of sections that the connected TC supports for section control

std::uint8_t get_connected_tc_number_channels_supported() const

Returns the number of channels that the connected TC supports for position control.

Returns:: Number of channels that the connected TC supports for position control

std::uint8_t get_connected_tc_max_boot_time() const

Returns the maximum boot time in seconds reported by the connected TC.

Returns:: Maximum boot time (seconds) reported by the connected TC, or 0xFF if that info is not available.

bool get_connected_tc_option_supported(ServerOptions option) const

Returns if the connected TC supports a certain option.

Parameters:: option – [in] The option to check against
Returns:: true if the option was reported as “supported” by the TC, otherwise false

Version get_connected_tc_version() const

Returns the version of the connected task controller.

Returns:: The version reported by the connected task controller

void on_value_changed_trigger(std::uint16_t elementNumber, std::uint16_t DDI)

Tells the TC client that a value was changed or the TC client needs to command a value to the TC server.

If you provide on-change triggers in your DDOP, this is how you can request the TC client to update the TC server on the current value of your process data variables.

Parameters:

elementNumber – [in] The element number of the process data variable that changed
DDI – [in] The DDI of the process data variable that changed

bool request_task_controller_identification() const

Sends a broadcast request to TCs to identify themseleves.

Upon receipt of this message, the TC shall display, for a period of 3 s, the TC Number

Returns:: true if the message was sent, otherwise false

bool reupload_device_descriptor_object_pool(std::shared_ptr<std::vector<std::uint8_t>> binaryDDOP)

If the TC client is connected to a TC, calling this function will cause the TC client interface to delete the currently active DDOP, reupload it, then reactivate it using the pool passed into the parameter of this function. This process is faster than restarting the whole interface, and you have to call it if you change certain things in your DDOP at runtime after the DDOP has already been activated.

Parameters:: binaryDDOP – [in] The updated device descriptor object pool to upload to the TC
Returns:: true if the interface accepted the command to reupload the pool, or false if the command cannot be handled right now

bool reupload_device_descriptor_object_pool(std::uint8_t const *binaryDDOP, std::uint32_t DDOPSize)

If the TC client is connected to a TC, calling this function will cause the TC client interface to delete the currently active DDOP, reupload it, then reactivate it using the pool passed into the parameter of this function. This process is faster than restarting the whole interface, and you have to call it if you change certain things in your DDOP at runtime after the DDOP has already been activated.

Parameters:

binaryDDOP – [in] The updated device descriptor object pool to upload to the TC
DDOPSize – [in] The number of bytes in the binary DDOP that will be uploaded

Returns:

true if the interface accepted the command to reupload the pool, or false if the command cannot be handled right now

bool reupload_device_descriptor_object_pool(std::shared_ptr<DeviceDescriptorObjectPool> DDOP)

If the TC client is connected to a TC, calling this function will cause the TC client interface to delete the currently active DDOP, reupload it, then reactivate it using the pool passed into the parameter of this function. This process is faster than restarting the whole interface, and you have to call it if you change certain things in your DDOP at runtime after the DDOP has already been activated.

Parameters:: DDOP – [in] The updated device descriptor object pool to upload to the TC
Returns:: true if the interface accepted the command to reupload the pool, or false if the command cannot be handled right now

void update(): The cyclic update function for this interface.

Note

This function may be called by the TC worker thread if you called initialize with a parameter of true, otherwise you must call it yourself at some interval.

Public Members

LanguageCommandInterface languageCommandInterface: Used to determine the language and unit systems in use by the TC server.