Notice!: I updated this method, and I have created an extension which is easier, faster and has much more stability. However, you can follow this tutorial If you want. EXTENSION HERE.
Notice!x2: I have made a tutorial JAVA | Cayenne REST API TUTORIAL in an actual programming language (Java).
Notice!: This is a BASIC tutorial about working with Cayenne’s REST API, with an easy app builder as AI2 or Thunkable. Maybe the process is not the “cleanest” way to do it, but it is the easiest way to get it done and this type of builders can’t do too much, or maybe I am dumb. Please SHARE any suggestions, or improvements.
Said that, in this tutorial we will learn to:
- Get an Auth Token with email and password for getting all the things listed below.
- Get Things ID and Sensors ID.
- Get Sensors data.
- Control an Actuator via API.
Download App Project Only compatible with beta.thunkable.com . But the blocks are compatible in any App builder like AI2.
General Overview
Getting an Auth Token
We will make a POST call to the API. To do that we need the component WEB in the category CONNECTIVITY, not WEB VIEWER component. Drag it to the project, and rename it to something like “authRequest”.
Initialize some variables to hold the data:
We will make a “to-do” procedure to have things clear, rename it to something like “authLogin”. Here we will make the POST request to the API. We need to set the coresponding headers and URL. Care! You have to put photo exact text, otherwise it won’t work.
{“grant_type”:“password”,
“email”:"
“,“password”:”
" }
After making the POST call, we have to parse the API response data that we get. We will make another “to-do” procedure, that we will call right after of getting the response That procedure needs an input to get the response, call it “dataIn”.
In the procedure we will parse the data from the response to get the Auth Token.
Getting Things/Sensors ID
Note!: You can directly get them from the links in the dashboard, but I was that stupid that I didn’t realize that, so I made a simple application to get them, if you are interested download it here. Note also that the word “thing” means also sensor.
To get Sensor ID in the link, just click config icon in the sensor widget.
You can pass this section if you want.
We need another WEB Component, rename it for “thingsRequest”.
First, initialize some variables.
We have to set the Generic Headers for the API calls, I recommend you to set it right after getting the authToken. Care again!: be sure you respect the spaces, there is one after “Bearer”.
Authorization
Bearer
X-API-Version
1.0
After that we will make a GET call to get our things list. We will do it with a “to-do” procedure, name it “getThings”. There we will set the corresponding URL and Headers.
After making that API call we have to parse that response, we will do it with a “to-result” procedure instead of “to-do” one. That procedure will need an input, thing’s name, to search its ID in the things list, name it “thingName”.
Getting Sensor’s Data
To get data value of a sensor we will need:
- Generic Header (see above)
- Sensor’s Device ID (see above)
- Sensor ID (see above)
First, we need another WEB component, rename it to “sensorDataRequest”.
Initialize some variables, the summary type means if the data is the latest, or it is the data of 1 hour ago… Use latest.
After that we will make a GET call to get sensor’s data. We will do it with a “to-do” procedure, name it “getSensors”. That procedure will need 3 inputs: “deviceID”, “sensorID” and “summaryType”. In that procedure we will set the corresponding URL and Headers.
Then, we will parse that data. I wasn’t able to get it done with a “to-result” procedure, which would be the cleanest way, so I done it with a “to-do” one, but using a set Any Label block, so we can set the data to a label directly from that procedure, so, this procedure will need an input I called “dataOut”.
Controlling an Actuator via API
To make an Actuator post you will need the Auth Token but not the Generic Headers, because actuators headers are diferent. You will need also another WEB component, rename it to “actuatorRequest”. You will need also the actuator device’s ID. Note!: If you see random values in your actuator in your dashboard is normal, because that request we are doing is directly to an MQTT DEVICE. This request is the only one that requires a Cayenne MQTT connected device, as ESP8266.
Initialize some variables.
We will do the POST call in a “to-do” procedure. That procedure will make the correct Header, and set it and corresponding URL. That procedure will need 3 inputs: “deviceID”, “channel” and “value”. The value, can be:
- 0-1 : for buttons or 2 state buttons
- 0-255 : for sliders.
Care!: Respect the space after “Bearer”.
Authorization
Bearer
content-type
application/json
Care!: Respect the spaces in the Post.
{ “channel”:
, “value”:
}
