Data types for Cayenne MQTT API

[rsiegel]

In light of some questions about how to pass data to Cayenne via MQTT, and knowing that the table in our documentation is incorrect/showing not-yet-released items, I wanted to share the following table to help with building virtualWrite() statements to pass data to Cayenne.

virtualWrite() expects a parameter format like:

virtualWrite(mqtt_channel_number, value, "type value", "unit value")

You may have noticed that we have shorter functions like luxWrite() that only need two parameters because they know the type and unit values already, but they are ultimately calling virtualWrite() and will not be covered here.

A few quick examples:

Pass temperature value 25.2 in Celsius to MQTT Channel 2
virtualWrite(2, 25.2, "temp", "c")

Pass generic value 17.222 to MQTT Channel 6
virtualWrite(6, 17.222, "analog_sensor", "null")

Digital 2-state value 1 on channel 5:
virtualWrite(5, 1, "digital_sensor", "d")

+------------------------------------+------------------+---------------------+------------+---------------------+
|             Data Type              |    Type Value    |        Unit         | Unit Value |       Widgets       |
+------------------------------------+------------------+---------------------+------------+---------------------+
| Digital Actuator                   | digital_actuator | Digital (0/1)       | d          | Button              |
| Analog Actuator                    | analog_actuator  | Analog              | null       | Slider              |
| Digital Sensor                     | digital_sensor   | Digital (0/1)       | d          | 2-State             |
| Analog Sensor                      | analog_sensor    | Analog              | null       | gauge, value, graph |
| Acceleration                       | accel            | Acceleration        | g          | gauge, value, graph |
| Barometric pressure                | bp               | Pascal              | pa         | gauge, value, graph |
| Barometric pressure                | bp               | Hectopascal         | hpa        | gauge, value, graph |
| Battery                            | batt             | % (0 to 100)        | p          | gauge, value, graph |
| Battery                            | batt             | Ratio               | r          | gauge, value, graph |
| Battery                            | batt             | Volts               | v          | gauge, value, graph |
| Carbon Dioxide                     | co2              | Parts per million   | ppm        | gauge, value, graph |
| Carbon Monoxide                    | co               | Parts per million   | ppm        | gauge, value, graph |
| Counter                            | counter          | Analog              | null       | gauge, value, graph |
| Current                            | current          | Ampere              | a          | gauge, value, graph |
| Current                            | current          | Milliampere         | a          | gauge, value, graph |
| Energy                             | energy           | Killowatt Hour      | kwh        | gauge, value, graph |
| External Waterleak                 | ext_wleak        | Analog              | null       | gauge, value, graph |
| Frequency                          | freq             | Hertz               | hz         | gauge, value, graph |
| Gyroscope                          | g                | Rotation per minute | rpm        | gauge, value, graph |
| Gyroscope                          | g                | Degree per second   | dps        | gauge, value, graph |
| Liquid                             | liquid           | Liter               | l          | gauge, value, graph |
| Liquid                             | liquid           | Milliliter          | ml         | gauge, value, graph |
| Luminosity                         | lum              | Lux                 | lux        | gauge, value, graph |
| Luminosity                         | lum              | Volts               | v          | gauge, value, graph |
| Luminosity                         | lum              | % (0 to 100)        | p          | gauge, value, graph |
| Luminosity                         | lum              | Ratio               | r          | gauge, value, graph |
| Magnetometer                       | mag              | Gauss               | ga         | gauge, value, graph |
| Magnetometer                       | mag              | Tesla               | tesla      | gauge, value, graph |
| Motion                             | motion           | Digital (0/1)       | d          | twostate            |
| Nitrogen Dioxide                   | no2              | Parts per billion   | ppb        | gauge, value, graph |
| Ozone                              | o3               | Parts per million   | ppm        | gauge, value, graph |
| Particle Matter                    | pm               | Micrograms          | mg         | gauge, value, graph |
| Power                              | pow              | Watts               | w          | gauge, value, graph |
| Power                              | pow              | Kilowatts           | kw         | gauge, value, graph |
| Proximity                          | prox             | Centimeter          | cm         | gauge, value, graph |
| Proximity                          | prox             | Meter               | m          | gauge, value, graph |
| Proximity                          | prox             | Digital (0/1)       | d          | gauge, value, graph |
| Rain Level                         | rain_level       | Centimeter          | cm         | gauge, value, graph |
| Rain Level                         | rain_level       | Millimeter          | mm         | gauge, value, graph |
| Received signal strength indicator | rssi             | dBm                 | dbm        | gauge, value, graph |
| Relative Humidity                  | rel_hum          | Percent (%)         | p          | gauge, value, graph |
| Relative Humidity                  | rel_hum          | Ratio               | r          | gauge, value, graph |
| Resistance                         | res              | Ohm                 | ohm        | gauge, value, graph |
| Signal Noise Ratio                 | snr              | Decibels            | db         | gauge, value, graph |
| Soil Moisture                      | soil_moist       | Percent (%)         | p          | gauge, value, graph |
| Soil pH                            | soil_ph          | Analog              | null       | gauge, value, graph |
| Soil Water Tension                 | soil_w_ten       | Kilopascal          | kpa        | gauge, value, graph |
| Soil Water Tension                 | soil_w_ten       | Pascal              | pa         | gauge, value, graph |
| Tank Level                         | tl               | Analog              | null       | gauge, value, graph |
| Temperature                        | temp             | Fahrenheit          | f          | gauge, value, graph |
| Temperature                        | temp             | Celsius             | c          | gauge, value, graph |
| Temperature                        | temp             | Kelvin              | k          | gauge, value, graph |
| Voltage                            | voltage          | Volts               | v          | gauge, value, graph |
| Voltage                            | voltage          | Millivolts          | mv         | gauge, value, graph |
| Wind Speed                         | wind_speed       | Kilometer per hour  | kmh        | gauge, value, graph |
+------------------------------------+------------------+---------------------+------------+---------------------+

[bestes]

Very helpful, I was just using this

[rsiegel]

Thanks. I’m hoping we can get a table plugin for the forum in the future so I can make the chart a little prettier.

[julian]

Is there a guide or page with all the other functions such as the mentioned luxwrite() or celsiuswrite, farenheitwrite… I tried some searches and looking around the website and I can’t really find it. Sorry if I’m missing something obvious.

[adam]

As far as I know those functions are for Arduino only. I looked in the docs and unfortunately can’t find a list of all of them.

[julian]

I ran those functions on the Pi using python and it works great. They were in the Github sample code called “Example-03-CayenneClient.py”

[rsiegel]

Hi @julian,

The only place right now where I know those functions are listed is in the client.py file that’s called in the library code: Cayenne-MQTT-Python/client.py at master · myDevicesIoT/Cayenne-MQTT-Python · GitHub

If you scroll down there, you’ll see a list of them. If you look closely you’ll notice they are just more convenient repackagings of the generic virtualWrite() function, so for example

celsiusWrite(2, 25.2)
and
virtualWrite(2, 25.2, "temp", "c")

are directly equivalent – both will pass 25.2˚C as a value to MQTT channel 2.

You can create your own custom write functions as well by defining them in that client.py file using the data types and units in the chart in the first post of this thread.

[spacefolder]

Hi Guys!

Is there any data type we can use to display System Up Time?
It would be great if we could just send the millis() counter, and get a HH:MM:SS in the Cayenne dashboard…

PD: I am aware of it’s roll over, but nonetheless, I think it would be great!
(Roll over is around 50 days with the esp8266)

Cheers!
Marc

[rsiegel]

Hi Marc,

If you have a look at our example Arduino MQTT connection sketches, you’ll see that each of them uses as one of the base examples an implementation of sending the millis() count to a value widget as demonstration of how you could send sensor data to your Cayenne dashboard:

void loop() {
	Cayenne.loop();

	//Publish data every 10 seconds (10000 milliseconds). Change this value to publish at a different interval.
	if (millis() - lastMillis > 10000) {
		lastMillis = millis();
		//Write data to Cayenne here. This example just sends the current uptime in milliseconds.
		Cayenne.virtualWrite(0, lastMillis);
	}
}

This as-is is just sending the raw millisecond count to the dashboard, but it could be multiplied into minutes or hours/days to provide something more human-readable.

What we’re missing right now, but have on the roadmap for future Cayenne development, is a time data type (and widgets that can display it properly), so you could actually do a HH:MM:SS display like you’re hoping here. I suppose you could do one with 3 different widgets for each of hours/minutes/seconds but that seems like it would be hacky at best

[spacefolder]

Hi!

Thanks for your reply @rsiegel

That’s how I actually get my System Uptime of my esp8266: days, hours, minutes, each on a separate channel. BTW although not the slickest way, it actually works just fine!

Still hope for a DD:HH:MM etc. widget
Cheers!
Marc

[rsiegel]

Glad to see it in action. Not as hacky as I originally thought I guess

I know we have a Time data type in the works (and a whole bunch of other ones that will nearly double the size of that list in the OP. ) This means we’ll need at least some sort of widget that is able to display what goes into it, so whether it is a time-specific widget or just an improvement to our value widget, I imagine we’ll have something for you in the future.

[bensimmo]

Do we have an update to this list ?
and somewhere to suggest additions to the list based on sensors?
(for example Particle Matter has 2.5 but no 10 or other sizes)
I see Yaw, Roll, and various others in my drop down. It would be really nice to set everything up in code rather than cross reference and manually set them up at the web display.
Also the ability to pass a ‘descriptive name’ would be good, rather than just it displaying Channel 2, Channel 10 etc.

(… I’m off to see how I send a tuple to the accelerometer setting as it seem to have three bars and I’ve sent it as three individual value
would be nice to have that on that on the magnetometer and gyro and rotation, even better in a 3D 3 axis display ;-))

thanks.

[shramik_salgaonkar]

we are currently in process of updating the list and will be out soon. For suggestion you can create a new suggestion topic in the community and we will look into it.
For accelerometer to send a tuple here is the code:

x = mpu6050.getAccX();
y = mpu6050.getAccY();
z = mpu6050.getAccZ();
char buffer[50];
buffer[0] = '[';
size_t offset = 1;
dtostrf(x, 1, 3, &buffer[offset]);
offset += strlen(&buffer[offset]);
buffer[offset++] = ',';
dtostrf(y, 1, 3, &buffer[offset]);
offset += strlen(&buffer[offset]);
buffer[offset++] = ',';
dtostrf(z, 1, 3, &buffer[offset]);
offset += strlen(&buffer[offset]);
buffer[offset++] = ']';
buffer[offset] = 0;
Serial.println(buffer);
Cayenne.virtualWrite(1, buffer, "accel", "g");

[bensimmo]

I’m using python3, so will have to work through that code and figure it out what it is doing and transfer it. (I’m not a c person)
But if it end at just (x,y,z) that’s easy.

Or is it ((1,x),(2,x),(3,x)) and a list in list?

[shramik_salgaonkar]

the format to send this data is

Cayenne.virtualWrite(channel, "[x,y,z]", "accel", "type");

example:

Cayenne.virtualWrite(1, "[2,1,3]", "accel", "g");

[bensimmo]

Excellent hope these appear in the documents and also the python api get in the documents.

Support has been and still is excellent (from ~over two years ago and now ), which is very nice to see.

Moving to MQTT seems a good choice as you’ve expanded beyond the initial offering and limited devices.

[bensimmo]

ok, my so far…
It needs work and is not fully usable right now.
acceleration gives the 3 in a box bars,
magnetometer, gyroscope and orientation(yaw/pitch/roll) do not. they don’t even really know they are what they are and manual setup is a pain (and can we have radians/second)

acceleration on the desktop interface (chrome here) does not allow min/max values to be saved, so the bars don’t move a lot and it also cannot be displayed as a graph.

So I’ll have to abandon for a while and hope things are better in a few months.
It’s ok for a few simple things like temperature and pressure on one axis, but nothing more involved.

Getting the data there in MQTT was fine and pretty easy (python3) but the display and interface is not.

(also the pink think/chat bubble in bottom right constantly hovers of things, like remove, meaning you cannot press it.)

[shramik_salgaonkar]

we have some upcoming new widgets that will solve most of your problem Cayenne Docs
it just took a little more time as we had to swift from old to new MQTT cayenne. Once we have solved all current issue we will start releasing some cool new widgets.

[royjhopkins]

virtualWrite() expects a parameter format like:

virtualWrite(mqtt_channel_number, value, "type value", "unit value")

I see you show different widgets in the table.

Can I specify the widget to be used as well?

[shramik_salgaonkar]

Data type listed in the table are only supported.