Note: This module is a low-level API that is not intended to be used by most developers.
The DevicePlugin wraps the underlying ActiveX or Mac OS X browser plugin API in a system independent manner.
This API provides the lowest level of interaction with the plugin and the GPS device connected to your machine. It simply wraps all of the plugin functions and exposes the primitive and xml information that the plugin accepts and returns.
It allows the user to:
All of the xml information that is referenced by the plugin is defined in the xsd you can see here: GarminPluginAPIV1.xsd Using this xml structure, you can upload from the device waypoints, trackpoints and metadata as well as download routes or tracks to the device.
The way the demo page is designed, the page itself has a 1:1 mapping from each button on the page to a javascript function that handles the UI portion of the page. You will find that each of those functions in turn call a function in demo page. The functions in GarminGpsPluginSetupTest.js finally make the call to methods of GarminGpsPlugin.js. The reason is to allow demo page to act as a set of standalone tests at some point in the future.
The quickest way to start developing is to take a look at the demonstration page (see the API Demo above). If you have the plugin and a device connected to your computer your are good to go!
This is a overview of the demonstration page usage and what to expect when using the demo page.
Here are sequence diagrams of these operations:
Before you do anything with the plugin, check to make sure that it's installed on your machine for the browser you're using. Then unlock the plugin with your site key and code. And finally, show what devices are connected to your machine. Then we can get on to reading from and writing to the device.
The JavaScript has a couple of dependencies in order for it to work properly. First off you need the plugin installed on your machine for your particular browser. Then, you need a key and a code to unlock the plugin before you can do anything with it. The demo page pre-loads the key for the url displayed in the popup. See the menu items called 'Get The Plugin' and 'Get Your Site Key' for actually getting the plugin on your browser and getting a site key for where you are running it.
On the demo page the first button you will see is called 'Determine if Plugin Installed'. This will show you if the plugin has been installed in the browser you are running. If the browser has the plugin installed you will see a alert popup window displaying the the text: "Plugin Found.". If it is not found you will see the text: "Plugin NOT Found."
The second button will unlock the device and start to look for devices plugged into your machine. If the plugin is found, you will see a prompt box displaying the url that you are running this help from and pre-populated in the input box is the key for this url. Once again, if you want this plugin to work on your site you will have to generate your own key - See the 'Get Your Site Key' menu item on the left. If the plugin is unlocked, you will see a popup displaying the text:'Plugin unlocked for : your url here'. Otherwise it will display: 'Plugin could not be unlocked using your code for the url: your url here'.
Once the steps listed in above are successfully completed, we can find out what devices are connected and what number they have been assigned by the plugin.
This is a two step process for the JavaScript considering that it is an asynchronous API. Step one is Initiating a Read and step two is checking that the read has completed. If the read has completed (check the completion state returned by finishReadFromGps()), then get the GpsXml read out of the device.
Hitting 'Start Reading From Device' will initiate a read that will execute and return immediately. Once this has been initiated, the plugin and the device are communicating and any information that the device has is in the process of being sent to the plugin.
You should see the Test Page display some text in the small window indicating that a read from the device has been initiated.
Once the read has been initiated, the second step is checking that the read operation has completed by hitting the (Finish Reading) button. This action also happens asynchronously and you will then see an alert of what the Completion state is. This is the value returned from the finishReadFromGps() method that indicates what state the plugin is in from your initiated read. Considering that this operation is asynchronous, you must keep polling with finishReadFromGps() and examining the returned value before you can reliably access the information that it has read. Once the finishReadFromGps() function returns a value of '3' which is 'finished', then you can call getGpsXml() to get the actual data.
Take a look at the finishReadAndGetData() on GarminGpsPluginSetupTest.js to see how this is handled.
You should see the Test Page display the xml information in the display window. It will also increase the size of the window and allow scrolling.
The Finish Reading button will perform three functions: 1) Show the completion state 2) If the completion state is '2' or waiting, show the user the GPS progress xml and return. 3)If the completion state is '3' or finished, return the GPS Xml from the device.
The completion state is nothing more that an integer that maps to a particular state of the plugin while an asynchronous operation is under way. Here are a list of possible completion states: 0: idle 1: working 2: waiting 3: finished
The GPS Xml returned should conform to: GPX.XSD . Therefore it can contain elements like waypoints, trackpoints and routes as well as metadata.
Just like Reading, this is a two step process for the JavaScript considering that it is an asynchronous API. Step one is initiating a write and step two is checking that the write has completed. You know your done when the the completion state returned by finishWriteToGps() is 'finished'.
Before hitting any buttons to write information to the device, you need some xml information to write to the device and a filename you want it to have once it has been written to the device. The filename should end in .gpx and the xml should conform to the gpx.xsd. See: GPX.XSD.
Just like the Read, this is a two step asynchronous process. Step one, you must initiate a write (Start Writing To the Device) that will execute and return immediately. At this point the plugin and the device are communicating where the information (including the filename) has been sent to the plugin and the plugin is sending it to the device.
The second step is checking that the write operation has completed by hitting the (Finish Writing) button. You will then see an alert of what the Completion state is. This is the value returned from the finishWriteToGps() method that indicates what state the plugin is in from your initiated write operation. Again, the plugin operates asynchronous ly meaning that you must keep polling it with finishWriteToGps(), examining the returned value to know when you are done. Once the finishWriteToGps() function returns a value of '3' which is 'finished', then you know you are done. Take a look at the finishWriteToDevice() on API Demo to see how this is handled.
You should see the Test Page display a finished message near the display window.
The Finish Reading button will perform two functions: 1) Show the completion state 2) If the completion state is '2' or waiting, show the user the GPS progress xml and return. 3)If the completion state is '3' or finished, return.
The completion state is nothing more that an integer that maps to a particular state of the plugin while an asynchronous operation is under way. Here are a list of possible completion states: 0: idle 1: working 2: waiting 3: finished
