From 24e8985adc05856fa69e5a63bab99937f8be9b50 Mon Sep 17 00:00:00 2001 From: RCayre Date: Thu, 30 Mar 2023 16:24:37 +0200 Subject: [PATCH] Updating documentation of cross protocols --- cross_protocols/README.md | 28 ++++++++++++++----- cross_protocols/ant_rx/main/ant_rx.c | 20 ++++++++++++- cross_protocols/ant_scan/main/ant_scan.c | 11 ++++++++ cross_protocols/ant_tx/main/ant_tx.c | 9 ++++++ cross_protocols/dot15d4_rx/main/dot15d4_rx.c | 8 ++++++ cross_protocols/dot15d4_tx/main/dot15d4_tx.c | 9 ++++++ cross_protocols/esperanto/include/esperanto.h | 26 +++++++++++------ cross_protocols/jam_ble/main/jam_ble.c | 6 ++++ cross_protocols/riitek_rx/main/riitek_rx.c | 6 ++++ cross_protocols/riitek_tx/main/riitek_tx.c | 6 ++++ 10 files changed, 113 insertions(+), 16 deletions(-) diff --git a/cross_protocols/README.md b/cross_protocols/README.md index 98aab0f..7b96262 100644 --- a/cross_protocols/README.md +++ b/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 ` diff --git a/cross_protocols/ant_rx/main/ant_rx.c b/cross_protocols/ant_rx/main/ant_rx.c index aab7073..3aff371 100644 --- a/cross_protocols/ant_rx/main/ant_rx.c +++ b/cross_protocols/ant_rx/main/ant_rx.c @@ -2,6 +2,12 @@ #include #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); diff --git a/cross_protocols/ant_scan/main/ant_scan.c b/cross_protocols/ant_scan/main/ant_scan.c index 3e1e00a..e0bb0f9 100644 --- a/cross_protocols/ant_scan/main/ant_scan.c +++ b/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++) { diff --git a/cross_protocols/ant_tx/main/ant_tx.c b/cross_protocols/ant_tx/main/ant_tx.c index 15678d9..298cbdb 100644 --- a/cross_protocols/ant_tx/main/ant_tx.c +++ b/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) diff --git a/cross_protocols/dot15d4_rx/main/dot15d4_rx.c b/cross_protocols/dot15d4_rx/main/dot15d4_rx.c index 62d2131..54af31e 100644 --- a/cross_protocols/dot15d4_rx/main/dot15d4_rx.c +++ b/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) diff --git a/cross_protocols/dot15d4_tx/main/dot15d4_tx.c b/cross_protocols/dot15d4_tx/main/dot15d4_tx.c index d349cd4..c00dd74 100644 --- a/cross_protocols/dot15d4_tx/main/dot15d4_tx.c +++ b/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) diff --git a/cross_protocols/esperanto/include/esperanto.h b/cross_protocols/esperanto/include/esperanto.h index a93a240..8553df3 100644 --- a/cross_protocols/esperanto/include/esperanto.h +++ b/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,6 +157,7 @@ typedef struct { bool enabled; } radio_config_t; +/* Structure representing a received packet and its metadata. */ typedef struct { uint8_t *packet; size_t total_size; @@ -157,18 +165,28 @@ typedef struct { 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 diff --git a/cross_protocols/jam_ble/main/jam_ble.c b/cross_protocols/jam_ble/main/jam_ble.c index 2aa0648..7a892b3 100644 --- a/cross_protocols/jam_ble/main/jam_ble.c +++ b/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) { diff --git a/cross_protocols/riitek_rx/main/riitek_rx.c b/cross_protocols/riitek_rx/main/riitek_rx.c index 4b4517f..e2504a4 100644 --- a/cross_protocols/riitek_rx/main/riitek_rx.c +++ b/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) diff --git a/cross_protocols/riitek_tx/main/riitek_tx.c b/cross_protocols/riitek_tx/main/riitek_tx.c index aa8c88c..6350392 100644 --- a/cross_protocols/riitek_tx/main/riitek_tx.c +++ b/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)