Garmin Communicator for jQuery

The Garmin Communicator plugin is pretty nice. It allows you to upload/download data to/from your Garmin Heart Rate monitor from a website. As well as Garmin Connect, lots of other sites use it, including Strava, my new favourite fitness tracking site.

One thing that Strava doesn't do is Workouts, which are training plans, and can be scheduled on a compatible HRM, so that you can start a specific workout on a given day without having to navigate through the menus to find it. Workouts can be complicated combinations of rules, like:

  • run for 10 mins, keeping pace below 5:00/km
  • run for 4 km, keeping HR within zone 2
  • rest until I press the button

and so on. I am in the process of writing a web app that allows for creation of these. I know Garmin Connect can do it, but it's a fun exercise. Being able to push the data from my web app to my HRM is kind-of useful.

So, whilst the Communicator plugin is good, the JavaScript API for it is pretty ordinary. For starters, it requires Prototype, and I'm strictly a jQuery guy. I know you can use both, but that's only the start of it.

To use the plugin, you need to include about a dozen JS files. Then, you have to do all of this crazy crap that just doesn't seem necessary. They have their own Broadcaster, which seems to do PubSub, and a couple of libraries for detecting the browser and if the plugin is installed. Then there is the heirarchy of DevicePlugin, DeviceControl and DeviceDisplay.

Anyway, the more I looked through the code, the more I thought it was needlessly complicated. Perhaps it's been written by Java guys.

So, welcome to the replacement.


<script src="jquery.js"></script>
<script src="underscore.js"></script>
<script src="garmin.js"></script>

I'm currently using underscore.js, as it gives a nicer .each() function, and provides _.union() for arrays, and _.range(). That may change, as less dependencies is better. I'd also like to be able to remove the dependence on jQuery. I use the DOM selector a few times, but also construct objects, append to the DOM, and use the $.parseXML() function quite a lot. For now, I'm happy to have these as dependencies.


  $(function() {
    var g = new Garmin.Communicator();
    // Read activities from the device.
    g.readActivities(function(data) {
      // data contains XML!
    // Write workouts to the device.
    g.writeWorkouts("Valid XML data");

This will inject the plugin into the page if it isn't already there, create a new instance of the Garmin.Communicator controller, and start looking for devices right away.

If there is already an instance of the controller, it will just return that.

You may pass an object to the constructor which can have a property unlockCodes, used to pass in the garmin unlock codes for your site:

var g = Garmin.Communicator({unlockCodes: ["foo", "bar"]});

You may generate Garmin Communicator unlock codes at Garmin Communicator API Key Generator. You will need to be registered to generate keys.

Not every method that the plugin (or the original code) has has been exposed: I've only added the bits that I needed as I went along.

There is more documentation, inline in the source file, but can be viewed in a nice way by cloning the repository and opening doc/index.html in a browser.