Developer Blog

Connect IQ Developer Summit 2017 Breakout - Designing for Garmin Devices

05/10/17 @ 01:00 PM

CIQ Summit Logo
In this breakout you will learn how to design your Connect IQ app from a UX perspective, and how to implement it using the available Connect IQ tools. You can read more after the break.

As of the release of the 2.2.5 SDK, Connect IQ is now supported on 22 different devices. Being supported on a wide array of different devices gives Connect IQ developers an opportunity to reach a very large portion of the Garmin user base. However, the broad spectrum of device configurations presents a challenge to Connect IQ developers: how best to structure your project to work on all these different platforms such that complexity and code duplication are minimized. In this post we’re going to talk about tools that the Connect IQ SDK provides that greatly reduce the amount of overhead required to support multiple devices.

Project Resources

The Connect IQ resource system provides a set of powerful tools that allow developers to define UI resources for use in their applications. The default directory structure created for a project by the Eclipse plugin sets up default resources that will apply to all devices that a project supports. However, using some specialized features of the Connect IQ resource compiler, you can easily create different sets of resources tailor made for specific, or groups of, devices.

Resource Folder Qualifiers

Before we get too much further into specifics of how to specialize your resources, the concept of a resource folder qualifier must be mentioned. The Connect IQ resource compiler operates off of folder names to determine what resources should be included for the device being targeted for a particular build. This is accomplished by using so-called resource folder qualifiers in the actual name of the resource folders. These qualifiers are simply keywords separated by - characters. For example, if you had designed resources specifically for the fēnix™ 3, you would create a folder named resources-fenix3 in your project and place all of your fēnix™ 3 specific resource files in it. Qualifiers can have multiple levels (which we will describe in more detail in later sections), with each level being separated by an additional - character.

Device Specific Resources

The most granular form of resource specialization is to create resources for specific devices. This is accomplished by appending the device ID to your resource folder name in the form resources-deviceid where deviceid must be one of the following strings corresponding to the device you wish to support:

                                                                                             
Device Name Device ID
Edge 520edge_520
Edge 820edge820
Edge 1000edge_1000
epix ®epix
fēnix™ 3, tactix™ Bravo, quatix™ 3fenix3
fēnix 3 HRfenix3_hr
D2™ Bravod2bravo
D2 Bravo Titaniumd2bravo_titanium
fēnix 5Sfenix5s
fēnix 5fenix5
fēnix 5Xfenix5x
fēnix Chronosfenixchronos
Forerunner® 230fr230
Forerunner 235fr235
Forerunner 630fr630
Forerunner 735XTfr735xt
Forerunner 920XTfr920xt
Forerunner 935fr935
Oregon 7 Seriesoregon7xx
Rino 7 Seriesrino7xx
vívoactivevivoactive
vívoactive HRvivoactive_hr

While using device-specific resource qualifiers offers you the most granularity, it can be cumbersome if your app supports a lot of different devices:

As you can see, the number of resource folders you have to maintain can quickly get out of hand. To help address this problem, the concept of device families was introduced.

Device Families

The most common reason for needing to override resources for specific devices, is to adjust page layouts to accommodate the different screen shapes and sizes that different devices can have. Families provide a way to group devices together at a higher level using the attributes of screen shape and size, allowing you to create resources that apply to all devices that fall within a particular configuration. There are two levels of attributes that define device families, the first level is screen shape and the second level is screen size. These attributes can be added to resource folder names using the - qualifier separator, just as you would for device IDs. The following table shows the different family qualifiers supported, as well as which devices are grouped together in those families

                                                     
Screen Shape Screen Size QualifierDevices In Family
round218 x 218D2 Bravo, D2 Bravo Titanium, fēnix 3, fēnix 3 HR, fēnix Chronos, fēnix 5S
round240 x 240fēnix 5, fēnix 5X, Forerunner 935
semiround215 x 180Forerunner 230, 235, 630, 735XT
rectangle205 x 148epix, vívoactive, Forerunner 920XT
rectangle148 x 205vívoactive HR
rectangle240 x 400Edge 1000 / Explore, Oregon 7 Series, Rino 7 Series
rectangle200 x 265Edge 520, Edge 820 / Explore

Family qualifiers can be applied at either the screen shape level, which is the least granular, or the screen shape and screen size level. The level of granularity chosen depends on the specific requirements for your app. A simple example of when you might care only about screen shape could be something simple like utilizing the top part of the screen on the round display and not on the semiround screen for which it is obscured. If, however, your app has detailed layouts that need to be adjusted for each screen size, you could add the screen size qualifier. The following example shows how you could structure your project using both screen shape, as well as more specific screen shape and size qualifiers.


Source Code Build Exclusions

While everything that has been discussed up to this point has been related to UI resources such as layouts and images, there are times when device-specific source code may be needed. The Connect IQ resource compiler allows you to create build exclusion resources that can control what source code gets included for an app build. These files live inside of any standard resource folder, and, as such, can be associated with device families or specific devices.

Why wouldn’t you want to always use one set of source code for all devices? There can be a number of reasons, but the most common are available memory, or very device-specific functionality that either is not UI related or cannot easily be done via layouts. Using memory concerns as an example, lets say you are developing an app that targets both Edge and fēnix 5 products. Because the Edge products have more available memory and processing power than the fēnix 5, you might want to include additional UI pages and extra features that make more sense on a larger, touch screen product. However, because you need to include a lot of additional source code to add these new views and additional functionality, your fēnix5 builds suddenly start running out of memory, all due to additional code space taken up by functionality don’t event want to use on that product! Build exclusions make it easy to solve this problem by allowing you exclude individual source code files, directories, or annotations for specific builds. The following examples show how you might set up a project with a different set of source code files for larger screen handheld devices such as an Edge, and wearable products such as the fēnix series.

As can be seen, an XML file called build.xml is present in both the top-level resources folder, as well as the resources-edge820 folder. The file present in the resources folder will effectively enable the “default” build behavior. Builds for specific products or families of products will have to override it, as can be seen with the resources-edge820 folder. Notice also how the source code is organized

The build files will refer to these folders to determine which files to exclude from a particular build. For this project, the wearable device build configuration (which lives in the base resources) folder is as follows:

<build>
    <exclude dir="../source/handheld" />
    <exclude annotation="handheld" />
</build>

Note that both a source code directory and an annotation are listed in the build exclusion file. This means that both the directory ../source/handheld and any code that carries the (:handheld) annotation will be excluded from the build. The annotation can prove useful if, as in this case, the “common” source code folder has some code that is mostly re-used between the two build configurations, but may contain snippets within existing source files that need to be different.

Finally, the build exclusion file for the handheld device configuration, as taken from the build.xml file in the resources-edge820 folder is configured as follows:

<build>
    <exclude dir="../source/wearable" />
    <exclude annotation="wearable" />
</build>

Conclusion

The tools presented in this article provide simple ways to ensure your apps can support a wide array of different devices. Thinking about how to structure your project to support multiple devices early in the development process will make long term maintenance much simpler as new Connect IQ enabled devices continue to be released, and with 22 devices already available the necessity of early planning is only going to grow.

Categories: Connect IQ SDK