Connect IQ SDK

Getting Started

The Connect IQ SDK

Before getting started with the installation on Mac or Windows, you’ll need Oracle Java™ Runtime Environment 8 (version 1.8.0 or higher) installed. Once that’s done, continue on to your platform’s installation instructions.

OS X Installation

  1. Visit the Connect IQ SDK download page
  2. After reviewing the SDK license agreement, click the Accept & Download for Mac button to download the SDK
  3. When the download has finished, locate the Connect IQ SDK disk image file in your Downloads folder and open it (a Finder window containing the SDK may open automatically)
  4. Create a new folder in a convenient location
  5. Drag the contents of the Connect IQ SDK disk image into this new folder
  6. Once complete, you may eject the disk image and delete the Connect IQ SDK disk image file
  7. Next, point your PATH to the Connect IQ bin directory in the Terminal. To temporarily add it to a single local shell instance:
$ export PATH=$PATH:path/to/connectiq-sdk/bin

For a more persistent addition, open .bash_profile in a text editor:

$ touch ~/.bash_profile
$ open ~/.bash_profile

Then add the line below to the file and save the changes:

$ export PATH=$PATH:path/to/connectiq-sdk/bin

Windows Installation

  1. Visit the Connect IQ SDK download page
  2. After reviewing the SDK license agreement, click the Accept & Download for Windows button to download the SDK
  3. Create a new folder in a convenient location
  4. When the download has finished, locate the Connect IQ SDK zip file and extract it to this new folder
  5. Once complete, you may delete the Connect IQ SDK zip file
  6. Next, point your PATH to the Connect IQ bin directory in the command prompt:
> set PATH=%PATH%;path\to\connectiq-sdk\bin

Linux Installation

  1. Visit the Connect IQ SDK download page
  2. After reviewing the SDK license agreement, click the Accept & Download for Linux button to download the SDK
  3. Create a new folder in a convenient location
  4. When the download has finished, locate the Connect IQ SDK zip file and extract it to this new folder
  5. Once complete, you may delete the Connect IQ SDK zip file
  6. Next, point your PATH to the Connect IQ bin directory in the command prompt:
$ export PATH=$PATH:path/to/connectiq-sdk/bin

For a more persistent addition, open .bash_profile in a text editor:

$ touch ~/.bash_profile
$ nano ~/.bash_profile

Then add the line below to the file and save the changes: CTRL-X

$ export PATH=$PATH:path/to/connectiq-sdk/bin

Using ANT stick in Linux

In order to use ANT stick in Linux the usb device should be accessible to the simulator. A udev rule must be installed in the system for the ANT stick to populate with non-root privileges.

Find the vendor and product id for the ANT stick

$ lsusb

Identify the ANT stick in the list and its vendor and product id. example:

Bus 001 Device 009: ID 0fcf:1009 Dynastream Innovations, Inc. ANTUSB-m Stick

Create a udev rule for this device

$ sudo touch /etc/udev/rules.d/50-connectiq-usbant.rules
$ sudo nano /etc/udev/rules.d/50-connectiq-usbant.rules

Then add the line below to the file and save the changes: CTRL-x

ACTION=="add", SUBSYSTEMS=="usb", ATTRS{idVendor}=="0fcf", ATTRS{idProduct}=="1009", MODE="664", GROUP="plugdev"

Restart the udev service and plug the ANT stick

$ sudo /etc/init.d/udev restart

Add yourself to the ‘plugdev’ group

$ sudo usermod -a -G plugdev <userName>

Basic Commands

After installation, three new shell commands are available: connectiq, monkeyc, and monkeydo.

> monkeyc -o <output.prg> -m <manifest.xml> [-z resource.xml;resource2.xml] <file1.mc> [file2.mc]...
monkeydo executable device_id [-t | -t test_name]

Argument Definition
executable A Connect IQ executable (PRG) to run
device_id The device to simulate (e.g. “fenix5”)
-t Execute Run No Evil unit tests. Supply an optional test method or class name to only run that test or set of tests.

Here is an example of a basic build and run cycle from the command line:

> connectiq                                       // Launch the simulator
> monkeyc -o myApp.prg -m manifest.xml myApp.mc   // Compile the executable
> monkeydo myApp.prg fenix5                       // Run in the simulator

The Eclipse Plug-in

The Connect IQ Eclipse plug-in turns Eclipse into a Connect IQ development environment. Its features include:

The Connect IQ plug-in requires either the Standard Edition or IDE for Java Developers (either 32 or 64 bit) of Eclipse Mars or newer and Oracle Java™ Runtime Environment 8 (version 1.8.0 or higher).

Installing the Eclipse XML Editor

Before you can install the Connect IQ plug-in you must make sure you have the Eclipse XML editor and tools installed.

  1. In the top menu, go to Help > Install New Software:

  2. Select your Eclipse distribution (Mars, Neon, etc.) from the available update sites.

  3. Check the box next to Web, XML, Java EE and OSGi Enterprise Development > Eclipse XML Editor and Tools.[1]

Installing the Eclipse Plug-in

  1. In the top menu, go to Help > Install New Software:

  2. Use the Add… button to add https://developer.garmin.com/downloads/connect-iq/eclipse/:

  3. Check the box next to Connect IQ in the list and hit Next:

  4. Dependent plug-in modules may need to be downloaded and installed. When this is complete, restart Eclipse to complete the installation.

Configuring the Eclipse Plug-in

  1. Next, the plug-in will need to know where to find the Connect IQ SDK. To set this, go to the Window > Preferences menu (Windows), or to Eclipse > Preferences (Mac):

  2. Click the Browse button and add the path to your Connect IQ SDK directory. Make sure it is referencing the root directory of the SDK and not the bin subdirectory.

  3. Add the Connect IQ perspective to Eclipse by selecting Window > Open Perspective > Other… and then select Connect IQ:

Generating a Developer Key (CIQ 1.3)

The Connect IQ compiler requires a developer key to sign apps when they’re compiled and packaged. The required key must be a RSA 4096 bit private key.

Note: It’s important you keep track of the key you use to sign app packages. You will need to use the same key to sign updates to an existing app on the store. If you lose your original signing key you will not be able to update your app.

Generating a Key Using OpenSSL

If you’re working from the command line you can generate a RSA key using OpenSSL. The following command will generate a valid signing key.

> openssl genrsa -out developer_key.pem 4096
> openssl pkcs8 -topk8 -inform PEM -outform DER -in developer_key.pem -out developer_key.der -nocrypt

This developer key, developer_key.der, is passed to the compiler using the -y command line option.

Generating a Key Using the Eclipse Plug-in

If you’re using the Eclipse Plug-in there is a key generation utility built-in. Here’s how to use it:

  1. In the top menu, go to Preferences > Connect IQ > Compiler
  2. Click the Generate button to open the wizard
  3. Set the output location for your developer key
  4. Click Finish to create the key

The developer key specified in the Connect IQ compiler preferences will automatically be passed to the compiler when a project is compiled.

Creating Your First Project

  1. Click the File menu, and choose New > Project

  2. Select Connect IQ Project and click Next to continue:

  3. Enter a name for your project and click Next:

  4. Set the project type to Watch Face

  5. Check the Square Watch and Round Watch target platforms, leaving the minimum SDK version at the default, and click Next:

  6. Select the Simple template, upon which the project will be based:

  7. Select English as the supported language, and click Finish:

    Eclipse will create the project and move to the Connect IQ perspective. Once the project is initialized, the following project elements will be created automatically:

bin
Contains binary and debug output from the app compilation
resources
Inputs to the resource compiler, such as layouts, images, fonts, and strings, and language-specific resources
source
Contains the Monkey C source files, initially broken into ‘App’ and ‘View’ files
manifest.xml
Application properties like the app id, the app type, and the targeted devices

About the Minimum SDK Version Field

The minimum SDK version allows you to configure device compatibility by enforcing that only devices that support, at a minimum, the SDK version you’ve selected to be enabled for your app. For example, if your app relies heavily on a feature of the 2.1.x SDK, such as the Sensor History feature, you can set your minimum SDK version to 2.1.x and the list of available devices will be pruned such that you cannot select an incompatible product.

Running the Program

Before running the app for the first time, you may wish to set up a Run Configuration in Eclipse, a pre-selected set of options with which to run a project to help speed development. For example, you may create one to execute your app as a widget on the fēnix 3. Once configured, new run configurations only need to be added if new app or device configurations are needed.

To add a run configuration:

  1. Click the Run > Run Configurations menu

  2. Right click on the Connect IQ App option in the list on the left side of the window, and select New:

  3. Give the configuration a name at the top

  4. Choose the Connect IQ project that will use this configuration (It should automatically select your current project, but the Project button can be used to select a different one)

  5. Choose a target device

  6. Select the SDK version to target. Only SDK versions compatible with your selected device will be displayed.

  7. Click Apply and Close:

Before running your program, start the Connect IQ simulator by clicking the Connect IQ menu and selecting Start Simulator, or clicking on the start simulator icon in the toolbar. A blank simulator window will appear.

With a Run Configuration created and the simulator started, you’re ready to go! Use the down arrow next to the Run > Run Configurations menu (or from the Run Configurations selector on the toolbar) to select your configuration.

If all goes well the following run output will appear in the console:

Found Transport: tcp
Connecting...
Connecting to device...
Device Version 0.1.0
Device id 1 name "A garmin device"
Shell Version 0.1.0
Connection Finished
Closing shell and usb

…and the watch will appear in the simulator:

About the Target SDK Version Field

The target SDK version field is populated with the versions of the SDK that the device you’ve selected supports. When selecting a target SDK, you are telling the compiler to target that SDK’s feature set when building your app.

Importing an Example

To try one of the Connect IQ sample apps, import it into your Eclipse workspace:

  1. Click the File menu

  2. Select Import…

  3. Choose Existing Projects into Workspace under the General section of the window, and click Next:

  4. Click the Browse button and select the root directory of the sample to import:

  5. Check all projects to import that are listed in the Projects window (in the example above, only one project is listed)

  6. If there are multiple projects in the root directory, check Search for nested projects to ensure that Eclipse locates all potential projects

  7. If you prefer to work with a copy of the project, check Copy projects into workspace

  8. Click Finish to complete the import

Side Loading an App

The Eclipse plug-in provides a wizard to help developers side load an application. Here’s how to use it:

  1. Click the Connect IQ menu

  2. Select Build Project for Device to open the wizard

  3. Choose the project and device for which you wish to build from the drop down menus

  4. Select the SDK version you would like to target. Only SDK versions compatible with the selected device will be displayed.

  5. Set the path to the private key to use to sign your app. See Generating a Key Using the Eclipse Plug-in for instructions on creating a key.

  6. Set the output directory to your device’s GARMIN/APPS directory

  7. Click the Build button.

The wizard will create an executable (PRG) of the selected project and save it to your device for testing.

If you are unable to choose a device for which to build (the menu appears empty), it means that there are no valid devices configured for your project. For example, the Square Watch and Round Watch device types are valid for simulation only and do not represent physical devices for which apps may be built.

To configure additional target platforms for your project:

  1. Right click on the project in the project explorer, and choose Properties

  2. Check the desired target platforms in the properties window


  1. Newer versions of the Eclipse installer will automatically include these tools. If you do not see them listed, then you may skip this step.  ↩