ThinkGeo Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Map Suite GPS Tracking Server Device Gateway Overview ======

The Map Suite GPS Tracking Server Device Gateway is a concept that allows for easy integration of custom GPS tracking hardware and functionality.  In order to help you understand how the Device Gateway works and how you can leverage its built-in web services, let's first take a look at the overall architecture of Map Suite GPS Tracking Server and how all of its components work together.

===== Map Suite GPS Tracking Server Architecture =====

<div floatright captionwithborder marginleft10px>
{{gpstrackingserver:Map Suite GPS Tracking Server Complete System Diagram.jpg ?250|Map Suite GPS Tracking Server Overview Diagram}}
\\
GPS Tracking Server Overview Diagram
</div>


Map Suite GPS Tracking Server is made up of three main parts:

  - The Web Portal
  - The Device Gateway
  - The Device Listeners

==== The Web Portal ====
The Map Suite GPS Tracking Server web portal is the web-based user interface where users can login to track the devices and interact with them.

==== The Device Gateway ====
The Map Suite GPS Tracking Server Device Gateway is a centralized database that allows multiple Map Suite GPS Tracking Server web portals to interact with a number of different devices in a common and robust way.  The Gateway is made up of a simple set of secure web service APIs that allow developers to easily integrate custom devices or sensor logic into Map Suite GPS Tracking Server.  The web service APIs were built with flexibility in mind, making custom integration easy and requiring no code changes to the Map Suite GPS Tracking Server web portal.

Some of the tasks that the Device Gateway handles include:

  * Posting location information
  * Facilitating two-way device communication
  * Raising device- or sensor-triggered alerts
  * Handling custom device or sensor data

==== The Device Listeners ====
The device listeners are custom programs that are built to communicate directly with a specific set of GPS tracking devices.  The device listener handles all communication to the end device, whether it is TCP, UDP, HTTP, SMS or any other communication protocol of your choosing.  It's the device listener's job to then transform the data it receives from the device and post it to the Map Suite GPS Tracking Server Device Gateway via the web service API.  Additionally, for devices with two-way communication support, the device listener must read data from the Map Suite GPS Tracking Server Device gateway and push it out to the device.

If you're interested in building your own device listener, start by downloading the [[Map Suite GPS Tracking Server Gateway SDK for .NET|Gateway SDK for .NET]] and the variety of [[Map Suite GPS Tracking Server Sample Listeners|Sample Listeners]] that we've prepared to help you learn the process.  During your development, you will likely find two tools invaluable.  One is the Device Simulator, a tool that helps you simulate posting locations, custom data, device triggered alerts and two-way communication.  The other is the Gateway Message Log, a web page that will help you check to see whether your custom listener is posting to the Gateway properly.  Both tools are included with your purchase of the Map Suite GPS Tracking Server.

===== Working with the Device Gateway =====
The Map Suite GPS Tracking Server Device Gateway will be an invaluable tool when you're adding support for custom tracking devices, sensors or functionality.  In order to work with the Map Suite GPS Tracking Server Device Gateway you will first need an API key.  Your API key will allow you to successfully authenticate against your Map Suite GPS Tracking Server's Device Gateway and encrypt all communication between your device listener and the gateway itself.

===== Device Gateway Web Service API Overview =====
The Map Suite GPS Tracking Server Device gateway is comprised of a web service that exposes four web methods through a WSDL SOAP based interface.  You can access the web services from your application by creating a web service reference to a particular URL on your Device Gateway server.  For instance, if your Device Gateway is hosted at <nowiki>http://gateway.mytrackingsystem.com</nowiki>, create a web service reference to <html> <i>http://gateway.mytrackingsystem.com/Gateway.asmx </i></html>.

==== Posting Data to the Device Gateway ====
Typically, the first functionality you will want to implement is the ability to post a tracking device's GPS location, device alerts, and custom data your Map Suite GPS Tracking Server.  This can all be accomplished with the ''DeviceMessageInsert'' web method.

<code csharp>
PostDeviceMessage(APIKey As string,  XMLmessage As string) As string
</code>

The ''DeviceMessageInsert'' method takes two parameters: ''APIKey'' and ''XMLmessage''.

''APIKey'' - For this parameter, enter your individual Map Suite GPS Tracking Server API key.  You received your API key when you signed up for your Map Suite GPS Tracking Server Starter Edition account.

''XMLmessage'' - This parameter represents the XML message that you will be posting to the Device Gateway.  Creating the XML message will be the main task of your custom device listener.  The XML message is made up of several elements that allow it to be flexible and that also provide enough information for the Map Suite GPS Tracking Server web portal to function properly.  You can download a detailed schema of the XML document from a particular URL on your Device Gateway server.  For instance, if your Device Gateway is hosted at <nowiki>https://gateway.thinkgeo.com</nowiki>, you can download the XML schema from <tt><nowiki>https://gateway.thinkgeo.com/LocationMessage.xsd</nowiki></tt>.

Below is a summary of each element included in the XML message document.

''<LocationMessage>'' - Required top-level element that encapsulates the entire XML message.

:  ''<DeviceID>'' - Required element that contains the ID of the device that is posting the information.  If your device is using cellular technology, this is typically the IMEI or ESN number.
	
:  ''<UtcDateTime>'' - Required element that contains the UTC time at which the information was received from the device.
	
:  ''<Longitude>'' - Required element that contains the longitude (X) coordinate of the device's location.
	
:  ''<Latitude>'' - Required element that contains the latitude (Y) coordinate of the device's location.
	
:  ''<GpsAccuracyInMeters>'' - Required element that represents the accuracy of the location coordinates that the device is reporting.  If you don't know the accuracy of your GPS device, we suggest you put a default value that is greater than 0.  (If you put 0, Map Suite GPS Tracking Server will disregard the location information and not trigger any location-based alerts.)
	
:  ''<AltitudeInMeters>'' - Required element that represents the altitude of the location that the device is reporting.  If no altitude is known, put 0.
	
: ''<SpeedInKph>'' - Required element that represents the current speed (in kilometers per hour) that the device is traveling at.
	
: ''<Idle>'' - Optional element that represents whether the device's status is idling or not. If you don't know or your device doesn't support idling, put 0.
	
: ''<Heading>'' - Required element representing the current heading in degrees (0-360) that the device is reporting.  If no heading is known, put 0.
	
: ''<RawDebugMessage>'' - Required element representing the entire raw message from the device before it was parsed.  This information can sometimes be helpful for troubleshooting and debugging device problems.  If no debugging information is needed, you can leave this element blank.
	
: ''<DeviceAlerts>'' - Optional element that will contain one or many ''<DeviceAlert>'' elements (see below).
	
:: ''<DeviceAlert>'' - Optional element that represents a device triggered alert.  One &lt;DeviceAlert&gt; element should be included for each alert that will be triggered.  For example, if you had both an AirBag alert and an OpenDoor alert triggered, there would be two <DeviceAlert> elements, one for each individual alert.
	
: ''<CustomData>'' - Optional element that will contain one or many child ''<CustomData>'' elements (see below).
	
:: ''<CustomData Name="Custom Data Name" MIMEType="Data Type">'' - Optional element that represents any custom data that the device may be providing.  This element also has two attributes called ''Name'' and ''MIMEType''.  The ''Name'' attribute controls the name that you want to give to the CustomData (for instance, "Photo File" or "Engine RPM") while the ''MIMEType'' attribute represents the MIME type of the custom data (for instance, "image/jpeg" or "text/plain").  For reference, here is [[http://www.utoronto.ca/webdocs/HTMLdocs/book/book-3ed/appb/mimetype.html|a list of available MIME types]].

Once you have created a valid XML document, the only thing left to do is populate the ''XMLmessage'' parameter and execute the web method.  Once you do, the new data should be visible in your Map Suite GPS Tracking Server web portal within a few seconds.

===== Implementing Two-Way Device Communication with the Device Gateway =====
Depending upon your requirements, it may be necessary to add support for two-way communication between your GPS tracking device and Map Suite GPS Tracking Server.  Many scenarios, such as on-demand tracking and reconfiguring devices over the wire, require two-way functionality.  The Map Suite GPS Tracking Server Gateway has a simple set of web methods that your device listener can poll that will allow you to implement two-way functionality for your device.

==== Receiving Device Commands ====
You can use the ''GetDeviceCommandsForApplication'' method to receive device commands from your Map Suite GPS Tracking Server.  Your device listener should poll this web method approximately every 30 to 60 seconds to see if a new device command has arrived.

<code csharp>
GetDeviceCommandsForApplication(APIKey As string,  ApplicationID As string) As string
</code>

This method will return an XML document that contains any pending device command message(s) for your Map Suite GPS Tracking Server installation.  Below is an explanation of the XML document that is returned:

''<DeviceCommandMessages>'' - Top-level element of the XML document that will encapsulate all of the device command messages.

:  ''<DeviceCommandMessage>'' - Parent element for a device command message.
	
::   ''<DeviceCommandMessageID>'' - Unique ID of the device command message.
	
:::    ''<DeviceID>'' - This is a unique identifier for the actual tracking device.  It's typically a phone number or email address, which allows the listener to proactively communicate with the device.
			
:::    ''<Parameters>'' - Parent element for all of the device command message's parameters.
			
:::: ''<Parameter Name="Parameter Name">'' - This element contains any parameter information needed for the device command message to be processed by the listener.

==== Updating Device Commands ====
Once you have successfully processed the device command in your device listener, you will want to update its status so that the end user knows whether the command completed successfully or not.  To do this, use the <code>UpdateDeviceCommandStatus</code> method described below.  (If you don't update the status, the Map Suite GPS Tracking Server Device Gateway will automatically expire the device command message after a specified amount of time.)

<code csharp>
UpdateDeviceCommandStatus(APIKey As string, ID As string, Status As string) As string
</code>

This method takes three parameters: <code>APIKey</code>, <code>ID</code> and <code>Status</code>.

''APIKey'' - For this parameter, enter your individual Map Suite GPS Tracking Server API key.  You received your API key when you signed up for your Map Suite GPS Tracking Server Starter Edition account.

''ID'' - For this parameter, enter the ID number of the device command message that you wish to update.

''Status'' - For this parameter, enter the string value for the updated status.  For example, you may want the status to show "Completed", "Still in Process", or "Error".  This string will be visible to users within the Map Suite GPS Tracking Server web portal.  The actual status message is flexible, so you are free to update it to whatever you want your users to see.

**Note:** The <code>UpdateDeviceCommandStatus</code> method can be called multiple times for the same device command message ID, allowing you to give the end user continued updates on the status of a single device command.

===== Using the Device Simulator to Test Your Custom Listener =====
The Device Simulator tool was developed to help you test the custom device listeners you develop by simulating the data posting and two-way communication methods described above.  The Device Simulator is included free with your purchase of the Map Suite GPS Tracking Server.

===== Getting Help =====
We've set up a dedicated [[http://gis.thinkgeo.com/forums|Support Forum]] for issues and questions regarding the Map Suite GPS Tracking Server Device Gateway and Device Simulator tool.  If you need help, simply post in the forums and one of our Map Suite GPS Tracking Server support specialists will be happy to lend a hand.
User Tools

Site Tools

Page Tools
