Step 3: Set up your Environment

Note: Sign in to the developer console to build or publish your skill.

Before you can prototype with the Alexa Connect Kit (ACK) development kit, you must set up your development environment. This includes completing the following steps:

Register for an Amazon Developer account.
Install the Alexa app to register your device.
Install Python 3.
Install and configure the Arduino IDE.
Download the ACK Device SDK.

Hardware prerequisites

You must meet the following hardware prerequisites to set up your development environment.

A computer with a USB port and a micro-USB cable – To connect the development kit boards to your computer.
2.4-GHz Wi-Fi network – To register and connect the ACK module.
An additional micro-USB cable (optional) - To debug the development board and update the ACK module firmware.

Step 3.1: Get an Amazon developer account

To access the ACK console, you need an Amazon developer account.

Step 3.2: Install the Alexa app

You need the Alexa app on your mobile device to scan the barcode that comes with the Development Kit and register your development device with ACK managed services and connect to Alexa. After the setup is complete, you can use the Alexa app to control your development device.

The following are the minimum versions of the Alexa app required for controlling an ACK development device:

Android – 2.2.314100.0
iOS – 2.2.3153270.0

To verify your Alexa app version

Open the Alexa app and log in.
Open the Menu and navigate to > Settings > General > About.
Verify that you have the correct minimum version of the Alexa app on your mobile device.
If you don't have the required minimum version of the app, follow the instructions to download the Alexa app.

Step 3.3: Install Python 3

You need Python 3.6.0 or later to run the setup.py script that comes with the ACK Device SDK. The setup script configures the Arduino IDE to access the ACK Device SDK source code.

Verify that you have Python 3.6.0 or later installed; otherwise, install it.

To install Python

Most macOS computers come with Python already installed, but you should verify which version you have. Open a terminal window and then run the following command:

python -V

If an earlier version of Python appears, or if you don't get a response to the command, download and install Python 3.6.0 or later. After you install it, run the following command:

python3 -V

The version of Python that you installed appears, similar to the following:

Python 3.7.4

To find out if you have Python installed on your computer, open a terminal window and run the following command:

which python

If you have already installed Python, the location appears and might or might not include the version number. If the location doesn't include the version number, run the following command:

python -V

If an earlier version of Python appears, or if you don't get a response to the command, download and install Python 3.6.0 or later. After you install it, run the following command:

python3 -V

The version of Python that you installed appears, similar to the following:

Python 3.7.4

Python isn't included on Windows computers by default. To find out if you have Python installed on your computer, open the Windows Start menu, and then enter "command" in the search bar. Select Command Prompt from the search results. In the command window, run the following command:

py

If you have already installed Python, the location appears and includes the version number.

Python 3.7.2 (tags/v3.7.2:9a3ffc0492, Dec 23 2018, 23:09:28) [MSC v.1916 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.

If an earlier version of Python appears, or if you don't get a response to the command, download and install Python 3.6.0 or later. After you install it, run the following command:

py

The version of Python that you installed appears, similar to the following:

Python 3.7.2 (tags/v3.7.2:9a3ffc0492, Dec 23 2018, 23:09:28) [MSC v.1916 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.

Step 3.4: Install and configure the Arduino IDE

Note: This step can take as long as 15 minutes to complete.

To install and configure the Arduino Software (IDE)

On the Arduino Software page, under Download the Arduino IDE, select the appropriate installer.

Important: For Windows, you must use the Windows installer, for Windows XP and up from the Arduino IDE site, not from the Windows store. The Windows store Arduino installer does not contain required library dependencies, so you must use the installer from the Arduino IDE site.
Launch the Arduino IDE.
Choose the Arduino Zero board and the Programming Port in the IDE:
1. Open the Board manager by going to Tools > Board > Boards Manager.
2. Find the Arduino SAMD Boards (32-bits ARM Cortex-M0+) package, version 1.6.18 or later, and install it.
  
  Important: This step will take a few minutes, and you might need to grant permissions for installation.
3. Verify that the USB cable is connected from the Arduino Programming Port to your machine.
4. Select Tools > Arduino SAMD Boards (32-bits ARM Cortex-M0+) Boards > Arduino Zero (Programming Port).
5. Select the Arduino Programming Port serial connection:
  - macOS
  - Linux
  - Windows
  In the Arduino IDE, select your serial port from the Tools > Port menu. On macOS it should be something like /dev/cu.usbmodem xxxxx (Arduino/Genuino Zero (Programming Port)).
  
  Tools > Port > /dev/cu.usbmodem 14302 (Arduino/Genuino Zero (Programming Port)).
  
  If you don't know the name of your serial port, open the Terminal application and run the following command:
  
  ls /dev/{tty,cu}.*
  In the Arduino IDE, select your serial port from the Tools > Port menu. On Linux it should be something like /dev/cu.usbmodem xxxxx (Arduino/Genuino Zero (Programming Port)).
  
  Tools > Port > /dev/cu.usbmodem (Arduino/Genuino Zero (Programming Port)).
  
  If you don't know the name of your serial port, open the Terminal application and run the following command:
  
  ls /dev/{tty,cu}.*
  In the Arduino IDE, select your serial port in from the Tools > Port menu. On Windows, it should be something like COM4 (Arduino/Genuino Zero (Programming Port)).
  
  If you have more than one USB COM device connected and you're not sure what port to select, navigate to the Windows desktop and right-click on My Computer, and then navigate to Properties > Hardware > Device Manager > Ports (COM & LPT). To find out what board is the Arduino Zero, you can disconnect your board and re-open the menu; the entry that disappears should be the Arduino Zero board.

Step 3.5: Download the ACK Device SDK and run the setup script

Download the ACK Device SDK and run the setup script to make the SDK source code and sample apps available in the Arduino IDE.

Download the ACK Device SDK version 3.0 or later from the resources page of the ACK developer console.

Note: If you're starting a new ACK product, and you purchased a USI Development Kit for ACK, you can upgrade your kit to SDK 4 before you begin development. For details, see ACK Device SDK 4.
Unzip the file.

Important: Don't unzip the ACK Device SDK .zip file in the Arduino Libraries folder because this might cause issues; the setup.py script configures and copies the files to the correct location.
Change directories into the unzipped folder, and use setup.py in user/platform/arduino to add the sample apps to the Arduino IDE example library.
- macOS
- Linux
- Windows
Change directories into the unzipped <ack-device-sdk>/user/platform/arduino directory. Replace /Users/username/Downloads with the path to your download location.
```
cd /Users/<username>/<Downloads>/<ack-device-sdk>/user/platform/arduino
```
Run the script:
```
python3 ./setup.py
```
You might see the following permission denied message:
```
./setup.py: Permission denied
```
If so, specify that it's an executable program:
```
sudo chmod +x setup.py
```
Now run your program:
```
python3 ./setup.py
```
Important: If you encounter an error message similar to Arduino documents directory not found see troubleshooting setup.

To view the helper commands available for setup.py, include the following --help argument

python3 ./setup.py --help
On Linux, open a shell and then change directories into the unzipped user/platform/arduino directory. Replace $HOME/username/Downloads with the path to your download location.
```
cd $HOME/<username>/<Downloads>/<ack-device-sdk>/user/platform/arduino
```
Run the script:
```
python3 ./setup.py
```
You might see the following permission denied message:
```
./setup.py: Permission denied
```
If so, specify that it's an executable program:
```
sudo chmod +x setup.py
```
Now run your program:
```
python3 ./setup.py
```
Important: If you encounter an error message similar to Arduino documents directory not found see troubleshooting setup.

To view the helper commands available for setup.py, include the following --help argument

python3 ./setup.py --help
Open the command prompt, and then change directories into unzipped ACK Device SDK folder > user\platform\arduino. Replace c:\downloads with the path to your download location.
```
cd /d c:\downloads\<ack-device-sdk>\user\platform\arduino
```
Run the script, using -3 as an argument to specify Python 3
```
py -3 setup.py
```
Important: If you encounter an error message similar to Arduino documents directory not found see troubleshooting setup.

To view the helper commands available for setup.py, include the following --help argument

py -3 user\platform\arduino\setup.py --help
Restart the Arduino IDE application to pick up the ACK sample applications, shown as examples in the Arduino IDE. You should now see the custom examples available in the File > Examples > Examples from Custom Libraries menu.

Tip: The ACK examples have the prefix AlexaConnectKit_.

Troubleshoot the setup.py script

When you run the setup.py script, you might see the message Arduino documents directory 'C:\users\xxx\Arduino\documents' not found. This can happen if you have a non-standard installation of the Arduino IDE, or if other software on your computer altered the environment variables, so that setup.py is unable to find the Arduino documents directory.

If this happens, use the --targetroot option to tell setup.py where the Arduino documents directory is. Verify the location of your Arduino documents folder in the Arduino IDE by going to Settings and viewing the Sketchbook location. The Sketchbook location is the Arduino Documents folder. Run the setup script with the --targetroot option as following:

setup.py --targetroot` <your_path\Arduino\documents>

For more troubleshooting, see Troubleshoot the Development Kit.

Was this page helpful?

Provide feedback

Last updated: Nov 27, 2023