feat(gfps_service): Add Google Fast Pair Service (#161)

* feat(gfps_service): Add Google Fast Pair Service
* Add google/nearby submodule under external folder
* Add gfps_service component implementing the device specific google/nearby support as well as a wrapper service for GFPS
* Add gfps_service example
* Update and rebuild docs (and clean up some extraneous files)
* Update CI

* rebuild docs

* readme: update

Author: finger563

Diff for: .github/workflows/build.yml

@@ -55,6 +55,8 @@ jobs:
           target: esp32
         - path: 'components/ft5x06/example'
           target: esp32s3
+        - path: 'components/gfps_service/example'
+          target: esp32s3
         - path: 'components/gt911/example'
           target: esp32s3
         - path: 'components/hid-rp/example'

Diff for: .gitmodules

@@ -34,3 +34,6 @@
 [submodule "external/hid-rp"]
 	path = external/hid-rp
 	url = https://github.com/intergatedcircuits/hid-rp
+[submodule "external/nearby"]
+	path = external/nearby
+	url = [email protected]:google/nearby

Diff for: components/gfps_service/CMakeLists.txt

@@ -0,0 +1,17 @@
+idf_component_register(
+  INCLUDE_DIRS "../../external/nearby/embedded/client/source" "../../external/nearby/embedded/common/source" "../../external/nearby/embedded/common/target" "include"
+  SRC_DIRS "../../external/nearby/embedded/client/source" "../../external/nearby/embedded/common/source" "../../external/nearby/embedded/common/source/mbedtls" "src"
+  REQUIRES "esp_hw_support" "esp-nimble-cpp" "mbedtls" "nvs_flash" "logger" "task" "timer" "base_component"
+)
+add_definitions(-DNEARBY_TRACE_LEVEL=6) # log levels are VERBOSE=1, DEBUG, INFO, WARN, ERROR, OFF=6
+add_definitions(-DNEARBY_PLATFORM_USE_MBEDTLS=1)
+add_definitions(-DNEARBY_FP_ENABLE_BATTERY_NOTIFICATION=0)
+add_definitions(-DNEARBY_FP_ENABLE_ADDITIONAL_DATA=0)
+add_definitions(-DNEARBY_FP_MESSAGE_STREAM=0)
+# add_definitions(-DNEARBY_PLATFORM_HAS_SE)
+# add_definitions(-DNEARBY_FP_HAVE_BLE_ADDRESS_ROTATION=0)
+# add_definitions(-DNEARBY_FP_ENABLE_SASS=0) # smart audio source switching
+add_definitions(-DNEARBY_FP_RETROACTIVE_PAIRING=1) # not sure what this is...
+add_definitions(-DNEARBY_FP_BLE_ONLY=1)
+add_definitions(-DNEARBY_FP_PREFER_BLE_BONDING=1)
+add_definitions(-DNEARBY_FP_PREFER_LE_TRANSPORT=1)

Diff for: components/gfps_service/Kconfig.projbuild

@@ -0,0 +1,13 @@
+menu "GFPS Configuration"
+    config GFPS_MODEL_ID
+        hex "GFPS Model ID"
+        default 0x0
+        help
+            Set the model id (24 bit) used for Google Fast Pair Service (GFPS)
+
+    config GFPS_ANTISPOOFING_PRIVATE_KEY
+        string "GFPS Anti-Spoofing Private Key"
+        default ""
+        help
+            Set the GFPS anti-spoofing private key, as a base64 uncompressed string.
+endmenu

Diff for: components/gfps_service/example/CMakeLists.txt

@@ -0,0 +1,22 @@
+# The following lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+
+
+# add the component directories that we want to use
+set(EXTRA_COMPONENT_DIRS
+  "../../../components/"
+)
+
+set(
+  COMPONENTS
+  "main esptool_py ble_gatt_server gfps_service"
+  CACHE STRING
+  "List of components to include"
+  )
+
+project(gfps_service_example)
+
+set(CMAKE_CXX_STANDARD 20)

Diff for: components/gfps_service/example/README.md

@@ -0,0 +1,35 @@
+# Google Fast Pair Service (GFPS) Service Example
+
+This example shows how to use the `espp::GfpsService` class together with the
+`espp::BleGattServer` class to create and manage a BLE GATT server that provides
+support for Google Fast Pair Service (GFPS) using the
+[nearby/embedded](https://github.com/google/nearby) framework.
+
+NOTE: this example uses a pre-registered device. If you want to register your
+own device(s), you must do that on the [nearby/devices
+dashboard](https://developers.google.com/nearby/devices).
+
+## How to use example
+
+### Hardware Required
+
+This example should run on any ESP32s3 development board as it requires no
+peripheral connections.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(Replace PORT with the name of the serial port to use.)
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+![CleanShot 2024-02-29 at 09 51 07](https://github.com/esp-cpp/espp/assets/213467/dbd44440-56dd-4a61-8448-9a1e4543d73b)

Diff for: components/gfps_service/example/main/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRC_DIRS "."
+                       INCLUDE_DIRS ".")

Diff for: components/gfps_service/example/main/gfps_service_example.cpp

@@ -0,0 +1,91 @@
+#include <chrono>
+#include <vector>
+
+#include "ble_gatt_server.hpp"
+#include "gfps_service.hpp"
+
+using namespace std::chrono_literals;
+
+extern "C" void app_main(void) {
+  espp::Logger logger({.tag = "Gfps Service Example", .level = espp::Logger::Verbosity::INFO});
+  logger.info("Starting");
+
+  //! [gfps service example]
+
+  // NOTE: esp-nimble-cpp already depends on nvs_flash and initializes
+  //       nvs_flash in the NimBLEDevice::init(), so we don't have to do that
+  //       to store bonding info
+
+  // create the GATT server
+  espp::BleGattServer ble_gatt_server;
+  std::string device_name = "ESP++ GFPS Example";
+  ble_gatt_server.set_log_level(espp::Logger::Verbosity::INFO);
+  ble_gatt_server.set_callbacks({
+      .connect_callback = [&](NimBLEConnInfo &conn_info) { logger.info("Device connected"); },
+      .disconnect_callback = [&](NimBLEConnInfo &conn_info) { logger.info("Device disconnected"); },
+      .authentication_complete_callback =
+          [&](NimBLEConnInfo &conn_info) { logger.info("Device authenticated"); },
+  });
+  ble_gatt_server.init(device_name);
+  ble_gatt_server.set_advertise_on_disconnect(true);
+
+  // let's create a GFPS service
+  espp::GfpsService gfps_service;
+  gfps_service.init(ble_gatt_server.server());
+
+  // now that we've made the input characteristic, we can start the service
+  gfps_service.start();
+  ble_gatt_server.start_services(); // starts the device info service and battery service
+  // NOTE: we could also directly start them ourselves if we wanted to
+  //      control the order of starting the services
+  // e.g.:
+  // ble_gatt_server.battery_service().start();
+  // ble_gatt_server.device_info_service().start();
+
+  // now start the gatt server
+  ble_gatt_server.start();
+
+  // let's set some of the service data
+  auto &battery_service = ble_gatt_server.battery_service();
+  battery_service.set_battery_level(99);
+
+  auto &device_info_service = ble_gatt_server.device_info_service();
+  uint8_t vendor_source = 0x02; // USB
+  uint16_t vid = 0x045E;        // Microsoft
+  uint16_t pid = 0x02FD;        // Xbox One Controller
+  uint16_t product_version = 0x0100;
+  device_info_service.set_pnp_id(vendor_source, vid, pid, product_version);
+  device_info_service.set_manufacturer_name("ESP-CPP");
+  // NOTE: this is NOT required to be the same as the GFPS SKU Name
+  device_info_service.set_model_number("espp-gfps-01");
+  device_info_service.set_serial_number("1234567890");
+  device_info_service.set_software_version("1.0.0");
+  device_info_service.set_firmware_version("1.0.0");
+  device_info_service.set_hardware_version("1.0.0");
+
+  // now lets start advertising
+  espp::BleGattServer::AdvertisingData adv_data = {
+      .name = device_name,
+      .appearance = 0x03C4, // Gamepad
+      .services = {},
+      .service_data =
+          {// these are the service data that we want to advertise
+           {gfps_service.uuid(), gfps_service.get_service_data()}},
+  };
+  espp::BleGattServer::AdvertisingParameters adv_params = {};
+  ble_gatt_server.start_advertising(adv_data, adv_params);
+
+  // now lets update the battery level every second
+  uint8_t battery_level = 99;
+  while (true) {
+    auto start = std::chrono::steady_clock::now();
+
+    // update the battery level
+    battery_service.set_battery_level(battery_level);
+    battery_level = (battery_level % 100) + 1;
+
+    // sleep
+    std::this_thread::sleep_until(start + 1s);
+  }
+  //! [gfps service example]
+}

Diff for: components/gfps_service/example/partitions.csv

@@ -0,0 +1,5 @@
+# Name,   Type, SubType, Offset,  Size
+nvs,      data, nvs,     0x9000,  0x6000
+phy_init, data, phy,     0xf000,  0x1000
+factory,  app,  factory, 0x10000, 2M
+littlefs, data, spiffs,         , 1M

Diff for: components/gfps_service/example/sdkconfig.defaults

@@ -0,0 +1,41 @@
+CONFIG_IDF_TARGET="esp32s3"
+
+# on the ESP32S3, which has native USB, we need to set the console so that the
+# CLI can be configured correctly:
+CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y
+
+# Common ESP-related
+#
+CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE=4096
+CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192
+
+CONFIG_FREERTOS_HZ=1000
+
+CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
+
+#
+# BT config
+#
+CONFIG_BT_ENABLED=y
+CONFIG_BT_BLUEDROID_ENABLED=n
+CONFIG_BT_NIMBLE_ENABLED=y
+CONFIG_BT_NIMBLE_LOG_LEVEL_NONE=y
+CONFIG_BT_NIMBLE_NVS_PERSIST=y
+CONFIG_BT_NIMBLE_GAP_DEVICE_NAME_MAX_LEN=100
+CONFIG_BT_NIMBLE_HOST_TASK_STACK_SIZE=8192
+
+# NOTE: we can support extended advertising (longer advertisement packets) by
+#       enabling the following:
+# CONFIG_BT_NIMBLE_EXT_ADV=y
+#
+#   HOWEVER: we don't currently support this as the API to ble_gatt_server will
+#            need to support this compile-time definition.
+
+# Set the default Tx power level (P9 = +9dBm = the default)
+# CONFIG_BT_CTRL_DFT_TX_POWER_LEVEL_P9=y
+
+# Support modem sleep (low power mode)
+# CONFIG_BT_CTRL_MODEM_SLEEP=y
+
+# Set the ESP-NIMBLE-CPP Config
+CONFIG_NIMBLE_CPP_LOG_LEVEL_NONE=y

Diff for: components/gfps_service/include/gfps.hpp

@@ -0,0 +1,137 @@
+#pragma once
+
+#include <chrono>
+#include <cstdint>
+#include <functional>
+#include <vector>
+
+#include <sdkconfig.h>
+
+#include <esp_mac.h>
+#include <esp_random.h>
+#include <nvs_flash.h>
+
+#include "nearby_fp_client.h"
+#include "nearby_fp_library.h"
+#include "nearby_platform_audio.h"
+#include "nearby_platform_battery.h"
+#include "nearby_platform_ble.h"
+#include "nearby_platform_bt.h"
+#include "nearby_platform_os.h"
+#include "nearby_platform_persistence.h"
+#include "nearby_platform_se.h"
+#include "nearby_platform_trace.h"
+
+#include "freertos/FreeRTOS.h"
+#include "freertos/semphr.h"
+#include "freertos/task.h"
+
+#include "logger.hpp"
+#include "task.hpp"
+#include "timer.hpp"
+
+#if CONFIG_BT_NIMBLE_ENABLED
+#include "NimBLEDevice.h"
+#endif
+
+namespace espp {
+namespace gfps {
+
+/// Function which GFPS will call to send notifications to the remote device
+/// @param characteristic The characteristic to notify
+/// @param data The data to send
+/// @param length The length of the data
+typedef std::function<bool(nearby_fp_Characteristic, const uint8_t *, size_t)> notify_callback_t;
+
+/// Configuration for the Google Fast Pair Service
+struct Config {
+  notify_callback_t notify; ///< Callback to enable gfps to notify the remote device of changes
+};
+
+/// Initialize the Google Fast Pair Service
+/// @param config The configuration for the service
+void init(const Config &config);
+
+/// Deinitialize the Google Fast Pair Service
+void deinit();
+
+/// Get the GFPS model ID
+uint32_t get_model_id();
+
+/// Set the remote public key
+/// @param public_key The public key
+void set_remote_public_key(const std::vector<uint8_t> &public_key);
+
+/// Set the remote public key
+/// @param public_key The public key
+/// @param length The length of the public key
+void set_remote_public_key(const uint8_t *public_key, size_t length);
+
+/// Get the remote public key
+/// @return The remote public key
+std::vector<uint8_t> get_remote_public_key();
+
+/// Get the underlying GFPS BLE interface
+const nearby_platform_BleInterface *get_ble_interface();
+
+/// Get the underlying GFPS BT interface
+const nearby_platform_BtInterface *get_bt_interface();
+
+#if CONFIG_BT_NIMBLE_ENABLED || defined(_DOXYGEN_)
+int ble_gap_event_handler(ble_gap_event *event, void *arg);
+#endif // CONFIG_BT_NIMBLE_ENABLED || defined(_DOXYGEN_)
+
+} // namespace gfps
+} // namespace espp
+
+#if CONFIG_BT_NIMBLE_ENABLED || defined(_DOXYGEN_)
+// for printing of BLE_GAP_EVENT_ using libfmt
+template <> struct fmt::formatter<ble_gap_event> {
+  constexpr auto parse(format_parse_context &ctx) { return ctx.begin(); }
+
+  template <typename FormatContext> auto format(const ble_gap_event &event, FormatContext &ctx) {
+    switch (event.type) {
+    case BLE_GAP_EVENT_CONNECT:
+      return fmt::format_to(ctx.out(), "BLE_GAP_EVENT_CONNECT");
+    case BLE_GAP_EVENT_DISCONNECT:
+      return fmt::format_to(ctx.out(), "BLE_GAP_EVENT_DISCONNECT");
+    case BLE_GAP_EVENT_CONN_UPDATE:
+      return fmt::format_to(ctx.out(), "BLE_GAP_EVENT_CONN_UPDATE");
+    case BLE_GAP_EVENT_ENC_CHANGE:
+      return fmt::format_to(ctx.out(), "BLE_GAP_EVENT_ENC_CHANGE");
+    case BLE_GAP_EVENT_PASSKEY_ACTION:
+      return fmt::format_to(ctx.out(), "BLE_GAP_EVENT_PASSKEY_ACTION");
+    case BLE_GAP_EVENT_SUBSCRIBE:
+      return fmt::format_to(ctx.out(), "BLE_GAP_EVENT_SUBSCRIBE");
+    case BLE_GAP_EVENT_MTU:
+      return fmt::format_to(ctx.out(), "BLE_GAP_EVENT_MTU");
+    case BLE_GAP_EVENT_REPEAT_PAIRING:
+      return fmt::format_to(ctx.out(), "BLE_GAP_EVENT_REPEAT_PAIRING");
+    default:
+      return fmt::format_to(ctx.out(), "BLE_GAP_EVENT_UNKNOWN ({})", (int)event.type);
+    }
+  }
+};
+#endif // CONFIG_BT_NIMBLE_ENABLED || defined(_DOXYGEN_)
+
+// for pritning of nearby_fp_Characteristic using libfmt
+template <> struct fmt::formatter<nearby_fp_Characteristic> {
+  constexpr auto parse(format_parse_context &ctx) { return ctx.begin(); }
+
+  template <typename FormatContext>
+  auto format(const nearby_fp_Characteristic &characteristic, FormatContext &ctx) {
+    switch (characteristic) {
+    case kModelId:
+      return fmt::format_to(ctx.out(), "kModelId");
+    case kKeyBasedPairing:
+      return fmt::format_to(ctx.out(), "kKeyBasedPairing");
+    case kPasskey:
+      return fmt::format_to(ctx.out(), "kPasskey");
+    case kAccountKey:
+      return fmt::format_to(ctx.out(), "kAccountKey");
+    default:
+      return fmt::format_to(ctx.out(), "nearby_fp_Characteristic_UNKNOWN ({})",
+                            (int)characteristic);
+    }
+  }
+};