Device API levels

TL;DR for any given device, compiler.json in the SDK device folder has the minimum required CIQ version for that device, which is also the maximum expected CIQ version for the app dev.

--

Open the SDK's devices folder, and navigate to compiler.json for the device of interest.

On Windows, the devices folder is at %appdata%\garmin\connectiq\devices. This folder contains a separate folder for each device (e.g. fr265).

Each device folder has several files, including compiler.json, has a partNumbers array containing information about each part number (this is not the same part number that's shown on the box or listed on the website).

Newer devices may only have one part number, while older devices may have different part numbers for worldwide (WW) and Asia-Pacific (APAC) devices. The value for worldWidePartNumber will indicate which partNumber is WW (which means that its CIQ version will always be newer or equal to the APAC CIQ version.)

Each partNumbers element has the following fields:

connectIQVersion: e.g. "4.2.3"

firmwareVersion: e.g. 1616

number: the actual part number e.g. "006-B4257-00"

connectIqVersion and firmwareVersion are actually the minimum versions an app built with device file can expect to see when deployed to a device. This is enforced when the user tries to download the app - if the device has a lower CIQ or firmware version than the minimum, the user will be prompted to updated.

Since those are the minimum required versions for the user, they are also the maximum expected versions for the app dev. e.g. If we know every user has 4.2.3 or higher, then we can't assume they have anything higher than 4.2.3.

Thanks,

So ... do the compiler.json files represent what's been pushed out to actual devices?

No, and you're welcome to vote on this "feature" (documentation) request: forums.garmin.com/.../improve-documentation-add-api-levels-and-system-levels-to-device-reference

I'll add that any "available" information (documentation, compiler.json) only has information about what would be the max api level if a certain kind of device was upgraded to the latest available firmware. There's no information on the minimum possible. Even when you think you have that information it's not really that. When you look at a certain device family, and then split it by part numbers then you'll only know what would be the minimum api level of that device family if all the devices would be ugraded to the latest firmware version. The problem is that once there is a new FW version the json is updated to indicate the CURRENT minimum version, but if a device doesn't upgrade the FW then they still have an older CIQ with older api versions... And I am not aware of any official documentation that would tell what would be the lowest version of a part number if the FW wasn't upgraded since the 1st item that came out of the factory.

BTW I made some effort to collect the data, and it may be correct for devices that came out since I started the project (but not necessarily, because it depends on the json files in the devices directory, that might or might not be correct, and more importantly I am not checking every day if there are new versions of the devices in the sdk manager so I might have skipped/missed some) The idea is that I have a script that scans the device files and extracts the min, max CIQ version for the devices, and it ADDS the newly available versions to a list, but also KEEPS the older versions in the csv files: https://github.com/flocsy/garmin-dev-tools (look at the files under csv/)

Interesting, thanks.

So I am drawing the conclusion that when the ciq version is updated in the compiler.json, then it's also possible for users to update real devices (timing difference between sdk update and real device update, earlier or later)?

Devices can. and often do, get a CIQ version update before you see it in compiler.json.  The last digit (the "3" in 4.2.3 for example) can just indicate a bug fix level.  It might still show as 4.2.1 in compiler.json. as that's the minimum level a user needs to have to install your app.  If the user has a level less that 4.2.1, they will be told they need a firmware update to install your app, but they don't need to have 4.2.3 -just 4.2.1 or later..

flocsy🤠 said:

I'll add that any "available" information (documentation, compiler.json) only has information about what would be the max api level if a certain kind of device was upgraded to the latest available firmware. There's no information on the minimum possible. Even when you think you have that information it's not really that.

I don't agree with this. Based on other threads and personal experience, if an app is built against a given device file, then the user will not be able to install it unless their device has the CIQ API version and firmware version specified in the device file, at a minimum. You will see that the exported .IQ file (zip archive) contains a manifest XML file which has the CIQ/firmware version for each device (and the naming scheme is something like "minApiVersion" which indeed suggests it's the minimum version.)

This means a device file does indeed specify the minimum possible CIQ version (*) for any given device, for apps that are built against that version of the device file. The only use case which isn't covered by looking at the latest device files is when you have an *old* app which hasn't been built again the latest device files. In this case, if you have a copy of the exported IQ file, you should be able to look at manifest to determine the minimum CIQ/firmware versions for that version of the app.

(* which is also the maximum CIQ version that you can safely *assume* is present)

Some anecdotal evidence: look at all the threads complaining that users can't install Spotify on their device because it has old firmware. There's also another thread that directly addresses this topic, but I don't have a link to it at the moment.

You can also test this for yourself by hand-editing a device file to increase the API version or firmware version to be greater than what's installed on your real device, uploading a beta app built against that device file, and observing what happens when you try to install it.

By the way, as far as what's in the manifest.xml file, this is what I pretty much always have:

minApiLevel="1.2.0"

The TL;DR is that the firmware version and CIQ version in a device's compiler.json are in fact the minimum versions your app will see on the device, when your app is built against that version of the device file; if the device doesn't have those versions, the store will prevent the user from installing the app.

This is the cause of the infamous complaints about being unable to install Spotify (for example) without a device update.

But yes, it is possible for a device to have a lower or higher version. If the version is lower, then they will be asked to update their app. If the version is higher, the app will install without any problems.