ThingWorx Lantronix PremierWaveXN Edge MicroServer Installation and Setup Guide

ThingWorx Lantronix PremierWaveXN Edge MicroServer Installation and Setup Guide July 2015

Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. User and training guides and related documentation from PTC Inc. and its subsidiary companies (collectively PTC ) are subject to the copyright laws of the United States and other countries and are provided under a license agreement that restricts copying, disclosure, and use of such documentation. PTC hereby grants to the licensed software user the right to make copies in printed form of this documentation if provided on software media, but only for internal/personal use and in accordance with the license agreement under which the applicable software is licensed. Any copy made shall include the PTC copyright notice and any other proprietary notice provided by PTC. Training materials may not be copied without the express written consent of PTC. This documentation may not be disclosed, transferred, modified, or reduced to any form, including electronic media, or transmitted or made publicly available by any means without the prior written consent of PTC and no authorization is granted to make copies for such purposes. Information described herein is furnished for general information only, is subject to change without notice, and should not be construed as a warranty or commitment by PTC. PTC assumes no responsibility or liability for any errors or inaccuracies that may appear in this document. The software described in this document is provided under written license agreement, contains valuable trade secrets and proprietary information, and is protected by the copyright laws of the United States and other countries. It may not be copied or distributed in any form or medium, disclosed to third parties, or used in any manner not provided for in the software licenses agreement except with written prior approval from PTC. UNAUTHORIZED USE OF SOFTWARE OR ITS DOCUMENTATION CAN RESULT IN CIVIL DAMAGES AND CRIMINAL PROSECUTION. PTC regards software piracy as the crime it is, and we view offenders accordingly. We do not tolerate the piracy of PTC software products, and we pursue (both civilly and criminally) those who do so using all legal means available, including public and private surveillance resources. As part of these efforts, PTC uses data monitoring and scouring technologies to obtain and transmit data on users of illegal copies of our software. This data collection is not performed on users of legally licensed software from PTC and its authorized distributors. If you are using an illegal copy of our software and do not consent to the collection and transmission of such data (including to the United States), cease using the illegal version, and contact PTC to obtain a legally licensed copy. Important Copyright, Trademark, Patent, and Licensing Information: See the About Box, or copyright notice, of your PTC software. UNITED STATES GOVERNMENT RESTRICTED RIGHTS LEGEND This document and the software described herein are Commercial Computer Documentation and Software, pursuant to FAR 12.212(a)-(b) (OCT 95) or DFARS 227.7202-1(a) and 227.7202-3(a) (JUN 95), and are provided to the US Government under a limited commercial license only. For procurements predating the above clauses, use, duplication, or disclosure by the Government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software Clause at DFARS 252.227-7013 (OCT 88) or Commercial Computer Software-Restricted Rights at FAR 52.227-19(c)(1)-(2) (JUN 87), as applicable. 01012015 PTC Inc., 140 Kendrick Street, Needham, MA 02494 USA

Table of Contents 1. Introduction... 1-1 About the Lantronix PremierWaveXN... 1-1 2. Installation... 2-1 Connect the PremierWaveXN to a local machine... 2-1 Download and Install the EMS MicroServer Package... 2-5 3. Configuration and Setup... 3-7 Setting up a WebSocket Connection... 3-7 Configuring and Running an Application... 3-11 Communicating via Serial Port... 3-15 Using lua Scripts... 3-17 4. TroubleShooting... Error! Bookmark not defined. Copyright 2015 ThingWorx, a PTC Business i

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. This document provides installation and usage instructions for setting up the Edge MicroServer with the Lantronix PremierWaveXN Application Server. About the Lantronix PremierWaveXN The PremierWave XN is a multi-port device server manufactured by Lantronix Corporation. It provides wifi-connectivity, supports data encryption, controls serial communication with other remote devices or computers, and features two serial ports, two USB ports, and a LAN port for connections. The Edge MicroServer Linux-ARM distribution may be installed on the PremierWaveXN, and this guide will follow the procedure for doing so. This guide will also follow the features involved with simulating a connection and pushing and pulling data from the PremierWaveXN device via Serial port. Page 1-1

2. Installation Setup of the PremierWaveXN device with an EMS will first require connecting to the device from a computer via Ethernet cable and a local DHCP Server. 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. Connect the PremierWaveXN to a local machine 1. Begin by downloading the DHCP server installer for Windows from: http://www.dhcpserver.de/cms/ 2. In Windows, before installing the DHCP server, open Network and Sharing Center, and then click the link on the left for Change Adapter Settings Page 2-1

3. Right-Click on Local Area Connection, and choose Properties. 4. Select Internet Protocol Version 4, and then click Properties. Click the button for Use the following IP address, and set a private IP address that starts with 192.168. Subnet Mask may be left as 255.255.255.0 5. Power on the Lantronix PremierWaveXN device, and connect it to your computer with an Ethernet cable. Note: From here on out, you may wish to disable any connection to another network to avoid Page 2-2

causing ip address conflicts with other devices on your local network. 6. Extract the DHCP Server package downloaded earlier, and run the dhcpwiz executable. Follow the steps in the wizard to get to the Network Interface Cards screen. 7. Select Local Area Connection, and confirm that its DHCP setting is disabled by default. 8. On the next screen, check HTTP (Web Server) and leave the others unchecked. Click Next. Page 2-3

9. Set the IP-Pool to a reasonable range which contains your local machine s IP address (chosen earlier). Click Next. 10. Check Overwrite Existing File, then click Write INI file. Click Next, then Finish. 11. Open the dhcpsrv program as an Administrator. 12. Check Firewall Enabled, click Configure. Install the service if you have not yet done so. Finally, click the Start button to begin running the DHCP Server. Note: If you have an instance of Apache Tomcat or any other local server running, you should stop it before clicking Start on the DHCP Server. 13. Open up a browser, and type in localhost/dhcpstatus.xml into the address bar. The Lantronix should be detectable and listed as a client, with an IP address assigned. Page 2-4

14. Open a linux terminal on the computer to connect to the Lantronix device via SSH. Use a program such as Putty or Cygwin. 15. The default username is root and the default password is also root. Download and Install the EMS MicroServer Package 1. Download the ThingWorx Edge MicroServer from the PTC Software Downloads site under Thingworx Edge MicroServers at https://support.ptc.com 2. Select the latest version of the MicroServer-xx-yy-zz-Linux-ARM. Important Note: Packaged in this Starter-Kit are the files config.json, config.lua, testsample.lua, and testtemplate.lua. The config.json and config.lua files should be copied to the /etc/ directory in the downloaded MicroServer folder. The testtemplate.lua and testsample.lua files should be copied to the following directories: etc/custom/template/testtemplate.lua etc/custom/sscripts/testsample.lua Page 2-5

3. In your command window connected to the PremierWaveXN, type the following command to copy the MicroServer to the device s file system (see right): scp r MicroServer root@192.168.137.2:/ltrx_user/microserver Note that this command will only work if the MicroServer folder, which was downloaded from the PTC Downloads site, is located in the root directory of the terminal program you are using to connect to the PremierWaveXN. For example, ensure the MicroServer root folder is copied to the home/username/ directory inside the Cygwin installation directory if you are using Cygwin terminal. Be sure to use the ip address of your actual device in place of the one listed above. 4. Enter root if prompted for a password. The copy should complete successfully. Page 2-6

3. Configuration and Setup Setting up a WebSocket Connection 1. On the PremierWaveXN, navigate to the /ltrx_user/microserver/etc/ folder. 2. The directory should list three configuration files. We will be modifying these existing configuration files for a quick startup. Note: There are example configuration files contained within the /etc/ folder which can be used as a starting point for setting up your configuration file. Config.json.minimal and config.json.complete are both there. The configuration file used by the EMS ultimately is whichever file is named just config.json. This guide will follow the steps necessary to modify the example config files that come with the EMS MicroServer package. For additional guidance and examples on setting a configuration file, please refer to http://support.ptc.com/cs/help/thingworx_hc/thingworx_6.0_hc/ and follow the guide section entitled ThingWorx WebSocketbased Edge MicroServer (WSEMS) 3. In the terminal, open the config.json.minimal file for editing using the vi command. For reference, enter vi config.json.minimal in the terminal window. Page 3-7

4. Modify the parameters in the file using the appropriate methods so that the file has parameters which resemble the screenshot at right: Note: It is important to supply your own appkey generated on the Thingworx platform, and your own chosen ip address and port. 5. The parameters used in the creation of this guide are shown at right for convenience. Your config file should resemble this when finished. { "http_server": { "host": "127.0.0.1", "port": 8000 }, "ws_servers": [{ "host": "192.168.137.1", "port": 80 }], "appkey": "YOUR APPKEY HERE", "resource": "/Thingworx/WS", "logger": { "level": "DEBUG" }, } "auto_bind": [{ "name": "MyGateway", "gateway": true }], "ws_connection":{ "encryption": "none", "verbose": true, "msg_timeout": 1000 } Page 3-8

6. This file should be saved as config.json and any file already there under that name should be overwritten. It may be more conducive to do this from the local computer and copy the MicroServer back over to the PremierWaveXN when finished. 7. Navigate back to the /MicroServer/ directory. 8. Type chmod 777 wsems to make this file permissible for execution. 9. Run the program by typing./wsems. You should see a screen resembling the following at right if it is functioning properly: Note that you should be running a local instance of the Thingworx Composer on your computer connected to the PremierWaveXN, and the server should be back online. Start Tomcat before running wsems. Page 3-9

10. In ThingWorx Composer, click the Monitoring drop-down, choose subsystems, and then click WS Communications and Refresh Now. You should see an active websocket listed. 11. Click Monitoring again, and choose Remote Things. From here, click the tab at the top labeled Unbound Things. Page 3-10

12. An unbound remote thing representing the PremierWaveXN device s EMS server should be listed here. The name is dependent on that supplied in the configuration file. Configuring and Running an Application 1. On the PremierWaveXN, navigate to the /etc/ directory again. 2. Open the config.lua file for editing. 3. Set the scrips.log_level parameter to DEBUG. This will provide you with more test information if needed. 4. Add the following lines to the script (see right): 5. Add or modify the following line in scripts.testthing, and leave the others as default: scripts.rap_host = 127.0.0.1 scripts.rap_port = 8000 identifier = test Page 3-11

6. Your config.lua file should resemble the following: 7. Save and close the file. 8. Type chmod 777 luascriptresource in the terminal. 9. Run wsems by typing./wsems. If it reports that it connected successfully to the Thingworx Platform, then open a second command window in the same directory on the PremierWaveXN, and type./luascriptresource. Page 3-12

10. On the Thingworx Composer, navigate to the Monitoring page, and click on Remote Things. Select the Unbound Tab, and you should be able to see MyGateWay and test listed (name varies depending on the chosen name in the config files). 11. Create a new Thing in Composer, that implements the RemoteThing Thing Template. 12. Click Browse next to its Identifier field on the right, and choose the identifier named Test. Save the entity. Page 3-13

13. Click Properties on the left, and check the value under isconnected. It should be set to true now. 14. Finally, click Manage Bindings, and then the Remote tab. Here, you should see a list of available properties to bind, from the EMS device. Page 3-14

Communicating via Serial Port This section will guide you through the process of using a connected PC to simulate a datareporting device using the ThingWorx Data Injector, and using it to connect to the Lantronix via serial port. 1. Verify that the PremierWaveXN is connected to the computer via serial cable, or serial to USB cable. Connect the serial cable to the PremierWaveXN s port 1. 2. In Google Chrome, download and install the Chrome ThingWorx Data Injector application at: https://chrome.google.com/webstore/detail /thingworx-datainjector/fplddibkdnnainjhgjddkgnlbiebnabc 3. Run the Thingworx Data Injector application. Choose 3-Bar Protocol from the Device drop-down, and ensure the value for Port is a recognized valid Port (use default value if in doubt), and choose 9600 for Baud Rate. Click Connect. You should see the Status Message change to Connected. For help, refer to the troubleshooting section of this document. Page 3-15

4. To test the connection between the PC and the Lantronix, press the Send button on the Data Injector. 5. In the Lantronix (via terminal), from the root MicroServer directory, type the following command (on right): cat < /dev/ttys2 6. You should see, in the terminal the values and names chosen in the Thingworx Data Injector. Note: If you do not see them, try opening ttys1, or ttys3 (depends on the serial port used). 7. Next, type the following command: echo e OK > /dev/ttys2 8. You should see the OK response in the data injector. Page 3-16

9. Refer to the terminal window screenshot at right to verify your commands: Using lua Scripts There is a file packaged into the MicroServer folder named luascriptresource. This executable uses the parameters specified in the config.lua file to connect to the web server opened up by the EMS. This webserver is then used to connect to the ThingWorx Platform. There are three files used in this section for configuration: etc/config.lua etc/custom/template/testtemplate.lua etc/custom/sscripts/testsample.lua Page 3-17

1. Open up the config.lua, and configure the properties as follows (see right): This will declare a thing named TestThing, and it will use the testtemplate.lua template to define specific properties and services. 2. Add the following line to the config.lua file as well (see right). This will point the script resource to use testsample.lua which contains lua functions for the EMS to call. 3. Define a property in the file testsample.lua (see right): BaseType defines the type of the property as it will appear on the ThingWorx platform. PushType defines whether or not the change of value of this property is to be pushed to the server. Handler tells the EMS to call a function in the script for this property. Key is the path to the function. Value is set to default a so that a default value exists. When we change the value later, we ll be able to confirm that the change has been made. Page 3-18

4. In the testsample.lua file, implement the following (see right): This property_string function collects the data sent in from the serial port to the ttys2 port (this file is a repository for data sent via serial port 1 to the PremierWaveXN). The ThingWorx data injector running on the laptop sends the formatted data to the serial port of the device, where it is collected. Then, the script sends the collected data, formatted in json, to the ThingWorx platform. It also writes a response message to the serial port afterwards, and the data injector will receive and display this message on the computer. 5. Back on the ThingWorx platform, create a thing named testthing, and implement the RemoteThing thing template. 6. Run./wsems on the PremierWaveXN. Open a second command window, and run./luascriptresource. Page 3-19

7. On the ThingWorx platform, select testthing, and click Browse next to its identifier field on the General Properties section. Here, select testit. 8. Click the Properties section of this Thing. Create a new property named testthing (STRING). Click Manage Bindings, then click Remote, and then add the testscriptdemo remote property to the testthing local property by clicking and dragging. 9. Under Remote Binding Info, set the Cache Options field to Fetched from Remote Every Read. Page 3-20

10. On the ThingWorx Data Injector application, click the Send button. 11. Immediately afterwards, you should see the content originally sent by the data injector appear on the ThingWorx platform as values for the testthing property. If you don t see it right away, click the refresh button. In the ThingWorx Data Injector, you should be able to see the response value listed in the Response field. This value was specified in the lua script. See the additional screenshot below. Page 3-21

4. Troubleshooting Problem Solution(s) 1. Cannot connect to localhost/dhcpstatus.xml in the browser. DHCP Server s management page can conflict with Tomcat s server manager page, when both are running at the same time. Turn off tomcat while trying to access the DHCP management page, and restart it after setting the configurations for the DHCP server. Otherwise, verify that DHCP server has been installed and configured correctly. 2. Encounter No such file error when attempting to copy the MicroServer folder to the PremierWaveXN device. 3. Cannot connect to My ThingWorx platform via websocket. Ensure that the Microserver folder downloaded from the PTC Downloads site is located in the proper directory of the terminal program you are using. Otherwise, reference it appropriately. For Cygwin, ensure the MicroServer folder is located in the home/username/ directory. 1. Check that the host address for ws_servers. It should refer to the DHCP server that has been set up in section one of this guide. 2. Replace the app_key, in the /etc/config.json file, with your own. You can create an app_key on Thingworx platform under the Application Key section. You can also supply a username and password instead of an appkey. You can find the examples for using usernames instead of appkeys in config.json.complete in the /etc/ directory. 3. Make sure that encryption is set to be none for local tests. It defaults to SSL. 4. Check whether your Windows Firewall has blocked communication by typing wget /your/ip/address/ from the PremierWaveXN. If it appears to be blocked, open Windows Firewall in Control Panel/All Control Panel Items, choose turn windows firewall on or off and select turn off windows firewall on public network location settings. 4. Cannot see the test thing on the ThingWorx Monitoring / Remote Things page. 1. Make sure you are viewing the unbound tab. 2. Confirm that the ip addres and port numbers are correct in the configuration files on the PremierWaveXN. 3. If you receive the following error message: [ERROR] 1970-01-01 06:17:23,899 luainterscriptbinding::l_executecallback: Error executing callback 'Thingworx//scripts/Thingworx/registerIdentifier' Returned: 404 /scripts/thingworx/registeridentifier/ not found Page 4-22

This may be caused by a time and date setting difference between the ThingWorx platform and the PremierWaveXN device. Change the time and date on the PremierWaveXN to match that of the local machine running ThingWorx by using the following command on the device: date s yyyy-mm-dd hh:mm:ss Where year, month, date, hours, minutes, and seconds are replaced by the correct values. Restart wsems and luainterscriptbinding on the PremierWaveXN. 5. While attempting to read data from the remote data injector, I get only unreadable code on the PremierWaveXN. 6. Unable to send data, or cannot see any COM ports for sending data to the PremierWaveXN from the Data Injector. 1. Choose 3-Bar Protocol on the Data Injector. Do NOT choose Lantronix PremierWave 2. Change the Baud value to that accepted by your Lantronix device. 1. You may need to manually install or re-install Device Drivers for the Windows Serial Port. a. Open Device Manager from Control Panel in Windows. b. Click on Ports (COM & LPT), and click Action > Add Hardware / Add Legacy Hardware c. Follow the steps in the wizard to manually add serial port (COM) drivers. d. Restart your computer and attempt to send data again. 2. If you still cannot see data, verify that you have checked all the ttysx files on the PremierWaveXN s /dev/ folder (where x is a number, either 0, 1, 2, or 3). 3. Try using an alternative COM port from the data injector. 4. Attempt to send data without using the data injector, by utilizing the Windows Powershell through Windows Command Prompt (tutorials available through Microsoft). This guide has been tested for compatibility with the Lantronix PremierWaveXN and the following ThingWorx platform and operating system: ThingWorx Platform Version OS ThingWorx 6.0.1 Windows 7, Service Pack 1 Page 4-23