Updating documentation of cross protocols

cross_protocols/README.md

@@ -1,6 +1,7 @@
 # Cross protocols artifacts
 
 This artifact includes a minimal cross-protocol library (ESPeranto) as an IDF component, and a set of examples demonstrating its use.
+
 It allows to alter the behaviour of the BLE controller by modifying some structures in exchange memory, to communicate with non natively supported protocol.
 
 The example should be compatible with ESP32, ESP32C3 and ESP32S3.
@@ -19,32 +20,45 @@ The examples provided are the following one:
 
 ## Requirements
 
-You need to install Espressif SDK **in version 4.4**. Follow the guide here:
-[link](https://docs.espressif.com/projects/esp-idf/en/v4.4/esp32/get-started/index.html)
+You need to install Espressif SDK **in version 4.4**. A full complete guide is available [here](https://docs.espressif.com/projects/esp-idf/en/v4.4/esp32/get-started/index.html). 
+
+Once the SDK is configured, clone the repository and go to the cross_protocols folder:
+
+`
+$ git clone https://github.com/RCayre/woot23_espwn32_artifacts
+$ cd woot23_espwn32_artifacts/cross_protocols
+`
+
+You can then build one of the provided example.
 
 ## Build a specific example
 
-* Go to the example directory.
+1. Go to the example directory. For example, if you want to build the **ant\_tx** example:
+
 `
 $ cd ant_tx
 `
 
-Clean the environment:
+2. Clean the environment:
+
 `
 idf.py fullclean
 `
 
-Pick your target (esp32, esp32s3 or esp32c3):
+3. Pick your target (esp32, esp32s3 or esp32c3):
+
 `
 idf.py set-target esp32
 `
 
-Build the example:
+4. Build the example:
+
 `
 idf.py build
 `
 
-Flash it on the board and monitor the output over serial port:
+5. Flash it on the board and monitor the output over serial port:
+
 `
 idf.py flash && idf.py monitor
 `

cross_protocols/ant_rx/main/ant_rx.c

@@ -2,6 +2,12 @@
 #include <string.h>
 #include "nvs_flash.h"
 #include "esperanto.h"
+/*
+* This example demonstrates the reception of ANT+ packets from ESP32, ESP32C3 and ESP32S3.
+
+* By default, it matches communications with 0xe81e as device number.
+* You can refer to the ant_scan example if you don't know the device number of the communication.
+*/
 
 /* ANT+ protocol specific constants */
 #define ANT_PLUS_PREAMBLE                 (0xa6c5)
@@ -10,7 +16,7 @@
 #define ANT_CRC16_INIT_VALUE              (0xFFFF)
 
 void ant_rx_callback(uint8_t *packet,size_t size, int8_t rssi, int frequency) {
-    /* ANT+ Reception callback. */
+    /* ANT+ Reception callback: triggered when a packet is successfully received. */
 
     /* Display the packet and its associated metadata. */
     esp_rom_printf("[frequency=%d, rssi=%d] ", frequency,rssi);
@@ -30,11 +36,21 @@ void ant_rx_callback(uint8_t *packet,size_t size, int8_t rssi, int frequency) {
 
 void configure_ant_plus(uint16_t device_number) {
     /* Configure radio to match ANT+ communications according to a specific device number.*/
+
+    // Initialize radio and configure the reception callback
     init_radio(ant_rx_callback);
+
+    // Configure the frequency on channel 57 (2457MHz)
     set_frequency(2457);
+
+    // ANT packets requires big endian, swap the packets.
     set_swapping(true);
+
+    // Configure the reception word
     uint32_t synchronization_word = ((ANT_PLUS_PREAMBLE << 16) | device_number);
     set_sync_word(synchronization_word);
+
+    // Use a 1MBps datarate
     set_data_rate(DATARATE_1M);
 }
 
@@ -50,8 +66,10 @@ void app_main(void)
     // Listen the packets received by a device with device number 0xe81e.
     uint16_t device_number = 0xe81e;
 
+    // Configure the radio
     configure_ant_plus(device_number);
 
+    // Start the radio in reception mode
     start_radio(MODE_RX);
     while (1) {
       vTaskDelay(1000 / portTICK_PERIOD_MS);

cross_protocols/ant_scan/main/ant_scan.c

@@ -3,6 +3,15 @@
 #include "nvs_flash.h"
 #include "esperanto.h"
 
+/*
+* This example demonstrates the scanning of ANT+ packets from ESP32, ESP32C3 and ESP32S3.
+*
+* It applies various filters to keep packets matching the Heart Rate Monitor device type,
+* and displays the candidate device numbers.
+*
+*/
+
+
 /* ANT+ protocol specific constants */
 #define ANT_PLUS_PREAMBLE                 (0xa6c5)
 #define HEART_RATE_MONITOR_DEVICE_TYPE    (0x78)
@@ -11,7 +20,9 @@
 
 void ant_scan_callback(uint8_t *packet,size_t size, int8_t rssi, int frequency) {
   /* ANT+ scan reception callback. */
+    // Check the rssi and the packet size
     if (rssi > -90 && size >= 7) {
+      // Check the device type
       if (packet[6] == HEART_RATE_MONITOR_DEVICE_TYPE) {
         esp_rom_printf("[frequency=%d, rssi=%d] Candidate device number: ", frequency,rssi);
         for (int i=4;i<6;i++) {

cross_protocols/ant_tx/main/ant_tx.c

@@ -3,6 +3,15 @@
 #include "nvs_flash.h"
 #include "esperanto.h"
 
+/*
+* This example demonstrates the transmission of ANT+ packets from ESP32, ESP32C3 and ESP32S3.
+* It imitates an ANT+ Heart Rate Monitor device.
+*
+* By default, it matches communications with 0xe81e as device number.
+* You can refer to the ant_scan example if you don't know the device number of the communication.
+*/
+
+
 /* ANT+ specific constants. */
 #define ANT_PLUS_PREAMBLE                 (0xa6c5)
 #define HEART_RATE_MONITOR_DEVICE_TYPE    (0x78)

cross_protocols/dot15d4_rx/main/dot15d4_rx.c

@@ -3,6 +3,14 @@
 #include "nvs_flash.h"
 #include "esperanto.h"
 
+/*
+* This example demonstrates the reception of 802.15.4 packets from ESP32C3 and ESP32S3.
+* It requires support of LE 2M Physical Layer, so it won't work on ESP32.
+*
+* It uses WazaBee attack to convert MSK symbols to the corresponding OQPSK symbols.
+* By default, it receives packets on channel 12.
+*/
+
 /* 802.15.4 specific constants. */
 #define DOT15D4_RX_PREAMBLE                 (0xa7)
 #define DOT15D4_MATCHING_PATTERN            (0x03f73a9b)

cross_protocols/dot15d4_tx/main/dot15d4_tx.c

@@ -3,6 +3,15 @@
 #include "nvs_flash.h"
 #include "esperanto.h"
 
+/*
+* This example demonstrates the transmission of 802.15.4 packets from ESP32C3 and ESP32S3.
+* It requires support of LE 2M Physical Layer, so it won't work on ESP32.
+*
+* It uses WazaBee attack to convert OQPSK symbols to the corresponding MSK symbols.
+* By default, it transmits packets on channel 12.
+*/
+
+
 /* 802.15.4 specific constants. */
 #define DOT15D4_RX_PREAMBLE                 (0xa7)
 #define DOT15D4_MATCHING_PATTERN            (0x03f73a9b)

cross_protocols/esperanto/include/esperanto.h

@@ -4,9 +4,12 @@
 #include "hci.h"
 #include "helpers.h"
 
+/* Test modes formats */
 #define LLD_TEST_MODE_RX                    0x1D
 #define LLD_TEST_MODE_TX                    0x1E
 
+
+/* Offsets and indexes in Exchange Memory and Function pointers arrays */
 #ifdef ESP32
 #define TX_LOOP_CALLBACK_INDEX              595
 #define TX_PUSH_CALLBACK_INDEX              598
@@ -129,17 +132,21 @@ typedef struct {
     #endif
 } pkt_header_t;
 
+/* Available datarates (1Mbps or 2Mbps). */
 typedef enum {
     DATARATE_1M = 0,
     DATARATE_2M = 1
 } datarate_t;
 
+
+/* Available radio modes. */
 typedef enum {
     MODE_RX = 0,
     MODE_TX = 1,
     MODE_JAMMER = 2
 } radio_mode_t;
 
+/* Structure storing information about the radio configuration. */
 typedef struct {
     rx_callback_t rx_callback;
     uint32_t sync_word;
@@ -150,25 +157,36 @@ typedef struct {
     bool enabled;
 } radio_config_t;
 
+/* Structure representing a received packet and its metadata. */
 typedef struct {
   uint8_t *packet;
   size_t total_size;
   int8_t rssi;
   int frequency;
 } rx_packet_t;
 
+
+/* Structure representing a packet to transmit. */
 typedef struct {
   uint8_t *packet;
   size_t size;
 } tx_packet_t;
+
 extern uint8_t *chip7_sleep_params;
 extern void *r_emi_get_mem_addr_by_offset(uint16_t offset);
 
+/* Esperanto Library API */
 void set_frequency(uint32_t frequency);
 void set_sync_word(uint32_t sync_word);
 void set_swapping(bool swapping);
 void set_data_rate(datarate_t datarate);
+void init_radio(rx_callback_t rx_callback);
+void start_radio(radio_mode_t mode);
+void stop_radio();
+void close_radio();
+void transmit_packet(uint8_t* packet, size_t size);
 
+/* Esperanto internals functions */
 #if defined(ESP32S3) || defined(ESP32C3)
 void configure_data_rate(datarate_t datarate);
 #endif
@@ -180,12 +198,4 @@ void configure_sync_word(uint32_t sync);
 void configure_format(uint8_t format);
 void disable_crc_checking();
 
-void init_radio(rx_callback_t rx_callback);
-
-void start_radio(radio_mode_t mode);
-void stop_radio();
-
-void close_radio();
-
-void transmit_packet(uint8_t* packet, size_t size);
 #endif

cross_protocols/jam_ble/main/jam_ble.c

@@ -4,6 +4,12 @@
 #include "esperanto.h"
 
 
+/*
+* This example demonstrates the simultaneous jamming of Bluetooth Low Energy advertising channels.
+* It only works on ESP32 for now (need some minor fixes to make it work on ESP32S3/ESP32C3.
+*/
+
+
 
 void app_main(void)
 {

cross_protocols/riitek_rx/main/riitek_rx.c

@@ -3,6 +3,12 @@
 #include "nvs_flash.h"
 #include "esperanto.h"
 
+
+/*
+* This example demonstrates the reception of Riitek packets from ESP32, ESP32S3 and ESP32C3.
+* It is configured to work with the address 02:20:20:86:68 on channel 26 (2426MHz).
+*/
+
 /* Riitek specific constants. */
 #define RIITEK_PREAMBLE                   (0xAA)
 #define RIITEK_CRC16_INIT_VALUE           (0x8b83)

cross_protocols/riitek_tx/main/riitek_tx.c

@@ -3,6 +3,12 @@
 #include "nvs_flash.h"
 #include "esperanto.h"
 
+
+/*
+* This example demonstrates the transmission of Riitek keystrokes packets from ESP32, ESP32S3 and ESP32C3.
+* It is configured to work with the address 02:20:20:86:68 on channel 26 (2426MHz).
+*/
+
 /* Riitek specific constants. */
 #define RIITEK_PREAMBLE                   (0xAA)
 #define RIITEK_KEYSTROKE_TYPE             (0x0B)