ESP-IDF Provisioning - iOS

Table of Contents

• Introduction
• Setup
• Build
• Custom-Data Messages
• Resources

Introduction

ESP-IDF consists of a provisioning mechanism, which is used to provide network credentials and/or custom data to an ESP32 device. This repository contains the source code for the companion iOS app for this provisioning mechanism.

This repository also implements the sending of custom data to a peripheral device.

This is licensed under Apache 2.0. The complete license for the same can be found in the LICENSE file.

Setup

To build this app, you will need a macOS development machines, with XCode installed. Make sure you have a developer account with Apple setup. More about the same can be found here

Note: This fork implements a work-around so that a paid developer account is no longer necessary. However, make sure to adjust the signing (i.e., enter a unique identifier to automatically provision).

Install Dependencies

swiftformat

The app depends on swiftformat. To install the same, you will need brew. Brew can be installed from brew.sh. Once you have brew installed and setup, run -

brew install swiftformat

protoc-gen-swift

We use protobuf files across different platforms(C, iOS, Android, Python) to serialize the data to be sent. The source files are the same across all these platforms and can be found in the proto directory in the root folder of this repository.

To convert these files to swift, we need protoc-gen-swift. We depend on version 1.0.3 of the same. This is part of swift-protobuf project maintained by Apple Inc. This project consists of two things -

• a runtime library
• a command line utility

The runtime library is installed as part of the next section. In this section, we will install the protoc-gen-swift command line utility.

To install, run the following command -

brew install swift-protobuf

Next, confirm that the version that you have installed is greater than 1.1.1.

$ protoc-gen-swift --version
protoc-gen-swift 1.1.1

Note that this version need to match the version number of SwiftProtobuf in EspressifProvision/Podfile

Cocoapods

Make sure you have Cocoapods installed. Installation steps can be found on cocoapods.org
Now navigate to EspressifProvision directory from the root directory, and run -

pod install

This ensures that you have the following dependencies installed -

• SwiftProtobuf
• Curve25519

Build

There are multiple app variants that you can build using this repository. You will need to select the right variant from the following available ones -

XCode Project Scheme	Transport	Security Scheme	ESP-IDF Example	ESP-IDF Example menuconfig
WifiSec0 Debug	Wi-Fi	0	examples/provisioning/softap_prov	Example Configuration -> Deselect Use Security Version 1
WifiSec1 Debug	Wi-Fi	1	examples/provisioning/softap_prov	Example Configuration -> Select Use Security Version 1
BLESec0 Debug	BLE	0	examples/provisioning/ble_prov	Example Configuration -> Deselect Use Security Version 1
BLESec1 Debug	BLE	1	examples/provisioning/ble_prov	Example Configuration -> Select Use Security Version 1
BLESec1 Release	BLE	1	examples/provisioning/ble_prov	Example Configuration -> Select Use Security Version 1
WifiSec1 Release	Wi-Fi	1	examples/provisioning/softap_prov	Example Configuration -> Select Use Security Version 1

For Security 1, for BLE or Wi-Fi, you can set an optional Proof of Possession key. Make sure that the key present in Example Configuration -> Proof-of-possession under ESP-IDF example menuconfig is the same as the one set in Info.plist file in the ./EspressifProvision/EspressifProvision/ folder

Custom-Data Messages

With this forked repository, the user has freedom to send string and uint32 data via a custom message configuration.

Upon connecting to a device, the user has is prompted to perform the traditional provisioning (the initial purpose of this repository) or send Custom Data.

Selecting custom data allows the user to enter a key, str_data, and int_data and send a custom configuration to the peripheral device. If the device is configured to take-in the data (and given a valid key), a custom action can be performed.

Definitions

• key: Uint32 identifier that can be used by peripheral firmware to execute a specific action
• str_data: String data to be handled by the firmware (can be NULL)
• int_data: Uint32 data to be handled by the firmware (can be NULL)

Note: Both str_data and int_data can be NULL or contain values. The configuration message is meant to be flexible; the data is to be validated and manipulated on the firmware side.

Key Things to Consider

• Confirm the .proto configurations are the same (names, data-types, etc.) on both the iOS and firmware side to ensure correct data transformation
• Confirm the custom data is being sent to the correct endpoint on the firmware-side
• While the custom-data can be delivered using security1, the message is currently only supporting security0

Resources

• Documentation for the latest version: https://docs.espressif.com/projects/esp-idf/. This documentation is built from the docs directory of this repository.

• The esp32.com forum is a place to ask questions and find community resources.

• Check the Issues section on github if you find a bug or have a feature request. Please check existing Issues before opening a new one.

• If you're interested in contributing to ESP-IDF, please check the Contributions Guide.