Announcing openHAB for Garmin

[the-ninth (Robert)]

The openHAB app for Garmin is now available in the Garmin Connect IQ Store — ready to bring smart home control to your wrist or bike computer.

After an initial development phase, the app has reached its first official release: v1.0.0.

The app is based on the familiar openHAB sitemap concept. Its entry point is a glance view showing the sitemap name, along with a full-screen widget that presents the sitemap in a menu structure similar to the watch’s native interface:

Sitemaps Features

The app currently supports a useful and well-rounded set of widgets:

• Frame
• Text
• Group
• Switch
• Selection
• Setpoint
• Slider

These features make it possible to display and control nearly all openHAB item types. The app also supports dynamic sitemap elements such as visibility conditions, custom colors, and icons.

The screenshots below show, clockwise from the top left: the menu structure for a sitemap page, the slider/setpoint widget, the rollershutter widget, and a multi-option switch.

Communication & Requirements

• The app communicates via the watch’s Bluetooth Low Energy (BLE) connection to a paired smartphone.
• Command execution uses a newly added REST API endpoint, available in openHAB 5.0 and as a backport for 4.3.x.
• Connectivity behavior differs by platform:
  • On iOS, the app can connect to openHAB servers via HTTP.
  • On Android, the app requires HTTPS with a publicly trusted certificate (self-signed certificates are not supported).
  • This can be achieved by connecting through myopenHAB.org, which provides a secure and trusted HTTPS endpoint.

Due to the app’s complexity and memory demands, it is supported only on devices with sufficient memory and a modern Connect IQ API level. Even on supported devices, large sitemaps may approach system limits. Significant development effort has gone into handling such cases gracefully.

Supported Devices

Examples of supported Garmin devices include:

• Fenix (6 Pro and newer)
• Epix 2 Pro
• Vivoactive (5 and newer)
• Forerunner (recent models)
• Edge (e.g., 540, 1040 — yes, you can now open your garage from your bike computer!)

For a complete list of supported devices, visit the app’s Connect IQ Store page.

Documentation

User documentation is available at:
www.openhab.org/docs/apps/garmin

Roadmap

Development doesn’t stop at v1.0.0. Planned future features include:

• Wi-Fi mode (removing the dependency on a smartphone)
• Improved support for larger sitemaps

[the-ninth (Robert)]

@florian-h05

I am looking forward to trying the app out myself. Probably the time has come for a new watch, my vivoactive is 7 years old, even though everything still works fine, I sometimes would like to have some additional features available. UPDATE: Just ordered a Fenix 6 Pro for a very good price.

The Fenix 6 Pro is not supported yet, but that shouldn’t be a major hurdle. In widget mode, it has more than enough memory to run the app smoothly. The only limitation is in the glance view, where available memory is tighter compared to newer models. I may need to simplify the glance UI slightly to ensure full compatibility.

[the-ninth (Robert)]

Here are a few screenshots from the latest iteration of the app:

The glance serves as the app’s entry point and displays the label defined in your openHAB sitemap.

Upon opening the app, your sitemap is displayed. In this example, it shows three frames and several light switches:

[Mark_VG (Mark)]

Hi
I have installed the App on a Forerunner 255 Music.

Setup to use via https://home.myopenhab.org/
Using Sitemap Name: garmin

Sitemap is:

sitemap garmin label="My Garmin" {
  Frame label="Outside" {
    Switch item=ShellyGateshelly1a4cf12f41d5e10163199231_Power label="Gate Control"
    Switch item=ShellyGateshelly1a4cf12f41d5e10163199231_Input label="Gate State"
  }
}

Works 100% via the Android App, but when using the Garmin Watch I get an error:

“Sitemap: Invalid response, check your app settings”

I cannot see anything wrong with the APP settings?

Thanks
Mark

[dschoepel (Dave J)]

I have a Garmin Approach S62 and would be happy to test functionality. Would this model be compatible with the app your developing?

[the-ninth (Robert)]

Hi Mark,

@Mark_VG

Works 100% via the Android App, but when using the Garmin Watch I get an error:

I think the issue might be the trailing / at the end of the URL. You should enter https://home.myopenhab.org (without the /). I think that will be a common mistake, so I’ll update the app to handle both formats more gracefully in an upcoming version.

Most of my testing so far has been with a local openHAB instance. Now that I’ve started using myopenhab.org more in the simulator, I’ve noticed that it occasionally shows an S-400 error. This shows up as a toast notification (a brief message at the top of the watch screen), indicating that the sitemap polling returned an unexpected result.

I’d be curious to know if you’re seeing the same issue. It might be that the polling interval is too aggressive for myopenhab.org.

By the way, version 0.0.4 now supports text fields. I noticed you’re displaying garage door status in a separate field - I do something similar. With the new text field support, it now looks like this:

[mvbergen]

Hi Robert,

Thank you very much for your work. I am using the app on a Garmin Epix 2 through the myopenhab.org cloud connection. I previously had the “myHomeControl” app running as per the instructions on your blog. With your instructions everything was set up in 5 minutes, including the webhook setup. Your app works way better, as I used to loose connection if I didn’t have Garmin Connect open on the phone (I am using iOS). The idea to use a sitemap is perfect, this saves a lot of configurations in the Garmin ConnectIQ app.

Occasionally (or actually quite frequently) I am seeing the error “Unexpected response: null”. I have seen the S-400 error maybe once only.

I will keep on testing and report if I have any useful findings. For now very happy with your app, it also looks very cool matching with the other Garmin apps (and much better than APICall) with the cool openHAB logo of my favorite home automation system on my favorite watch

[the-ninth (Robert)]

@dschoepel

I have a Garmin Approach S62 and would be happy to test functionality. Would this model be compatible with the app your developing?

Unfortunately, compatibility with the Garmin Approach S62 is unlikely.

As with the Vivoactive 3 discussed earlier in this thread, the S62 provides very limited memory for Connect IQ apps - only 59.9 kB. By comparison, the newer Approach S70 (which I believe is its direct successor) offers around 763 kB, more than ten times as much.

This limited memory must accommodate everything: the application heap, binary code, and any image resources. As a result, both the feature set of the app and the size of the sitemap it displays directly impact memory usage.

In its current state, the latest app version already consumes about 68 kB in my demo setup - with support for just frames, switches, and text elements, and using a relatively small sitemap.

While there’s always potential for further optimization, I don’t expect to achieve compatibility with the S62 or similar-generation devices.

[the-ninth (Robert)]

@mvbergen

Occasionally (or actually quite frequently) I am seeing the error “Unexpected response: null”. I have seen the S-400 error maybe once only.

Both errors are actually the same - the S-400 is used in the toast notification, where there is not enough space to show the full error text.

Do you see the full version (“Unexpected response: null”) error in the glance view or the full-screen widget? If possible, could you take a photo the next time it appears?

I’ve created a GitHub issue to track this:
https://github.com/TheNinth7/ohg/issues/35

If you have a GitHub account, feel free to post the photo there directly. Otherwise, you’re welcome to share it here too

[mvbergen]

@the-ninth

If you have a GitHub account, feel free to post the photo there directly.

Full screen widget photo posted in GitHub

[Mark_VG (Mark)]

@the-ninth

I think the issue might be the trailing / at the end of the URL. You should enter https://home.myopenhab.org (without the /).

Thank you. That was it.

@the-ninth

occasionally shows an S-400

Will monitor.

@the-ninth

With the new text field support, it now looks like this:

Excellent. Will update and see.

Thank you. Hoping to see the Updates to allow native control. Will look at the Webhooks option too in teh next few days.

[dschoepel (Dave J)]

Thanks for the quick response. So, the S70 is a possible candidate. Hmm…

[the-ninth (Robert)]

Update on S-400 / Unexpected response: null Errors

I’ve configured my Garmin watch to access openHAB via myopenHAB.org and can now consistently reproduce the issue.

Throughout the day, I’ve published several updates to the app - the latest is version 0.0.4.3. This version makes the polling interval configurable, with a default of 3000ms. With the longer interval, the errors occur less frequently - but that may simply be because fewer requests are being made, not because the underlying issue is resolved.

Importantly, I’ve also been able to reproduce the issue outside the Garmin app. When repeatedly calling the Sitemap REST API via Firefox, I occasionally receive an HTTP 200 OK response with an empty body.

Initially, I suspected this might be due to rate limiting, but typically rate-limited responses return HTTP error codes like 429 or 503, not a 200.

So it appears the issue is not specific to the Garmin app itself. I’ve started a thread in the myopenHAB subforum to gather more input:

Intermittent Empty Responses with HTTP 200 from myopenHAB Sitemap API

I’m currently testing my openHAB for Garmin app, which regularly polls the sitemap API via myopenHAB.org. Both I and other users have noticed that, occasionally - and somewhat regularly - the API returns an HTTP 200 (OK) status, but with no content in the response body. I’ve reproduced this behavior outside of the Garmin app as well, simply by repeatedly requesting the same URL in Firefox: https://home.myopenhab.org/rest/sitemaps/garmin_demo (garmin_demo is the sitemap name.) Below are the H…

[the-ninth (Robert)]

Until more information is available about the Unexpected response issue, I’ve improved the error handling in version v0.0.5.1:

• The “Unexpected response” is now treated as a temporary communication error. It will be shown as a toast notification, while the menu remains active.
• Only after three consecutive communication errors will a full-screen error be shown to indicate a persistent problem.

[the-ninth (Robert)]

If anyone is able to test the latest version (now 0.0.5.3), I’d really appreciate it if you could let me know whether you’re now only seeing SEMRES errors, or if S-400 is still showing up as well.

On my watch, the app is now quite usable with myopenhab.org. The SEMRES error still pops up occasionally, but thanks to the new error handling, it only appears as a toast notification - so the app remains fully usable.

[Mark_VG (Mark)]

Hi

@the-ninth

latest version (now 0.0.5.3)

How do you see what version is installed? I an seeing S-2 errors

Thanks

[the-ninth (Robert)]

Currently, the installed version is only visible indirectly through the Connect IQ app. If there’s no update option available, you’re likely on the latest version - but keep in mind, Connect IQ can be unreliable in this regard.

I’ve added a feature request to show the version directly within the app:
Add system info view to show app version number · Issue #38 · openhab/openhab-garmin · GitHub

As for the error: the first letter indicates the request type - “S” for sitemap, “C” for command, etc. The number that follows tells you more:

• If it starts with a dash (like -2), it’s a Garmin SDK error.
• If it doesn’t, it’s an HTTP response code from the server.

Garmin explains their error codes here (scroll to “Constant Summary”):
Toybox.Communications
I also plan to include this in the app documentation:
Add troubleshooting section to documentation · Issue #41 · openhab/openhab-garmin · GitHub

Specifically, -2 is BLE_HOST_TIMEOUT, which means there is a timeout between watch and the phone. For reference, -300 would mean a timeout between the phone and the server.

Can you confirm whether your watch has a stable Bluetooth connection to your phone? Is the error persistent, or does it happen only occasionally?

A complete connection loss usually results in error -104, which the app detects and displays as ‘No phone’.

[Mark_VG (Mark)]

Thanks for the explanation. It is my Sons watch - so the error was most likely due to him moving around while I setup his watch.

This did trigger me to try the App again with his phone nowhere near.

The app still opens and shows a status. The “No Phone” error only comes up if you try and toggle a switch etc. Does this mean that the sitemap is cached? There does not seem to be any indication when opening the app that the status may be "stale?

I also just checked with Garmin Express and do not see an option to configure the polling interval - so assume the App version has not updated?

[the-ninth (Robert)]

@Mark_VG

The app still opens and shows a status. The “No Phone” error only comes up if you try and toggle a switch etc. Does this mean that the sitemap is cached? There does not seem to be any indication when opening the app that the status may be "stale?

I also just checked with Garmin Express and do not see an option to configure the polling interval - so assume the App version has not updated?

Yes, it sounds like you’re still using an older version of the app. I use the Garmin Connect IQ phone app to install and update apps myself - I haven’t tried Garmin Express, so I’m not sure how well it works.

You’re also right about the sitemap being cached. This is done to speed up app startup. The sitemap fetched for the glance view is cached as well, so there’s a good chance (though not a guarantee) that the app launches with an up-to-date sitemap. However, if you switch from the glance to the full app before the glance receives a new sitemap, the app may initially still display the older cached version.

Regarding error handling:

• Communication errors currently show up only as toast notifications, which can be a hint that the data is outdated.
• If three consecutive communication failures occur, the app escalates to a full-screen error.

There’s still quite a bit of room for improvement:

• Better differentiation between temporary and fatal communication errors
• Automatically invalidating the cached sitemap after a fatal error
• Passing error states from the glance to the full app - currently, the glance just shows the cached sitemap name or “openHAB” and doesn’t indicate errors

For now, I’m prioritizing better error handling and general stability over new features.

[mvbergen]

Hi Robert,

I waited a bit responding as I was seeing if I could trigger any of the error messages. It takes a while for me before I can see the new version in Connect IQ. Sometimes killing the app / rebooting the phone helps but the latest is 0.0.5.2 for me now.

As I said, the app works flawless without showing connection errors.

• iOS version 0.0.5.2
• openHAB 4.3.5 with webhook binding (0.2.0) setup as per instructions