Class Garmin.DeviceControl

A controller object that can retrieve and send data to a Garmin device. Provides listener and callback functionality.

The controller must be unlocked before anything can be done with it. Then you'll have to find a device before you can start to read data from and write data to the device.

We use the observer pattern to handle the asynchronous nature of device communication. You must register your class as a listener to this Object and then implement methods that will get called on certain events.

Events:

onStartFindDevices called when starting to search for devices. the object returned is {controller: this}

onCancelFindDevices is called when the controller is told to cancel finding devices {controller: this}

onFinishFindDevices called when the devices are found. the object returned is {controller: this}

onException is called when an exception occurs in a method object passed back is {msg: exception}

onInteractionWithNoDevice is called when the device is lazy loaded, but finds no devices, yet still attempts a read/write action {controller: this}

onStartReadFromDevice is called when the controller is about to start reading from the device {controller: this}

onFinishReadFromDevice is called when the controller is done reading the device. the read is either a success or failure, which is communicated via json. object passed back contains {success:this.garminPlugin.GpsTransferSucceeded, controller: this}

onWaitingReadFromDevice is called when the controller is waiting for input from the user about the device. object passed back contains: {message: this.garminPlugin.MessageBoxXml, controller: this}

onProgressReadFromDevice is called when the controller is still reading information from the device. in this case the message is a percent complete/ {progress: this.getDeviceStatus(), controller: this}

onCancelReadFromDevice is called when the controller is told to cancel reading from the device {controller: this}

onFinishWriteToDevice is called when the controller is done writing to the device. the write is either a success or failure, which is communicated via json. object passed back contains {success:this.garminPlugin.GpsTransferSucceeded, controller: this}

onWaitingWriteToDevice is called when the controller is waiting for input from the user about the device. object passed back contains: {message: this.garminPlugin.MessageBoxXml, controller: this}

onProgressWriteToDevice is called when the controller is still writing information to the device. in this case the message is a percent complete/ {progress: this.getDeviceStatus(), controller: this}

onCancelWriteToDevice is called when the controller is told to cancel writing to the device {controller: this}

Defined in: GarminDeviceControl.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	Garmin.DeviceControl() A controller object that can retrieve and send data to a Garmin device.

Field Summary
Field Attributes	Field Name and Description
<static>	Garmin.DeviceControl.FILE_TYPES Constants defining possible file types associated with read and write methods.
<static>	Garmin.DeviceControl.FINISH_STATES Constants defining possible states when you poll the finishActions
<static>	Garmin.DeviceControl.MESSAGES Constants defining possible errors messages for various errors on the page
<static>	Garmin.DeviceControl.TRANSFER_DIRECTIONS Constants defining the strings used by the Device.xml to indicate transfer direction of each file type

Method Summary
Method Attributes	Method Name and Description
	bytesAvailable(relativeFilePath) Determine the amount of space available on a mass storage mode device (the currently selected device according to this.deviceNumber).
	cancelFindDevices() Cancels the current find devices interaction.
	cancelReadFromDevice() User canceled the read.
	cancelWriteToDevice() Cancels the current write transfer to the device.
	checkDeviceReadSupport(datatype) Checks if the device lists the given datatype as a supported readable type.
	checkDeviceWriteSupport(datatype) Checks if the device lists the given datatype as a supported writeable type.
	checkForUpdates() Checks plugin for updates.
	doesCurrentDeviceSupportHealth() Returns true if FIT health data can be read from the device.
	downloadFirmwareToDevice(updateResponsesXml) Download and install a list of unit software updates.
	downloadToDevice(xmlDownloadDescription) Downloads and writes binary data asynchronously to device.
	findDevices() Finds any connected Garmin Devices.
	getBinaryFile(relativeFilePath, relativeFilePath) Return the specified file as a UU-Encoded string Minimum version 2.6.3.1 If the file is known to be compressed, compressed should be set to false.
	getCompressedFitnessData() Returns the last read fitness data in compressed format.
	getCurrentDeviceXml() Returns the DeviceXML of the current device, as a string.
	getDeviceNumber() Get the device number of the connected device to communicate with (multiple devices may be connected simultaneously, but the plugin only transfers data with one at a time).
	getDevices() Get a list of the devices found
	getDevicesCount() Number of devices detected by plugin.
	getDeviceStatus() Get the status/progress of the current state or transfer
	getGpsData() Returns the GPS data that was last read as an XML DOM.
	getGpsDataString() Returns the GPS data that was last read as an XML string.
	getPluginVersion() Gets the version number for the plugin the user has currently installed.
	getPluginVersionString() Gets a string of the version number for the plugin the user has currently installed.
	getReadCompletionState() Returns the completion state of the current read.
	initialize() Instantiates a Garmin.DeviceControl object, but does not unlock/activate plugin.
	isPluginInitialized() Determines if the plugin is initialized
	isPluginInstalled() Determines if the plugin is installed on the user's machine
	isUnlocked() True if plugin has been successfully created and unlocked.
	mapTcxToFit() Attempts to map a TCX fitness type to the corresponding FIT type.
	readCourseDetailFromFitnessDevice(courseId) Asynchronously reads a single fitness course from the connected device as TCX format.
	readCoursesFromFitnessDevice() Asynchronously reads entire fitness course data (CRS) from the connected device.
	readDataFromDevice(fileType, fileListingOptions) Generic read method, supporting GPX and TCX Fitness types: Courses, Workouts, User Profiles, Activity Goals, TCX activity directory, and various directory reads.
	readDetailFromDevice(fileType, dataId) Generic detail read method, which reads a specific fitness activity from the device given an activity ID.
	readFromDevice() Asynchronously reads GPX data from the connected device.
	readGoalsFromFitnessDevice() Asynchronously reads fitness goals data (TCX) from the connected device.
	readHistoryDetailFromFitnessDevice(historyId) Asynchronously reads a single fitness history record from the connected device as TCX format.
	readHistoryFromFitnessDevice() Asynchronously reads entire fitness history data (TCX) from the connected device.
	readUserProfileFromFitnessDevice() Asynchronously reads fitness profile data (TCX) from the connected device.
	readWorkoutsFromFitnessDevice() Asynchronously reads fitness workout data (WKT) from the connected device.
	register(listener) Register to be an event listener.
	respondToMessageBox(response) Responds to a message box on the device.
	setDeviceNumber(deviceNumber) Sets the deviceNumber variable which determines which connected device to talk to.
	setPluginLatestVersion(reqVersionArray) Sets the latest plugin version number.
	setPluginRequiredVersion(reqVersionArray) Sets the required version number for the plugin for the application.
	toString() String representation of instance.
	unlock(pathKeyPairsArray) Unlocks the GpsControl object to be used at the given web address.
	writeAddressToDevice(address) Writes an address to the currently selected device.
	writeCoursesToFitnessDevice(tcxString, fileName) Writes fitness course data (TCX) to the device selected in this.deviceNumber.
	writeDataToDevice(dataType, dataString, fileName) Generic write method for GPX and TCX file formats.
	writeFitnessToDevice(tcxString, fileName) DEPRECATED - See #writeCoursesToFitnessDevice Writes fitness course data (TCX) to the device selected in this.deviceNumber.
	writeGoalsToFitnessDevice(tcxString) Writes fitness goals data (TCX) string to the device selected in this.deviceNumber.
	writeToDevice(gpxString, fileName) Writes the given GPX XML string to the device selected in this.deviceNumber.
	writeUserProfileToFitnessDevice(tcxString, fileName) Writes fitness user profile data (TCX) string to the device selected in this.deviceNumber.
	writeWorkoutsToFitnessDevice(tcxString, fileName) Writes fitness workouts data (XML) string to the device selected in this.deviceNumber.

Class Detail

Garmin.DeviceControl()

A controller object that can retrieve and send data to a Garmin device.

Requires:: Prototype; BrowserDetect; Garmin.DevicePlugin; Garmin.Broadcaster; Garmin.XmlConverter

Field Detail

<static> Garmin.DeviceControl.FILE_TYPES

Constants defining possible file types associated with read and write methods. File types can be accessed in a static way, like so:

Garmin.DeviceControl.FILE_TYPES.gpx

NOTE: 'gpi' is being deprecated--please use 'binary' instead for gpi and other binary data.

<static> Garmin.DeviceControl.FINISH_STATES

Constants defining possible states when you poll the finishActions

<static> Garmin.DeviceControl.MESSAGES

Constants defining possible errors messages for various errors on the page

<static> Garmin.DeviceControl.TRANSFER_DIRECTIONS

Constants defining the strings used by the Device.xml to indicate transfer direction of each file type

Method Detail

bytesAvailable(relativeFilePath)

Determine the amount of space available on a mass storage mode device (the currently selected device according to this.deviceNumber).
Minimum Plugin version 2.5.1

Parameters:
{String} relativeFilePath: - if a file is being replaced, set to relative path on device, otherwise set to empty string.

Returns:: -1 for non-mass storage mode devices.

See:: #downloadToDevice

cancelFindDevices()

Cancels the current find devices interaction.

Minimum Plugin version 2.0.0.4

cancelReadFromDevice()

User canceled the read.

Minimum plugin version 2.0.0.4

cancelWriteToDevice()

Cancels the current write transfer to the device.

Minimum plugin version 2.0.0.4
Minimum plugin version 2.2.0.1 for writes of GPX to SD Card

checkDeviceReadSupport(datatype)

Checks if the device lists the given datatype as a supported readable type. Plugin version affects the results of this function. The latest plugin version is encouraged. Internal file type support (such as directory types) is detected based on base type. i.e. tcxDir -> tcx, fitDir -> fit

Parameters:
datatype

checkDeviceWriteSupport(datatype)

Checks if the device lists the given datatype as a supported writeable type. Plugin version affects the results of this function. The latest plugin version is encouraged. Internal file types (such as directory types) are NOT detected as supported write types.

Parameters:
datatype

checkForUpdates()

Checks plugin for updates. Throws an exception if the user's plugin version is older than the one set by the API. Plugin updates are not required so use this function with caution.

See:: #setPluginLatestVersion

{Boolean} doesCurrentDeviceSupportHealth()

Returns true if FIT health data can be read from the device.

Returns:: {Boolean}

downloadFirmwareToDevice(updateResponsesXml)

Download and install a list of unit software updates. Start the asynchronous StartUnitSoftwareUpdate operation. Check for completion with the FinishUnitSoftwareUpdate() method. After completion check the DownloadDataSucceeded property to make sure that all of the downloads were successfully placed on the device. See the Schema UnitSoftwareUpdatev3.xsd for the format of the UpdateResponsesXml description

Parameters:
updateResponsesXml

See:: Garmin.DeviceControl.cancelWriteToDevice; Garmin.DevicePlugin.downloadDataSucceeded; Garmin.DevicePlugin._finishWriteToDevice

downloadToDevice(xmlDownloadDescription)

Downloads and writes binary data asynchronously to device.

Minimum plugin version 2.0.0.4

Parameters:
xmlDownloadDescription: {String} XML string containing information about the files to be downloaded onto the device.
This xml must conform to one of two schemas:
GarminPluginAPIV1
DeviceDownloadV1 Recommended

See:: #Garmin.GpiUtil

findDevices()

Finds any connected Garmin Devices. When it's done finding the devices, onFinishFindDevices is dispatched

this.numDevices = the number of devices found
this.deviceNumber is the device that we'll use to communicate with

Use this.getDevices() to get an array of the found devices and this.setDeviceNumber({Number}) to change the device.

Minimum Plugin version 2.0.0.4

See:: #getDevices; #setDeviceNumber

getBinaryFile(relativeFilePath, relativeFilePath)

Return the specified file as a UU-Encoded string
Minimum version 2.6.3.1 If the file is known to be compressed, compressed should be set to false. Otherwise, set compressed to true to retrieve a gzipped and uuencoded file.

Parameters:
{String} relativeFilePath: path relative to the Garmin folder on the device
relativeFilePath

getCompressedFitnessData()

Returns the last read fitness data in compressed format. A fitness read method must be called and the read must finish successfully before this function returns good data.

Minimum plugin version 2.2.0.2

Returns:: Compressed fitness XML data from the last successful read. The data is gzp compressed and base64 expanded.

See:: #readDataFromDevice; #readHistoryFromFitnessDevice; #readHistoryDetailFromFitnessDevice; #readCourseDetailFromFitnessDevice

getCurrentDeviceXml()

Returns the DeviceXML of the current device, as a string.

getDeviceNumber()

Get the device number of the connected device to communicate with (multiple devices may be connected simultaneously, but the plugin only transfers data with one at a time).

Returns:: the device number (assigned by the plugin) determining which connected device to talk to.

{Array} getDevices()

Get a list of the devices found

{Number} getDevicesCount()

Number of devices detected by plugin.

{Garmin.TransferProgress} getDeviceStatus()

Get the status/progress of the current state or transfer

getGpsData()

Returns the GPS data that was last read as an XML DOM.
Pre-requisite - Read function was called successfully.

Minimum plugin version 2.1.0.3

Returns:: XML DOM of read GPS data

See:: #readDataFromDevice; #readHistoryFromFitnessDevice; #readHistoryDetailFromFitnessDevice; #readCourseDetailFromFitnessDevice

getGpsDataString()

Returns the GPS data that was last read as an XML string.
Pre-requisite - Read function was called successfully.

Minimum plugin version 2.1.0.3

Returns:: XML string of read GPS data

See:: #readDataFromDevice; #readHistoryFromFitnessDevice; #readHistoryDetailFromFitnessDevice; #readCourseDetailFromFitnessDevice

{Array} getPluginVersion()

Gets the version number for the plugin the user has currently installed.

Returns:: An array of the format [versionMajor, versionMinor, buildMajor, buildMinor].

See:: #getPluginVersionString

{String} getPluginVersionString()

Gets a string of the version number for the plugin the user has currently installed.

Returns:: A string of the format "versionMajor.versionMinor.buildMajor.buildMinor", i.e. "2.0.0.4"

See:: #getPluginVersion

{Number} getReadCompletionState()

Returns the completion state of the current read. This function can be used with GPX and TCX (fitness) reads.

Returns:: {Number} The completion state of the current read. The completion state can be one of the following:

0 = idle
1 = working
2 = waiting
3 = finished

initialize()

Instantiates a Garmin.DeviceControl object, but does not unlock/activate plugin.

{Boolean} isPluginInitialized()

Determines if the plugin is initialized

{Boolean} isPluginInstalled()

Determines if the plugin is installed on the user's machine

{Boolean} isUnlocked()

True if plugin has been successfully created and unlocked.

{Garmin.DeviceControl.FILE_TYPES} mapTcxToFit()

Attempts to map a TCX fitness type to the corresponding FIT type.

Parameters:
Garmin.DeviceControl.FILE_TYPES: fileType

Returns:: {Garmin.DeviceControl.FILE_TYPES} fileType, null if no mapping exists.

readCourseDetailFromFitnessDevice(courseId)

Asynchronously reads a single fitness course from the connected device as TCX format. Only handles reading from the device in this.deviceNumber.

When the data has been gathered, the onFinishedReadFromDevice is fired, and the data is stored in this.gpsDataString

Minimum plugin version 2.2.0.2

Parameters:
{String} courseId: The name of the course on the device.

See:: #readDetailFromDevice

readCoursesFromFitnessDevice()

Asynchronously reads entire fitness course data (CRS) from the connected device. Only handles reading from the device in this.deviceNumber

When the data has been gathered, the onFinishedReadFromDevice is fired, and the data is stored in this.gpsDataString

Minimum plugin version 2.2.0.1

See:: #readDataFromDevice

readDataFromDevice(fileType, fileListingOptions)

Generic read method, supporting GPX and TCX Fitness types: Courses, Workouts, User Profiles, Activity Goals, TCX activity directory, and various directory reads.

Fitness detail reading (one specific activity) is not supported by this read method, refer to readDetailFromDevice for that.

As of Communicator v3.0.0.0, if TCX data is requested from a FIT device, the plugin will attempt a conversion from FIT to TCX. Note: TCX cannot fully represent FIT, therefore this conversion can be lossy. For guaranteed fidelity when reading FIT files, use getBinaryFile instead.

Examples:

myControl.readDataFromDevice( Garmin.DeviceControl.FILE_TYPES.gpx );

var theListOptions = [{dataTypeName: 'UserDataSync',
                        dataTypeID: 'http://www.topografix.com/GPX/1/1',
                        computeMD5: false}];
myControl.readDataFromDevice( Garmin.DeviceControl.FILE_TYPES.readableDir,
                              theListOptions );

Parameters:
{String} fileType: The filetype to read from device. Possible values for fileType are located in Garmin.DeviceControl.FILE_TYPES -- detail types are not supported.
{Object[]} fileListingOptions Optional: Array of objects that define file listing options.
fileListingOptions properties:
{String} dataTypeName: Name from GarminDevice.xml
{String} dataTypeID: Identifier from GarminDevice.xml
{Boolean} computeMD5: compute MD5 checksum for each listed file

Throws:
: InvalidTypeException, UnsupportedTransferTypeException

See:: #readDetailFromDevice, #getBinaryFile, Garmin.DeviceControl#FILE_TYPES

readDetailFromDevice(fileType, dataId)

Generic detail read method, which reads a specific fitness activity from the device given an activity ID. Supported detail types are history activities and course activities. The resulting data read is available in gpsData as an XML DOM and gpsDataString as an XML string once the read successfully finishes. Typically used after calling readDataFromDevice to read a fitness directory.

Minimum plugin version 2.2.0.2

Parameters:
{String} fileType: Filetype to be read from the device. Supported values are Garmin.DeviceControl.FILE_TYPES.tcxDetail and Garmin.DeviceControl.FILE_TYPES.crsDetail
{String} dataId: The ID of the data to be read from the device. The format of these values depends on the type of data being read (i.e. course data or history data). The CourseName element in the course schema is used to identify courses, and the Id element is used to identify history activities.

Throws:
: InvalidTypeException, UnsupportedTransferTypeException

See:: #readDataFromDevice, #readHistoryDetailFromFitnessDevice, #readCourseDetailFromFitnessDevice

readFromDevice()

Asynchronously reads GPX data from the connected device. Only handles reading from the device in this.deviceNumber.

When the data has been gathered, the onFinishedReadFromDevice is fired, and the data is stored in this.gpsDataString and this.gpsData

See:: #readDataFromDevice

readGoalsFromFitnessDevice()

Asynchronously reads fitness goals data (TCX) from the connected device. Only handles reading from the device in this.deviceNumber

When the data has been gathered, the onFinishedReadFromDevice is fired, and the data is stored in this.gpsDataString

Minimum plugin version 2.2.0.1

See:: #readDataFromDevice

readHistoryDetailFromFitnessDevice(historyId)

Asynchronously reads a single fitness history record from the connected device as TCX format. Only handles reading from the device in this.deviceNumber.

When the data has been gathered, the onFinishedReadFromDevice is fired, and the data is stored in this.gpsDataString Minimum plugin version 2.2.0.2

Parameters:
{String} historyId: The ID of the history record on the device.

See:: #readDetailFromDevice

readHistoryFromFitnessDevice()

Asynchronously reads entire fitness history data (TCX) from the connected device. Only handles reading from the device in this.deviceNumber.

When the data has been gathered, the onFinishedReadFromDevice is fired, and the data is stored in this.gpsDataString

Minimum plugin version 2.1.0.3

See:: #readDataFromDevice

readUserProfileFromFitnessDevice()

Asynchronously reads fitness profile data (TCX) from the connected device. Only handles reading from the device in this.deviceNumber

When the data has been gathered, the onFinishedReadFromDevice is fired, and the data is stored in this.gpsDataString

Minimum plugin version 2.2.0.1

See:: #readDataFromDevice

readWorkoutsFromFitnessDevice()

Asynchronously reads fitness workout data (WKT) from the connected device. Only handles reading from the device in this.deviceNumber

When the data has been gathered, the onFinishedReadFromDevice is fired, and the data is stored in this.gpsDataString

Minimum plugin version 2.2.0.1

See:: #readDataFromDevice

register(listener)

Register to be an event listener. An object that is registered will be dispatched a method if they have a function with the same dispatch name. So if you register a listener with an onFinishFindDevices, and the onFinishFindDevices message is called, you'll get that message. See class comments for event types

Parameters:
{Object} listener: Object that will listen for events coming from this object

See:

respondToMessageBox(response)

Responds to a message box on the device. Minimum version 2.0.0.4

Parameters:
{Number} response: should be an int which corresponds to a button value from this.garminPlugin.MessageBoxXml

setDeviceNumber(deviceNumber)

Sets the deviceNumber variable which determines which connected device to talk to.

Parameters:
{Number} deviceNumber: The device number

setPluginLatestVersion(reqVersionArray)

Sets the latest plugin version number. This represents the latest version available for download at Garmin. We will attempt to keep the default value of this up to date with each API release, but this is not guaranteed, so set this to be safe or if you don't want to upgrade to the latest API.

Parameters:
reqVersionArray: {Array} The latest version to set to. In the format [versionMajor, versionMinor, buildMajor, buildMinor] i.e. [2,2,0,1]

setPluginRequiredVersion(reqVersionArray)

Sets the required version number for the plugin for the application.

Parameters:
reqVersionArray: {Array} The required version to set to. In the format [versionMajor, versionMinor, buildMajor, buildMinor] i.e. [2,2,0,1]

{String} toString()

String representation of instance.

{Boolean} unlock(pathKeyPairsArray)

Unlocks the GpsControl object to be used at the given web address.

Minimum Plugin version 2.0.0.4

Parameters:
{Array} pathKeyPairsArray: baseURL and key pairs.

Returns:: True if the plug-in was unlocked successfully

writeAddressToDevice(address)

Writes an address to the currently selected device.

Parameters:
{String} address: The address to be written to the device. This doesn't check validity

writeCoursesToFitnessDevice(tcxString, fileName)

Writes fitness course data (TCX) to the device selected in this.deviceNumber.

Minimum plugin version 2.2.0.1

Parameters:
tcxString: {String} TCX Course XML string to be written to the device. This doesn't check validity.
fileName: {String} filename to write data to on the device. Validity is not checked here.

writeDataToDevice(dataType, dataString, fileName)

Generic write method for GPX and TCX file formats. For binary write, use #downloadToDevice.

Parameters:
{String} dataType: - the datatype to write to device. Possible values are located in #Garmin.DeviceControl.FILE_TYPES
{String} dataString: - the datastring to write to device. Should be in the format of the dataType value.
{String} fileName: - the filename to write the data to on the device. File extension is not necessary, but is suggested for device compatibility. This parameter is ignored when the dataType value is FitnessActivityGoals (see #writeGoalsToFitnessDevice).

Throws:
: InvalidTypeException, UnsupportedTransferTypeException

See:: #writeToDevice, #writeFitnessToDevice

writeFitnessToDevice(tcxString, fileName)

DEPRECATED - See #writeCoursesToFitnessDevice

Writes fitness course data (TCX) to the device selected in this.deviceNumber.

Minimum plugin version 2.2.0.1

Parameters:
tcxString: {String} TCX Course XML string to be written to the device. This doesn't check validity.
fileName: {String} filename to write data to on the device. Validity is not checked here.

writeGoalsToFitnessDevice(tcxString)

Writes fitness goals data (TCX) string to the device selected in this.deviceNumber. All fitness goals are written to the filename 'ActivityGoals.TCX' in the device's goals directory, in order for the device to recognize the file.

Minimum plugin version 2.2.0.1

Parameters:
tcxString: {String} ActivityGoals TCX string to be written to the device. This doesn't check validity.

writeToDevice(gpxString, fileName)

Writes the given GPX XML string to the device selected in this.deviceNumber.

Minimum plugin version 2.0.0.4

Parameters:
gpxString: XML to be written to the device. This doesn't check validity.
fileName: The filename to write data to. Validity is not checked here.

writeUserProfileToFitnessDevice(tcxString, fileName)

Writes fitness user profile data (TCX) string to the device selected in this.deviceNumber.

Minimum plugin version 2.2.0.1

Parameters:
tcxString: XML (user profile) string to be written to the device. This doesn't check validity.
fileName: String of filename to write it to on the device. Validity is not checked here.

writeWorkoutsToFitnessDevice(tcxString, fileName)

Writes fitness workouts data (XML) string to the device selected in this.deviceNumber.

Minimum plugin version 2.2.0.1

Parameters:
tcxString: XML (workouts) string to be written to the device. This doesn't check validity.
fileName: String of filename to write it to on the device. Validity is not checked here.

Communicator Plugin API Version 1.9

Classes

Class Garmin.DeviceControl