Module Provisioning

This page provides an overview of the different Alexa Connect Kit (ACK) module states used in the product development process and when to transition between these states.

What's module provisioning?

Module provisioning is the process of programming your physical ACK module through different module lifecycle states to facilitate the ACK development process, for example to enable or disable certain functionality.

Why do I have to provision my modules?

Each state of the provisioning process completes a series of key tasks necessary to register your product with Alexa and finalize your product. For example, you move your module to the product provisioned state to associate your virtual product with your hardware. When you ship your product to customers, you move your module into the locked state.

When do I provision my modules?

You start module provisioning after you design your product and create a virtual product in the ACK developer console. Module provisioning applies to both prototyping, developing, and manufacturing. However, each phase of your project has slightly different requirements to move through the process.

How do I provision my modules?

To move your ACK module to a new state, you use relevant ACK Module Utility commands. Depending on your development or manufacturing cycle, you might move your module forward or backwards through the process to lock or unlock specific functionality.

Module lifecycle states

The three primary module lifecycle states that you transition to using Module Utility commands are module provisioned, product provisioned, and locked.

There are also two secondary states, including product provisioned–registered, and locked–registered. Modules move to these secondary states automatically when registered with Alexa at different points in time, meaning you don't explicitly move to these states using Module Utility commands.

Module lifecycle state diagram

The following diagram illustrates the relationship between your product and the different module states.

Alexa Connect Kit module life cycle
ACK Module Lifecycle

Module lifecycle state descriptions

Primary states:

  • Module provisioned – The default factory setting of a module. Here, a module doesn't represent a product, you can't register it with Alexa and it has limited functionality.

    For example, a module is in this state when you receive it from an ACK module manufacturer.

  • Product provisioned – The process of associating the virtual product you created in the ACK developer portal with a physical ACK module. When the module is in this state, a module represents a product but it's not yet registered with Alexa.

    For example, if you created a virtual product for a fan, moving to product provisioned associates your module with that fan. After you do this, you can view it in the developer console and register it with Alexa using Wi-Fi Simple Setup (WSS) for testing.

  • Locked – The final, production-ready state of a module. Locking your module prevents further provisioning attempts. You can't change its product association or reverse the locked state. You must lock your module before you ship your products to end customers, typically before the manufacturing process. Here, your module represents a product and customers can register it with Alexa using Wi-Fi Simple Setup (WSS) for daily use.

    For example, after your lock your module, it's permanently programmed as fan. Users can register and deregister it with Alexa as needed.

Secondary states:

  • Product provisioned–registered – Your module automatically enters this state when it's registered in the Alexa app with Wi-Fi Simple Setup (WSS), while in the product provisioned state. Here, your module represents a product and is registered with Alexa and ACK managed services.

    For example, your module is typically in this state when you're testing your device during development.

  • Locked–registered – Your module enters this state when it's registered in the Alexa app with Wi-Fi Simple Setup (WSS), while in the locked state. In this state, your module is locked as a product and registered with Alexa and ACK managed services using Wi-Fi Simple Setup.

    For example, your module is typically in this state when a customer purchases your device and sets it up using thier own Alexa app

High-level steps to provision modules

Use the information in the following table to understand how to move through the module provisioning process.

Primary states

Module state Purpose Next steps

Module provisioned

Leave your module in this state during product design.

Complete the following tasks, depending on your needs:

  1. Create a virtual product in the ACK developer console.
  2. Provision your module to product provisioned. You can only provision modules that you created in the developer console.
    • Prototype product – Use the Module Utility provision command.
    • Manufacture product – Use the Module Utility provision command, authorized with a YubiKey. For more details on using YubiKeys, see YubiKey Overview.

Product provisioned

Your module is now associated with a virtual product, you can now register it with the Alexa and test it using voice and in the Alexa app. Typically, you spend the most of your time in this state.

Complete the following tasks, depending on your needs:

  • Test product – Register your device with an Amazon account using Wi-Fi Simple Setup (WSS). After you register your device, it automatically moves to product provisioned-registered.
  • Finalize product – Lock your module with your virtual product using the lockmodule command. This operation can't be undone.
  • Revert product – Move your device back to module provisioned with the reverttomoduleprovisoned command. Use this command if you want to reassociate your module with a different virtual product.

Locked

Your module is now locked to your virtual product and is ready to be shipped with as a final product.

Complete one of the following tasks, depending on your needs:

  • Test your product by registering your it with an Amazon account using Wi-Fi Simple Setup (WSS). This moves your module to the locked-registered state.
  • Ship your product to your customers. Your customers can now register and operate your device with Alexa.

Secondary states

Module state Purpose Next steps

Product provisioned–registered

Triggers automatically when a product provisioned device is registered with Alexa using Wi-Fi Simple Setup (WSS).

After your module is in the product provisioned–registered state and connected to the Alexa services, you can test it using voice utterances or Alexa app.

If you're testing product provisioned–registered devices, deregister your test account when you finish. To deregister a device, delete it in Alexa app or factory reset it.

Locked–registered

Triggers automatically when a locked device is registered with Alexa. This state is typically activated by users when they purchase and register your devices.

After your module is in the locked-registered state and connected to the Alexa services, you can test it using voice utterances or Alexa app. If you're testing locked devices, deregister your test account when you finish. To deregister a device, delete it in Alexa app or factory reset it.

Example: provision an ACK development kit

The following example walks you through an example of how to provision an ACK development kit from a development sample to an end-product.

  1. Purchase an ACK development kit – When you receive your development kit, your module is already in the product provisioned state. Its product type is a development kit.

    If you register it with Alexa, it shows up as a development kit in the ACK developer console.

  2. Create a virtual product – Create your own product in the ACK developer console. For example, a fan.

    After you create your virtual product, your module is still in the product provisioned state and is still associated as a development kit. This is because you haven't associated your it with your virtual product.

  3. Provision your module as your own product – To associate your module to your own virtual product, you reprovision your device. For example, when you do this, your development kit becomes a fan.

    To complete this step, download your product's provisioning configuration file from the ACK developer console and use it with the ACK Module Utility provision command.

  4. Develop your software and test your devices – While you develop your software and test your devices, your module remains in the product provisioned state.

    If you register it with the Alexa app during your testing, it automatically moves to the product provisioned–registered state.

  5. Finalize and manufacture your devices – You're now ready to manufacture and mass produce your devices.

    Before start manufacturing, you must move your device to the locked state. To complete this step, use the ACK Module Utility lockmodule command. This operation can't be undone.

Factory reset the module

When the module is registered with Alexa though WSS, you use the Alexa app to reset the module. When you factory reset the module, it clears user and product data and requests the host microcontroller unit (HMCU) application to return device to the factory default settings. You can factory reset the module when it's in a locked state or product provisioned state.

To factory reset the module with the Alexa app:

  1. Open the Alexa app.
  2. Select Devices.
  3. Select All Devices.
  4. Choose the device you want to factory reset.
  5. Select the Trash Icon to delete the device from the Alexa app.
  6. Select Yes to confirm deletion.

    This factory resets the module.