[VT]: Allow selection of VT client pools based on server version

This change makes it possible for a consumer of the library to choose
at runtime which object pool(s) to use based on the version of the VT server.

Author: ad3154

isobus/include/isobus/isobus/isobus_virtual_terminal_client.hpp

@@ -330,6 +330,8 @@ namespace isobus
 			Disconnected, ///< VT is not connected, and is not trying to connect yet
 			WaitForPartnerVTStatusMessage, ///< VT client is initialized, waiting for a VT server to come online
 			SendWorkingSetMasterMessage, ///< Client is sending the working state master message
+			SendGetMemoryInitial, ///< We send an initial get memory message for 0 bytes to get the version of the VT server
+			WaitForGetMemoryInitialResponse, ///< Client is waiting for a response to the initial
 			ReadyForObjectPool, ///< Client needs an object pool before connection can continue
 			SendGetMemory, ///< Client is sending the "get memory" message to see if VT has enough memory available
 			WaitForGetMemoryResponse, ///< Client is waiting for a response to the "get memory" message
@@ -1234,6 +1236,10 @@ namespace isobus
 		                     const std::vector<std::uint8_t> *pool,
 		                     const std::string &version = "");
 
+		/// @brief Returns the number of object pools that have been assigned for upload
+		/// @returns The number of object pools that have been assigned for upload
+		std::size_t get_number_of_object_pools() const;
+
 		/// @brief Configures an object pool to be automatically scaled to match the target VT server
 		/// @param[in] poolIndex The index of the pool you want to auto-scale
 		/// @param[in] originalDataMaskDimensions_px The data mask width that your object pool was originally designed for
@@ -1252,6 +1258,15 @@ namespace isobus
 		/// @param[in] version An optional version string. The stack will automatically store/load your pool from the VT if this is provided.
 		void register_object_pool_data_chunk_callback(std::uint8_t poolIndex, std::uint32_t poolTotalSize, DataChunkCallback value, std::string version = "");
 
+		/// @brief Sets a callback that will be called when the client is ready for object pool upload. You should call this before initialize if you're planning to use it.
+		/// @details This will be called once the VT version of the server is known so that you can select which
+		/// object pools you want to upload based on that information. This is optional. If you want to use this mechanism,
+		/// simply set your object pools in the callback using set_object_pool or register_object_pool_data_chunk_callback.
+		/// If you fail to do this when the callback is called, no object pools will be uploaded until you call set_object_pool, though that
+		/// would not be particularly thread safe unless you passed false to the initialize function. You can also just set your object pools before connecting if you want to always upload the same pools.
+		/// @param[in] callback The callback to call when ready for object pool upload
+		void set_on_ready_for_object_pool_callback(std::function<void(VTVersion)> callback);
+
 		/// @brief Periodic Update Function (worker thread may call this)
 		/// @details This class can spawn a thread, or you can supply your own to run this function.
 		/// To configure that behavior, see the initialize function.
@@ -1676,6 +1691,7 @@ namespace isobus
 		EventDispatcher<AuxiliaryFunctionEvent> auxiliaryFunctionEventDispatcher; ///< A list of all auxiliary function callbacks
 
 		// Object Pool info
+		std::function<void(VTVersion)> onReadyForObjectPoolCallback;
 		DataChunkCallback objectPoolDataCallback = nullptr; ///< The callback to use to get pool data
 		std::uint32_t lastObjectPoolIndex = 0; ///< The last object pool index that was processed
 	};

isobus/src/isobus_virtual_terminal_client.cpp

@@ -1264,6 +1264,11 @@ namespace isobus
 		}
 	}
 
+	std::size_t VirtualTerminalClient::get_number_of_object_pools() const
+	{
+		return objectPools.size();
+	}
+
 	void VirtualTerminalClient::set_object_pool_scaling(std::uint8_t poolIndex,
 	                                                    std::uint32_t originalDataMaskDimensions_px,
 	                                                    std::uint32_t originalSoftKyeDesignatorHeight_px)
@@ -1303,6 +1308,11 @@ namespace isobus
 		}
 	}
 
+	void VirtualTerminalClient::set_on_ready_for_object_pool_callback(std::function<void(VTVersion)> callback)
+	{
+		onReadyForObjectPoolCallback = callback;
+	}
+
 	void VirtualTerminalClient::update()
 	{
 		StateMachineState previousStateMachineState = state; // Save state to see if it changes this update
@@ -1337,7 +1347,26 @@ namespace isobus
 				{
 					if (send_working_set_master())
 					{
-						set_state(StateMachineState::ReadyForObjectPool);
+						set_state(StateMachineState::SendGetMemoryInitial);
+					}
+				}
+				break;
+
+				case StateMachineState::SendGetMemoryInitial:
+				{
+					if (send_get_memory(0))
+					{
+						set_state(StateMachineState::WaitForGetMemoryInitialResponse);
+					}
+				}
+				break;
+
+				case StateMachineState::WaitForGetMemoryInitialResponse:
+				{
+					if (SystemTiming::time_expired_ms(lastVTStatusTimestamp_ms, VT_STATUS_TIMEOUT_MS))
+					{
+						LOG_ERROR("[VT]: VT server has timed out while waiting for initial get memory message. Disconnecting.");
+						set_state(StateMachineState::Disconnected);
 					}
 				}
 				break;
@@ -1352,6 +1381,11 @@ namespace isobus
 						LOG_ERROR("[VT]: Ready to upload pool, but VT server has timed out. Disconnecting.");
 						set_state(StateMachineState::Disconnected);
 					}
+					else if (onReadyForObjectPoolCallback)
+					{
+						// Attempt to indicate to the user that we need at least one object pool to proceed.
+						onReadyForObjectPoolCallback(get_connected_vt_version());
+					}
 
 					if (!objectPools.empty())
 					{
@@ -2774,10 +2808,14 @@ namespace isobus
 
 						case static_cast<std::uint8_t>(Function::GetMemoryMessage):
 						{
-							if (StateMachineState::WaitForGetMemoryResponse == parentVT->state)
+							if (StateMachineState::WaitForGetMemoryInitialResponse == parentVT->state)
 							{
 								parentVT->connectedVTVersion = message.get_uint8_at(1);
-
+								LOG_DEBUG("[VT]: Server version is " + isobus::to_string(static_cast<int>(parentVT->connectedVTVersion)));
+								parentVT->set_state(StateMachineState::ReadyForObjectPool);
+							}
+							else if (StateMachineState::WaitForGetMemoryResponse == parentVT->state)
+							{
 								if (0 == message.get_uint8_at(2))
 								{
 									// There IS enough memory