Adding IOT sensors into Tandem API

UPDATE:

See this video for a complete walkthrough: Youtube "Sending Data to a Autodesk Tandem Stream"

Introduction

Ready to enhance your Autodesk Tandem digital twin with IoT sensor data?

Adding IoT sensor data to your Tandem Digital twin unlocks the heat-map feature. This feature lets you visualize how your rooms and spaces are being occupied and how they heat up in some parts, but cool down, in others.

By capturing this information over a long period of time, Tandem can help you find patterns in your energy usage and track down anomalies in your building equipment.

addSensorData

"How do I get my sensor data into Tandem, in the first place?" - Well, there are a few ways.

This guide will show you how to do this, via the Tandem Data API.

Let's begin...

Terminology

In Tandem, we use these terms:

Stream: A stream is similar to other elements in Tandem in that it can be created, classified, and deleted. However, unlike other elements, streams do not possess geometry. Instead, they are represented through a marker (resembling a pushpin) and can be linked to a Host. This Host provides the marker with a specific 3D location within the model.
Host: A Host is an entity within Tandem that assigns a 3D location to a stream's marker, integrating it into the model's spatial context.
Identifier: Each stream is uniquely identified by a key. This key is a long identifier, 24 bytes in length, that is encoded using Base64 encoding.
```
i.e. AQAAAPeahQ-rkEcwiMvDS9re0QQAAAAA
```

Ways to Stream

There are different ways to send data from sensors to streams in Tandem:

Send Stream Data Directly and Configuring via Tandem UI
Using Tandem Data API
- Data for Individual Stream
- Data for Multiple Stream

1. Send Stream Data Directly and Configuring via Tandem UI

The easiest option is to configure Tandem UI and send a POST request, directly from your sensor or gateway, containing a JSON payload ( a measurement like temperature or proximity). Here is an example system diagram:

option1

To configure the Tandem UI, go to the Streams Tab, choose a stream, and click 'Copy Link' button to copy the "ingestion" URL
Paste this into your sensor/gateway configuration

copylink

Example Payload:

A sensor sending a temperature measurement via a POST request:

{ 
  "temperature": 20.2 
}

Notes:

The payload should contain only numeric values (such as 20.2)
The payload can include the timestamp of the event (optional). The timestamp can be specified either using Unix epoch time or as an RFC 3339 formatted string.
The URL provided will include credentials for a given stream (important to keep this intact).

For more info, see these Tandem resources:

2. Send Stream Data using Tandem API

A second approach uses a Service (blue) that connects the gateway to the Tandem API.

Use this approach when:

The gateway does not provide a compatible way to trigger HTTP calls when sensor data changes
If data needs to be transformed (i.e., from string to number)

Send Data for Individual Stream

Send data using a POST request to a single stream, using this URL format:

https://:secret@tandem.autodesk.com/api/v1/timeseries/models/:modelID /streams/:streamID

The payload should follow same rules as above.

Note that some HTTP clients don’t support credentials included in the URL.

Here is an example, using an Authorization header to pass the credentials:

const authHeaderValue = Buffer.from(':somesecret').toString('base64'); 
const modelID = 'urn:adsk.dtm:APCMKgIDSyOFpZ763lew7Q'; 
const streamID = 'AQAAAC6lzjQuhETds3FO9vuJy5EAAAAA'; 

const url = `https://tandem.autodesk.com/api/v1/timeseries/models/${modelID}/streams/${streamID}`; 

const res = await fetch(url, { 
   method: 'POST', 
   headers: { 
     authorization: `Basic ${authHeaderValue}`, 
   }, 
   body: JSON.stringify(payload)
});

Note: that credentials need to be encoded using Base64 encoding.

Send Data for Multiple Stream

Use the following URL to send data for multiple streams:

https://tandem.autodesk.com/api/v1/timeseries/models/:modelID/webhooks/generic

The payload should include an "id" of the stream to update, i.e.:

{ 
  "id": "AQAAAPeahQ-rkEcwiMvDS9re0QQAAAAA", 
  "temperature": 20.2 
}

The payload can also include optional timestamp:

{
  "id": "AQAAAPeahQ-rkEcwiMvDS9re0QQAAAAA",
  "temperature": 20.2,
  "timestamp": 1711608163
}

It is also possible to send data for multiple streams in one call. In this case, the payload should be an array of objects, like this:

[ 
  { 
    "id": "AQAAAPeahQ-rkEcwiMvDS9re0QQAAAAA", 
    "temperature": 20.2 
  }, 

  { 
    "id": "AQAAAICIyq2_bkchtSbK3sPFeHcAAAAA", 
    "temperature": 20.2 
  } 
]

This approach can be also used when you need to send "historical" data for one stream - in this case provide different timestamps:

[
  {
    "id": "AQAAAPeahQ-rkEcwiMvDS9re0QQAAAAA",
    "temperature": 20.2,
    "timestamp": 1711606800
  },
  {
    "id": "AQAAAPeahQ-rkEcwiMvDS9re0QQAAAAA",
    "temperature": 20.1,
    "timestamp": 1711607100
  },
  {
    "id": "AQAAAPeahQ-rkEcwiMvDS9re0QQAAAAA",
    "temperature": 20.2,
    "timestamp": 1711607100
  }
]

If using a service architecture, then best practice is to send sensor data, only when it's values change.

Timestamp

As mentioned before timestamp is optional - if not provided actual server time is used. Timestamp can be specified using epoch format. It's also possible to use RFC 3339 - check out this post for more details and examples.

Authentication

The requests need to be authenticated using an Authorization header. Here are two options:

Basic authentication. You can copy authorization token using Webhook Integration command from the menu in the Streams panel. This command also allows regenerating the token if necessary.
OAuth authentication. The authorization token can be generated using APS Authentication service. In the case of a 2-Legged token, the service needs to be added to the facility or account – see here for more details. Make sure to use correct scope (data:write).

Additional Notes

The maximum payload size is 10 MB. Take this into account when sending data for multiple streams.
The minimum interval when sending data is 1 minute.
It is possible to send partial data – i.e., stream has 3 parameters, but you can send only one if the other two did not change.

Troubleshooting

In case of issues, you may try the following:

Use tools like Postman to verify that connection to Tandem works.
Use Configure Connections command in Tandem to map values between input data and stream:

config

Configured connection/mapping is used for all streams in the facility.

Use numeric values only.
Try to keep your payload simple, avoid using spaces or special characters in variable names.
Use Refresh command to update streams in facility to reflect latest changes.

Examples

You can find examples on GitHub:

Examples are for Node.js – additional there are examples in Python.

Summary

In this article, you learned how to ingest IoT sensor data into Tandem, via the Tandem Data API.

Coming soon, we’ll also provide Tandem Connect – a no-code/low-code integration platform for Autodesk Tandem. Tandem Connect will simplify integrations, like this one, and provide library of reusable plug-ins and pipelines. Stay tuned for more details soon.

If you need help with connecting your sensors to Tandem or any other Tandem questions, reach out to us at: aps.help@autodesk.com

Twitter:

Tags:

Viewer

Tandem Data API

Data Visualization extension

Code Samples

Back to Community Blog