-
Notifications
You must be signed in to change notification settings - Fork 7.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add FTM support and examples (#5272)
Rework of #5266 by @pedrominatel
- Loading branch information
Showing
8 changed files
with
366 additions
and
6 deletions.
There are no files selected for viewing
90 changes: 90 additions & 0 deletions
90
libraries/WiFi/examples/FTM/FTM_Initiator/FTM_Initiator.ino
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,90 @@ | ||
/* Wi-Fi FTM Initiator Arduino Example | ||
This example code is in the Public Domain (or CC0 licensed, at your option.) | ||
Unless required by applicable law or agreed to in writing, this | ||
software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR | ||
CONDITIONS OF ANY KIND, either express or implied. | ||
*/ | ||
#include "WiFi.h" | ||
|
||
/* | ||
THIS FEATURE IS SUPPORTED ONLY BY ESP32-S2 AND ESP32-C3 | ||
*/ | ||
|
||
// Change the SSID and PASSWORD here if needed | ||
const char * WIFI_FTM_SSID = "WiFi_FTM_Responder"; // SSID of AP that has FTM Enabled | ||
const char * WIFI_FTM_PASS = "ftm_responder"; // STA Password | ||
|
||
// FTM settings | ||
// Number of FTM frames requested in terms of 4 or 8 bursts (allowed values - 0 (No pref), 16, 24, 32, 64) | ||
const uint8_t FTM_FRAME_COUNT = 16; | ||
// Requested time period between consecutive FTM bursts in 100’s of milliseconds (allowed values - 0 (No pref) or 2-255) | ||
const uint16_t FTM_BURST_PERIOD = 2; | ||
|
||
// Semaphore to signal when FTM Report has been received | ||
xSemaphoreHandle ftmSemaphore; | ||
// Status of the received FTM Report | ||
bool ftmSuccess = true; | ||
|
||
// FTM report handler with the calculated data from the round trip | ||
void onFtmReport(arduino_event_t *event) { | ||
const char * status_str[5] = {"SUCCESS", "UNSUPPORTED", "CONF_REJECTED", "NO_RESPONSE", "FAIL"}; | ||
wifi_event_ftm_report_t * report = &event->event_info.wifi_ftm_report; | ||
// Set the global report status | ||
ftmSuccess = report->status == FTM_STATUS_SUCCESS; | ||
if (ftmSuccess) { | ||
// The estimated distance in meters may vary depending on some factors (see README file) | ||
Serial.printf("FTM Estimate: Distance: %.2f m, Return Time: %u ns\n", (float)report->dist_est / 100.0, report->rtt_est); | ||
// Pointer to FTM Report with multiple entries, should be freed after use | ||
free(report->ftm_report_data); | ||
} else { | ||
Serial.print("FTM Error: "); | ||
Serial.println(status_str[report->status]); | ||
} | ||
// Signal that report is received | ||
xSemaphoreGive(ftmSemaphore); | ||
} | ||
|
||
// Initiate FTM Session and wait for FTM Report | ||
bool getFtmReport(){ | ||
if(!WiFi.initiateFTM(FTM_FRAME_COUNT, FTM_BURST_PERIOD)){ | ||
Serial.println("FTM Error: Initiate Session Failed"); | ||
return false; | ||
} | ||
// Wait for signal that report is received and return true if status was success | ||
return xSemaphoreTake(ftmSemaphore, portMAX_DELAY) == pdPASS && ftmSuccess; | ||
} | ||
|
||
void setup() { | ||
Serial.begin(115200); | ||
|
||
// Create binary semaphore (initialized taken and can be taken/given from any thread/ISR) | ||
ftmSemaphore = xSemaphoreCreateBinary(); | ||
|
||
// Listen for FTM Report events | ||
WiFi.onEvent(onFtmReport, ARDUINO_EVENT_WIFI_FTM_REPORT); | ||
|
||
// Connect to AP that has FTM Enabled | ||
Serial.println("Connecting to FTM Responder"); | ||
WiFi.begin(WIFI_FTM_SSID, WIFI_FTM_PASS); | ||
while (WiFi.status() != WL_CONNECTED) { | ||
delay(500); | ||
Serial.print("."); | ||
} | ||
Serial.println(""); | ||
Serial.println("WiFi Connected"); | ||
|
||
Serial.print("Initiating FTM session with Frame Count "); | ||
Serial.print(FTM_FRAME_COUNT); | ||
Serial.print(" and Burst Period "); | ||
Serial.print(FTM_BURST_PERIOD * 100); | ||
Serial.println(" ms"); | ||
|
||
// Request FTM reports until one fails | ||
while(getFtmReport()); | ||
} | ||
|
||
void loop() { | ||
delay(1000); | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,110 @@ | ||
# Wi-Fi FTM Initiator Arduino Example | ||
|
||
This example demonstrates how to use the Fine Timing Measurement (FTM) to calculate the distace from the Access Point and the device. This is calculated by the Wi-Fi Round Trip Time (Wi-Fi RTT) introduced on the [IEEE Std 802.11-2016](https://en.wikipedia.org/wiki/IEEE_802.11mc) standard. | ||
|
||
This example was based on the [ESP-IDF FTM](https://github.com/espressif/esp-idf/tree/master/examples/wifi/ftm). See the README file for more details about on how to use this feature. | ||
|
||
Some usages for this feature includes: | ||
|
||
* Indoor positioning systems. | ||
* Navigation. | ||
* Device Location. | ||
* Smart Devices. | ||
* Alarms. | ||
|
||
# Supported Targets | ||
|
||
Currently, this example supports the following targets: | ||
|
||
| Supported Targets | ESP32-S2 | ESP32-C3 | | ||
| ----------------- | -------- | -------- | | ||
|
||
## How to Use Example | ||
|
||
In order to use the FTM, you will need a Responder or Wi-Fi router with FTM capabilities. If you don't own one, you can use a second ESP32-S2 or ESP32-C3 to simulate one. | ||
See the **Responder** example to prepare the environment. | ||
|
||
* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). | ||
|
||
### Configure the Project | ||
|
||
To configure this project, you can change the following configuration related to FTM feature: | ||
|
||
```c | ||
// Change the SSID and PASSWORD here if needed | ||
const char * WIFI_FTM_SSID = "WiFi_FTM_Responder"; // SSID of AP that has FTM Enabled | ||
const char * WIFI_FTM_PASS = "ftm_responder"; // STA Password | ||
|
||
// FTM settings | ||
// Number of FTM frames requested in terms of 4 or 8 bursts (allowed values - 0 (No pref), 16, 24, 32, 64) | ||
const uint8_t FTM_FRAME_COUNT = 16; | ||
// Requested time period between consecutive FTM bursts in 100’s of milliseconds (allowed values - 0 (No pref) or 2-255) | ||
const uint16_t FTM_BURST_PERIOD = 2; | ||
``` | ||
|
||
* Change the Wi-Fi `SSID` and `PASSWORD` as the same as the Responder/Router. | ||
* Change `FTM_FRAME_COUNT` with the number of frames requested to the Responder. | ||
* Change `FTM_BURST_PERIOD` with the time between each FTM burst. | ||
|
||
To see more details about FTM, please see the [ESP-IDF docs](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/network/esp_wifi.html). | ||
|
||
#### Using Arduino IDE | ||
|
||
To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). | ||
|
||
* Before Compile/Verify, select the correct board: `Tools -> Board`. | ||
* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. | ||
|
||
#### Using Platform IO | ||
|
||
* Select the COM port: `Devices` or setting the `upload_port` option on the `platformio.ini` file. | ||
|
||
## Log Output | ||
|
||
Expected log output: | ||
|
||
``` | ||
ESP-ROM:esp32s2-rc4-20191025 | ||
Build:Oct 25 2019 | ||
rst:0x1 (POWERON),boot:0x8 (SPI_FAST_FLASH_BOOT) | ||
SPIWP:0xee | ||
mode:DIO, clock div:1 | ||
load:0x3ffe6100,len:0x4b0 | ||
load:0x4004c000,len:0xa6c | ||
load:0x40050000,len:0x25c4 | ||
entry 0x4004c198 | ||
Connecting to FTM Responder | ||
..... | ||
WiFi Connected | ||
Initiating FTM session with Frame Count 16 and Burst Period 200 ms | ||
FTM Estimate: Distance: 0.13 m, Return Time: 0 ns | ||
FTM Estimate: Distance: 0.13 m, Return Time: 0 ns | ||
FTM Estimate: Distance: 0.13 m, Return Time: 0 ns | ||
FTM Estimate: Distance: 0.00 m, Return Time: 0 ns | ||
... | ||
``` | ||
|
||
## Troubleshooting | ||
|
||
***Important: Make sure you are using a good quality USB cable and that you have a reliable power source.*** | ||
|
||
* **Programming Fail:** If the programming/flash procedure fails, try reducing the serial connection speed. | ||
* **COM port not detected:** Check the USB cable and the USB to Serial driver installation. | ||
|
||
If the error persist, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute). | ||
|
||
## Contribute | ||
|
||
To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) | ||
|
||
If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! | ||
|
||
Before creating a new issue, be sure to try the Troubleshooting and to check if the same issue was already created by someone else. | ||
|
||
## Resources | ||
|
||
* Official ESP32 Forum: [Link](https://esp32.com) | ||
* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) | ||
* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) | ||
* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) | ||
* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com) |
23 changes: 23 additions & 0 deletions
23
libraries/WiFi/examples/FTM/FTM_Responder/FTM_Responder.ino
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
/* Wi-Fi FTM Responder Arduino Example | ||
This example code is in the Public Domain (or CC0 licensed, at your option.) | ||
Unless required by applicable law or agreed to in writing, this | ||
software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR | ||
CONDITIONS OF ANY KIND, either express or implied. | ||
*/ | ||
#include "WiFi.h" | ||
// Change the SSID and PASSWORD here if needed | ||
const char * WIFI_FTM_SSID = "WiFi_FTM_Responder"; | ||
const char * WIFI_FTM_PASS = "ftm_responder"; | ||
|
||
void setup() { | ||
Serial.begin(115200); | ||
Serial.println("Starting SoftAP with FTM Responder support"); | ||
// Enable AP with FTM support (last argument is 'true') | ||
WiFi.softAP(WIFI_FTM_SSID, WIFI_FTM_PASS, 1, 0, 4, true); | ||
} | ||
|
||
void loop() { | ||
delay(1000); | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,94 @@ | ||
# Wi-Fi FTM Responder Arduino Example | ||
|
||
This example demonstrates how to use the Fine Timing Measurement (FTM) to calculate the distace from the Access Point and the device. This is calculated by the Wi-Fi Round Trip Time (Wi-Fi RTT) introduced on the [IEEE Std 802.11-2016](https://en.wikipedia.org/wiki/IEEE_802.11mc) standard. | ||
|
||
This example will simulate the Router with FTM capability. | ||
|
||
This example was based on the [ESP-IDF FTM](https://github.com/espressif/esp-idf/tree/master/examples/wifi/ftm). See the README file for more details about on how to use this feature. | ||
|
||
Some usages for this feature includes: | ||
|
||
* Indoor positioning systems. | ||
* Navigation. | ||
* Device Location. | ||
* Smart Devices. | ||
* Alarms. | ||
|
||
# Supported Targets | ||
|
||
Currently, this example supports the following targets: | ||
|
||
| Supported Targets | ESP32-S2 | ESP32-C3 | | ||
| ----------------- | -------- | -------- | | ||
|
||
## How to Use Example | ||
|
||
See the **Initiator** example to prepare the environment. | ||
|
||
* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). | ||
|
||
### Configure the Project | ||
|
||
To configure this project, you can change the following configuration related to STA: | ||
|
||
```c | ||
// Change the SSID and PASSWORD here if needed | ||
const char * WIFI_FTM_SSID = "WiFi_FTM_Responder"; | ||
const char * WIFI_FTM_PASS = "ftm_responder"; | ||
``` | ||
|
||
* Change the Wi-Fi `SSID` and `PASSWORD` as the same as the Initiator. | ||
|
||
To see more details about FTM, please see the [ESP-IDF docs](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/network/esp_wifi.html). | ||
|
||
#### Using Arduino IDE | ||
|
||
To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). | ||
|
||
* Before Compile/Verify, select the correct board: `Tools -> Board`. | ||
* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. | ||
|
||
#### Using Platform IO | ||
|
||
* Select the COM port: `Devices` or setting the `upload_port` option on the `platformio.ini` file. | ||
|
||
## Log Output | ||
|
||
Expected log output: | ||
|
||
``` | ||
Build:Oct 25 2019 | ||
rst:0x1 (POWERON),boot:0x8 (SPI_FAST_FLASH_BOOT) | ||
SPIWP:0xee | ||
mode:DIO, clock div:1 | ||
load:0x3ffe6100,len:0x4b0 | ||
load:0x4004c000,len:0xa6c | ||
load:0x40050000,len:0x25c4 | ||
entry 0x4004c198 | ||
Starting SoftAP with FTM Responder support | ||
``` | ||
|
||
## Troubleshooting | ||
|
||
***Important: Make sure you are using a good quality USB cable and that you have a reliable power source.*** | ||
|
||
* **Programming Fail:** If the programming/flash procedure fails, try reducing the serial connection speed. | ||
* **COM port not detected:** Check the USB cable and the USB to Serial driver installation. | ||
|
||
If the error persist, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute). | ||
|
||
## Contribute | ||
|
||
To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) | ||
|
||
If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! | ||
|
||
Before creating a new issue, be sure to try the Troubleshooting and to check if the same issue was already created by someone else. | ||
|
||
## Resources | ||
|
||
* Official ESP32 Forum: [Link](https://esp32.com) | ||
* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) | ||
* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) | ||
* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) | ||
* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.