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.

The following code illustrates the syntax of the Module Utility CLI.

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

barcode

The barcode command generates the product and package QR files for your product. The customer uses the barcode when they set up your device with Wifi Simple Setup. For details, 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.

Syntax

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

Parameters

Parameter Description Required
--port, -p <port> The serial port that the ACK module is connected to. Yes
--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. Yes
--includedsndevice This adds a device serial number (DSN) value to the barcode. No
--out, -o <output directory> The output directory for the barcode image files. If not specified, the current directory is used. No
--loglevel Set the type of messages to log. Logs are stored to your system's TEMP directory. Valid values are off, info, warning, and error. The default is error. No
--help, -h Display help for the command. No

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

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.

Syntax

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

Parameters

Parameter Description Required
--port, -p <port> The serial port that the ACK module is connected to. Yes
--dsn Prints the module's device serial number (DSN). No
--firmwareversion Prints the module's firmware version. No
--puk Prints the public key for the module. No
--loglevel Set the type of messages to log. Logs are stored to your system's TEMP directory. Valid values are off, info, warning, and error. The default is error. No
--help, -h Display help for the command. No

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

The listports command shows the available serial ports on your computer, and their connection statuses. Use this command before other commands that require a --port parameter.

Syntax

listports

Parameters

Parameter Description Required
--loglevel Set the type of messages to log. Logs are stored to your system's TEMP directory. Valid values are off, info, warning, and error. The default is error. No
--help, -h Display help for the command. No

Example

Select the tab that corresponds to your operating system.

Enter the following code into the terminal:

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

The following output appears:

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)

Enter the following code into the terminal:

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

The following output appears:

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)

Enter the following code into the terminal:

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

The following output appears:

COM12 (inUse: true)
COM3 (inUse: false)

lockmodule

The lockmodule command locks your module as a specific virtual product, such as a microwave. For details, see Module Life Cycle.

Syntax

lockmodule --port <port> [--noprompt]

Parameters

Parameter Description Required
--port, -p <port> The serial port that the ACK module is connected to. Yes
--noprompt Locks the module without user confirmation. No
--loglevel Set the type of messages to log. Logs are stored to your system's TEMP directory. Valid values are off, info, warning, and error. The default is error. No
--help, -h Display help for the command. No

Example

Enter the following code into the terminal:

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

provision

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

provision (ACK managed services)

When you provision by using ACK managed services, device certificates are generated by ACK managed services and stored to the module's memory. For step-by-step instructions, see Provision Your Module.

This is the default method for provision. Unless you are ready to start manufacturing your product, use this method.

Syntax

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

Parameters

Parameter Description Required
--port, -p <port> The serial port that the ACK module is connected to. Yes
--provisionconfigfile <path>/ProvisioningInfo_[devicetypeid].conf The path to the provisioning configuration file. You download the provisioning file from the ACK developer console. You must specify either --provisionconfigfile, or all of --devicetype, --simplesetupid, and --simplesetupztskey.
--devicetype, -d <device type ID> A randomly generated string that corresponds to a unique device type. You must specify either --provisionconfigfile, or all of --devicetype, --simplesetupid, and --simplesetupztskey.
--simplesetupid, -i <simple setup ZTS key> A string that's used for Wifi Simple Setup. You must specify either --provisionconfigfile, or all of --devicetype, --simplesetupid, and --simplesetupztskey.
--simplesetupztskey <simple setup ZTS key> A string that's used for Zero-Touch Setup. You must specify either --provisionconfigfile, or all of --devicetype, --simplesetupid, and --simplesetupztskey.
--loglevel Set the type of messages to log. Logs are stored to your system's TEMP directory. Valid values are off, info, warning, and error. The default is error. No
--help, -h Display help for the command. No

Example

To provision a module by using 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, a message like The module is already provisioned as product AZCQX0BWIKW8F. Reprovision? Y/N appears. In this case, choose Y to provision the module again.

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

provision (Yubikey)

Provision by using a YubiKey when you are ready to start manufacturing your product. 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 step-by-step instructions, see Provision Your Module with a YubiKey.

Syntax

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>]

Parameters

Parameter Description Required
--port, -p <port> The serial port that the ACK module is connected to. Yes
--provisionconfigfile <path>/ProvisioningInfo_[devicetypeid].conf The path to the provisioning configuration file. You download the provisioning file from the ACK developer console. You must specify either --provisionconfigfile, or all of --devicetype, --simplesetupid, and --simplesetupztskey.
--devicetype, -d <device type ID> A randomly generated string that corresponds to a unique device type. You must specify either --provisionconfigfile, or all of --devicetype, --simplesetupid, and --simplesetupztskey.
--simplesetupid, -i <simple setup ID> A string that is used for Wifi Simple Setup. You must specify either --provisionconfigfile, or all of --devicetype, --simplesetupid, and --simplesetupztskey.
--simplesetupztskey <simple setup ZTS key> A string that is used for Zero-Touch Setup. You must specify either --provisionconfigfile, or all of --devicetype, --simplesetupid, and --simplesetupztskey.
--yubikeypinfile <path>/YubiKeyPin.txt The path to the file that contains the YubiKey pin. The file is named YubiKeyPin.txt. Yes
--yubikeyslot <slot number> The YubiKey smart card slot number, as an integer. For Windows, specify the slot number if your YubiKey slot is different than 0. For Ubuntu 16.04 or earlier, specify the slot number if your YubiKey slot is different than 1. For Ubuntu 18.04 and later, always specify the slot number. To locate the slot number, see Identify the YubiKey slot number. No
--loglevel Set the type of messages to log. Logs are stored to your system's TEMP directory. Valid values are off, info, warning, and error. The default is error. No
--help, -h Display help for the command. No

Example

Enter the following code into the terminal:

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

The following output appears:

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

reverttomoduleprovisioned

The reverttomoduleprovisioned command reverts a module from a product provisioned state to a module provisioned state. For details, see Module Life Cycle.

Syntax

reverttomoduleprovisioned --port <port>

Parameters

Parameter Description Required
--port, -p <port> The serial port that the ACK module is connected to. Yes
--loglevel Set the type of messages to log. Logs are stored to your system's TEMP directory. Valid values are off, info, warning, and error. The default is error. No
--help, -h Display help for the command. No

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 --port <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

The updatemodule command updates a module over the wire with a new firmware package from Amazon. Download firmware packages from the Resources page of the ACK developer console.

Syntax

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

Parameters

Parameter Description Required
-p,--port <port> The serial port that the ACK module is connected to. Yes
--updatefile <file path> The path to the firmware update file. Yes
--fallback For firmware versions earlier than v211091120. This is a deprecated process for updating the module; use only if directed by Amazon. No
--loglevel Set the type of messages to log. Logs are stored to your system's TEMP directory. Valid values are off, info, warning, and error. The default is error. No
--help, -h Display help for the command. No

Example

Enter the following code into the terminal:

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

version

The version command displays the current version of the ACK Module Utility.

Syntax

version

Parameters

Parameter Description Required
--loglevel Set the type of messages to log. Logs are stored to your system's TEMP directory. Valid values are off, info, warning, and error. The default is error. No
--help, -h Display help for the command. No

Example

Enter the following code into the terminal:

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

Output similar to the following appears:

Version: 4.0.2.0