question

stephenm27 avatar image
stephenm27 asked

Garmin OneHelm details?

Hello,

Does anyone know the html5 app deployment process that is expected by the Garmin OneHelm MFDs in order to display the button for on the OneHelm page (e.g. Victron app)?

Background:

The MFD is broadcasting a SSDP query for upnp:rootdevice every 5 seconds on the Garmin network. If my software responds with a SSDP notify that identifies a location (e.g. http://172.16.57.150:8000/venus-data.zip), the MFD proceeds to download it, however I still do not see the Victron button in the OneHelm page on the MFD. This zip file has been created using the tools in the venus html5 app repo so I was hoping it would be structurally correct for use via OneHelm.

Does anyone have any ideas as to what I might be missing to make it show up in OneHelm on the MFD?


marine mfd apphtml5garmin
2 |3000
Toggle Comment visibility. Current Visibility: Viewable by all users

Up to 8 attachments (including images) can be used with a maximum of 190.8 MiB each and 286.6 MiB total.

6 Answers
stephenm27 avatar image
stephenm27 answered ·

The details to enable custom software to appear as a OneHelm applet on Garmin MFDs:

  • Multicast DNS
    • a mDns server must be running on the network interface that is on the same network as the Garmin MFD
    • a txt record having the name "_garmin-mrn-html" that has the following options must be served:
      • protovers: 1
      • path: <path to json file>
  • HTTP
    • a HTTP server must be running on the network interface that is on the same network as the Garmin MFD
    • a json file having the name/path specified in the mDns txt record above must exist and minimally include the following properties:
      • path: the path (url stem) to the root of the OneHelm app
      • title: the title for the application
      • icon: url for the OneHelm applet icon to display
      • id: generated app guid used by the OneHelm infrastructure to distinguish apps

With these two services configured, it can be observed that the Garmin MFD will routinely request the mDNS record, followed by a request for the json config file specified therein, followed by a HTTP request for the path property specified in the json config file.

Notes:

  • There appears to be no current restriction to force use of HTTPS/SSL (bad).
  • Chrome developer tools enable UI mock-up using specified screen aspect ratios so development can be done in absence of the MFD (good).

I've now deployed a vessel monitoring and control system that leverages the MFD via OneHelm as an available interface (in addition to requisite iOS devices).

Some selected UI snaps as rendered via Chrome for a GPSMap 922 MFD:

screenshot-2023-11-01-at-120953-pm.png

screenshot-2023-11-01-at-121026-pm.png

screenshot-2023-11-01-at-121052-pm.png


Hope this helps someone else get started...I'll answer any questions I can for those headed down this path.

-enjoy

sdm


screenshot-2023-11-01-at-120953-pm.png (62.3 KiB)
screenshot-2023-11-01-at-121026-pm.png (76.4 KiB)
screenshot-2023-11-01-at-121052-pm.png (63.8 KiB)
1 comment
2 |3000
Toggle Comment visibility. Current Visibility: Viewable by all users

Up to 8 attachments (including images) can be used with a maximum of 190.8 MiB each and 286.6 MiB total.

tmorton avatar image tmorton commented ·
This is great information @stephenm27 Thank you for sharing!
1 Like 1 ·
Peter Buijs - NL avatar image
Peter Buijs - NL answered ·

https://www.victronenergy.com/live/venus-os:mfd-garmin

Does this help?


2 |3000
Toggle Comment visibility. Current Visibility: Viewable by all users

Up to 8 attachments (including images) can be used with a maximum of 190.8 MiB each and 286.6 MiB total.

stephenm27 avatar image
stephenm27 answered ·

While that document is the most detailed I’ve been able to find, it’s unfortunately missing the specific app deployment details for OneHelm apps. I can’t determine for example, if the MFD expects the html app to be bundled in a single zip file, packaged as a tar file with a manifest, etc. I’ve mimicked what the Venus html app does (using a RasperryPi) without any success.

If I had a working example to examine or a tcpdump from a working scenario, I could sort it out. As you might imagine, Garmin offers no documentation for this and does not respond to requests from individual users regarding OneHelm.

I’m hoping someone in the Victron user community has conquered this as it seems they are extremely technically savvy users…


2 |3000
Toggle Comment visibility. Current Visibility: Viewable by all users

Up to 8 attachments (including images) can be used with a maximum of 190.8 MiB each and 286.6 MiB total.

rwspalding avatar image
rwspalding answered ·

I have been asking Garmin for years about this and they will not disclose the implementation. What I think is happening is that the MFD finds the web server on the Victron device (via UPnP) and then pulls up the HTML5 code on the MFD. The HTML "app" on the MFD then starts listening for MQTT data. I don't think that the Garmin MFD consumes a zip or any other package as that would suggest a 3rd party software installation on the Garmin device.....Garmin would not allow that.

2 |3000
Toggle Comment visibility. Current Visibility: Viewable by all users

Up to 8 attachments (including images) can be used with a maximum of 190.8 MiB each and 286.6 MiB total.

stephenm27 avatar image
stephenm27 answered ·

Update: properly configuring multicast DNS and UPnP will enable you to have your own custom app show up on the MFD as a OneHelm application. It took significant reverse-engineering but I have finally succeeded in doing this.

Ultimately, I'm not entirely clear why Garmin has not publicly documented this for use by independent developers as there is no "hacking" involved--just a collection of properly configured services.

12 comments
2 |3000
Toggle Comment visibility. Current Visibility: Viewable by all users

Up to 8 attachments (including images) can be used with a maximum of 190.8 MiB each and 286.6 MiB total.

klangen avatar image klangen commented ·
Hi @stephenm27 do you mind share any details about this here or in a PM?
0 Likes 0 ·
stephenm27 avatar image stephenm27 klangen commented ·
PM me and I'll be happy to share what I learned to make it work.
0 Likes 0 ·
klangen avatar image klangen stephenm27 commented ·
New to this forum and was thinking I could send PM's haha Don't see a way but please send an email to buga_brusa0j@icloud.com (proxy email as I don't want to publish my own here)
0 Likes 0 ·
klangen avatar image klangen klangen commented ·
@stephenm27 Sorry apple has some problem so the proxy email did not work, so if you have sent something could you please send it again? Sorry for the trouble!
0 Likes 0 ·
bain-gurley avatar image bain-gurley commented ·
@stephenm27 Would you mind sending me the same information? I've been trying to reverse-engineer OneHelm for a while and cannot get it. Like @Klangen I just joined to respond to this post and can't PM. Could you send the information to 4thegoals [at] protonmail.com ? thanks so much.
0 Likes 0 ·
spah avatar image spah commented ·
Hi @stephenm27 I'm also trying to create a custom html5 App for my GpsMap, it's working right now, except for the SSDP / MDNS part.

Any chance you can send me ( sebastien[at]pahour[dot]com ) the protocol you've discoverd ?

Best regards


0 Likes 0 ·
stephenm27 avatar image stephenm27 spah commented ·

See the accepted answer for this thread...it has all known details. If you have specific questions, I'm happy to try to answer those.

0 Likes 0 ·
spah avatar image spah stephenm27 commented ·

@stephenm27 not shure I've understood this part correctly :

  • Multicast DNS
    • a mDns server must be running on the network interface that is on the same network as the Garmin MFD
    • a txt record having the name "_garmin-mrn-html" that has the following options must be served:
      • protovers: 1
      • path: <path to json file>


My software has a mDns server started and shows the following values when called with zeroconf :

| ----------------------------------------------
| HOST
| ----------------------------------------------
| Id: 172.16.65.119
| DisplayName: esp32
| IPs: 172.16.65.119
| Services: 1
| -------------------
| Service #0
| -------------------
| Service: _garmin-mrn-html._tcp.local.
| ServiceName: esp32._garmin-mrn-html._tcp.local.
| Port: 80
| TTL: 120
| PropertySets: 1
| -------------------
| Property Set #0
| -------------------
| path = /config.json
| protovers = 1
| name = _garmin-mrn-html
| -------------------
| -------------------


Everything seems OK ... but it's not seen by GPSMAP, it never asks for "config/json"

0 Likes 0 ·
stephenm27 avatar image stephenm27 spah commented ·

I think I know what the issue is, but would like to confirm before I provide details. I should be able to verify in the next day or so (I need access to my Garmin MFD).

0 Likes 0 ·
spah avatar image spah stephenm27 commented ·
@stephenm27 thank you so much ! Waiting to read you soon. Best regards.
0 Likes 0 ·
stephenm27 avatar image stephenm27 spah commented ·

From my brief review over the weekend, there is potentially the need to respond to the SSDP/UPNP discovery broadcast that the Garmin MFD is constantly sending (port 1900 tcp). The response should contain:

  • USN field specifying the uuid of your application (create your own using uuidgen)
  • LOCATION field that is the URL (e.g. http://172.16.62.9:8000/onehelm/upnp.xml) to a xml descriptor file similar to the following:
<?xml version="1.0" encoding="utf-8"?>
<root xmlns="urn:schemas-upnp-org:device-1-0">
  <specVersion>
    <major>1</major>
    <minor>0</minor>
  </specVersion>


  <device>
    <deviceType>urn:schemas-upnp-org:device:Basic:1</deviceType>
    <friendlyName>App Name</friendlyName>
    <manufacturer>Your company name</manufacturer>
    <manufacturerURL></manufacturerURL>
    <modelName></modelName>
    <modelNumber></modelNumber>
    <modelURL></modelURL>
    <serialNumber></serialNumber>
    <presentationURL>/</presentationURL>
    <UDN>uuid:43b78dbe-b1ef-11ed-a269-b827eb0b1de2</UDN>
  </device>
</root>

Once the Garmin MFD receives this UPNP response, it will retrieve the above descriptor. Note that it appears this descriptor is cached indefinitely by the Garmin so once received, it may not be downloaded again immediately (TTL value specified in the UPNP response may affect this).

The uuid specified in this descriptor must match the id field in the JSON config file advertised by the mDNS server.

I believe this is the missing piece that you need. As you might expect, there was significant debugging effort required and ultimately some elements were not deemed necessary to enable OneHelm. Unfortunately, UPNP was believed to be one of these when I initially updated this thread. Hope this helps...enjoy!


0 Likes 0 ·
spah avatar image spah stephenm27 commented ·

@stephenm27 Thanks a lot for the time spent on analysing the protocol and for answering to me ! Reading your message I'm pretty shure you're right and the UPNP part is certainly the missing one in my application. Will implement this. Best regards.

0 Likes 0 ·
tal-maizels avatar image
tal-maizels answered ·

Hi, I wonder if someone bumped into the same issue. We also have an html5 app running on Garmin MFD through OneHelm. We're using python ZeroConf to register the service and usually it works great. Sometimes we notice that when MFD and our server loads, the mDNS broadcast starts but Garmin doesn't register the service. Only if we restart the python service it succeeds.

If someone run into this issue, i'd love to hear about it.


Thanks,

2 |3000
Toggle Comment visibility. Current Visibility: Viewable by all users

Up to 8 attachments (including images) can be used with a maximum of 190.8 MiB each and 286.6 MiB total.

Related Resources

Additional resources still need to be added for this topic