Connect IQ Pro Tip: Connect IQ and Travis CI

This is a guest post written by Achim Seufert.

You probably have already seen them all over GitHub; these fancy little badges indicating among other things that a project’s build-process is or . Check Bootstrap‘s main-page for example:

They’re pretty much becoming a standard for projects using build-tools like Maven, Gradle, npm, etc. The badges actually aren’t a feature of GitHub itself, but originate from services like TravisCI, AppVeyor, or David. The README files of GitHub projects, usually plain Markdown-files being rendered to HTML, simply point to automatically generated images provided by these services.

In this tutorial I’ll show you how to use TravisCI to build and track status of your Connect IQ project.

Getting Started

TravisCI is a free-of-charge continuous-integration-service for open-source projects that seamlessly integrates with your GitHub repository. Whenever you push some changes to your repository, TravisCI will fire up a fresh VM which can run a set of tasks which usually include compiling your code, executing unit-tests, packaging, and so on. Furthermore there’s a wide variety of options that let you define notifications being sent from TravisCI in case one of these tasks will fail or behave in an unexpected way. Our goal should be to have TravisCI build and package a Connect IQ-app and visualize the outcome of these tasks with either passing or failing.

Building via the Command Line

At this point I’m assuming that you already have created a GitHub repository containing your Connect IQ project. The most important task is getting our app built and packaged via command line instead of using the Eclipse Plugin. This can be achieved by invoking the Monkey C compiler through the monkeybrains.jar library which can be found in the bin-folder of your Connect IQ SDK. We also have to keep in mind that this should run on a UNIX-based console, since TravisCI starts a Linux-VM for us. As a side note it’s good to know that TravisCI is stateless, meaning you don’t have to worry about cleaning up your environment after a build; you’ll get a fresh VM every time a build gets triggered.

Our compile/package command should look something like this:

java -jar "${MB_HOME}/bin/monkeybrains.jar" ${PARAMS} ${SOURCES}

 
We basically just use Java and execute the JAR’s main-class, passing in some params and sources. In order to make things a bit more generic and convenient, I’ve created a shell-script (mb_runner.sh) which wraps the calls to the monkeybrains.jar. Place it in your project root alongside the manifest.xml. The params are built automatically; source and resources will also automatically be found and passed over. Finally, the script can also be used to package the app. Compiling and packaging an app requires a “Developer Key” (see the Getting Started in the Programmer’s Guide).

The three things the script needs in order to run are:

1. The MB_HOME environment variable to be set and pointing to your Connect IQ SDK
2. The MB_PRIVATE_KEY environment variable to be set and pointing to your private key
3. A file called mb_runner.cfg, also residing in your project-root, which contains a few details specific to your app. Check out the mb_runner.cfg.sample and adjust the settings to fit your needs.

If you want to see more details about mb_runner read the README.md. Running the following will build and package your app:

./mb_runner.sh package

Prepare the Project/Repository for TravisCI

There are three more things to do:

1. Create the .travis.yml config file in your repository-root
2. In your repository root you’ll need to create a simple shell-script travis.sh in which we’ll be preparing/invoking the mb_runner script
3. Link your repo with TravisCI

The .travis.yml file should look like this:

language: java

jdk: oraclejdk8

before_script:
    - sudo apt-get install -qq dos2unix
script:
    - ./travis.sh

Here we simply tell TravisCI to use a default Java environment (with Oracle’s JDK8 installed), install the required dos2unix package, and run the travis.sh shell script shown below. This will prepare our freshly created VM-environment so we can run our actual MonkeyC-compile-job:

#!/bin/bash
# travis.sh script to

SDK_URL="https://developer.garmin.com/downloads/connect-iq/sdks/connectiq-sdk-win-2.2.4.zip"
SDK_FILE="sdk.zip"
SDK_DIR="sdk"

PEM_FILE="/tmp/developer_key.pem"
DER_FILE="/tmp/developer_key.der"

###

wget -O "${SDK_FILE}" "${SDK_URL}"
unzip "${SDK_FILE}" "bin/*" -d "${SDK_DIR}"

openssl genrsa -out "${PEM_FILE}" 4096
openssl pkcs8 -topk8 -inform PEM -outform DER -in "${PEM_FILE}" -out "${DER_FILE}" -nocrypt

export MB_HOME="${SDK_DIR}"
export MB_PRIVATE_KEY="${DER_FILE}"

./mb_runner.sh package

As you can see, we’re downloading/extracting the Connect IQ SDK, generating a new private key for compilation/packaging, and setting the environment variables accordingly before running the mb_runner script.

After committing/pushing the three new files (mb_runner.sh, mb_runner.cfg, .travis.yml) to your repo you can finally link it to TravisCI as a final step. Just head over to the TravisCI homepage and log in using your GitHub credentials. Navigate to your account-settings and simply select the repository you want to activate.

And that’s it!  From now on every new commit/push to your repository will trigger TravisCI and compile/package your app. If any build errors occur when committing a change you’ll get notified about it.

Adding Badges to the README

As a reward for our hard work we now can decorate our repository’s main page by adding the status-banner. Replace `[username]`, `[reponame]`, `[branchname]` with values that fit to your project:

![Build Status](https://travis-ci.org/[username]/[reponame].svg?branch=[branchname])](https://travis-ci.org/[username]/[reponame])

Of course you can put up an extra banner for each branch (master, development, etc.) you have.

Including a Companion App

If you happen to have an Android or iOS companion app along with your Connect IQ app, you could easily combine the build-process of both apps. If you’re having an Android app for example, then you’ll want to have it built by TravisCI as well. Since you’re already booting up a fresh Java-environment for this, you can just run your Connect IQ app build immediately afterwards. TravisCI will then return a combined result of both jobs meaning, if one fails then it will be an overall failure.

For such a case, the .travis.yml file could look something like this:

language: android

jdk: oraclejdk8

android:
  components:
    - tools
    - platform-tools
    - tools
    - build-tools-25.0.2
    - android-25
  licenses:
    - android-sdk-license-.+
    - '.+'

before_install:
    - mkdir "$ANDROID_HOME/licenses" || true
    - echo -e "\n8933bad161af4178b1185d1a37fbf41ea5269c55" > "$ANDROID_HOME/licenses/android-sdk-license"
    - echo -e "\n84831b9409646a918e30573bab4c9c91346d8abd" > "$ANDROID_HOME/licenses/android-sdk-preview-license"

# the following part will be used to perform a compile-/package-run for the ConnectIQ-app;
# afterwards we change into the "android"-subfolder and continue with the standard Android Gradle-build
before_script:
    - sudo apt-get install -qq dos2unix
script:
    - cd ciq && ./travis.sh
- cd ../android && ./gradlew build

mb_runner Submodule

Instead of manually adding the mb_runner script to you project root, you also can include it as a Git submodule by running the following in your project root:

git submodule add https://github.com/4ch1m/mb_runner.git

This will create a mb_runner subdirectory, containing the mb_runner.sh file. You will still have to add/create a mb_runner.cfg file in your project’s root and adjust it to your needs.

Conclusion

Continuous integration has become a necessity of modern software project. Having TravisCI watch over your sources - ensuring that everything is still in a “buildable” state - makes commiting/pushing your code to the repo less frightening. Using the above techniques you can bring continuous integration to your Connect IQ GitHub projects.

Achim Seufert is a developer in Würzburg, Germany. Check out his GitHub and website.