TLSR827x Find My Network Accessories SDK Developer Handbook

---

SDK Introduction

Telink Find My Network Accessories SDK is an application solution based on Apple Find My Network ADK, and it has passed Apple Find My Network Self-Certification Test Cases certification tests. Users can develop FMN Accessory products with complete functionality using this SDK. Currently, Telink TLSR9 and 827X series chips have implemented the Find My Network Accessories (FMNA) solution. This chapter will introduce the Find My Network Accessories SDK scheme based on the 827X chip in detail.

SDK organizational structure

File structure

After importing the Telink Find My Network Accessories SDK into the IDE, the displayed file organization structure is as shown in the following figure (using telink_b87_fmn_sdk as an example). There are 10 top-level folders: algorithm, application, boot, common, crypto, drivers, proj_lib, stack, UARPDK, and vendor.

algorithm: Provides some common algorithms, such as aes_ccm. Most of the corresponding C files for these algorithms are encapsulated in the library files, leaving only the corresponding header files.

application: Provides some common application processing programs, such as print, keyboard, etc.

boot: Provides the software bootloader for MCU, which is the assembly processing program that runs after the MCU is powered on or wakes up from deep sleep, preparing for the execution of subsequent C programs.

common: Provides some common cross-platform handling functions, such as memory handling functions, string handling functions, etc.

crypto: Includes the open-source third-party mbedtls standard algorithm library and provides the implementation of cryptographic interfaces and sample tests in the FMN ADK.

drivers: Provides MCU peripheral driver programs such as Clock, Flash, I2C, USB, GPIO, UART, etc.

proj_lib: Stores the necessary library files for the operation of the SDK. Files such as the BLE protocol stack, RF driver, PM driver, etc., are encapsulated within the library files.

stack: Stores the header files related to the BLE protocol stack. The source files are compiled into the library files and are not visible to the user.

UARPDK: It is used for the underlying logic implementation of the FMN UARP feature.

vendor: Stores demo code or user's own code.

The vendor directory contains 3 projects: b85m_demo, b85m_feature, and b85m_slave. Currently the FMN feature is only supported on b85m_slave. The vendor directory also contains the common, platform folders.

main.c

The main.c file contains the main function and interrupt handling functions. The main function is the entry point of the program and includes the necessary configuration for the system to work properly. Considering the power consumption when the program enters deep retention, it is recommended that users do not modify it. The interrupt handling function serves as the entry function when the system triggers an interrupt.

app_config.h

This is the user configuration file used to configure various parameters of the entire system (such as BLE parameters, GPIO configuration, low power enable/disable, encryption enable/disable, etc.).

In the subsequent introduction of SDK configuration, detailed explanations of the meanings of each parameter in app_config.h will be provided.

Application files

app.c: It is used to complete BLE system initialization, event/data processing, low power handling, FMNA initialization, main loop processing, and so on.

app_att.c: Provides GATT service table and profile. The GATT service table already includes standard GATT services, standard GAP services, and FMNA-related services. Users can refer to these and add their own services and profiles.

app_ui.c: Mainly provides keystroke functions.

app_buffer.c: It is used to define the buffers used by each layer of the stack, e.g., Link Layer TX & RX buffer, L2CAP layer MTU TX & RX buffer, HCI TX & RX buffer, etc.

app_opt.c: It is used for CPU wake-up initialization, rf drv initialization, etc.

battery_check.c: It is used for battery level detection and low battery handling.

FMNA files

fmna_adv.c: It is used for setting the content of FMNA broadcast packets.

fmna_akm_platform.c: It is used for store and restore of fmna key.

fmna_config_control_point.c: It is used for setting FMNA related parameters and status, controlling audio play/stop, and issuing commands for unpairing and other interactions.

fmna_connection.c: It is used for switching, querying, judging the connection and disconnection status of FMNA, as well as handling the logic for unpairing.

fmna_crypto.c: It is used for initializing FMNA crypto, handling data processing in the pairing process, generating FMNA keys, and managing the logic for serial number processing.

fmna_debug_control_point.c: It is used for parameter settings and log retrieval of FMNA devices in debug mode through the FMCA tool app.

fmna_gatt.c: FMNA interacts with write request and indicate operations through BLE GATT, implemented by callback functions, and so on.

fmna_motion_detection.c: The processing implementation of motion detection in the separated state of FMNA devices, and so on.

fmna_nfc.c: It is used for NFC initialization, obtaining and updating NFC URL keys, and so on.

fmna_nonowner_control_point.c: It is used for non-owner control of FMNA devices, such as playing and stopping sounds.

fmna_paired_owner_control_point.c: It is used for owners to retrieve the current primary key, iCloud ID, serial number, and other information from FMNA devices.

fmna_pairing_control_point.c: It is used for FMNA devices to process pairing commands.

fmna_state_machine.c: It is used for logic implementation of the state machine, including handling events such as boot, pair, separated, nearby, connecting, FMNA pair, FMNA pair complete, connected, disconnecting, etc.

fmna_version.c: It is used for initialization and retrieval of FMNA version.

./UARP/fmna_uarp_control_point.c: It is used for UARP initialization, connection, disconnection, packet handling, and so on.

./UARP/FMNASampleUARP.c: It is used for FMNA sample initialization, controller addition/removal, message sending/receiving, buffer malloc/free, querying firmware information, firmware storage, and so on.

platform files

fmna_adv_platform.c: It is used for implementing FMNA to set the broadcast content for three states: FMNA Pair, Separated, and Nearby.

fmna_battery_platform.c: It is used for obtaining the battery level.

fmna_connection_platform.c: It is used for active disconnection, requesting sec info, obtaining serial number, and storing token in flash memory, etc.

fmna_gatt_platform.c: It is used for implementing the indicate logic in FMNA.

fmna_malloc_platform.c: It is used for implementing the malloc and free functionality.

fmna_motion_detection_platform.c: It is used for hardware simulation to implement motion detection functionality.

fmna_sound_platform.c: It is used for hardware simulation to implement sound play and stop functionality.

common files

app_sched.c: It is used for implementation solutions for event schedulers.

blt_common.c: It is used for setting up the MAC address for Bluetooth devices.

blt_fw_sign.c: It is used for firmware signature verification.

blt_led.c: the LED control logic based on hardware implementation.

blt_soft_timer.c: It is used for the implementation of software timers.

common_dbg.c: It is used for hardware debug serial port initialization in low-power mode.

custom_pair.c: It is used for binding device information processing, MAC address management, etc.

device_manage.c: It is used for management of connection device information (e.g. connection handle, attribute handle, BLE device address, address type, etc.).

flash_fw_check.c: It is used for firmware crc check.

nfc.c: It is used for nfc function implementation.

simple_sdp.c: It is used for implementation of the SDP (Service Discovery Protocol) function for Master.

tl_audio.c: It is used for data format conversion for audio devices.

BLE stack entry

The BLE interrupt handling entry function is blc_sdk_irq_handler().

The BLE logic and data processing entry function is blc_sdk_main_loop(), which is responsible for processing data and events related to the BLE stack.

Software bootloader introduction

In Telink FMN SDK, different types of MCU correspond to different bootloader files. The bootloader file is stored in the boot folder. Telink FMN SDK bootloader file is composed of two parts, link file and cstartup.S assembly file.

Bootloader files

The bootloader file for the Telink FMN SDK is shown below:

There are two link files in Telink FMN SDK, boot.link (supports suspend mode) and boot_32k_retn.link (supports suspend mode and deep sleep retention mode).

Note:

• The link file that actually takes effect when compiling the project is b85m_ble_sdk/boot.link.
• Telink FMN SDK only supports boot_32k_retn.link and the content of b85m_ble_sdk/boot/boot_32k_retn.link has been copied to b85m_ble_sdk/boot.link by default.

The cstartup.S file in the Telink FMN SDK varies depending on the size of the SRAM resources of the chip. There are two cstartup.S files for each type of MCU, 'RET_32K' means that it supports deep sleep retention 32K mode. 8273 and 8278 both have 64 KB SRAM, so their cstartup.S files are exactly the same, unified with the 8278 configuration.

Note:

The Telink FMN SDK only supports RET_32K mode.

Take 827x_slave and MCU selects 8278 as an example, the method of cstartup.S file corresponding to user setting is as follows:

Find the file "cstartup_8278_RET_32K.S" under the boot/8278 folder, find the macro MCU_STARTUP_8278_RET_32K in the file, and then configure it in the project's property setting window as shown in the following figure.

Library introduction

The library corresponding to the Telink FMN SDK configuration project is shown below.

Note:

The Telink FMN SDK currently only supports the library of liblt_8278_m0s4.a.

SDK Configuration

SDK project compilation configuration

SDK project compilation configuration: 827x_slave.

Flash configuration

Flash configuration: the default support is 1MB flash (can be reduced to 512KB flash).

RAM configuration

RAM configuration: 64KB of RAM, including 32KB of Deep Retention RAM.

Multi-connection mode

Multi-connection mode: default supports 0 master + 2 slave connections.

SMP configuration

SMP configuration: SMP enabled by default, SMP level: just work.

PM configuration

PM configuration: PM enabled and supports deepsleep_retention.

LED configuration

LED configuration: enabled by default, used for LED switching action to simulate the sound play, stop function of FMNA.

Software timer configuration

Software timer configuration: enabled by default, need to support FMNA multiple timer settings, currently supports up to 16 timer tasks.

Debug function

Debug function: disabled by default, but must be enabled only when using the tool APP FMCA to do test case test.

Motion detection configuration

Motion detection configuration: enabled by default, use GPIO high and low level to simulate motion action.

NFC function

NFC function: optional configuration, 8278 does not support NFC function at present due to the limited resources of retention RAM.

UARP function

UARP function: supported by default, need to use the tool APP FMCA to do test case to verify the firmware upgrade function.

Low power detection function

Low power detection function: supported by default, need to stop broadcasting and turn off the machine when the power is lower than the set threshold.

Low power detection GPIO configuration

Event scheduling configuration

Event scheduling configuration: Maximum support for processing 4 events and 8 queue buffers.

UART debug function

a. UART debug function configuration: enable macro UART_PRINT_DEBUG_ENABLE to turn on the serial port log printing function.

b. UART parameter settings: support 1Mbps baud rate, GPIO port is set to PB0.

c. UARP debug function configuration: Enable UART_PRINT_DEBUG_ENABLE, then disable UARP_DISABLE_LOGS and UARP_DISABLE_REQUIRE_LOG to enable the debug UARP function.

System main frequency configuration

System main frequency configuration: support 12M, 16M, 24M, 32M, 48M, with unit of Hz, it is recommended that users use the default value of 32M, too small value will affect the algorithm running speed, too large value will affect the low power consumption.

DLE and MTU settings

DLE and MTU settings: the default value of DLE is 200 and the default value of MTU is 200.

RF power setting

RF power setting: the default configuration is 4dBm as required by the FMN protocol.

SDK flash layout

a. Mac address: 0xFF000, size of 8 bytes. The frequency offset address: 0xFE000, size set according to user's requirement (512 bytes range).

b. SMP pairing key: 0xF2000 - 0xF5000, size of 16KB, normal pairing uses the first 8KB, too many pairing times will use the next 8KB backup area.

c. Telink FMN function related data storage

• Primary key address: 0xF7000 - 0xF8000, size of 8KB, 0xF8000 just work as the backup area of primary key.

• secondary key address: 0xF6000, size of 4KB.

• software auth uuid address: 0xF9000, size of 16 bytes.

• software auth Token address: 0xF9010, size of 1040 bytes.

• icloud id address: 0xF9600, size of 60 bytes.

• M_P key address: 0xFA000, size of 57 bytes.

• Shared secret key address: 0xFA100, size of 32 bytes.

• Current separated key address: 0xFB000, size of 28 bytes.

SDK Function

FMN profile

Accessory information service

Service uuid: 87290102-3C51-43B1-A1A9-11B9DC38478B

Characteristics uuid: 6AA5XXXX-6352-4D57-A7B4-003A416FBB0B

Find My network service

Service uuid: 0xFD44

Characteristics uuid: 4F86XXXX-943B-49EF-BED4-2F730304427A

Firmware update service

Service uuid: 0xFD43

Characteristics uuid: 94110001-6D9B-4225-A4F1-6A4A7F01B0DE

Processing logic of pairing command

FMNA_SERVICE_OPCODE_INITIATE_PAIRING

Since the retention RAM is not enough, the device receives the initiating pairing command, disables the deep retention function to ensure that the contents of all variables remain unchanged during the pairing process, and reads the token from the flash for pairing.

FMNA_SERVICE_OPCODE_FINALIZE_PAIRING

It is used to verify and confirm pairing to apple device (contains steps such as accessory verify S2, decrypt E3, generate C3, generate E4, send pairing status to owner device).

FMNA_SERVICE_OPCODE_PAIRING_COMPLETE

Calculate the primary key and secondary key, and start the key rotate timer to generate the key at regular intervals, and enable the deep retention function after the pairing is completed to reduce the power consumption.

Sound play and stop for object location

Processing logic of play and stop command by owner control

Processing logic of play and stop command by non-owner control

Sound play and stop

The sound play and stop processing is simulated by LED light on and off for demonstration, users need to realize this function.

Motion detection function

Start motion detection

Motion detection method

Demonstration of motion detect is simulated through the GPIO interface, which is required by the user to implement this feature.

Processing logic after motion detected

After judging the number of motion detections exceeds 10 times, it switches to backoff mode detection; if it does not exceed 10 times, it enters backoff mode detection after a 20-second timeout.

Switch to backoff mode

Unwanted tracking detection

The Unwanted tracking detection feature is used to notify the user of the existence of an unrecognized accessory that may be following the movement, and the user can find this accessory by playing a sound via Bluetooth control.

UARP firmware upgrade

UARP interface initialization

Processing of UARP packets receiving

Since the retention RAM is not enough, the device turns off the deep retention function after receiving the first packet to ensure that the contents of all variables remain unchanged during the firmware upgrade process, and the packet is received to do group packet (append) processing of the data.

Processing of UARP appended packets

Clear the data reception buffer when processing of the data after appended packets is completed.

Write UARP append data to flash

When the firmware data is received, every 512 bytes received will be written to flash. As the program runs to the position of writing the first data, it means that the firmware version and other information has been confirmed to be correct and can be upgraded. At this time, in order to ensure the speed of firmware upgrading and normal execution, the program will turn off sleep and not to enter sleep. Therefore, the function of deep retention is restored here to prevent the program from entering deep retention when the OTA is abnormal.

UARP response

After the data is processed, a response is sent to the owner device.

Restart after UARP firmware received

Execute restart after firmware data receiving is complete.

SDK Module

mbedtls algorithm library

It is a set of open source algorithm library, implements encryption algorithms, X.509 certificate operation, and SSL/TLS and DTLS protocols, and provides the reference implementation of the PSA encryption API specification. Telink FMN SDK used in the sha256 (hash calculation), ANSI x9.63 KDF (key calculation generation), NIST P-224 elliptic curve (elliptic curve point calculation and verification), ECDSA/ECDH (signature verification), AES-128-GCM (encryption and decryption) and other algorithms.

fm-crypto function interface

The FMN application layer mainly uses the interfaces of the fm-crypto.c file (as shown in the figure below) to call the mbedtls algorithm library, in order to achieve functionalities such as pairing, encryption/decryption, signature verification, key generation, and hash calculation.

State machine

FMN state machine

The accessory operations can be described using a state machine, and the transitions performed between them are based on the logic of the interaction of the accessory with the owner device.

FMN unpaired event handlers

Unpaired: the accessory must be in the unpaired state after the first power-up startup or before accessory pairing is complete. In this state, the accessory must treat the Find My network service as a primary service in the connectable broadcast package. The user initiates pairing at the owner device and thereafter the accessory enters the pairing process.

FMN connection and pairing

Connected: after successfully pairing with the owner device, the accessory must enter the connected state. Once the pairing is complete, the owner device may disconnect from the accessory. Once paired, the accessory cannot be paired with any other Apple device. It must remain paired until it successfully completes the unpairing process with the owner device. The accessory must re-enter the connected state from either the nearby or separated state, or when the owner device connects. The accessory can simultaneously connect to two Apple devices on the same iCloud account. The motion detection and unwanted tracking detection protocols are not available in the connected state. When the accessory enters the connected state, the broadcast payload should be set to the nearby key. If link encryption is not completed within 10 seconds, the paired accessory must disconnect.

Note:

The pairing process is also part of the connected state machine.

FMN nearby

Nearby: the accessory must enter the nearby state immediately after disconnecting the owner device. The accessory remains in the nearby state for a set period of time (default 15 minutes). The Motion detection and unwanted tracking detection protocols are not available in the nearby state. When the accessory enters this state, the broadcast payload should be set to the nearby key.

FMN separated

Separated锛歍he accessory enters the separated state under 2 conditions: 1. the accessory has been paired and started from reset, power up and reinitialization. 2. the accessory enters the separated state after a timeout in the nearby state. The motion detection and unwanted tracking detection protocols are available in the separated state. When the accessory enters the separated state, the broadcast payload should be set to the primary or secondary key.

SDK Flow

Pairing flow chart

Pairing process

Generate pairing data: After the Bluetooth connection is paired, accessory will generate C1 in the pairing data and start the pairing process after receiving the initiating pairing data sent by the owner device, and then generate the key seed (SeedK1) for each pairing session, which is then encrypted by the input parameters (SessionNonce, Software auth token, Software auth UUID, Serial Number, Product Data, FW Version, E1, SeedK1) are encrypted by the encryption key (Q_E) to generate E2 in the pairing data.

Note:

The accessory must regenerate SeedK1 for each pairing task.

Send pairing data:The accessory sends the pairing data generated in the previous step (containing C1 and E2) via ble indicate.

Finalize pairing:The owner device sends finalize pairing data to the accessory and initiates the final pairing process to complete the pairing.

Validate and confirm pairing:The accessory analyzes the finalize pairing data, verifies the signature (S2) in the finalize pairing data using the signing verification key (Q_A), decrypts E3 in the finalize pairing data to obtain the new token issued by the Apple server. It then generates C3 in the pairing status based on C2 in the finalize pairing data. The accessory assembles and encrypts the new token along with other parameters (Software auth UUID, Serial Number, SessionNonce, E1, Status) to generate E4 in the pairing status. Finally, the accessory saves the new token to flash for use in the next pairing process.

Send pairing status: The accessory sends the pairing status (containing C3 and E4) generated in the previous step through the BLE indication interface. The owner device receives the pairing status to confirm whether the previously issued new token has been successfully received by the accessory, thereby determining the success of the pairing process.

Pairing complete:The owner confirms the successful pairing and issues a "pairing complete" to the accessory. The accessory will set the paired flag and enter the nearby state, then generate Primary and secondary keys and start the key rotation timer to initiate the iteration of Primary and secondary keys.