Mistake on this page? Email us

Using the factory tool demo CLI commands

This section is a full reference for the factory tool demo. It allows you to tailor the demo to your factory setup.

Tip: We have an end-to-end tutorial of the demo.

Command structure

The factory tool demo's basic command structure is:

python ft_demo\sources\ft_demo.py [global options] <specific command> [command options]

For example:

python ft_demo\sources\ft_demo.py --config-file=sample-config.yml setup

Command exit codes

A successful command exits with code 0 and a validation warning list.

The exit status in the event of failure is non-zero. For more information, see:

Global options

Debug logs

You can write debug logs to either a file or a standard error:

Option Explanation
-v, --verbose An option available for all commands for extra verbosity.
--log-file=<filename> The path to the factory tool demo log file.

Log file

The functionality of writing factory tool demo logs to a file uses log rotation, and retains up to 10 MB of logs.

Log level for the debug log file

You can configure the level of information that is included in the debug log file. The default log level for the debug log file is ERROR.

For verbose log output, pass the -v or --verbose flags. To increase verbosity, pass the -vv flag. For example:

python ft_demo\sources\ft_demo.py -v --log-file app_debug.log ...
python ft_demo\sources\ft_demo.py -vv --log-file app_debug.log ...
# or, combined with debug log
python ft_demo\sources\ft_demo.py --verbose --log-file app_debug.log  ...

Configuration file path

Option Explanation
-c, --config-file=<filename> The path to the FCU configuration file. The default path is <FCU Home>\config\fcu.yml.

The setup command - setting up FCU as a certificate authority (CA)

The setup command sets up certificate authorities for the demo, including:

  • FCU as the demo's CA.
  • Any additional CAs that you set up to sign custom-generated keys.

The setup command creates a private key and matching certificate for each CA that you configure.

For intermediate CAs in a certificate chain, the setup command creates a certificate signing request (CSR). After your CA signs the CSR, provide the full certificate chain to FCU.

The setup command wraps the fcu.FactoryToolApi object's setup_factory_configurator_utility method. For more information about the setup_factory_configurator_utility API, see Integrating FCU with your factory tool.

Note: Make sure to set up the FCU configuration file correctly before running the setup command. For more information, see Configuring FCU and Provisioning information.

Run the setup command as follows:

python ft_demo\sources\ft_demo.py [global options] setup [setup options]

Setup options

Options Required or optional Explanation
-f, --force Optional Overrides all existing CA keys and certificates.
-s, --skip-existing Optional Skip all existing CA keys and certificates and generate keys and certificates for newly configured CAs only.

When the setup completes, you'll get a message indicating success or failure and the path to the generated certificate or CSR.

If FCU is a CA or you create a certificate chain using FCU is an intermediate CA, you must upload the certificate, or the certificate chain generated by signing the CSR, to the portal.

Setup status

To check the CA setup status, use setup status:

python ft_demo\sources\ft_demo.py --config-file=sample-config.yml setup status

The command returns the setup status and the paths to the CA private key and certificate or CSR.

Examples

setup status:
status: 0
ca details:
 - keystore_dir: C:\factory_configurator_utility\keystore
 - certificate_file: C:\factory_configurator_utility\keystore\fcu.crt
 - private_key_file: C:\factory_configurator_utility\keystore\fcu_private_key.pem
errors:
warnings:

When FCU is an intermediate CA (the setup-ca-as-intermediate parameter in the FCU configuration file is true):

setup status:
status: 0
ca details:
 - keystore_dir: C:\factory_configurator_utility\keystore
 - certificate_file: C:\factory_configurator_utility\keystore\fcu.crt
 - csr_file: C:\factory_configurator_utility\keystore\fcu_csr.pem
 - private_key_file: C:\factory_configurator_utility\keystore\fcu_private_key.pem
errors:
warnings:

When an additional certificate authority is configured (the setup-ca-as-intermediate parameter in the additional certificate authorities section is false):

setup status:
status: 0
ca details:
 - keystore_dir: C:\factory_configurator_utility\keystore
 - certificate_file: C:\factory_configurator_utility\keystore\fcu.crt
 - csr_file: C:\factory_configurator_utility\keystore\fcu_csr.pem
 - private_key_file: C:\factory_configurator_utility\keystore\fcu_private_key.pem
additional ca details:
    ca-name-example:
       - keystore_dir: C:\dev\factory\keystore\ca-name-example
       - certificate_file: C:\dev\factory\keystore\ca-name-example\ca_cert.crt
       - private_key_file: C:\dev\factory\keystore\ca-name-example\ca_private_key.pem
errors:
warnings:

The inject command

The inject command calls FCU to aggregate device configuration and then calls the factory tool to inject the device configuration to the device and verify the device result.

The basic structure of the inject command is:

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

The inject command uses the fcu.FactoryToolApi object's prepare_device_configuration method to configure the device, and the verify_device_response method to check whether the configuration was applied properly to the device. For more information about these methods, see FCU API references and Integrating FCU with your factory tool.

Inject options

Options Required or optional Explanation
--endpoint-name=<device endpoint name> Required This parameter is later used to access the device.
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.
--serial-number=<device serial number> Required This parameter is used to generate the LwM2M device object.
--device-keys-location=<path to device keys> Required when device-key-generation-mode or entropy-generation-mode is externally_supplied; otherwise, ignored. <path to device keys> is the path to look up device-specific files that contain your DTLS private key and certificate pairs, and/or entropy file. You can use the environment variable DEVICE_KEYS_LOCATION instead.
--factory-fcc-disable Optional Sets a flag that disables the factory configuration client (FCC) on an IoT device. You should only set this once you have completed provisioning information on the device, as this flag disables the inject process.
--device-config-file <path to YAML file> Optional <path to YAML file> is the path, including the file name, to the YAML file that defines the device-specific custom properties. If the device-specific custom properties YAML file contains a property with the same name and type as exists in the fcu.yml FCU configuration file, FCU injects the device-specific custom property.

Transport options

Factory tool demo can inject data using one of these transport mechanisms:

Injecting over a serial connection

To inject data over a serial connection, use serial with the following options:

Options Required or optional Explanation
--port=<serial port> Required The serial port to send to. Default: COM1.
-b, --baud=<baud rate> Required The baud rate for serial port communication. Default: 115200.
-t, --connection-timeout=<timeout in seconds> Required Serial connection timeout in seconds. Default: 10.

Example:

$ python ft_demo\sources\ft_demo.py
    --config-file=\local\arm\mbed\factory-configurator\config.yml
    inject
    --serial-number=SOME-SN
    --endpoint-name=EP-some-device-endpoint
    --device-keys-location=\local\arm\mbed\factory-configurator\per-device-resources\com2
    serial --port=COM2

Injecting over a TCP connection

To inject data over a TCP connection, use tcp with the following options:

Options Required or optional Explanation
--ip=<IP address> Required The IP address for TCP communication.
--port=<port number> Required The TCP port number to send to. Default: 7777.
-t, --connection-timeout=<timeout in seconds> Required TCP connection timeout in seconds. Default: 30.

Example:

$ python ft_demo\sources\ft_demo.py
    -vv
    --log-file=\tmp\log\tmp-execution.log
    --config-file=\local\arm\mbed\factory-configurator\config.yml
    inject
    --serial-number=SOME-OTHER-SN
    --endpoint-name=EP_some_other_device_endpoint
    --device-keys-location=\local\arm\mbed\factory-configurator\per-device-resources\ip-159
    tcp --ip=10.10.10.159

Writing device configuration to a file

To write device configuration to a file, use to_file with the following options:

Options Required or optional Explanation
--output-file=<path and name of the output file to be created> Required The path in which to create the device configuration output file.

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

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

Command output

Exit codes:

  • 0 on success.
  • Non-zero on failure of any sort. See error codes for details.

Information output:

  • Debug and log messages are printed to the command standard error.
  • Execution result is printed to the standard output as YAML:
definitions:
  statusInfo:
    type: integer
  messageText:
    type: string
  errorInfo:
    type: object
    properties:
      message:
        type: string
      error_code:
        type: integer
  errorInfoList:
    type: array
    items:
      "$ref": "#\definitions\errorInfo"
  warningInfoList:
    type: array
    items:
      type: string
  enrollmentIdText:
  	type: string
  deviceResponseStatus:
    properties:
      status:
        "$ref": "#/definitions/statusInfo"
      message:
        "$ref": "#/definitions/messageText"
      errors:
        "$ref": "#/definitions/errorInfoList"
      warnings:
        "$ref": "#/definitions/warningInfoList"
    type: object
    required:
    - status
    - message
properties:
  status:
    "$ref": "#/definitions/statusInfo"
  message:
    "$ref": "#/definitions/messageText"
  enrollment_id:
    "$ref": "#/definitions/enrollmentIdText"  
  deviceResponse:
    "$ref": "#/definitions/deviceResponseStatus"
type: object
required:
- status
- message

Response for a successful inject:

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

Response for a successful inject with first-to-claim mode:

status: 0
message: "OPERATION COMPLETED SUCCESSFULLY"
enrollment_id: A-F1:37:F5:36:08:45:F2:30:BE:77:C5:25:6D:B1:2A:DC:CF:58:E5:45:2A:C9:FC:82:C6:41:88:69:9B:BE:39:01
deviceResponse:
  status: 0
  message: "The Factory process succeeded"

Response for a successful inject including validation warning:

status: 0
message: "OPERATION COMPLETED SUCCESSFULLY (with warnings)"
warning_list:
- "Validation notice number 201 in field: UseBootstrap. 'No Bootstrap Mode' was selected"
deviceResponse:
  status: 0
  message: "The Factory process succeeded"
  warnings:
  - "Bootstrap mode not activated:mbed.UseBootstrap"

Sample error from the device:

status: 1004
message: "Execution failed on device with error #14"
deviceResponse:
  status: 14
  message: "File operation general error:mbed.BootstrapDeviceCert"
  errors:
  - error_code: 14
    message: "File operation general error:mbed.BootstrapDeviceCert"

Sample error from the demo tool (before injection):

status: 1003
message: "Timeout waiting for device token"

Sample device configuration validation error from the demo tool's injection to file:

status: 400
message: "Validation error in FCU configuration file"
error_list:
- "Validation notice number 1035 in field: device-info.manufacturer-name. Null value not allowed"