Merge branch 'develop'

# Conflicts:
#	extras/docs/quickstart.rst

Author: Patrick Bechon

examples/KerbalSimpitEchoNames/KerbalSimpitEchoNames.ino

@@ -0,0 +1,66 @@
+/* KerbalSimpitEchoNames
+   A demonstration of reading the SOI name and the vessel name
+   and echo it back to KSP for debug purpose.
+   It could also be displayed to a screen if one is available
+   (not included in this example)
+
+*/
+
+#include "KerbalSimpit.h"
+
+
+// Declare a KerbalSimpit object that will communicate using the "Serial" device.
+KerbalSimpit mySimpit(Serial);
+
+void setup() {
+  // Open the serial connection.
+  Serial.begin(115200);
+
+  // Set up the build in LED, and turn it on.
+  pinMode(LED_BUILTIN, OUTPUT);
+  digitalWrite(LED_BUILTIN, HIGH);
+
+  // This loop continually attempts to handshake with the plugin.
+  // It will keep retrying until it gets a successful handshake.
+  while (!mySimpit.init()) {
+    delay(100);
+  }
+  // Turn off the built-in LED to indicate handshaking is complete.
+  digitalWrite(LED_BUILTIN, LOW);
+  // Display a message in KSP to indicate handshaking is complete.
+  mySimpit.printToKSP("Connected", PRINT_TO_SCREEN);
+  // Sets our callback function. The KerbalSimpit library will
+  // call this function every time a packet is received.
+  mySimpit.inboundHandler(messageHandler);
+  // Send a message to the plugin registering for the channels.
+  mySimpit.registerChannel(SOI_MESSAGE);
+  mySimpit.registerChannel(VESSEL_NAME_MESSAGE);
+}
+
+void loop() {
+  // Check for new serial messages.
+  mySimpit.update();
+}
+
+void messageHandler(byte messageType, byte msg[], byte msgSize) {
+  switch(messageType) {
+  case SOI_MESSAGE: {
+      // Parse the SOI name
+      String SOIName = (char *) msg;
+      SOIName[msgSize] = '\0';
+
+      // Echo it to KSP
+      mySimpit.printToKSP("I'm orbitting " + SOIName, PRINT_TO_SCREEN);
+    }
+    break;
+    case VESSEL_NAME_MESSAGE: {
+      // Parse the vessel name
+      String vesselName = (char *) msg;
+      vesselName[msgSize] = '\0';
+
+      // Echo it to KSP
+      mySimpit.printToKSP("I'm " + vesselName, PRINT_TO_SCREEN);
+    }
+    break;
+  }
+}

examples/KerbalSimpitHelloWorld/KerbalSimpitHelloWorld.ino

@@ -69,7 +69,7 @@ void messageHandler(byte messageType, byte msg[], byte msgSize) {
     // The message payload will be either "low" or "high".
     // We use the strcmp function to check what the string payload
     // is, and set the LED status accordingly.
-    if (strcmp(msg, "low")) {
+    if (strcmp((char*) msg, "low")) {
       digitalWrite(LED_BUILTIN, LOW);
     } else {
       digitalWrite(LED_BUILTIN, HIGH);

examples/KerbalSimpitStressTest/KerbalSimpitStressTest.ino

@@ -0,0 +1,70 @@
+/* KerbalSimpitStressTest
+   A demonstration of subscribing to all channel and check what is the impact
+   of taking too long to call mysimpit.update.
+*/
+#include "KerbalSimpit.h"
+
+// Declare a KerbalSimpit object that will
+// communicate using the "Serial" device.
+KerbalSimpit mySimpit(Serial);
+
+// Store last time the log was sent to KSP
+unsigned long lastTimeLogging = 0;
+const long intervalLogging = 5000;
+
+// Store number of messages received
+int msgNbr = 0;
+
+void setup() {
+  // Open the serial connection.
+  Serial.begin(115200);
+
+  // Set up the build in LED, and turn it on.
+  pinMode(LED_BUILTIN, OUTPUT);
+  digitalWrite(LED_BUILTIN, HIGH);
+  // This loop continually attempts to handshake with the plugin.
+  // It will keep retrying until it gets a successful handshake.
+  while (!mySimpit.init()) {
+    delay(100);
+  }
+  // Turn off the built-in LED to indicate handshaking is complete.
+  digitalWrite(LED_BUILTIN, LOW);
+  // Display a message in KSP to indicate handshaking is complete.
+  mySimpit.printToKSP("Connected", PRINT_TO_SCREEN);
+  // Sets our callback function. The KerbalSimpit library will
+  // call this function every time a packet is received.
+  mySimpit.inboundHandler(messageHandler);
+
+  // Here you can register all the channels you want to use.
+  // mySimpit.registerChannel(ALTITUDE_MESSAGE);
+  // ...
+  
+  // By default, register all available channels (even some non existant ones)
+  for(byte b = 0; b <= 128; b++){
+    mySimpit.registerChannel(b);
+  }
+}
+
+void loop() {
+  // Check for new serial messages.
+  mySimpit.update();
+
+  // Emulate a time consuming treatement. Increase/descrease this value to see the impact on the number of recevied/lost messages.
+  delay(10);
+
+  unsigned long currentMillis = millis();
+  if (currentMillis - lastTimeLogging >= intervalLogging) {
+    lastTimeLogging = currentMillis;
+
+    mySimpit.printToKSP("Number of msg " + String(msgNbr));
+    msgNbr = 0;
+    
+    mySimpit.printToKSP("Number of lost msg " + String(mySimpit.packetDroppedNbr));
+    mySimpit.packetDroppedNbr = 0;
+  }
+}
+
+void messageHandler(byte messageType, byte msg[], byte msgSize) {
+  //Ignore all messages, just count them
+  msgNbr ++;
+}

extras/docs/quickstart.rst

@@ -124,3 +124,10 @@ The examples_ directory of the library contains several example sketches
 that demonstrate the different functionality of the library.
 
 .. _examples: https://github.com/Simpit-team/KerbalSimpitRevamped-Arduino/tree/main/examples
+
+When you first install Simpit, you have to modify the *Settings.cfg* file that is found in the *GameData\KerbalSimpit* folder.
+You can copy the provided ``Settings.cfg.sample`` as a baseline, and you must at least define the port name to use. More information in :any:`troubleshooting`.
+
+Simpit allows several controllers to be used at the same time. For this, you can define several *SerialPort* blocks in the *Settings.cfg* file. All controllers are managed independently.
+
+Simpit also allows you to open/close a port while the game is running. This allows you to reprogram the Arduino while KSP is running (you have to close the port, upload the program, open the port again).

extras/docs/troubleshooting.rst

@@ -81,6 +81,34 @@ Here is an example.
 	System.Threading.ThreadHelper.ThreadStart () (at <ad04dee02e7e4a85a1299c7ee81c79f6>:0)
 	UnityEngine.UnhandledExceptionHandler:<RegisterUECatcher>m__0(Object, UnhandledExceptionEventArgs)
 
+When I add more functionalities to my controller, it starts to behave strangely (messages lost, corrupted, etc.)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+It is probable that the Arduino serial buffer size is too small given the time between each call to ``simpit.update`` and the number of messages sent. You can test this by displaying ``mySimpit.packetDroppedNbr``. If it is non-zero, it means that some messages were corruped.
 
+To fix it, you have several solutions :
+ * Increase the serial buffer size in ``HardwareSerial.h``. To find the right file to modify, see here : https://forum.arduino.cc/t/solved-serial-buffer-size/581828/10. There should be a log line in KSP.log indicating the buffer size when an Arduino connect. The default is 64 bytes and the recommandation is at least 256.
+ * Reduce the number of channels you subscribe to
+ * Call ``simpit.update`` more frequently. For instance if you have a controller with several parts, you can call ``simpit.update`` between each part update instead of updating all the parts and only then call ``simpit.update``.
 
+To test that this is not the root cause of your issue, you can use the KerbalSimpitStressTest example. Subscribe to all the channels you want to use, and test several values of delay to see if some messages are lost. Then try on you controller to measure what is the delay between two calls to ``simpit.update`` and compare the two values.
+
+
+I have some issues with custom action groups (CAG) when using Action Group Extended (AGExt)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There is some know issues when using AGExt.
+
+For stock CAG (below 10), AGExt seems to disregard activating empty CAG. This means that the controller cannot activate any CAG between 1-10 even when the those CAGs can be activated via keyboard since the game allow to activate empty CAG.
+
+There is also an issue that in some cases the toggling of a CAG is not working when the CAG content was not set at launch but is modified during flight.
+The root cause might be the content of the stock CAG not being the same as the AGExt CAG with the same number.
+Simpit is only using the AGExt CAG, not the stock one, when AGExt is installed.
+In this case, you should check (and modify) CAG content using AGExt GUI only, not the stock one, to avoid this issue.
+
+For non-stock CAG (11 and above), there seem to be an issue with empty CAGs.
+AGExt allow to activate empty CAG, and the value of the CAG seems to be shared between several vessels (behavior not consistent with stock CAG).
+Meaning that if craft A and B have an empty CAG 11, it can be toggled on any craft and when switching craft, the value is kept instead of being tied to the vessel.
+If the CAG is populated on both craft, switching from one to the other works as expected.
+
+There is no known workaround currently, the issue seems to be in the way AGExt handle those edgecases. AGExt should not be installed when not needed.

library.properties

@@ -1,5 +1,5 @@
 name=KerbalSimpit
-version=2.1.0
+version=2.2.0
 author=Rogor, LRTNZ <simpit.team@gmail.com>
 maintainer=Rogor, LRTNZ <simpit.team@gmail.com>
 sentence=A library for interfacing with the Kerbal Space Program video game.

src/Helpers.cpp

@@ -42,3 +42,9 @@ void KerbalSimpit::setCameraMode(byte mode)
 {
   _send(CAMERA_CONTROL_MODE, &mode, 1);
 }
+
+void KerbalSimpit::cycleNavBallMode()
+{
+  byte payload = 0;
+  _send(NAVBALLMODE_MESSAGE, &payload, 1);
+}