Vantron VT-M2M-TC-VM ThingWorx Setup Guide October 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 PTC software products and software documentation are commercial items as that term is defined at 48 C.F.R. 2.101. Pursuant to Federal Acquisition Regulation (FAR) 12.212 (a)-(b) (Computer Software) (MAY 2014) for civilian agencies or the Defense Federal Acquisition Regulation Supplement (DFARS) at 227.7202-1(a) (Policy) and 227.7202-3 (a) (Rights in commercial computer software or commercial computer software documentation) (FEB 2014) for the Department of Defense, PTC software products and software documentation are provided to the U.S. Government under the PTC commercial license agreement. Use, duplication or disclosure by the U.S. Government is subject solely to the terms and conditions set forth in the applicable PTC software license agreement. PTC Inc., 140 Kendrick Street, Needham, MA 02494 USA
Contents Introduction... 2 About the Vantron VT-M2M_TC_VM... 2 Installation... 2 Compile the Vantron lvdemo Executable... 2 Prerequisites... 2 Connect the VT-M2M-TC to a Monitor Peripheral... 4 Configuration and Setup... 5 Import Demo Entities into your ThingWorx Platform... 5 Setting up a WebSocket Connection... 6 Troubleshooting... 10 Compatibility... 11 Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 1
Introduction This document provides installation and usage instructions for setting up the client demo, which utilizes the ThingWorx C-SDK, with the Vantron VT-M2M-TC-VM Gateway Device. About the Vantron VT-M2M_TC_VM The VT-M2M-TC-VM is a multi-port gateway device manufactured by Vantron Corporation. It provides Wi-Fi-connectivity, WLAN 3G connectivity, supports data encryption, controls serial communication with other remote devices or computers, and features an Intel ATOM E3845/E3827/E3815 processor and serial, Ethernet, and USB ports for connections. Installation Setup of the VT-M2M-TC-VM device to connect to ThingWorx EMS will first require access to a computer or virtual machine running Linux (Ubuntu 14.04 or later is preferred). Note: This guide was written for a computer running Microsoft Windows. Modify procedures as needed for your environment. Refer to the Troubleshooting section of this guide for help with frequently asked questions. Compile the Vantron lvdemo Executable This guide explains how to connect ThingWorx to the Vantron VT-M2M-TC-VM gateway device using a custom executable that establishes a secure WebSocket connection to the ThingWorx Platform. (These instructions do not utilize the client demo.) Prerequisites You need access to a computer with Ubuntu 14.04 or later; earlier versions of Ubuntu have not been tested. You may to run a virtual machine with Ubuntu in order to compile the software. Note: This guide was written using Ubuntu on a virtual machine. All screen shots and instructions assume an Ubuntu machine. 1. Copy each of the following files from this starter kit package to the Ubuntu machine: toolchain file, debootstrap-squeeze-i386.tar.bz2 ThingWorx C SDK, tw-c-sdk v1-1-1-38 demo executable, lvdemo_src Note: If you are missing the ThingWorx C-SDK, you can download the latest version from support.ptc.com. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 2
2. Open a terminal in Ubuntu and type the following to gain root access: sudo su: Above: Ubuntu terminal window. 3. Type the following pre-installations commands into the terminal (installing qtcreator is necessary for making the executable, later in this guide): apt-get install qemu-user-static apt-get install qtcreator 4. Extract the toolchain file to an appropriate directory: tar xjf debootstrap-squeeze-i386.tar.bz2 C /root/ 5. Combine the SDK and lvdemo_src files into the same directory, as follows (the file structures will be similar, but they will not be overwritten): a. Create a directory named tw-c-sdk. b. Put all the files and directories within ThingWorx-C-SDK-1-1-1-38/tw-c-sdk/ and all the files within lvdemo_src/tw-c-sdk/ into the tw-c-sdk directory. c. Confirm that no files are overwritten. 6. Move the newly created tw-c-sdk directory into the debootstrap-squeeze-i386 directory. 7. Using the chroot command, limit the compile environment to the debootstrap-squeeze-i386 directory, which should now contain all of the files copied in steps 5 and 6: chroot /root/debootstrap-squeeze-i386 8. Compile the ThingWorx C-SDK to obtain an intermediate file: cd /tw-c-sdk/examples/steamsensorwithfiletransferandtunneling/linux/ make BUILD=release PLATFORM=gcc-linux-x86-32 cp /tw-c-sdk/build/obj/gcc-linux-x86-32/release/libtw.a /tw-c-sdk/api/tw Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 3
9. Build the lvdemo: cd /tw-c-sdk/build) mkdir out cd out make 10. Copy the new Executable file (lvdemo) to the VT-M2M-TC-VM, using one of the following methods: Using a terminal program a. Connect to the V VT-M2M-TC device from your computer. b. Open a terminal program such as Putty. c. From the terminal program, connect to the Ubuntu machine and copy the file to the VT-M2M-TC using SCP. OR Transfer files to the device over a local area network a. Plug the display into the Vantron VT-M2M-TC-VM device (using either the VGA port or the display port output. b. Plug a keyboard into the USB port on the device. c. Navigate to your Windows network and copy the file from your computer to the Vantron device. Note: Ensure that the run.sh, settings.json, and lvdemo and so directories are located under the same directory on the VT-M2M-TC device (preferably all in the /opt/lv-demo/ directory). See the next section for connecting to the Vantron device. Please note that you should NOT move on to section 3 of this guide until the lvdemo executable file has been copied to the VT-M2M-TC-VM device. Connect the VT-M2M-TC to a Monitor Peripheral 1. Connect a Panel-7 display to VT-M2M-TC- VM. Note: If no display is shown then view the back of Panel-7 and select to switch the display on. 2. Connect a USB keyboard to the VT-M2M-TC-VM. 3. Power on the VT-M2M-TC-VM, open a terminal window and type sudo su ; the default password is vantron. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 4
4. Open a Linux terminal, such as Putty, to connect to the VT-TC-VM device. Configuration and Setup This starter kit includes a zip file containing the entities associated with the Vantron Demo ThingWorx mashup. You need to set up those entities in your ThingWorx Platform. Import Demo Entities into your ThingWorx Platform 1. Log into your ThingWorx Platform (Composer 6.0 or later), and import the entities as a whole package. 2. Note the URL and port of your ThingWorx Platform server. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 5
3. Create an Application Key on this ThingWorx server. Make note of the Application Key (also known as AppKey ) as you will need to use it again later in this guide. Setting up a WebSocket Connection 1. On the VT-M2M-TC-VM, via Putty or a similar Linux terminal program, type: Ifconfig This returns the changes to the network information. 2. Verify internet connection. Type ping 8.8.8.8 or other Internet address. The following steps are needed for testing out how the data gathered from the VT-M2M-TC VM device is reported. These steps are to be used with a sense plate or similar sensor connected to the VT-M2M- TC-VM via USB cable. This next steps ensure the system recognizes the USB device index for the sensor plate. 3. Create a hyperlink: Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 6
4. Copy the file 99-usb-serial.rules to /etc/udev/rules.d/: The contents of the file 99-usb-serial.rules should be the following text: SUBSYSTEM=="tty",ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523",SYMLINK+="ttySAD P" 5. Connect the Sense plate by USB cable to the VT-M2M-TC- VM device. 6. Go to the target catalog directory by typing the following: cd /opt/lv-demo 7. Configure the IP address and port number of the ThingWorx Platform to which you want to connect (i.e, the Platform configured with the Vantron Mashup) by editing the settings.json file in this directory. Modify it using the vi settings.json command in Linux. In this example, the Platform server location is set to 221.237.156.248:8443. For your use, point the settings.json server IP and server port to your SSL-enabled server and the port 443. Be sure to supply the correct appkey as well. These may be generated in the ThingWorx platform from the appkey section on the home Composer screen 8. To start the data-reporting demo program, run the run.sh file by typing the following command: Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 7
./run.sh If the program executes properly and the configuration is correct, you should see an output in the terminal window similar to this: It is important that you see the Websocket_connected! output to confirm a successful connection to the ThingWorx Platform. Assuming you have a successful connection, continue with the next step in this procedure. 9. Navigate to the URI of the ThingWorx Platform server, configured in settings.json earlier, and do the following: a. Click the Monitoring drop-down and select Subsystems. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 8
b. Click WS Communications and then click Refresh Now. In the displayed list, you will see an active WebSocket or an additional WebSocket. 10. Navigate to the VantronMainUI_US mashup (if included) and choose the monitor name on the left that matches the monitor name specified earlier in the settings.json file. If all steps were performed successfully, you will see a mashup with reported data similar to the following: This completes the setup of the Vantron VT-M2M-TC device with a demo data-acquisition program named lvdemo. You may write and copy your own executable programs to interface with the ThingWorx Platform using the TW C SDK, to suit your needs. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 9
Troubleshooting Problem 1 Using the Windows Powershell [System.IO.Ports.SerialPort]::getportnames() command, I am unable to see any available port numbers. 2 Encounter No such file error when attempting to copy the MicroServer folder to the VT-M2M-TC device. 3 The VT-M2M-TC board cannot connect to the Internet via Ethernet cable. 4 Error while attempting to open a WebSocket connection (VT-M2M- TC device). Solution(s) 1. Verify that the computer is connected to the VT-M2M-TC board via serial cable. 2. You may need to manually install or reinstall 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. Restart your computer and attempt to send data again. Ensure that the MicroServer directory downloaded from the PTC Downloads site is located in the proper directory of the terminal program you are using; otherwise, reference it as appropriate. For Cygwin, ensure the MicroServer directory is located in the home/username/ directory. 1. Verify that the Ethernet cable is connected to a port with a valid Internet connection (verify with another computer). 2. Verify that the VT-M2M- C board is configured to manually set an IP address. 3. Verify that the default gateway for the VT- M2M-TC board is correct. 1. Confirm that the VT-M2M- TC device has access to the Internet. 2. Confirm the accuracy of the IP address and port numbers in the settings.json file. 3. Confirm the appkey authenticity in the settings.json file. 4. Confirm the ThingWorx Platform at the IP address specified in the settings.json file is up and running. Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 10
Problem 5 The run.sh program does not execute on the VT-M2M-QK device. Solution(s) 5. Ensure that you have a valid certificate for an SSL connection to the server running ThingWorx. 1. Ensure that the lvdemo, settings.json, run.sh, and so directories (containing libraries) are all located within the /data/lv-demo/ folder on the VT-M2M-TC device 2. Ensure that the run.sh directory references the correct filename of the lvdemo executable. Use the vi command to check and update the filename of the lvdemo as appropriate. 3. Ensure you have compiled the executable using the latest version of the C-SDK. Compatibility This guide has been tested for compatibility with the Vantron VT-M2M- TC and the following ThingWorx Platform and operating system: ThingWorx Platform Version OS ThingWorx 6.0.1 Windows 7, Service Pack 1 Copyright 2015 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved. 11