Cayenne API tutorial for beginners beginners with ai2/thunkable

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:
blocks1

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”:”
" }

Captura1
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”.

Captura2
In the procedure we will parse the data from the response to get the Auth Token.

Captura3

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.
Captura5

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.
Captura6

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”.
Captura7

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.
Captura10

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.
Captura13

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”:
}

9 Likes

This is amazing, thank you very much for sharing.

Have any ideas what you ultimately want to accomplish with it?

1 Like

Thanks! With an own app I can add more things like text-to-speech and voice recogniser, also a camera surveillance system viewer, and much more as custom widgets you can make, like LCD one that people wanted, or Numeric Keypad, easily.
I have developed (well im still developing) my HAM app, which is the app that i posted to the ESP8266 contest, altough screenshots in the post are outdated. New GUI:



It has camera surveillance system viewer, voice recogniser, TTS, and I still have to integrate all the 28 sensors I have in the dashboard plus the actuators.

2 Likes

awesome tutorial @Neoxelox. cant wait to do my first app using cayenne api.

1 Like

This is very cool @Neoxelox ! Thank you for sharing my friend.

~B

1 Like

If anyone makes an app post it, I wanna know!!

Hopefully @shramik_salgaonkar and @ebtenorio will use it to create something :slight_smile:
~B

2 Likes

Haha! Indeed @bestes! That’s for sure!

2 Likes

@bestes half way done.

2 Likes

@Neoxelox why MIT app inventor said :

i’m on web app. Is there a new version ? and how to update ?

sorry i forgot to put that the project file is only compatible with beta.thunkable.com. Is an AI2 but MUCH better.
BUT the blocks are compatible in any ai2 like builder.

2 Likes

I have an error at the beginning, then does not appear, please tell me how to remove it?

I did that the data from different sensors would be updated on one page, but they appear in different label.
jpgll

Then I did on different screen,
after that everything became good, but the error is always at the beginning.

send me a private message with all your blocks, right click on a blank space → save blocks as image. please.

1 Like

I have the same error than sin-in-cyn36, The error at the beginning always appears2bb94660f95be6de05983b1bf8254d66b754159b_1_690x80
How can I solve this problem?

As I said to @sin-in-cyn36 it appears because you don’t let time to download sensor data and parse it. So, just add time between getSensors and getSensorsData. Also if you have that functions in a timer, please slow down that timer. Finally make sure your auth token , sensor is and device id is correct

1 Like

Let us know what you come up with @sin-in-cyn36 @frengomm. And thanks for helping @Neoxelox. :slight_smile:

~B

1 Like

Hi! Timer 1 - getsensors-1 sec,timer 2 - getsensordata -5 sec,the error has disappeared.

2 Likes