New Developer FAQ

• Where can I download the SDK?
• How do I get started with Connect IQ?
• Am I allowed to charge for my app though the Connect IQ app store?
• Can I display seconds on my watch face?
• How do I format output padded with leading zeros?
• How can I load the apps I develop to my device for testing purposes?
• I have side-loaded an app as described above, but app settings won't work. Why is this?
• How can I test or debug Connect IQ apps I am developing?

Where can I download the SDK?

The latest version of the SDK can be found at http://developer.garmin.com/connect-iq/sdk/.

How do I get started with Connect IQ?

• The Programmer's Guide and User Experience Guide are good places to start gaining familiarity with Monkey C and Connect IQ.
  
• API Documentation is available on our developer site.
• The SDK also includes a set of sample apps in the 'samples' folder that demonstrate the capabilities of Connect IQ.

If you have questions along the way, these forums are the best place to go for assistance. Many questions have already been answered in previously posted threads, however both the Connect IQ team and several experienced developers monitor the forums to answer new questions or respond to issues you may encounter.

 Am I allowed to charge for my app though the Connect IQ app store?

Yes, you are! It is acceptable to list prices, link to payment sites, or ask for donations on the Connect IQ app store as long as solicitations are related to your app. The app store falls under the the Connect IQ SDK License Agreement, which does not forbid solicitation for sales of apps by app developers. However, solicitation for business on Garmin sites other than the app store (such as this forum) is prohibited but Garmin's Terms of Use.

Can I display seconds on my watch face?

Yes, you can! However, one priority of Connect IQ is the preservation of battery life, so we have a system in place that governs how often watch faces may be updated. Generally, watch faces update once per minute in low power mode, and once per second when in full power mode. The watch will enter full power mode for a few seconds when the user gestures to look at it, and then returns to low power mode. Developers will often detect this transition to full power mode, display a seconds indicator for a few moments, and then hide the seconds indicator once the device returns to low power mode. Newer devices may also support Always On watch faces, which can update once per second as long as they operate within certain limits.

You can find out more about low power mode, full power mode, and Always On watch faces in the Programmer's Guide and User Experience Guide, or read about the related APIs in the API Docs.

How do I format output padded with leading zeros?

Many Connect IQ apps include time values that require leading zeros. For example, time written in an HH:MM:SS format appears as "12:05:05" rather than "12:5:5". Monkey C includes string formatting functions that can get this job done using a %02d format specifier.

A common error is to specify a format of %.2d or %0.2d. This may pad a decimal with leading zeros in some languages, such as in C++'s printf() function, but Monkey C follows the C99 standard. C99 requires the 0 flag to specify padding with leading zeros for d, i, o, u, x, X, a, A, e, f, F, g, and G conversions. In addition, C99 states that if a precision is specified with '.', the the 0 flag is ignored.

How can I load the apps I develop to my device for testing purposes?

Apps are typically installed to devices via the Connect IQ App Store, but it's often useful to side-load an app to a device for testing without having to first upload a version to the app store. Here's how:

1. In Eclipse, choose Connect IQ > Build for Device Wizard…
2. In the Build for Device Wizard window:
   • Choose the project you wish to build
   • Choose the target device
   • Choose the SDK version to target
   • Specify a signing key
   • Set an output location
   • Click Finish
3. Connect your device to the computer via USB (it should appear as a drive)
4. Copy the PRG file made by the Build for Device Wizard from the output location to /GARMIN/APPS on your device
5. Disconnect your device; the app should be available for use

I have side-loaded an app as described above, but app settings won't work. Why is this?

App settings allow user to configure an app via Garmin Express or Garmin Connect Mobile, and depend on the Connect IQ App Store to function properly. When an app is side loaded, this connection to the Connect IQ App Store is never established. If you have an app that uses app settings that needs to be tested, you may submit the app to the Connect IQ App Store and test out the settings features while the app is either in a beta state or pending approval.

How can I test or debug Connect IQ apps I am developing?

A simple way to test Connect IQ apps is to include System.println() statements at strategic points in your app. Within Eclipse, these statements will output to the console. On a device, these statements write to the /GARMIN/APPS/LOGS<APPNAME>.TXT file, if it exists. This file is not automatically created, so must be created manually and named to match the name of the app's PRG file. For example, to log output from /GARMIN/APPS/MYAPP.PRG, create the /GARMIN/APPS/LOGS/MYAPP.TXT file.

For more advanced debugging, Connect IQ has a unit testing framework called Run No Evil, and a debugger that's included in the Connect IQ plug-in for Eclipse that can be used to dig into potential issues within the Connect IQ simulator. Check out the How to Test chapter of the Programmer's Guide for more info.

In addition to these tools, there are two general types of on-device crash that can occur related to Connect IQ, which each generate log files: app crashes and device crashes. App crashes typically result in an app quitting unexpectedly or displaying an 'IQ!' icon, but does not cause the entire device to crash or reboot. This kind of crash is most commonly due to a bug in an app, though it can also be due to a bug in Connect IQ itself. Whenever an app crash occurs, a /GARMIN/APPS/LOGS/CIQ_LOG.YML file is written to the device, which usually contains a call stack from the app (older devices may write a CIQ_LOG.TXT file). Device crashes typically cause the device to reboot or freeze. These indicate a Connect IQ or device firmware bug, and should be much less common than app crashes. When a device crash occurs, an ERR_LOG.TXT file is typically written to /GARMIN or /GARMIN/DEBUG on the device, containing stack trace information related to the crash. Garmin's device teams can take a look at the device crash logs to determine the cause of the crash and will typically provide a fix in a future firmware release.

When any crash log file exceeds 5 KB, it will automatically be archived to <LOGNAME>.BAK, and a new log will be started. Any old .BAK files will be overwritten when the archive occurs, so the maximum practical space available for logging is ~10 KB.

9. I just downloaded the latest SDK. Can I build apps that will work on any device that supports Connect IQ?

Yes! We have designed the SDK so that you can target any Connect IQ-compatible devices, whether they support version 1.2.x, 1.3.x, or 2.1.x.

Anything built for 1.2.x devices will work on 1.3.x and 2.1.x devices, so it's the most inclusive approach as long as you don't need the newest features for your app. Building for 2.1.x will limit the devices you can target, but will give you access to all of the latest goodies.

In the 2.1.2 SDK release, we added an option to the App Export Wizard that allows you to select a target Connect IQ version, which limits the selectable target devices to only those that support the Connect IQ version you've chosen. The only decision for you to make is which devices you would like to support. Here's a handy-dandy table to help with that choice:

10. My app uses app settings, and it sometimes crashes after changing the settings, but the rest of the time it works fine. What can cause this?

With GCM for Android there is an issue where it sets a value as a Float when a Number is expected. It's good practice to check the value to ensure it's the expected type. For example, this code will check for a null value and convert the value to a Number as long as it is not null. Otherwise, a default value is returned:

function readKeyInt(myApp,key,thisDefault) {
    var value = myApp.getProperty(key);
    if(value == null || !(value instanceof Number)) {
        if(value != null) {
            value = value.toNumber();
        } else {
            value = thisDefault;
        }
    }
    return value;
}

11. I think that I've found a bug with CIQ. Where do I report it?

If you think you've found a bug in the platform we have a Bug Reports tool here in the community.  Please make sure to read the Bug Reports Wiki and follow the directions there on rules and usage there. If you post about a bug in the regular forums your thread may be moved or deleted.

12. I keep getting a "Too Many Arguments Error", but I never used to get this. What is going on?

We added a functionality in the 2.1.2 SDK release to perform an argument count check on function and method calls. This was included as part of a larger security effort, which includes things like app signing and encryption of app data. Overall, this is a good thing, since it promotes more robust source code prevents some potential security exploits. Unfortunately, it has also caused some apps to crash on 1.3.x and 2.1.x devices when built with the 2.1.2 SDK even though these same apps execute without issue when built with earlier SDK releases. This kind of crash appears in the CIQ_LOG.txt file as a "Too many arguments" error, signifying the argument count check has failed.

In most cases, the culprits behind this "Too many arguments" issue are missing 'state' arguments for onStart() and onStop(). These are currently unused argument and were passed implicitly in earlier versions of Connect IQ, but must now be included explicitly. Another example that can cause this is something like an initialize() function for a Drawable, which takes an array of options but to which none are passed.

The new minimum SDK selector is designed to build for the highest supported SDK for each device. For example, consider this set of devices: device A (2.1.x), B (1.3.x), and C (1.2.x). The table below illustrates how the build system is designed to function:

It can sometimes be difficult to troubleshoot this issue due to a bug in our build system. The Build For Device Wizard may build a PRG for a target VM version lower than expected for a given device. The result is that a PRG made with the Build For Device Wizard will operate without issue on a device, but the same app will fail with a "Too many arguments" error when using a PRG from the App Export Wizard (i.e. installed from the store). As a consequence, it can be difficult to obtain a useful call stack in the CIQ_LOG.txt. We have a fix for this that will be included in an upcoming release of the SDK.