The Things Network (TTN) & Microshare integration
How to: stream IoT packets from The Things Network (TTN) to Microshare
This tutorial assumes that you already registered for and have a TTN account. It also assumes that you have provisioned at least one device sending uplink packages to TTN.
This tutorial will show you how to configure your TTN applications to forward IoT data to the microshare.io data lake. It will take you through creating a microshare account, generating a streaming token, and using it in a TTTN notification target. After this you’ll be able to use the functionality of the microshare platform to share your data securely, build data workflows, Apps, etc.
Register for a Microshare.io account
The microshare registration process is simple.
- Browse to https://app.microshare.io.
Click Sign Up.
- You will receive an email asking you to confirm your account & setting your account password.
Your experience should be similar to the screenshots below.
How to send data to microshare
Now that you have created your account, you own a little piece of the microshare data lake. You will now use TTN’s automated redirection of packets, aka a device’s notification target, to pass that data through to microshare’s RESTful API.
The API needs to know two things when receiving data from an external service:
- The owner of the data
- The category of the data
These two pieces of information are configured in TTN’s Application Integrations sections.
To identify yourself as the owner of the streamed data, you must generate a token for your microshare account. Generating this token will be covered in the next section.
The category under which every one of your data packets get stored in microshare is called a
recType (as in the Type of your Record). There are no preset categories, you can use whatever you want, and even reuse a recType for two separate devices. We will give you some tips on how to determine recTypes later
Generate a Microshare Pipe Token
Now you’ll generate a Pipe Token using microshare’s API. The easiest way to interact with the microshare api is to use Postman
To install Postman on your computer:
Go to our API documentation page
Click on the
Run in Postmanbutton to install Postman on you computer and automatically load in our Postman API collection and environment.
If that fails, go to the Postman website to install Postman manually, then download and import the collection and environment from our API documentation page.
Open Postman on your computer to see the microshare collection. You can select and manage environment from the top right of your Postman app.
To use the token generation calls, you need to identify yourself with your username, password and an APIkey.
To get a microshare APIkey:
- Log in your microshare account
- Go to
Manage -> Keys.
CREATE NEW APPand give a friendly name to your APIkey (why not “HackIoT”?).
- Once the key is created, , click on the value in the API KEY (CLIENT ID) section to copy it to your clipboard. (See the screenshots below)
To finally generate the microshare Pipe Token:
- Go back to Postman and edit your environment.
Copy the APIkey and enter your username and password.
- This allows you to run the request
Authentication -> Request pipe token. The generated token is returned under the
access tokenkey in the result set and is valid for an unlimited time. The Pipe token can only be used to post data to the microshare platform.
Later we’ll use the
Request Token call that returns an access token which is only valid for 48 hours and can be used with the other microshare APIs.
Note All generated tokens can be found, copied or revoked from the
Manage -> Key -> Tokens screen in microshare. If you didn’t copy the pipe token just after the call, go on that screen, find the Pipe typed token and copy it.
Setup your TTN Application Integration
- Now that you have your generated token log into TTN choose your application & click the
- Click the
- Enter data into the following fields:
- Process ID: give your integration a name like
- Access Key: select the
- URL: the url value is composed of the base url https://api.microshare.io/share/ and the
recTypevalue you chose previously.
Tip: We usually compose a recType based on the data’s origin, using a schema from the most general to more specific. For example, here the device is a sodaq board, provisioned in TTN, physically located in Reading in the UK, so the recType can be:
uk.reading.ttn.sodaqan example url & recType is
- Method: Select the
- Authorization: Enter the word
Bearerthen paste your pipe token that you previously generated. The value should look similar to this example:
- Click the
- Process ID: give your integration a name like
All the other fields are not required for this tutorial.
Below is an example of an
Next you should see your newly created microshare HTTP integration running in the Integrations Overview section
Verify the data streaming to microshare
Your TTN device data should now be streaming to your microshare account. You can verify that with the microshare API.
You are going to use the
Share -> Get Shares by recType call, for which you need a
- Open and run the request
Authentication -> Request Token. The generated
access-tokenis automatically copied to your environment, so you are immediately ready to run other requests.
- Open the
Shares -> Get Shares by recTypeto configure it.
- Specify the recType you used in TTN in the query params.
The response of the request is a view of all the data THAT YOU ONLY HAVE ACCESS TO stored under the specified recType:
The TTN data is under the
objs -> data keys. The
payload_fields key holds your device’s payload data which is generally sensor data such as temperature, GPS or CO2 measurements.
Use our Robot decoding library to decode the Low Power Payload
If you execute the request again, the number of records will increase as the data is streamed. The microshare metadata tells you how many pages of records you have, and the total number of records (platform wide) stored under this recType.
totalCount value can be higher than the total number of records you own. This is because another user could be storing data under the same recType. Don’t worry, you will only see your data, and the other user will only see their data, unless you have created Rules to share your data.
Learn more on how to work collaboratively with other users by sharing records, check out our Rules guide