Injecting the configuration onto the device

To inject a configuration bundle onto the device, use the factory tool demo CLI tool inject command:

python ft_demo\sources\ft_demo.py [global options] inject [inject options] <serial|tcp|to_file> [transport options]

For more information about the inject command, see the factory tool demo CLI tool inject command documentation.

Using the Ethernet interface

1. For Mbed OS targets only:

   1. Connect to the device using an Ethernet cable (for injection) and a USB cable (if you want to use a serial terminal to monitor progress).
   2. Open the serial port monitor on the PC.
   3. Reset the device. After a few seconds, the device IP and port number show in the serial port monitor.

2. For native Linux targets only:

   1. Select an entropy source:

      export ENTROPYSOURCE=<file-name>
      

      The ENTROPYSOURCE environment variable is optional. If you do not set ENTROPYSOURCE, the application uses /dev/random.

      Note: The application must have permission to access the entropy source file selected above.

   2. Select the Ethernet interface name:

      export ETHERNET_LINUX_IFACE_NAME=<Ethernet interface name>
      

      Note: If you do not set the ETHERNET_LINUX_IFACE_NAME environment variable, the application uses the default interface on the build machine. Therefore, you must set this variable if you want to use an interface that is different from the default interface on the build machine.

   3. Run the application:

      ./factory-configurator-client-example.elf
      

3. Navigate to the root directory of FCU.

4. Run the appropriate inject command:

   Note: For the endpoint-name attribute, we recommend using only the characters a-z, A-Z,0-9, '+,-.:/= and SPACE. For more information, see endpoint name.

   • To use FCU as a certificate authority:

     python ft_demo\sources\ft_demo.py inject --endpoint-name=<device endpoint name> --serial-number=<device serial number> tcp --ip=<device IP> --port=<port number>
     

     For example:

     python ft_demo\sources\ft_demo.py inject --endpoint-name=<device endpoint name> --serial-number=111 tcp --ip=10.45.51.47 --port=7777
     

   • To use your own certificate authority:

     python ft_demo\sources\ft_demo.py inject --endpoint-name=<device endpoint name> --serial-number=<device serial number> --device-keys-location=<path to the folder with your resources> tcp --ip=<device IP> --port=<port number>
     

     For example:

     python ft_demo\sources\ft_demo.py inject --endpoint-name=<device endpoint name> --serial-number=111 --device-keys-location=C:\factory_configurator_utility\ft_demo\my_resources tcp --ip=10.45.51.47 --port=7777
     

   • To inject device-specific custom properties from a separate custom properties YAML file:

     python ft_demo\sources\ft_demo.py inject --endpoint-name=<device endpoint name> --serial-number=<device serial number> --device-config-file=<path to the device custom properties file, including file name> tcp --ip=<device IP> --port=<port number>
     

     For example:

     python ft_demo\sources\ft_demo.py inject --endpoint-name=<device endpoint name> --serial-number=111 --device-config-file=C:\factory_configurator_utility\ft_demo\custom_properties.yml tcp --ip=10.45.51.47 --port=7777
     

   • If you're using an ATECC608A secure element:

     python ft_demo\sources\ft_demo.py inject --serial-number=<device serial number> tcp --ip=<device IP> --port=<port number>
     

     For example:

     python ft_demo\sources\ft_demo.py inject --serial-number=111 tcp --ip=10.45.51.47 --port=7777
     

     Warning: FCU uses the endpoint_name value in generating a device certificate. If your device has pre-provisioned credentials, do not pass the endpoint_name attribute; otherwise, you will receive an error.

5. The injection process starts. The FCU console shows:

   status: 0
   message: "OPERATION COMPLETED SUCCESSFULLY"
   deviceResponse:
      status: 0
      message: "The Factory process succeeded"
   

   The expected last output message in the Serial port monitor is:

   Successfully processed comm message
   

Using the serial interface

1. Connect the device to the serial port using a USB cable.

2. Locate the device's COM port.

3. Navigate to the root directory of FCU.

4. Run the appropriate inject command:

   Note: For the endpoint-name attribute, we recommend using only the characters a-z, A-Z,0-9, '+,-.:/= and SPACE. For more information, see endpoint name.

   • To use FCU as a certificate authority:

     python ft_demo\sources\ft_demo.py -vvv inject --endpoint-name=<device endpoint name> --serial-number=<device serial number> serial --port=<COM port>
     

     For example:

     python ft_demo\sources\ft_demo.py -vvv inject --endpoint-name=<device endpoint name> --serial-number=111 serial --port=COM8
     

   • To use your own certificate authority:

     python ft_demo\sources\ft_demo.py -vvv inject --endpoint-name=<device endpoint name> --serial-number=<device serial number> --device-keys-location=<path to the folder with your resources> serial --port=<COM port>
     

     For example:

     python ft_demo\sources\ft_demo.py -vvv inject --endpoint-name=<device endpoint name> --serial-number=111 --device-keys-location=C:\factory_configurator_utility\ft_demo\my_resources serial --port=COM8
     

   • To inject device-specific custom properties from a separate custom properties YAML file:

     python ft_demo\sources\ft_demo.py -vvv inject --endpoint-name=<device endpoint name> --serial-number=<device serial number> --device-config-file=<path to the device custom properties file, including file name> serial --port=<COM port>
     

     For example:

     python ft_demo\sources\ft_demo.py -vvv inject --endpoint-name=<device endpoint name> --serial-number=111 --device-config-file=C:\factory_configurator_utility\ft_demo\custom_properties.yml serial --port=COM8
     

   • If you're using an ATECC608A secure element:

     python ft_demo\sources\ft_demo.py -vvv inject --serial-number=<device serial number> serial --port=<COM port>
     

     For example:

     python ft_demo\sources\ft_demo.py -vvv inject --serial-number=111 serial --port=COM8
     

     Warning: FCU uses the endpoint_name value in generating a device certificate. If your device has pre-provisioned credentials, do not pass the endpoint_name attribute; otherwise, you will receive an error.

5. The injection process starts.

   The expected last output message in the FCU console is:

   2020-09-16 11:54:00,251 INFO AUDIT: Initializing Factory Tool API Object: operation completed successfully
   2020-09-16 11:54:00,474 INFO AUDIT: Prepare Device Configuration: operation completed successfully ;SOME_EP: my_device - AID: some_aid
   2020-09-16 11:54:00,508 INFO AUDIT: Verify device response: operation completed successfully ;SOME_EP: my_device - AID: some_aid
   status: 0
   message: "OPERATION COMPLETED SUCCESSFULLY"
   deviceResponse:
      status: 0
      message: "The Factory process succeeded"
   

Writing device configuration to a file

Note: You cannot use the to_file option if you're working with device-generated keys.

1. Navigate to the root directory of FCU.

2. Run the appropriate inject command:

   Note: For the endpoint-name attribute, we recommend using only the characters a-z, A-Z,0-9, '+,-.:/= and SPACE. For more information, see endpoint name.

   • If you're using your own certificate authority:

     python ft_demo\sources\ft_demo.py -vvv inject --endpoint-name=<device endpoint name> --serial-number=<device serial number> --device-keys-location=<path to the folder with your resources> to_file --output-file=<file>
     

     For example:

     python ft_demo\sources\ft_demo.py -vvv inject --endpoint-name=<device endpoint name> --serial-number=111 --device-keys-location=C:\factory_configurator_utility\ft_demo\my_resources to_file --output-file=c:\fcu\config_bundle.bin
     

   • If you're using FCU as a certificate authority:

     python ft_demo\sources\ft_demo.py -vvv inject --endpoint-name=<device endpoint name> --serial-number=<device serial number> to_file --output-file=<file>
     

     For example:

     python ft_demo\sources\ft_demo.py -vvv inject --endpoint-name=<device endpoint name> --serial-number=111 to_file --output-file=c:\fcu\config_bundle.bin
     

   • To inject device-specific custom properties from a separate custom properties YAML file:

     python ft_demo\sources\ft_demo.py -vvv inject --endpoint-name=<device endpoint name> --serial-number=<device serial number> --device-config-file=<path to the device custom properties file, including file name> to_file --output-file=<file>
     

     For example:

     python ft_demo\sources\ft_demo.py -vvv inject --endpoint-name=123 --serial-number=111 --device-config-file=C:\factory_configurator_utility\ft_demo\custom_properties.yml to_file --output-file=c:\fcu\config_bundle.bin
     

   The expected last output message in the FCU console is:

   status: 0
   message: "OPERATION COMPLETED SUCCESSFULLY"
   

Disabling factory configuration after injection

You can pass the --factory-fcc-disable argument as part of the inject command to block the injection process on the device in the future.

Note: After you pass the --factory-fcc-disable argument as part of the inject command, you cannot inject the device again.

Where to go next

Your device is now provisioned and has permission to connect to your Device Management account.

You may want to run the full Device Management Client tutorials to see how to connect provisioned devices to the cloud.