Module Utility CLI Reference

This page outlines the commands and parameters available to use in the Module Utility Command Line Interface (CLI), version 4.0.6.0 or later. For installation instructions and general information about the tool, see the Module Utility CLI Quick Start.

Synopsis

java -jar ackmoduleutility.jar <command> <subcommand> <parameter> [global flag]

Available commands

Command Description
barcode Generates the barcode images used for product registration.
deviceinfo Prints the module's device serial number, firmware version, and public key.
listports Prints the available serial ports and their connection status.
lockmodule Locks the module as a product after product provisioning. For more information, see the Module Life Cycle Overview.
provision Provisions the module as a product. For more information, see the Module Life Cycle Overview.
reverttomoduleprovisioned Restores the module to a non-product-provisioned state.
updatemodule Updates the module firmware over the wire.
version Prints the Module Utility version number.

Global flags

These flags are available to all Module Utility CLI commands.

–help

Name

--help, -h

Description

Displays inline help.

–loglevel

Name

--loglevel

Description

Sets the log level of data output. If you don't specify a level, by default logs are generated at the error level. Logs are stored to your system's TEMP directory. Accepted arguments: off, info, warning, and error.

Command reference

The following are the commands available in the Module Utility CLI.

barcode

Name

barcode

Synopsis

barcode -p <port> [--includedsndevice] --out <output directory> --upc <upc>

Description

The barcode command generates the product and package QR files used for Wifi Simple Setup. For more information, see general guidance on barcode printing.

Two files each are generated for the package and product barcodes:

  • A .png image.
  • A file that contains a string associated with the QR code.

There are four files generated in total. The DVC_XXXXXXXXXXXXXXXX.png is the QR code that the customer scans in the Alexa app to register their product.

Required parameters

Parameter Description
-p,--port <port> The serial port that the ACK module is connected to.
--upc <upc> The universal product code (UPC) is a 12 digit numeric value assigned for the product by the manufacturer. The UPC is used on the product's outer packaging.

Optional parameters

</tr>
Parameter Description
[--includedsndevice] This adds a device serial number (DSN) value to the barcode.
[-o,--out <output directory>] The output directory for the barcode image files. If not specified, the current directory is used.

Example

Enter the following code into the terminal:

$ java -jar <path>/ackmoduleutility.jar barcode -p <port> --upc <upc>

The following output appears:

Barcode files successfully created in ./ directory.

deviceinfo

Name

deviceinfo

Synopsis

deviceinfo -p <port> [--dsn] [--firmwareversion] [--puk]

Description

This command returns the device serial number (DSN), public key, and firmware version of the module. Information can be retrieved in any order, or in any combination. If you don't include any parameters, all three are returned.

Required parameters

Parameter Description
-p,--port <port> The serial port that the ACK module is connected to.

Optional parameters

Parameter Description
[--dsn] Prints the module's device serial number (DSN).
[--firmwareversion] Prints the module's firmware version.
[--puk] Prints the public key for the module.

Example

Enter the following code into the terminal:

$ java -jar <path>ackmoduleutility.jar deviceinfo -p <port>

The following output appears:

DSN : G3T0WEXXXXXXXXXX
Firmware version : 3.211107020.build1906080404
PUK : MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADQcEZFlFdfR9L/Cnfd1jJ53+zywDFl4eEyuVxBFxYad8=

listports

Name

listports

Synopsis

listports

Description

Lists the available serial ports on your computer and their current connection status.

Example

The listports command shows the available serial ports, and their connection statuses. This is a helpful command because --port is a required parameter for many of the Module Utility CLI commands.

Enter the following code into the terminal:

$ java -jar <path>/ackmoduleutility.jar listports

The following output appears:

Select the tab that corresponds to your operating system.

Serial ports available:
/dev/tty.usbserial-DO01FW9A (inUse: true)
/dev/cu.BoseRevolveSoundLink-SP (inUse: true)
/dev/tty.BoseRevolveSoundLink-SP (inUse: true)
/dev/tty.Bluetooth-Incoming-Port (inUse: false)
/dev/cu.Bluetooth-Incoming-Port (inUse: false)
/dev/cu.usbserial-DO01FW9A (inUse: true)
Serial ports available:
/dev/tty.usbserial-DO01FW9A (inUse: true)
/dev/cu.BoseRevolveSoundLink-SP (inUse: true)
/dev/tty.BoseRevolveSoundLink-SP (inUse: true)
/dev/tty.Bluetooth-Incoming-Port (inUse: false)
/dev/cu.Bluetooth-Incoming-Port (inUse: false)
/dev/cu.usbserial-DO01FW9A (inUse: true)
COM12 (inUse: true)
COM3 (inUse: false)

lockmodule

Name

lockmodule

Synopsis

lockmodule -p <port> [--noprompt]

Description

Locks a module as a specific virtual product, such as a microwave.

Required parameters

Parameter Description
-p,--port <port> The serial port that the ACK module is connected to.

Optional parameters

Parameter Description
[--noprompt] Locks the module without user confirmation.

Example

Enter the following code into the terminal:

$ java -jar <path>/ackmoduleutility.jar lockmodule -p <port>

provision

Name

provision

Synopsis

provision provides two different methods for provisioning. ACK managed service provisioning is the recommended method.

ACK managed services (default)

provision -p <port> {--provisionconfigfile <path> | [-d <DeviceType ID>] [-i <Simple Setup ID value>] [--simplesetupztskey <Simple Setup ZTS key value>]}

YubiKey-based

provision -p <port> {--provisionconfigfile <path> | [-d <DeviceType ID>] [-i <Simple Setup ID value>] [--simplesetupztskey <Simple Setup ZTS key value>]} --yubikeypinfile <path>/ [--yubikeyslot <Yubikey slot number>]

Description

The provision command changes the module state to product provisioned, and generates device certificates used for authorization and registration with Alexa. For information about provisioning, see the Module Life Cycle Overview.

This command provides two different methods for provisioning:

  • ACK managed services (default) – This is the default method for provision. For this method, device certificates are generated by ACK managed services and stored to the module's memory. For step-by-step instructions, see Steps to Provision a Module – ACK managed services.

  • YubiKey-based – This method relies on relies on device certificates stored on a YubiKey hardware security module, provided by Amazon. Contact your Amazon business representative to use this method. For more information, see Steps to Provision a Module – YubiKey.

Required parameters

ACK managed services (default)

These are the required parameters for the default ACK managed service method:

Parameter Description
-p,--port <port> The serial port that the ACK module is connected to.
{--provisionconfigfile <path>/ProvisioningInfo_[devicetypeid].conf | [-d,--devicetype <device type>] [-i,--simplesetupid <simple setup ID>] [--simplesetupztskey <simple setup ZTS key>]} --provisionconfigfile <path>/ProvisioningInfo_[devicetypeid].conf – The path to the provisioning configuration file downloaded from the ACK Console. You can either use a configuration file, or manually specify the following arguments.

-d,--devicetype – A randomly generated string that corresponds to a unique device type. This corresponds to the DeviceType identified in the configuration file.

-i,--simplesetupid – A string that is used for Wifi Simple Setup (WSS). See Understand Wifi Simple Setup for more information about WSS.

--simplesetupztskey – A string that is used from Zero-Touch Setup (ZTS). See Zero-Touch Setup for more information about ZTS.

Yubi-key based

These are the required parameters for the YubiKey-based method:

Parameter Description
-p,--port <port> The serial port that the ACK module is connected to.
--provisionconfigfile <path>/ProvisioningInfo_[devicetypeid].conf The path to the provisioning configuration file for the product. The provisioning file is downloaded from the ACK Console.
You can either use the configuration file as an argument, or manually specify the --devicetype, --simplesetupztskey, and --simplesetupztskey parameters.
--yubikeypinfile <path>/YubiKeyPin.txt The path to the YubiKeyPin.txt file that contains the YubiKey pin.

Optional parameters

Yubi-key based

These are the optional parameters for the YubiKey-based method:

Parameter Description
[--yubikeyslot <YubiKey slot number>] The YubiKey smart card slot number. Accepted value: integer. For Windows, you must specify the slot number if your YubiKey slot is different that your platform's default. The default for Windows is 0. For Ubuntu 18.04 and later, the parameter must always be specified. For Ubuntu 16.04 or earlier, the default is 1. To locate the slot number, see Use the OpenSC tool to identify the YubiKey slot number.

Example

ACK managed services

To provision a module with ACK managed services, enter the following code into the terminal:

$ java -jar <path>/ackmoduleutility.jar  provision  -p <port> --provisionconfigfile <path>/ProvisioningInfo_[devicetypeid].conf

If the module is already provisioned as a product, you'll see a message like The module is already provisioned as product AZCQX0BWIKW8F. Reprovision? Y/N. In this case, choose *Y to reprovision the module.

Alternatively, you can omit the configuration file and manually specify the --devicetype, --simplesetupid, and --simplesetupztskey. For example:

$ java -jar <path>/ackmoduleutility.jar  provision  -p <port> --devicetype <device type ID> --simplesetupid <simple setup ZTS key> --simplesetupztskey <simple setup ZTS key>]

The following output appears:

java -jar ackmoduleutility.jar provision -p /dev/tty.usbserial-XXXXXX --provisionconfigfile /Users/<username>/Downloads/ProvisioningInfo.conf
Device provisioning beginning for device type AZCQXXXXXXXX...
Setting device information
Authorization is required. Your web browser should open the "Login with Amazon" page to the following link, please login with your Amazon developer credentials associated with device type AZCQXXXXXXXX. https://devicesigner.amazon.com/v1/authn?state=eBMxweDVK4bTojmFeHcXsQ-o2Oa1gelBSNOL9oSau6tIVWTrcpLGGvIbUKaY0AoNGE
Waiting for you to login using "Login with Amazon"  |
Login detected, sending request for device certificate to the ACK service...
Device certificate request was successful and device certificate has been provided to ACK module utility.
Device provisioning continuing...
Device provisioning successful

Yubi-key based

Enter the following code into the terminal:

$ java -jar <path>/ackmoduleutility.jar  provision --yubikeypinfile <path>/YubiKeyPin.txt --provisionconfigfile <path>/ProvisioningInfo_[devicetypeid].conf -p <port>

The following output appears:

Device Provisioning Beginning...
Setting device information
Connecting to YubiKey
Setting certificates
Device Provisioning Successful

reverttomoduleprovisioned

Name

reverttomoduleprovisioned

Synopsis

reverttomoduleprovisioned -p <port>

Description

reverttomoduleprovisioned reverts a module from a product provisioned state to a module provisioned state. For more information about module states, see Understand Module States.

Required parameters

Parameter Description
-p,--port <port> The serial port that the ACK module is connected to.

Example

To revert the ACK Module from a product provisioned state to a module provisioned state, enter the following code into the terminal: :

$ java -jar <path>/ackmoduleutility.jar reverttomoduleprovisioned -p <port>

The following output appears:

Verifying module is provisioned as a product.
Revert to module provisioned in progress.
Verifying module reverted.
Revert to module provisioned successful.

updatemodule

Name

updatemodule

Synopsis

updatemodule [--fallback] -p <port> --updatefile <file path>

Description

Updates a module over the wire with a new firmware package from Amazon, which you can download from the ACK Console Resources.

Required parameters

Parameter Description
-p,--port <port> The serial port that the ACK module is connected to.
--updatefile <file path> The path to the firmware update file.

Optional parameters

Parameter Description
[--fallback] For firmware versions earlier than v211091120. This is a deprecated process for updating the module; use only if directed by Amazon.

Example

Enter the following code into the terminal:

$ java -jar <path>/ackmoduleutility.jar updatemodule -p <port> --updatefile <file path>

version

Name

version

Synopsis

version

Description

Displays the current version of the ACK Module Utility.

Example

Enter the following code into the terminal:

$ java -jar <path>/ackmoduleutility.jar version

The following output appears:

Version: 4.0.2.0