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... 2-2 3. Further Customization... 3-6 Application Explanation... 3-6 4. Troubleshooting... 4-10 5. Compatibility... 5-11
1. Introduction 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 data reporting device, with minimal design requirements on the part of the user. The Edge MicroServer provides an always-on connection to the platform, and it opens a local web server that interacts with the REST API available on the platform. The ThingWorx C SDK provides the libraries and tools for necessary for developers to create a custom application for interfacing with the ThingWorx platform. This document provides installation and usage instructions for setting up the ThingWorx C SDK with the B&B Electronics Spectre LTE Router. About the Spectre LTE The Spectre LTE is a multi-port gateway device manufactured by B&B Electronics Corporation. It provides cellular internet connection to connected devices over 2G, 3G, and 4G LTE networks, and features integrated WiFi b/g/n router connectivity. The device is designed to be operable in a wide range of temperature environments. The ThingWorx C-SDK distribution may be installed on the Spectre LTE, and this guide will follow the procedure for doing so along with the Conel C SDK. This guide will also follow the features involved with using the Conel C SDK to use a demo application, and the ThingWorx C-SDK to connect the device to the Platform. Page 1-1
2. Installation Setup of the Spectre LTE will first require the following prerequisites: A B+B Smartworx / Conel V2 Router and power supply (you can order from here: http://www.bb-elec.com/products/wireless-cellular/cellular- Routers.aspx) An Ethernet Cable (you will receive this with your router) A PC running Linux (you only need to run Linux if you want to modify B&B s example code, and compile your own) A ThingWorx Platform Server Installed and set up o Tutorial can be found here (https://twc.thingworx.com/thingworx/filerepositorydownloader?downlo ad- repository=thingworxpublicrepository&downloadpath=%2fdocumentation%2f5+0+install+and+configuration.pdf ). o You will need a ThingWorx User Community login (https://twc.thingworx.com/thingworx/twc_welcome.htm l) The packaged example for this starter-kit (thingworx-v2.tgz), which is also available for download here: https://github.com/bbelec/thingworx/releases/download/v1.1.1/thingworx-v2.tgz Refer to the Troubleshooting section of this guide for help with frequently asked questions. Set up the Spectre LTE 1. The Start Guide for V2 routers here: conel.com. To insure you get the correct version select the router you have from the following table here (http://www.conel.com/routers-gprs-edge-umts-hsdpa-hsupa-hspa/). Click on your router and then go to the Downloads tab. You will need to create a free account and sign-in. Follow the instructions in the Start Guide to login to the Router. When you are finished, you should be able to log in to the router after connecting it to your computer with an Ethernet cable (url: http://192.168.1.1). The default login credentials are: Username: root Password: root Page 2-2
2. Your router should have a web interface similar to the screenshot at right. 3. On the router s interface page, select User Modules under Customization on the left side column. Set up the ThingWorx Application 1. This Starter Kit includes an example ThingWorx application. This example periodically sends statistics about the router to the ThingWorx platform. Page 2-3
2. On the router s User Modules page, click Choose File next to New Module. Here, locate the thingworx.tgz file, which will be located among the extracted folders of the thingworx-v2.tgz archive, in the following directory: /router/application/thingworx.tgz Next, click the Add or Update button to add it to the list. Your User Modules page should look like the one at right: 3. Click the Application s name to open it for configuration. Enter the address for your ThingWorx Platform Server. Enter v2thing in the Thing Name Field to use the provided example application. You ll also need to provide an application key for your ThingWorx platform. You can create these in your ThingWorx Composer. Be sure you check the Enable ThingWorx Client checkbox at the top. Leave the other fields alone, and click Apply. Page 2-4
4. On your ThingWorx Composer, click Import/Export at the top-right, and choose Import from File. Ensure Entities is chosen. 5. Navigate to the location of your extracted v2 files, and import the v2thing.xml file. It is located in the extracted file system under /thingworx-v2/server/v2thing.xml. Click Import. Note: If you encounter an error while importing at this stage, see the Troubleshooting section, item #1. 6. Three new entities should appear in your Composer: v2thing, v2key, and v2mashup. 7. From here, select v2mashup, and then make sure Info is selected on the top bar, and Mashup Preview is selected on the menu under Entity Information: Page 2-5
Page 2-6
3. Further Customization The following section contains information provided by B&B Electronics for the purposes of customizing your particular setup with ThingWorx using example code and the Router and Conel SDKs. Application Explanation The User Module uses the Conel C SDK (you can get this from here: https://github.com/bb-elec/v2- api-public/releases/download/v1.0.0/sdk-v2.tgz) and some in-built functions on the router, to get data from the router. These data values, provided in the example in this guide, are: - Data transferred over the LAN connection - CPU temperature - Supply voltage. - Value on Binary GPIO In - Value on Serial Port 1 Additionally the application provides a service that writes high or low on the Binary GPIO Out pin. Retrieving Properties The following code snippets retrieve the data values from the router, using the Router s C API. The ThingWorx C SDK handles connecting to the server and sending the data (refer to the ThingWorx C SDK documentation for a better explanation of how it connects and sends data). The ThingWorx SDK has a function called datacollectiontask, which is used to get the values to send to the server. To get the temperature of the CPU, we use the V2 GPIO API call: The temperature is given in degrees kelvin, so first you convert to Celsius (-=273), and then set the temperature property. The next example makes use of the status command, which is a system-command on the router: Page 3-6
This captures the output of the status command, and then parses it to obtain just the value. Another API call is used to get the value on the GPIO In 0: Getting the value on the serial line is slightly more complicated. The API contains a function to open the port, but you ll need to set some parameters (baudrate, stopbits etc.): Here we use the local web server on the device to configure the serial port. Next, the port is opened, read from, and closed. It is important to close the port file descriptor after use. Page 3-7
Using Services To perform some operation on the device that can be triggered from the ThingWorx Server a service is needed. This application uses a service that writes high or low on the GPIO Out pin. This service is called from the server and a value to write on the GPIO is retrieved from the remote call. The value is then written to the output pin using the V3 GPIO API. Page 3-8
To Augment the Provided Example The first thing you need to do is setup your environment. Router SDK: - Download the Router SDK - Extract the Router SDK to the ROOT directory $ tar -zxf SDK-v2.tgz -C / Get the Router C SDK from here: (https://github.com/bb-elec/v2-apipublic/releases/download/v1.0.0/sdk-v2.tgz) Thingworx SDK: - Download the ThingWorx C SDK (https://support.ptc.com/appserver/auth/it/esd/product.jsp?prodfamily=tws) - In your home directory create a directory called Thingworx $ mkdir ~/ThingWorx - Extract the ThingWorx C SDK to this directory $ unzip C-SDK-1.0.0.27.zip -d ~/ThingWorx/ ThingWorx application example: - Download the ThingWorx application example - Extract the example to the ThingWorx directory you already created $ tar -zxf thingworx-v2.tgz -C ~/ThingWorx/ Get the example from here: (https://github.com/bbelec/thingworx/releases/download/v1.1.1/thingworx-v2.tgz) The following steps describe how to build the supplied example: - At this stage you should have a directory in HOME called ThingWorx with tow directories in it: thingworx-v2 and tw-c-sdk - You should also have a directory called STM in /opt - To compile go into thingworx-v2 then router then src and run make: $ cd ~/ThingWorx/thingworx-v2/router/src $ make - When make is finished there should be an archive called thingworx-v2.tgz; this is what goes on the router under User Modules. Page 3-9
4. Troubleshooting Problem Solution(s) 1. Error encountered while attempting to import the v2thing.xml entity package. 1. Your version of the ThingWorx platform may be incompatible with the version of the extension or file you are attempting to import. 2. Try updating your ThingWorx Composer to the latest version. If that fails, open the v2thing.xml in a text editor, and modify the information in the <Entities build=.> tag (first line in the file), and modify the build, majorversion, minorversion, revision, and schemaversion values to match those of your Composer. To get the values correct, Try exporting a Thing from your Composer, and check the values of these parameters and match them to those in the v2thing.xml file. 3. Check the ThingWorx Application Log file under Monitoring at the top right to read details about your error. It is possible that the import requires the presence of an entity, such as the v2valuestream entity. Create a new Value Stream if this is the case named v2valuestream, which is based on a RemoteValueStream template. Following the save of this entity, attempt to import the xml file again. 2. No data is sent to the ThingWorx Platform from the router. 1. This is likely a problem with your ThingWorx Client Module configuration on the router s User Modules page. Verify that the following information is correct: 1) The IP address or url of the ThingWorx Server, including the port; 2) The spelling of the Thing Name which binds properties from the Remote router Thing; 3) the Application Key (try using an application key with administrative rights). Also, verify that the Enable ThingWorx Client checkbox is checked. Page 4-10
5. Compatibility This guide has been tested for compatibility with the Spectre LTE and the following systems and platform versions: Software Version ThingWorx Platform ThingWorx 6.0.1 OS Windows 7, Service Pack 1 BnB Spectre LTE Firmware 3.1.1 (2014-30-05) Page 5-11