This is a brief tutorial that will show you how to connect your Arduino Uno to ThingWorx and upload values to a ThingWorx “Thing.” First you will learn how to set up a ThingShape, a Thing, a Service within your ThingShape, and an Application Key. Next you will learn how to program your Arduino Uno to start sending data to your ThingWorx Things! Two simple ThingWorx libraries along with example codes are included with this tutorial. They will allow you to start pushing data in minutes!
Requirements:
- ThingWorx hosted instance
- Arduino Uno
- Ethernet or WiFi Shield with corresponding libraries
- Arduino Environment
In this post:
Tutorial 1: Setting up your ThingWorx Thing
In order to start pushing data to ThingWorx, we must first define our ThingShape, service, Thing, and Application Key.
1: Create an Application Key
An application key is the authentication that you use to send or receive data from your Thing. It is associated with a ‘tag’ that is common to all of the components of your thing. To create the key first get to the home page of your ThingWorx Composer.
1.1: Under the “Security” heading on the left click on “Application Keys.”
1.2: Next, click on the “New” button towards the top of the screen. Fill in the required fields
1.3: Now, create a tag by clicking on the wand next to tags. Either choose an existing tag or create a new one. The tag ties your application key to all the components of your Thing.
1.4: After selecting a tag click Save at the top and you will see that an Application Key has populated the “keyId” field.
2: Create a ThingShape and Service
2.1: From the ThingWorx Composer home page select Thing Shapes on the left side of the page under the “Modeling” heading.
2.2: Next select “New” at the top of the screen and fill out the required fields.
2.3: Make sure your tag matches the tag you used when creating your Application Key. On the left side of the screen select “Properties.”
2.4: Select “Add My Property” to start adding Properties to your ThingShape. These are the values that you will be pushing to the ThingWorx site via your Arduino’s ethernet or wifi shield. Select “Number” as the type. You should have a Properties page that looks something like this:
2.5: Now we’ll create a service that reads values from your Arduino and populates your Properties with them. First, while still in the ThingShape edit mode, click on Services on the left hand side and select the “Add My Service” button at the top.
2.6: Fill in the Name and Description, then click on Inputs/Outputs.
Add inputs that correspond to the data values that you are sending from the Arduino. These input names MUST match the names that you select in your Arduino code (discussed later). Also make sure that the type is set to STRING. Next, we need to write a short JavaScript that will convert the string values to type float and then populate the properties. Note below that properties will have a “me.” in front of them.
2.7: Click the Done button at the bottom and then the Save button at the top to complete your ThingShape and Service.
3: Create a Thing
3.1: From the Composer home page click “Thing” and then click “New”. Populate the required fields. Make sure your tag is the same one you used for your ThingShape and Application Key. Choose the “GenericThing” as your Thing Template. Choose the ThingShape that you just created as your implemented ThingShape.
3.2: Now click Save and you’re done with your Thing!
4: Test your Service
4.1: While you are still in your Thing you can now test the service you made by clicking on Services on the left side of the screen. If the Service doesn’t show up then click save again on your Thing and ThingShape and close and reopen your Thing tab. The screen should look something like the one below when you click on Services.
4.2: Click the “Test” button on the Service that you just created and populate the fields. Click Execute Service.
4.3: Now exit out of that window and go to your Properties tab on the left and refresh the properties. The values should have populated into your properties!
If the properties didn’t update or you got a JavaScript error, be sure to check back through your Property names, types, and JavaScript code and ensure that it matches the formats from above.
Tutorial 2: Programming your Arduino
Included in this tutorial are two Arduino libraries, called ThingWorxWiFi (5.2 KB .zip) and ThingWorxEthernet (4.9 KB .zip). They also come with example programs. Download these libraries and place them in the /Arduino/libraries folder. Open up your Arduino Environment and under File/Examples, find the Example code for the particular hardware you are using (either WiFi or Ethernet shield). This tutorial will walk you through the Ethernet code. The WiFi code is almost identical save for the required WiFi network information. When you open the code it should look like this:
Make sure you denote how many values you will be pushing to ThingWorx (next to the #define sensorCount). Now fill in the required info: a unique MAC address, server, app key, thing name, service name, the names of your values or sensor values (these must match your Service variables exactly!), the time between connections, and the corresponding pins that your sensors are on. This is all you need to start pushing values! The code as written will send your raw (0 to 1028) analog to digital converted values to ThingWorx. You may choose to process your data into usable values before you send it off. If so, either modify the values in this loop:
Or however you see fit.
