Module Utility CLI Reference

The Alexa Connect Kit (ACK) Module Utility Command Line Interface (CLI) provides commands and options for managing ACK products.

For installation instructions and general information about the tool, see the Module Utility CLI Quick Start.

Command reference

You can run the Module Utility CLI from the command line or use the CLI within scripts. To run the Module Utility CLI, use the following syntax:

$ java -jar ackmoduleutility.jar <command> <subcommand> <option> [global flag]
Command Description

barcode

Generates the product and package QR files for your product.
The customer uses the barcode when they connect your device with Wi-Fi Simple Setup. For details, see general guidance on barcode printing.

deviceinfo

Gets the device serial number (DSN), public key, and firmware version of the module.

listports

Displays the available serial ports on your computer, and their connection statuses.

lockmodule

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

provision

Changes the module state to product provisioned, and generates device certificates used for authorization and registration with Alexa.

reverttomoduleprovisioned

Reverts a module from a product provisioned state to a module provisioned state.

updatemodule

Updates a module over-the-wire with a new firmware package from Amazon.

version

Displays the current version of the ACK Module Utility.

barcode

The barcode command generates the product and package QR files for your product. The command creates two files for the package and product barcodes:

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

The command generates four files 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>

Options

Parameter Description Required
--port, -p <port> The serial port that your device SoC or ACK module connects 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
--dpi Set an explicit DPI value for the barcode. Use any value supported by the Barcode4J library. If not specified, a value of 300 is used. No
--productsize Set an explicit size in millimeters for the Product barcode. Use any value supported by the Barcode4J library. If not explicitly set, the command calculates the size automatically. No
--packagesize Set an explicit size in millimeters for the Package barcode. Use any value supported by the Barcode4J library. No
--help, -h Display help for the command. No

Example

In a terminal window, at the command prompt, enter the following command:

Copied to clipboard.

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

The following output appears:

Barcode files successfully created in ./ directory.

deviceinfo

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

Options

Parameter Description Required
--port, -p <port> The serial port that your device SoC or ACK module connects 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

In a terminal window, at the command prompt, enter the following command:

Copied to clipboard.

$ 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

Options

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.

In a terminal window, at the command prompt, enter the following command:

Copied to clipboard.

$ 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)

In a terminal window, at the command prompt, enter the following command:

Copied to clipboard.

$ 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)

In a terminal window, at the command prompt, enter the following command:

Copied to clipboard.

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

Options

Parameter Description Required
--port, -p <port> The serial port that your device SoC or ACK module connects 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

In a terminal window, at the command prompt, enter the following command:

Copied to clipboard.

$ 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, the provision command generates device certificates flashes them to the module's memory. For step-by-step instructions, see Provision Your Module.

This method is the default method for the provision command. Unless you're 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>]}

Options

Parameter Description Required
--port, -p <port> The serial port that your device SoC or ACK module connects 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 Wi-Fi 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, in a terminal window, at the command prompt, enter the following command:

Copied to clipboard.

$ 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:

Copied to clipboard.

$ 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're 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>]

Options

Parameter Description Required
--port, -p <port> The serial port that your device SoC or ACK module connects 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's used for Wi-Fi 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

In a terminal window, at the command prompt, enter the following command:

Copied to clipboard.

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

Options

Parameter Description Required
--port, -p <port> The serial port that your device SoC or ACK module connects 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, In a terminal window, at the command prompt, enter the following command:

Copied to clipboard.

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

Options

Parameter Description Required
-p,--port <port> The serial port that your device SoC or ACK module connects 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

In a terminal window, at the command prompt, enter the following command:

Copied to clipboard.

$ 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

Options

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

In a terminal window, at the command prompt, enter the following command:

Copied to clipboard.

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

Output similar to the following appears:

Version: 4.0.2.0

Was this page helpful?

Last updated: Mar 07, 2025