docs: add esc-button handling to examples

also worked through the two VT tutorials and updated them accordingly

examples/virtual_terminal/esp32_platformio_object_pool/src/main.cpp

@@ -21,37 +21,63 @@
 static std::shared_ptr<isobus::VirtualTerminalClient> virtualTerminalClient = nullptr;
 static std::shared_ptr<isobus::VirtualTerminalClientUpdateHelper> virtualTerminalUpdateHelper = nullptr;
 
-// This callback will provide us with event driven notifications of button presses from the stack
-void handleVTKeyEvents(const isobus::VirtualTerminalClient::VTKeyEvent &event)
+// This callback will provide us with event driven notifications of softkey presses from the stack
+void handle_softkey_event(const isobus::VirtualTerminalClient::VTKeyEvent &event)
 {
+	if (event.keyNumber == 0)
+	{
+		// We have the alarm ACK code, so if we have an active alarm, acknowledge it by going back to the main runscreen
+		virtualTerminalUpdateHelper->set_active_data_or_alarm_mask(example_WorkingSet, mainRunscreen_DataMask);
+	}
+
 	switch (event.keyEvent)
 	{
 		case isobus::VirtualTerminalClient::KeyActivationCode::ButtonUnlatchedOrReleased:
-		case isobus::VirtualTerminalClient::KeyActivationCode::ButtonStillHeld:
 		{
 			switch (event.objectID)
 			{
-				case Plus_Button:
+				case alarm_SoftKey:
 				{
-					virtualTerminalUpdateHelper->increase_numeric_value(ButtonExampleNumber_VarNum);
+					virtualTerminalUpdateHelper->set_active_data_or_alarm_mask(example_WorkingSet, example_AlarmMask);
 				}
 				break;
 
-				case Minus_Button:
+				case acknowledgeAlarm_SoftKey:
 				{
-					virtualTerminalUpdateHelper->decrease_numeric_value(ButtonExampleNumber_VarNum);
+					virtualTerminalUpdateHelper->set_active_data_or_alarm_mask(example_WorkingSet, mainRunscreen_DataMask);
 				}
 				break;
 
-				case alarm_SoftKey:
+				default:
+					break;
+			}
+		}
+		break;
+
+		default:
+			break;
+	}
+}
+
+// This callback will provide us with event driven notifications of button presses from the stack
+void handle_button_event(const isobus::VirtualTerminalClient::VTKeyEvent &event)
+{
+	switch (event.keyEvent)
+	{
+		case isobus::VirtualTerminalClient::KeyActivationCode::ButtonUnlatchedOrReleased:
+		case isobus::VirtualTerminalClient::KeyActivationCode::ButtonStillHeld:
+		{
+			switch (event.objectID)
+			{
+				case Plus_Button:
 				{
-					virtualTerminalUpdateHelper->set_active_data_or_alarm_mask(example_WorkingSet, example_AlarmMask);
+					virtualTerminalUpdateHelper->increase_numeric_value(ButtonExampleNumber_VarNum);
 				}
 				break;
 
-				case acknowledgeAlarm_SoftKey:
+				case Minus_Button:
 				{
-					virtualTerminalUpdateHelper->set_active_data_or_alarm_mask(example_WorkingSet, mainRunscreen_DataMask);
+					virtualTerminalUpdateHelper->decrease_numeric_value(ButtonExampleNumber_VarNum);
 				}
 				break;
 
@@ -110,8 +136,8 @@ extern "C" void app_main()
 
 	virtualTerminalClient = std::make_shared<isobus::VirtualTerminalClient>(TestPartnerVT, TestInternalECU);
 	virtualTerminalClient->set_object_pool(0, testPool, (object_pool_end - object_pool_start) - 1, "ais1");
-	virtualTerminalClient->get_vt_soft_key_event_dispatcher().add_listener(handleVTKeyEvents);
-	virtualTerminalClient->get_vt_button_event_dispatcher().add_listener(handleVTKeyEvents);
+	virtualTerminalClient->get_vt_soft_key_event_dispatcher().add_listener(handle_softkey_event);
+	virtualTerminalClient->get_vt_button_event_dispatcher().add_listener(handle_button_event);
 	virtualTerminalClient->initialize(true);
 
 	virtualTerminalUpdateHelper = std::make_shared<isobus::VirtualTerminalClientUpdateHelper>(virtualTerminalClient);

examples/virtual_terminal/version3_object_pool/main.cpp

@@ -12,9 +12,7 @@
 
 #include <atomic>
 #include <csignal>
-#include <functional>
 #include <iostream>
-#include <memory>
 
 //! It is discouraged to use global variables, but it is done here for simplicity.
 static std::shared_ptr<isobus::VirtualTerminalClient> virtualTerminalClient = nullptr;
@@ -26,37 +24,63 @@ void signal_handler(int)
 	running = false;
 }
 
-// This callback will provide us with event driven notifications of button presses from the stack
-void handleVTKeyEvents(const isobus::VirtualTerminalClient::VTKeyEvent &event)
+// This callback will provide us with event driven notifications of softkey presses from the stack
+void handle_softkey_event(const isobus::VirtualTerminalClient::VTKeyEvent &event)
 {
+	if (event.keyNumber == 0)
+	{
+		// We have the alarm ACK code, so if we have an active alarm, acknowledge it by going back to the main runscreen
+		virtualTerminalUpdateHelper->set_active_data_or_alarm_mask(example_WorkingSet, mainRunscreen_DataMask);
+	}
+
 	switch (event.keyEvent)
 	{
 		case isobus::VirtualTerminalClient::KeyActivationCode::ButtonUnlatchedOrReleased:
-		case isobus::VirtualTerminalClient::KeyActivationCode::ButtonStillHeld:
 		{
 			switch (event.objectID)
 			{
-				case Plus_Button:
+				case alarm_SoftKey:
 				{
-					virtualTerminalUpdateHelper->increase_numeric_value(ButtonExampleNumber_VarNum);
+					virtualTerminalUpdateHelper->set_active_data_or_alarm_mask(example_WorkingSet, example_AlarmMask);
 				}
 				break;
 
-				case Minus_Button:
+				case acknowledgeAlarm_SoftKey:
 				{
-					virtualTerminalUpdateHelper->decrease_numeric_value(ButtonExampleNumber_VarNum);
+					virtualTerminalUpdateHelper->set_active_data_or_alarm_mask(example_WorkingSet, mainRunscreen_DataMask);
 				}
 				break;
 
-				case alarm_SoftKey:
+				default:
+					break;
+			}
+		}
+		break;
+
+		default:
+			break;
+	}
+}
+
+// This callback will provide us with event driven notifications of button presses from the stack
+void handle_button_event(const isobus::VirtualTerminalClient::VTKeyEvent &event)
+{
+	switch (event.keyEvent)
+	{
+		case isobus::VirtualTerminalClient::KeyActivationCode::ButtonUnlatchedOrReleased:
+		case isobus::VirtualTerminalClient::KeyActivationCode::ButtonStillHeld:
+		{
+			switch (event.objectID)
+			{
+				case Plus_Button:
 				{
-					virtualTerminalUpdateHelper->set_active_data_or_alarm_mask(example_WorkingSet, example_AlarmMask);
+					virtualTerminalUpdateHelper->increase_numeric_value(ButtonExampleNumber_VarNum);
 				}
 				break;
 
-				case acknowledgeAlarm_SoftKey:
+				case Minus_Button:
 				{
-					virtualTerminalUpdateHelper->set_active_data_or_alarm_mask(example_WorkingSet, mainRunscreen_DataMask);
+					virtualTerminalUpdateHelper->decrease_numeric_value(ButtonExampleNumber_VarNum);
 				}
 				break;
 
@@ -140,8 +164,8 @@ int main()
 
 	virtualTerminalClient = std::make_shared<isobus::VirtualTerminalClient>(TestPartnerVT, TestInternalECU);
 	virtualTerminalClient->set_object_pool(0, testPool.data(), testPool.size(), objectPoolHash);
-	virtualTerminalClient->get_vt_soft_key_event_dispatcher().add_listener(handleVTKeyEvents);
-	virtualTerminalClient->get_vt_button_event_dispatcher().add_listener(handleVTKeyEvents);
+	virtualTerminalClient->get_vt_soft_key_event_dispatcher().add_listener(handle_softkey_event);
+	virtualTerminalClient->get_vt_button_event_dispatcher().add_listener(handle_button_event);
 	virtualTerminalClient->initialize(true);
 
 	virtualTerminalUpdateHelper = std::make_shared<isobus::VirtualTerminalClientUpdateHelper>(virtualTerminalClient);

sphinx/README.md

@@ -13,6 +13,7 @@ doxygen doxyfile
 ```
 
 Install required python modules:
+
 ```bash
 pip install -r requirements.txt
 ```