Xirgo OBD II Protocol Adapter SDK Setup Guide. Version 1.0

Size: px

Start display at page:

Download "Xirgo OBD II Protocol Adapter SDK Setup Guide. Version 1.0"

Laurence Preston Hunter
5 years ago
Views:

1 Xirgo OBD II Protocol Adapter SDK Setup Guide Version 1.0

2 Introduction... 2 About the Protocol Adapter SDK... 2 About Xirgo... 3 Installation... 3 Configuration and Setup... 3 Configuring the Xirgo device... 3 Configuring the Protocol Adapter... 4 Running the Protocol Adapter SDK... 5 Troubleshooting... 7 Compatibility... 8 Document Revision History... 8 Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 1

Introduction About the Protocol Adapter SDK The Internet of Things is a rapidly-growing and oftentimes fragmented network of devices which frequently don t unify under a standardized language which

3 Introduction About the Protocol Adapter SDK The Internet of Things is a rapidly-growing and oftentimes fragmented network of devices which frequently don t unify under a standardized language which connects them easily to each other. There exist many examples of devices which may be perfectly suited to reporting data in a specialized role, but for which their data reporting is shrouded in a proprietary format. When the ThingWorx platform needs to connect to one of these devices, the need for a translator, or Protocol Adapter, arises. The Protocol Adapter SDK is a package provided by ThingWorx for the purposes of connecting such a device, whose firmware and/or data format is unchangeable and incompatible with ThingWorx, to the ThingWorx Platform: Reporting Device Websocket Platform Proprietary Device Protocol Adapter Platform Often, these devices open a TCP or UDP networking socket and send data using a proprietary format. To allow these devices to connect to the ThingWorx Platform, the Protocol Adapter SDK runs intermediary to the device and ThingWorx, and listens on a specified port for any incoming device messages, and it parses the incoming messages from the device s native format into properties that are then transmitted to the ThingWorx Platform. It should be noted that the Protocol Adapter SDK should ideally be set up to run on an intermediary server, separate from the one on which the ThingWorx Platform is located (for scalability purposes). However, the Protocol Adapter SDK may also be run on the same server on which the ThingWorx Platform is located. Typically, when available on devices which are capable, the ThingWorx Edge MicroServer is installed on a client device for collecting and reporting data to ThingWorx using a secure WebSocket connection, instead of the Protocol Adapter SDK. The Edge MicroServer is a powerful component of the ThingWorx architecture. The Edge MicroServer allows for the rapid deployment of connections between the ThingWorx platform and an associated Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 2

4 data reporting device, with minimal design requirements on the part of the user. It provides an alwayson connection to the platform, and it opens a local web server that interacts with the REST API available on the platform. About Xirgo The device Xirgo 2000 series is a versatile plug and play OBD II device. The device monitors and tracks vital information. The device is capable of sending GSM and GPRS messages that constitute the GPS coordinates of the device, speed of the vehicle, the IMEI number of the device, time, date, etc. This guide will follow the steps in configuring the Xirgo device to report data to a ThingWorx server via the Protocol Adapter SDK. The Protocol Adapter SDK allows only for one-way communication in this case. Installation The Protocol Adapter may run on an AWS server or a local machine, but IP address of the server running Thingworx platform should be configured in the Protocol Adapter. Please note that this guide was written for a computer running Microsoft Windows. Refer to the Troubleshooting section of this guide for help with frequently asked questions. Configuration and Setup Configuring the Xirgo device 1. Power on the device by interfacing the device with the OBD II port of the vehicle. 2. Insert a valid SIM card with a cellular data plan into the device in the position indicated on the right. 3. The Xirgo 2000 series have three LEDs to indicate communication behavior of the device. O: The OBD LED is orange in color. It flickers when the ignition of the vehicle is ON and it is OFF when the ignition is turned OFF. C: The cellular LED is blue in color. It blinks every three seconds to indicate that it is connected to the cellular network and it is capable of communicating via SMS messages. G: The GPS LED is green in color. It blinks regularly to indicate a GPS lock. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 3

5 4. The Xirgo device is configured using +XT commands. The commands can be sent via SMS messages if the SIM card has an active data plan or by connecting the Xirgo device to a PC via USB using a TELNET session. The XT commands will remain the same for either methods. 5. In order to receive response messages from the device, the device has to be configured to send response messages to a destination mobile phone number. This has to be configured with the +XT:1008 command on the right. Note: After sending this command all response messages will be sent to this number regardless of the phone number of the device from which the commands were sent. 6. Configure the device with the APN of the SIM network by using the command on the right. +XT:1008,<phone_number> Note: Replace <phone_number> with the destination mobile phone number. +XT:1002,,,<apn> Note: Replace <apn> with the APN of the network to which the SIM card is configured. The empty fields in the above command are for username and password in case the cellular network is configured to it. 7. Configure the device to the IP address and port number of the server running the Protocol Adapter such that the Protocol Adapter server receives the messages sent from the device containing vital information from the device. +XT:1001,<server_port>,< server_ip_address>,2 Note: Replace <server_port> and <server_ip_address> with the port and IP address of the server running the Protocol Adapter. Configuring the Protocol Adapter 1. Included in the starter kit for the Xirgo Protocol Adapter SDK package, you ll find a file labeled config.json in the root level of the Xirgo.zip package. Open this file for editing with a text editor. In config.json, change the value of socketport under ConnectionServerSettings to the port to which the device has been configured to, in the above given steps. The Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 4

6 Protocol Adapter will be listening on this port. Remember that the GPRS port for the device is the same. 2. In config.json, change the thingworxserverapikey to an Application Key currently being used by your Thingworx application. Set the thingworxserver and thingworxserverport to the IP address and port number, respectively, of the machine that is running the Thingworx platform. Your configuration should be similar to the image on the right. The socketport is set to the port number to which the device has been configured. The socketprotocol is set to UDP since messages from the device are sent in data packets. Running the Protocol Adapter SDK Before running the Protocol Adapter SDK, make sure that the Thingworx application is running on the referenced port and server address. Make sure that the Xirgo device is plugged in, switched ON, and it is located in an area with clear GPS signal (such as a window or outside area). 1 Using Eclipse IDE: Import the project into the eclipse workspace. File->Import- >Java->Existing Projects -> browse to the folder containing the project. Note: Create a new Java Project in your IDE if necessary before importing. 2 Build a Runnable JAR file using File > Export > Runnable JAR File, and run it Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 5

7 from command line (alternatively, run within Eclipse IDE) using the command: Java jar <jar-filename>.jar 3 While the program is running, you should see a series of output messages, beginning with a successful connection message, and including an Accepted client connection message indicating that the Protocol Adapter is receiving an incoming message from the Xirgo device (see the example log below). If you do not receive these messages in the log, verify that the connection settings on both your Xirgo device and in the config.json files are correct. In addition, verify that the specified listener port is open on your server and that no firewalls are blocking the UDP connection. 4 When your Protocol Adapter listener successfully receives a connection from the Xirgo device, it should automatically create a remote thing on your ThingWorx instance, to which you may bind a Remote Thing entity on the platform and add data bindings. Data forwarded from the Protocol Adapter will be visible under Manage Remote Bindings on a Remote Thing entity in ThingWorx which carries the same name/identifier as that created by the Protocol Adapter on the platform. Above: Successful data reporting from the Protocol Adapter to the Thingworx platform. Note the value of isconnected is set to True. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 6

8 Troubleshooting Problem Solution(s) 1. Not receiving any response message from the device. 1. Ensure that the device is configured with the correct phone number, APN on which the response is expected. 2. Ensure that the IP Address and Port number are the same as the IP address and Port on which the Protocol Adapter server is running. 3. Ensure that the SIM card is valid and the cellular LED is briefly blinking every 3 seconds indicating cellular connectivity. 4. Ensure that the Protocol Adapter is running on the specified IP address and listening on the specified port number. 5. Ensure that the firewall is disabled for the specified port number for UDP connection on the server running the Protocol Adapter. 2. Protocol Adapter SDK giving error: Refilling connections on [endpoint 0, uri: ws://localhost:80/thingworx/ws] failed : Connection authentication/registration FAILED 1. Ensure that the config.json has the correct port number, server address, and Application key for the Thingworx application. 2. Ensure that Tomcat is running and ThingWorx is running at the specified port. 3. Verify that the specified port is open and that your url is correct. Try to connect with SSL disabled. 5. While the Xirgo device is running and reporting data to the server, the Protocol Adapter SDK is merely stating the following debug message: [ClientHandler: ] Client has been idle, sending websocket ping... The Xirgo device is not able to connect to the Protocol Adapter SDK. 1. Ensure that the Cellular LED is blinking every 3 seconds and GPS LED is blinking to verify connectivity. 2. Ensure that the Xirgo device is kept somewhere outside building to obtain GPS coordinates, since GPS doesn t work in indoor environments. Verify your SIM card s data and GPRS capability and try an alternate SIM card if necessary. 3. Check the Xirgo device +XT command settings and make sure that the GPRS server hostname is set to the public IP address of the Computer/AWS server running the Protocol Adapter SDK. Ensure that Protocol Adapter is listening on the UDP port is the same as the port number to which the device is configured. 4. Ensure that config.json is configured correctly and it is modified accordingly with a valid Thingworx App-key, Thingworx server IP address, Thingworx server port number. 5. Disable firewall setting for the UDP port on the server on which the Protocol Adapter is listening. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 7

9 Compatibility This guide has been tested for compatibility with the Xirgo Device and the following ThingWorx platform, server, and operating system: ThingWorx Platform Version ThingWorx 6.5 OS Xirgo Device Windows 7, Service Pack 1, Windows Server 12 hosted on AWS Xirgo 2000 series Document Revision History Revision Date Version Description of Change October 12, Initial Release Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 8

B&B Spectre LTE Edge MicroServer Setup Guide

B&B Spectre LTE Edge MicroServer Setup Guide July 2015 Table of Contents 1. Introduction... 1-1 About the Spectre LTE... 1-1 2. Installation... 2-1 Set up the Spectre LTE... 2-1 Set up the ThingWorx Application...