garmin-plugin /

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. That may change, as less dependencies is better.



    // Put the listeners you want in this.
    var delegate = {};
    var g = Garmin.Communicator(delegate, true);

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

Your delegate's attributes that match the various events are then called when an event occurs. You can also manually set listeners for the events like $(document).on('onFinishReadFromDevice', handler). The handler will recieve a jQuery Event object, and depending upon the event, there may also be a data object. contains a reference to the controller object.


  $(function() {
    var g = 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 usage is new: there may still be some bugs (like things happening before the devices are loaded), as I'm still looking into the bare constructor.


To be finalised. Source code contains some info about this, but may change.


Called before the search for devices occurs.