Class Garmin.DeviceControl

Object
   |
   +--Garmin.DeviceControl

class Garmin.DeviceControl

Garmin.DeviceControl 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

Requires:

- BrowserDetect
- Garmin.DevicePlugin
- Garmin.Broadcaster
- Garmin.XmlConverter

Field Detail

FILE_TYPES

<static> Object FILE_TYPES

Constants defining possible file types associated with read and write methods.

FINISH_STATES

<static> Object FINISH_STATES

Constants defining possible states when you poll the finishActions

MESSAGES

<static> Object MESSAGES

Constants defining possible errors messages for various errors on the page

TRANSFER_DIRECTIONS

<static> Object TRANSFER_DIRECTIONS

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

Garmin.DeviceControl

Garmin.DeviceControl()

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

Requires:
- BrowserDetect
- Garmin.DevicePlugin
- Garmin.Broadcaster
- Garmin.XmlConverter

cancelFindDevices

void cancelFindDevices()

Cancels the current find devices interaction.

Minimum Plugin version 2.0.0.4

cancelReadFromDevice

void cancelReadFromDevice()

User canceled the read.

Minimum plugin version 2.0.0.4

cancelWriteToDevice

void 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

checkForUpdates

void checkForUpdates()

Checks plugin for updates. These updates are not required, though an exception is thrown, so use this function with caution.

downloadToDevice

void downloadToDevice(xmlDownloadDescription, filename)

Writes GPI info to the currently selected device.

Minimum plugin version 2.0.0.4

Parameters:
xmlDownloadDescription - {String} xml string to be written to the device.
fileName - {String} the filename to write the data to.

findDevices

void 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()

getCompressedFitnessData

Object 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()

getDevices

Array getDevices()

Get a list of the devices found

getDeviceStatus

Garmin.TransferProgress getDeviceStatus()

Get the status/progress of the current state or transfer

getGpsData

Object 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

Object 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()

getPluginVersion

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()

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()

getReadCompletionState

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

void initialize()

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

isPluginInitialized

Boolean isPluginInitialized()

Determines if the plugin is initialized

isPluginInstalled

Boolean isPluginInstalled()

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

isUnlocked

Boolean isUnlocked()

True if plugin has been successfully created and unlocked.

readCourseDetailFromFitnessDevice

void readCourseDetailFromFitnessDevice(<String> 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:
courseId - The name of the course on the device.

See:
- readDetailFromDevice()

readCoursesFromFitnessDevice

void 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

void readDataFromDevice(<String> fileType)

Generic read method, supporting GPX, TCX, Courses, Workouts, User Profiles, TCX activity directory, and TCX course directory reads.

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

Parameters:
fileType - Possible values for fileType are located in Garmin.DeviceControl.FILE_TYPES--detail types are not supported.

See:
- readDetailFromDevice()
- Garmin.DeviceControl.FILE_TYPES

readDetailFromDevice

void readDetailFromDevice(<String> fileType, <String> 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 this.gpsData as an XML DOM and this.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:
fileType - Filetype to be read from the device. Supported values are Garmin.DeviceControl.FILE_TYPES.tcxDetail and Garmin.DeviceControl.FILE_TYPES.crsDetail
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.

See:
- readDataFromDevice()
- readHistoryDetailFromFitnessDevice()
- readCourseDetailFromFitnessDevice()

readFromDevice

void 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()

readHistoryDetailFromFitnessDevice

void readHistoryDetailFromFitnessDevice(<String> 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:
historyId - The ID of the history record on the device.

See:
- readDetailFromDevice()

readHistoryFromFitnessDevice

void 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

void 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

void 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

void register(<Object> 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:
listener - Object that will listen for events coming from this object

See:
- {Garmin.Broadcaster}

respondToMessageBox

void respondToMessageBox(<Number> response)

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

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

setDeviceNumber

void setDeviceNumber(<Number> deviceNumber)

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

Parameters:
deviceNumber - The device number

setPluginRequiredVersion

void 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]

unlock

Boolean unlock(<Array> pathKeyPairsArray)

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

Minimum Plugin version 2.0.0.4

Parameters:
pathKeyPairsArray - baseURL and key pairs.

Returns:
True if the plug-in was unlocked successfully

writeAddressToDevice

void writeAddressToDevice(<String> address)

Writes an address to the currently selected device.

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

writeFitnessToDevice

void writeFitnessToDevice(tcxString, fileName)

Writes the given TCX Course XML string 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.

writeToDevice

void 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

void writeUserProfileToFitnessDevice(tcxString, fileName)

Writes the given TCX User Profile XML 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

void writeWorkoutsToFitnessDevice(tcxString, fileName)

Writes the given TCX Workouts 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.