Texas Instruments Matter Factory Data Programming User Guide#

This document describes how to use the factory data programming feature for Matter example applications from Texas Instruments.

Background#

The Matter specification lists various information elements that are programmed at the factory. These values do not change and some are unique per device. This feature enables customers developing Matter products on TI devices to program this data and use this as a starting point towards developing their factory programming infrastructure for their Matter devices.

Solution Overview:#

TI Matter examples allow the use of factory data in the following two ways:

Example Out of Box Factory Data : Use TI example DAC values to get started. This is intended to be used when just starting with Matter or during development until customer or product specific data is not required.
Custom factory data : Allows users to configure custom factory data via a JSON file. The custom values are then processed by a script provided by TI and merged with the Matter application to create a binary that can be flashed on to devices.

Solution Block Diagram#

Block Diagram

Each element is described in more detail below:

Factory Data JSON: This file is located at src/platform/cc13xx_26xx. Developers can configure this per device. Elements in this file are from the specification.
Matter Application with dummy factory data: Any TI Matter example application
MCUBoot: MCUBoot image used for OTA. This is built with the Matter application and does not require additional build steps from developers.
create_factory_data.py: Processes a factory data JSON file and generates a hex file with the unique factory data values configured in the JSON file.
factory_data_trim.py: When using the custom factory data option, this script removes the dummy factory data which is required to be able to successfully compile the application.
oad_and_factory_data_merge_tool.py: Merges the factory data hex, Matter application without factory data and MCUBoot image to generate a functional hex that can be programmed onto the device.

Flash memory layout#

Memory Layout 2

How to use#

Out of box factory data location is configured to be on second last page of flash. For CC13x4, the starting address is 0xFE800. This can be configured in the linker file.

To configure:

Linker file: Set the start address for factory data in the linker file being used by the application

FLASH_FACTORY_DATA (R)  : ORIGIN = 0x000fe800, LENGTH = 0x00000900

/* Define base address for the DAC arrays and struct */
    PROVIDE (_factory_data_base_address =
        DEFINED(_factory_data_base_address) ? _factory_data_base_address : 0xFE800);

create_factory_data.py: Set the address of the start of the factory data elements. Refer to the comments in the script.

    # there are 17 elements, each element will need 8 bytes in the struct
    # 4 for length of the element, and 4 for the pointer to the element
    # factory data starts at 0xFE800, so the elements will
    # start 136 bytes after the start address
    factory_data_dict = json.load(args.factory_data_json_file[0])
    factory_data_schema = json.load(args.factory_data_schema[0])

    validate(factory_data_dict, factory_data_schema)
    factory_data = factory_data_dict['elements']

    struct_idx = 0
    values_idx = 0
    value_address = 0xFE888

   subprocess.call(['objcopy', 'temp.bin','--input-target','binary','--output-target', 'ihex', args.factory_data_hex_file, '--change-addresses=0xfe800'])

In the example’s args.gni file, set ‘custom_factory_data’ to true

It is recommended to keep 2 dedicated pages for CC13x4 for factory data.

Formatting certs and keys for JSON file#

To format the DAC, private key and PAI as hex strings as shown in the Factory Data JSON file, use the chip-cert tool located at src/tools/chip-cert and run the convert-cert command, and list -X, or X.509 DER hex encoded format, as the output format. These strings can then be copied into the JSON file.

The SPAKE parameters should be converted from base-64 to hex as well before being copied into the JSON file.

Creating images#

The example application can be built using the instructions in the example’s README. The factory data from the JSON file will be formatted into a hex file that will then be merged into the final executable. The final executable will be named {example-application}-mcuboot.hex for CC13x4, and the factory data that was inputted into the JSON file will be named {example-application}-factory-data.hex.

Texas Instruments Matter Factory Data Programming User Guide

Contents