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

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

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

Example

Select the tab that corresponds to your operating system.

• macOS
• Linux
• Windows

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

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

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

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

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

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

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

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

Related topics

• Module Utility CLI
• Tutorials: Module Provisioning
• Get Support for the Alexa Connect Kit

Last updated: Nov 27, 2023