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:

• The full list of factory tool demo error codes.
• The full list of factory configurator utility error codes.

Global options

Debug logs

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

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

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

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

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:

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:

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:

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"