User-Initiated Triggers

A user-initiated trigger is an action that occurs on your Alexa Connect Kit (ACK)-based device, after a user completes a pre-programmed pattern, such as pressing a unique button combination. For example:

  • Initiate a factory reset after completing five consecutive physical power on/off cycles, such as power cycling a lamp.
  • Initiate device setup mode after pressing and holding a specific button, such as a connect to Wi-Fi button.

You can program the following user-initiated triggers on ACK-based device: setup mode, factory reset, and logs upload.

Setup mode

ACK-based devices use Amazon Frustration-Free Setup (FFS) to connect devices to a Wi-Fi network and register them with Alexa. By implementing FFS on your device, you can use the same Alexa setup and authentication technology that Amazon uses for its own devices. You don't have to create a separate companion app to guide the user through setup. And the user, in turn, doesn't have to switch between different apps during the setup process.

To learn about each of the FFS setup modes, click the following tabs:

Zero-Touch Setup (ZTS)

How it works

Zero-Touch Setup (ZTS) is the ideal setup flow for ACK-based devices, because it doesn't require users to initiate the set up process explicitly. This automation can help lower setup friction.

ZTS uses the Alexa app, or other nearby Amazon devices (Echo, Fire TV), to auto-detect when your device powers on. It then attempts to configure the device without asking the user to enter their Amazon account information or Wi-Fi credentials.

Prerequisites

  • Only works with devices personally purchased on amazon.com.
  • When a customer purchases a device on amazon.com, they must link their Alexa account during the checkout process.
  • Customers must already store their Wi-Fi credentials in an Amazon Wi-Fi Locker, before they purchase and link their device.

Device association

  • Your device packaging has an outer FFS barcode that contains information uniquely identifying the device.
  • During product shipment, Amazon attempts to associate the purchased device with the correct user account, which was supplied during the amazon.com checkout process.

User registration

  • When a user powers on the device, nearby FFS provisioners (such as an Echo device or Fire TV) detect the device and then attempt to onboard the product to the Wi-Fi network.

Example

Example of ZTS user flow
Barcode Setup (BCS)

How it works

If Zero-Touch Setup (ZTS) doesn't work, use Barcode Setup (BCS) as the first fallback method to set up your devices.

To register a device with BCS, the user opens the Alexa app and then follows the on-screen instructions. Here, the user must find, and then scan an FFS 2D inner barcode for the device, which is typically provided with the device. After a user scans the barcode, the Alexa app tries to onboard the device to the applicable Wi-Fi network, and register it with Alexa.

Prerequisites

  • The user installs the Alexa app.
  • Your device comes with an inner barcode that contains information to identify that the device is unique.

User registration

  • Use BCS as a fallback scenario when ZTS doesn't work or when the user wants to re-register the device.
  • To get started, the user scans an inner barcode contained on the device (or in the device manual) with the Alexa app.

Example

Example of BCS user flow
Example of BCS user flow
Example of BCS user flow
User-Guided Setup (UGS)

How it works

If Zero-Touch Setup (ZTS) and Barcode Setup (BCS) don't work, User Guided Setup (UGS) provides a final fallback method to set up your devices. For example, if ZTS fails (because the device wasn't registered on amazon.com) and BCS is unavailable (because the barcode is missing), users should set up the device by using UGS.

After the user taps the DON'T HAVE A BARCODE? button in the Alexa app, UGS guides them through a predefined setup flow.

This approach requires the user to physically interact with the device to initiate the device setup process.

Prerequisites

  • The user installs the Alexa app.
  • You implemented a User-Initiated trigger on your device to start UGS. For example, by using a button combination, power on/off pattern, or choosing an item in a menu.

User registration

  • UGS is the typical fallback scenario when both ZTS and BCS don't work. For example:
    • Barcode is damaged or lost.
    • Barcode can't be placed on the packaging or device.
    • ZTS isn't configured upon purchase.
  • To get started, the users starts UGS by following steps in the Alexa app or from another authoritative source, such as your product's user manual.

Example

The following images show an example of a device triggering UGS. In these images, the user selects DON'T HAVE A BARCODE?, and then finishes setting their device up.

Example of UGS user flow
Example of UGS user flow

Factory reset

A factory reset typically occurs after a user completes your predefined factory reset trigger. For example, the user might press and hold a designated reset button, or enter a specific pattern on a keypad.

When the factory reset occurs, your device must erase all locally stored user configurations and preferences, and then revert to the factory default state. After the reset finishes, your ACK Device SDK application must also communicate the factory reset condition to the ACK module. This communication removes all Wi-Fi credentials from the device, and then deregisters the device from Alexa.

Implementation details

  • When a factory reset completes, the device enters the ready for setup state.
  • If a user removes a device from the Alexa app, it automatically triggers a factory reset. Here, the device receives a factory reset event from Alexa services.
  • Document your factory reset instructions in the user manual of your device and on a relevant device support page.

Upload logs

You can program a trigger that uploads logs generated by the ACK device by using the ACK Analytics Service. For details about collecting logs, see ACK Analytics Service.

Example: User-initiated triggers for a switch

The following example provides a mock template to define the user-initiated triggers for a switch.

Device trigger User action (device input) Indication of trigger on device

Barcode Setup (BCS)

N/A, the FFS inner barcode that's required to start BCS is printed in the user manual and attached to the metal plate of the switch.

N/A, BCS automatically starts after the device powers on (when the device isn't registered). LED starts blinking to indicate that it's in setup mode.

User-Guided Setup (UGS)

Press and hold the power switch in the On position for 10 seconds.

LED blinks yellow three times to confirm that the device is in UGS mode. LED continues to blink while in setup mode.

Factory reset

Quickly turn the power switch On and Off five times in a row, then hold in the On position for 10 seconds.

LED flashes red five times to confirm a factory reset.

Upload Logs

Press and hold the power switch in the On position for 20 seconds. The LED blinks five times to confirm that the log operation started.

LED blinks green five times after 30 seconds. Blinks twice when completed successfully.

Was this page helpful?

Last updated: Nov 27, 2023