comments updated

Author: fabiankuffer

README.md

@@ -1,11 +1,11 @@
 # SimLinkModule-Software
 
-This is the software for a BLE game controller expansion module for the TBS Tango 2. The data transfer between the module and the remote control takes place via CRSF. An output for the BLE connection status is done via an OLED display type SSD1306.
+This is the software for a BLE game controller expansion module for the TBS Tango 2. The data transfer between the module and the remote control takes place via CRSF. The first eight channels are transmitted analog and the remaining eight channels are transmitted digital. An output for the BLE connection status is done via an OLED display type SSD1306. ESP-32 Dev Kit C V4 from AZ- Delivery used.
 
 ## Tested operating systems
-- [x] Windows 11
-- [x] Android 10
-- [x] Pop! OS 22.04 LTS
+- [x] Windows 11 (tested with Velocidrone)
+- [x] Android 10 (tested with FPV.SkyDive)
+- [x] Pop! OS 22.04 LTS (tested with Velocidrone)
 
 ## TODO
 - [ ] Create a case → will be provided to another repo
@@ -17,5 +17,5 @@ This is the software for a BLE game controller expansion module for the TBS Tang
 - [ ] iOS not working. Connection can be established and automatic reconnection also works. RPA works. HID data is also subscribed and sent, but not processed by iOS.
     - Probably needs a closer look with XCode and Packetlogger (Mac required :thinking: )
     - Or a ticket to the Apple Developer Technical Support Team (Apple Developer account required :thinking: )
-- [ ] Pop! OS kernel doesn't recognize HID version when connecting via BLE (always version 0.0) → Works with an XBox Controller
-- [ ] For an Xbox controller, the client configuration descriptor of the report is set to 01 00 (by default). Here the default is 00 00 → Should be according to the specification.
+- [ ] Pop! OS kernel doesn't recognize HID version when connecting via BLE (always version 0.0) → Linux Kernel output is correct with an XBox controller
+- [ ] For an XBox controller, the client configuration descriptor of the report is set to 01 00 (by default). Here the default is 00 00 → Should be according to the specification.

components/crsf/crsf.c

@@ -18,17 +18,30 @@ static uint8_t scale_Range_Digital(uint16_t value);
 
 ChannelDataStruct channelData = {0};
 
+/**
+ * Calc crc for a single char.
+ * 
+ * @param crc       current crc value 
+ * @param a         char to check
+ * @return          new crc value
+ */
 static uint8_t crcSingleChar(uint8_t crc, uint8_t a)
 {
+    //move char bitstring eight times to the left and every time there is a 1 at the msb then xor with the generatorpolynom 0xD5 --> normal crc calculation
     crc ^= a;
-    //zeichen wird acht mal nach links geschoben und jedes mal geschaut ob höchste stelle eine 1 ist, wenn dann polynom xor --> klassisches crc rechnen
     for (int i = 0; i < 8; i++) {
         crc = (crc << 1) ^ ((crc & 0x80) ? 0xD5 : 0);
     }
     return crc;
 }
 
-//get crc from message
+/**
+ * CRC calculation for a whole string
+ * 
+ * @param message       get crc for this string
+ * @param length        length of the string
+ * @return              return the crc value
+ */
 static uint8_t crcMessage(uint8_t message[], uint8_t length)
 {
     uint8_t crc = 0;
@@ -38,12 +51,22 @@ static uint8_t crcMessage(uint8_t message[], uint8_t length)
     return crc;
 }
 
-//scale from range [173,1811] to range [0,2047]
+/**
+ * scale range from [173,1811] to [0,2047]
+ * 
+ * @param value         value to scale
+ * @return              new scaled value 
+ */
 static uint16_t scale_Range_Analog(uint16_t value){
     return (uint16_t)((value-173)*1.25);
 }
 
-//scale from range [173,1811] to range [0,1]
+/**
+ * @brief scale range from [173,1811] to [0,1]
+ * 
+ * @param value         value to scale
+ * @return              new scaled value
+ */
 static uint8_t scale_Range_Digital(uint16_t value){
     if(value <= 992){
         return 0;
@@ -53,9 +76,9 @@ static uint8_t scale_Range_Digital(uint16_t value){
 }
 
 void initCRSF_read(){
-    /* Configure parameters of an UART driver,
-     * communication pins and install the driver */
-    //uart driver erstellt eigene interrupts
+    /* configure the uart driver
+     * the uart driver creates his own interrupt
+     */
     uart_config_t uart_config = {
         .baud_rate = 420000,
         .data_bits = UART_DATA_8_BITS,
@@ -65,19 +88,20 @@ void initCRSF_read(){
         .source_clk = UART_SCLK_APB,
     };
 
-    //UART 2 verwenden, da uart 0 für console benötigt wird und uart1 hab ich gelesen für spi oder irgendetwas anderes
+    //use uart 2, because uart 0 is used for the console and uart1 could be used for spi
     ESP_ERROR_CHECK(uart_driver_install(UART_NUM_2, 1024 * 2, 0, 0, NULL, 0));
     uart_set_line_inverse(UART_NUM_2,UART_SIGNAL_RXD_INV);
     ESP_ERROR_CHECK(uart_param_config(UART_NUM_2, &uart_config));
     ESP_ERROR_CHECK(uart_set_pin(UART_NUM_2, UART_PIN_NO_CHANGE, 16, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE));
 
-    //interrupt auslösen bei timeout (primär) und bei überlauf eines thresholds
+    //trigger interrupt after the timeout (primary) or if a overflow happens
     uart_intr_config_t uart_intr = {
         .intr_enable_mask = UART_INTR_RXFIFO_TOUT | UART_INTR_RXFIFO_FULL,
         .rx_timeout_thresh = 10,
         .rxfifo_full_thresh = 200,
     };
-    //diese interrupt schwellwellen speichern
+
+    //store the interrupt thresholds
     ESP_ERROR_CHECK(uart_intr_config(UART_NUM_2, &uart_intr));
     ESP_ERROR_CHECK(uart_enable_rx_intr(UART_NUM_2));
 }
@@ -88,72 +112,72 @@ void crsf_get_ChannelData_task(void *arg)
     uint8_t *data = (uint8_t *) malloc(1024);
 
     while (1) {
-        //bool if channel data changed from channeldata t-1
+        //bool if channel data changed from channeldata t-1. Used to send a BLE update
         bool changed = false;
 
         // get size in uart buffer
         int length = 0;
         ESP_ERROR_CHECK(uart_get_buffered_data_len(UART_NUM_2, (size_t*)&length));
 
-        //mit daten arbeiten, wenn welche vorhanden sind
+        //work with the data, if data exists
         if(length){
 
             //read uart data
             int len = uart_read_bytes(UART_NUM_2, data, length, 20 / portTICK_PERIOD_MS);
 
-            //RX Buffer leeren wenn Frame im temporären buffer
+            //clear rx buffer after the data is in the temp buffer
             uart_flush(UART_NUM_2);
 
-            //len of data read from rx buffer
+            //check again the length of the data in the temp buffer
             if(len > 0){
-                //daten durchgehen
+                //loop through data
                 for(int i = 0; i < len; i++){
-                    //Paketaufbau: 0xEE (Addresse) + 0x18 (Länge in Byte) + 0x16 (Typenfeld: Kanaldaten)
+                    //check for packets with the data: 0xEE(address) + 0x18(length in Bytes) + 0x16(typefield: channel data)
                     if((data[i] == 0xEE) && (i+25)<len){
                         if(data[i+2] == 0x16){
-                            //CRC überprüfen ob kein rest rauskommst
+                            //CRC check. should be zero
                             if(crcMessage(data+i+2, data[i+1]) == 0){
 
-                                //used = wie viel Bits bereits in einen Byte verwendet wurden
+                                //used = How many bits were used in a temp buffer byte.
                                 int used = 0;
-                                //dataIndex = Index des Datenbytes im Buffer
+                                //dataIndex = Index of the data byte in the buffer
                                 int dataIndex = i+3;
 
-                                //Da 16 kanäle vorhanden sind muss es 16 mal durchgegangen werden
+                                //loop through all 16 channels
                                 for(int j = 0; j<16; j++){
-                                    //Die restlichen vorhandenen Daten eines Bytes an LSB setzen
+                                    //Set the remaining existing data of a temp buffer byte to LSB.
                                     uint16_t value = data[dataIndex] >> used;
 
-                                    //ein neues Byte muss verwendet werden
+                                    //use a new byte from the temp buffer.
                                     dataIndex++;
 
-                                    //Anzahl der noch vorhanden Bits eines Bytes im angefangenen Byte
+                                    //Number of remaining channel bits of a byte in the started temp buffer byte.
                                     uint8_t availableBits = 8-used;
 
                                     if(11-availableBits > 8){
-                                        //3Bytes werden benötigt, wenn für ein Kanal (11Bit) noch mehr als 8 Bit benötigt werden
+                                        //3bytes are required if more than 8 bits are still needed for one channel (11bit)
 
-                                        //komplettes zweites Byte verwenden
+                                        //use entire second byte
                                         value = value | (data[dataIndex] << availableBits);
-                                        //ein neues Byte muss verwendet werden
+                                        //use a new Byte
                                         dataIndex++;
 
-                                        //vom dritten Byte noch die benötigten Bits in die MSB stellen schieben
+                                        //from the third byte still shift the needed bits into the MSB
                                         value = value | ((data[dataIndex]&((1U << (11-(8+availableBits))) - 1U)) << (8+availableBits));
 
-                                        //Anzahl der verwendeten Bits im akutellen Byte neu berechnen
+                                        //Recalculate number of used bits in current temp buffer byte
                                         used = 11-(8+availableBits);
                                     } else {
-                                        //Wenn nur ein zweites Byte für 11Bit-Daten benötigt wird
+                                        //If only a second byte is needed for 11Bit data
 
-                                        //Aus dem zweiten Byte noch die fehlenden Bits an die MSB stellen schieben von 11 Bit
+                                        //Move the missing bits from the second byte to the MSB positions. (11Bit per channel)
                                         value = value | ((data[dataIndex]&((1U << (11-availableBits)) - 1U)) << availableBits);
 
-                                        //berechnen wie viele Bits im aktuellen Byte schon verwendet wurden
+                                        //calculate how many bits in the current temp buffer byte have already been used
                                         used = 11-availableBits;
                                     }
 
-                                    //Kanaldaten abspeichern --> ersten 8 kanäle sind analog rest digital
+                                    //store channel data --> first 8 channel are analog rest ist digital
                                     uint16_t newVal;
                                     uint8_t origDataButtons;
                                     switch(j){
@@ -235,18 +259,18 @@ void crsf_get_ChannelData_task(void *arg)
                                             break;
                                     }
                                 }
-                                //Kanaldaten ausgeben
-                                //wenn esp_logi ausgegeben wird dann kann es sein das watchdog timer für den task nicht zurückgesetzt wird ist aber nicht so schlimm solang der output einfach weggelassen wird in stpäteren code
+
                                 if(changed){
                                     if(notify_state_report_data){
                                         struct os_mbuf *om;
 
-                                        //dann passt die größe vom paket zu den report deskriptor wenn 17 fesst vorprogrammiert ist --> sizeof(channelData) gibt 18
+                                        //set size to 17, because of padding bits in the struct channelData calculates 18
                                         om = ble_hs_mbuf_from_flat(&channelData, 17);
                                         //Deprecated. Should not be used. Use ble_gatts_notify_custom instead.
                                         ble_gattc_notify_custom(conn_handle, report_data_handle, om);
                                     }
                                 }
+                                //if esp_logi is used then the watchdog timer for the task may not be reset
                                 //ESP_LOGI("Channel-Data","%4d %4d %4d %4d %4d %4d %4d %4d %4d %4d %4d %4d %4d %4d %4d %4d", channelData.throttle, channelData.yaw, channelData.pitch, channelData.roll, channelData.aux1, channelData.aux2, channelData.aux3, channelData.aux4, (channelData.buttons & (0x01<<0)), (channelData.buttons & (0x01<<1)), (channelData.buttons & (0x01<<2)), (channelData.buttons & (0x01<<3)), (channelData.buttons & (0x01<<4)), (channelData.buttons & (0x01<<5)), (channelData.buttons & (0x01<<6)), (channelData.buttons & (0x01<<7)));
                                 break;
                             }
@@ -255,6 +279,7 @@ void crsf_get_ChannelData_task(void *arg)
                 }
             }
         } else {
+            //Create a delay if no data could be loaded
             vTaskDelay(10 / portTICK_PERIOD_MS);
         }
     }

components/crsf/include/crsf.h

@@ -16,10 +16,19 @@ typedef struct ChannelDataStruct{
   uint8_t buttons;      //buttons = aux12(b8) .. aux5(b1)
 } ChannelDataStruct;
 
-//store for channeldata
+//global store for channeldata
 extern ChannelDataStruct channelData;
 
+/**
+ * initializes UART to read remote control channel data.
+ */
 void initCRSF_read();
+
+/**
+ * Read the UART data. Check if it is the right frame and make a CRC check. Then process the channel data and convert it to a range from 0 to 2047.
+ * 
+ * @param arg Required for FreeRTOS. Not used.
+ */
 void crsf_get_ChannelData_task(void *arg);
 
 #endif

components/ssd1306/include/ssd1306_font.h

@@ -1,17 +1,18 @@
-#ifndef SSD1306_FONT_H
-#define SSD1306_FONT_H
-
 //font: VCR OSD Mono by Riciery Leal
 //font is free even for commercial purposes.
 //https://www.dafont.com/font-comment.php?file=vcr_osd_mono
 //https://www.dafont.com/de/vcr-osd-mono.font
 
+#ifndef SSD1306_FONT_H
+#define SSD1306_FONT_H
+
 #define CHAR_WIDTH  10
 #define CHAR_HEIGHT 14
 
-//Ein Hex wert stellt eine Spalte eines Zeichen dar
-//lsb sind die unteren pixel des zeichens
-//die 2 msb werden immer übersprungen
+/*One hex-value is a column of a char
+ *the LSB of a hex-value are the bottom pixel of a char
+ *two MSBs are skipped
+ */
 const uint16_t VCR_OSD_MONO[43][10] = {
     {0x0000,0x0000,0x0000,0x0000,0x0000,0x0000,0x0000,0x0000,0x0000,0x0000}, // 
     {0x0038,0x00FE,0x19C7,0x1983,0x1983,0x1983,0x1983,0x1CC6,0x0FFF,0x07FF}, // a
@@ -55,7 +56,7 @@ const uint16_t VCR_OSD_MONO[43][10] = {
     {0x0000,0x0000,0x0000,0x0000,0x07F3,0x07F3,0x0000,0x0000,0x0000,0x0000}, // !
     {0x0000,0x0000,0x0000,0x0000,0x0003,0x0003,0x0000,0x0000,0x0000,0x0000}, // .
     {0x0000,0x00C0,0x00C0,0x00C0,0x00C0,0x00C0,0x00C0,0x00C0,0x00C0,0x0000}, // -
-    {0x0000,0x3FFF,0x3FFF,0x3003,0x3003,0x3003,0x3003,0x3FFF,0x3FFF,0x0000}, // unknown
+    {0x0000,0x3FFF,0x3FFF,0x3003,0x3003,0x3003,0x3003,0x3FFF,0x3FFF,0x0000}, // unknown char
 };
 
 #endif

components/ssd1306/include/ssd1306_images.h

@@ -3,8 +3,7 @@
 
 //drawn in: https://www.pixilart.com/draw
 //converted from png to bitstring with: https://www.dcode.fr/binary-image
-//convert bitstring to hex array: Bin2Hex.py <filename> in tools folder
-
+//convert bitstring to hex array: bin2ByteArray.py <filename> in tools folder
 const uint8_t connectedImage[] = {0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x80,0xC0,0xE0,0xF0,0xF8,0xF8,0xFC,0xFC,0xFC,0xFE,0xFE,0xFE,0xFE,0xFE,0xFE,0x00,0x00,0x00,0x00,0x00,0xFE,0xFE,0xFE,0xFE,0xFE,0xFE,0xFC,0xFC,0xFC,0xF8,0xF8,0xF0,0xE0,0xC0,0x80,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xC0,0xC0,0xE0,0xE0,0x60,0x60,0x60,0x60,0xE0,0xC0,0xC0,0xC0,0xC0,0x80,0x80,0x80,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x80,0x80,0x80,0x80,0xF0,0xFC,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0x06,0x06,0x06,0x06,0x06,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFC,0xF0,0xE0,0xE0,0x60,0x60,0x60,0x70,0x30,0x30,0x30,0x38,0x18,0x18,0x18,0x18,0x18,0x1C,0x0C,0x0E,0x0E,0x06,0x06,0x06,0x06,0x0E,0x0C,0x0C,0x0C,0x0C,0x0C,0x1C,0x1C,0x18,0x18,0x38,0x38,0x30,0x30,0x70,0xE0,0xE0,0xC0,0x80,0x01,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x01,0x01,0x01,0x03,0x03,0x07,0x06,0x0E,0x0E,0x0C,0x1C,0x18,0x18,0x18,0x18,0x18,0x1C,0x0C,0x0C,0x0C,0x0C,0x0E,0x0E,0x06,0x06,0x06,0x07,0x03,0x03,0x03,0x03,0x01,0x01,0x0F,0x3F,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0x60,0x60,0x60,0x60,0x60,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0x3F,0x0F,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x01,0x01,0x01,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x01,0x03,0x07,0x0F,0x1F,0x1F,0x3F,0x3F,0x3F,0x7F,0x7F,0x7F,0x7F,0x7F,0x7F,0x00,0x00,0x00,0x00,0x00,0x7F,0x7F,0x7F,0x7F,0x7F,0x7F,0x3F,0x3F,0x3F,0x1F,0x1F,0x0F,0x07,0x03,0x01,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00};
 
 #endif