First Steps

Datacake ❀ Particle.io

Introduction

With Datacakes native Particle.io Integration, any Particle.io device can be integrated into the Datacake Cloud.

To transfer measured values into the Datacake Cloud, a simple Particle.publish("event", "1.23"); is all you need - and your measurement data is already being transferred into the Datacake Cloud according to a freely definable event mapping.

Features

In the Datacake Cloud the data from your Particle.io devices can be used for the following functions:

  • Creation of real-time dashboards via WYSIWYG editor

  • Definition of rules for notification by SMS High-resolution long-term data storage incl. graphic evaluation

  • Export of measurement data to CSV, Excel or JSON or via REST-API

  • Inviting people to collaborate including management of rights and roles

  • Deployment of the portal to customers, employees, etc.

  • Creation of global dashboards

  • Use of a managed Node-RED variant called Cake Red

  • Debug overview with continuous storage of the last 100 Particle.io Publishes

Necessary steps

The steps necessary for setting up the integration are straightforward. If an appropriate Particle.io product / device is available, it usually only takes a few minutes until data can be transferred to the cloud. These steps look like this:

  • Creating a New API Device

  • Create data fields

  • Link Particle Device to API Device

  • Create Dashboard

  • Create rules

  • Have cake!

Add new API-Device

Integrations are available in the Datacake Cloud as an extension to a device. We call this API device, so the first step to integration is to create a new device - or API device.

To do this, navigate to "All devices" in the "Fleet" group on the sidebar and click the "Add device" button, as shown in the screenshot below.

Your browser should show the following:

Now select the device type "API" and assign a corresponding name for the new device. You can change these later at any time.

Finally confirm the input by clicking on the button "Add and configure device". This will automatically switch to the configuration overview, which is required for the next step.

Create Database-Fields

To be able to store measured values, corresponding fields must be created into the database. Scroll to the group "Fields" in the configuration view of the device and click (as marked on the following screenshot) on the button "Add field".

After clicking - It should show the following:

Name

Here you can choose the name for this field. This is freely selectable and can also be changed later as often as you like.

Identifier

This is the identifier of the measurement field, which describes the field uniquely internally in the database. This identifier is also used for the API and appears again and again in various areas of the cloud.

No worries! Even if you change the name of the field, the identifier stays the same.

For technical reasons, the identifier can only be edited when the field is created. As soon as you have created the field using the "Save" button, you can no longer edit it. If you want to change the identifier, you must delete the field and create a new one.

Type

An appropriate data type must be defined for the respective fields.

Please pay attention to the correct specification of the type when creating! For technical reasons, you will not be able to change it at a later date. This is only possible if you delete the respective field and then create a new one!

Integer

Stores values as Integers.

  • Structure: Particle.publish("numberofcakes","42");

Location

The Location-type stores geo-coordinates, which can be used e.g. for the map widget to display positions of a device.

  • Structure: Particle.publish("cakeplace","(<latitude>, <longitude>)");

  • Example: Particle.publish("cakeplace","(51.96236,7.62571)");

Float

Stores values as Floats.

  • Structure: Particle.publish("caketemp","3.21");

Boolean

Stores values as Booleans.

  • Structure: True = Particle.publish("aboolean","1");

  • False = Particle.publish("aboolean","0");

String

Stores values as whole Strings.

  • Structure: Particle.publish("whathesaid","hello world!");

Counter

Currently the counter field is only supported by the Datacake D Zero Hardware. We are in the process of transferring the functionality for the API devices.

Examples

Further down in this chapter you will find code examples for your devices.

Define a Unit

Display Unit

In this field, you can define a unit for the respective measured value in the form of a user-defined text.

Unit

Various units are available for you to pre-select. The purpose of this is an automated conversion to any other unit (see next item).

Display Unit

If you have selected a predefined unit, you can use the drop-down menu to select a unit into which the measured value is to be converted.

Float Digits

If the respective type of the field allows decimal places, you can specify with which precision (number of decimal places) this is displayed or stored in the database. To do this, enter the desired number of digits in the mask.

Formula

This point has its own chapter. However, we will touch on the subject briefly here. Formulas can be used to perform mathematical calculations for the measured value.

Available Placeholders

As elements of the formula, you can, for example, use measured values to perform calculations that are dependent on several measured values.

Database fields that use a formula for calculation should usually be defined purely virtually, i.e. not populated with measured values from a device. The background is as follows:

If you define a formula in a field which receives its measured value via a linked Particle Device or the REST API, the value resulting from the formula is not stored in the database!

Example

The following screenshot shows database fields created for the storage of measurement data generated by the Particle.io Asset Tracker.

Setup Particle Integration

To connect your Particle.io device with the Datacake-API device, the Particle.io integration will be configured. For this purpose there is a button "Configure" at the end of the configuration tab in the group "Integrations". The following content should be visible when pressing this button:

Das Particle.io Integrations Modal

Create new Webhook

The data is transferred from the Particle.io Device Cloud via Webhook to the Datacake Cloud. For this purpose, a corresponding Webhook integration must be created in the Particle Console. This works for devices in Particle products as well as in your personal device list.

Add new Integration

In the Particle Console, select "Integrations" from the sidebar and add a new integration by clicking on "New Integration".

A selection of available integrations appears. Select here the type "Webhook".

Webhook konfigurieren

After selection, a configuration view appears. Enter the following URL in the corresponding field (URL):

  • https://api.datacake.co/integrations/particle/

Then you specify the event name of the event which you call in your Particle.publish();, e.g. myevent for Particle.publish("myevent", "1.23");

Also - have a look at the following screenshot:

Set Particle Device-ID

The device ID of your Particle.io device must now be entered in the Datacake-Particle Integration. This binds the API device to the respective Particle Device.

A Particle.io Device ID can only be used once. If it is already bound to an API device, it cannot be re-connected e.g. to another API device!

Add Event Mapping

Now you have to specify the event mapping. Here the respective event must be defined via the "Event Name" (marked red in the following screenshot), as well as the structure of the data must be described. To do this, use the drop-down menu (marked blue in the following screenshot) to select the respective fields.

The event mapping expects you to select the fields exactly in the order they appear in the Particle.publish(); function call. Note the example shown in the form!

Add another Event Mapping

If you have defined more than one Particle.publish(); event in the device firmware of your device, you can of course create further event mappings. Simply click on the button again and follow the steps described above.

The following screenshot shows an exemplary implementation with multiple event mappings or publishings:

Transmitting Data

This chapter briefly discusses the structure in which data is transmitted. Usually, you do not have to make any major changes to your firmware. Only when transferring several values per Publish is it necessary to maintain a structure. This is described in more detail in this chapter.

Concept

To transfer data to the Datacake cloud, it is sufficient to call Particle.publish(); in the code of your device and pass the measurement data via semicolon-separated values. Like this:

  • Particle.Publish("event","(51.96236,7.62571);42;1.23;hello world);

In this example, the transmitted measured values would be as follows:

  • Location = 51.96236, 7.62571

  • Integer = 42

  • Float = 1,23

  • String = "hello world"

We call this scheme "Event Mapping".

Aggregation

As shown in the example above, it is not necessary to define a separate Particle.publish(); for each type. You can merge as many fields as you like into one Publish. The maximum Publish Payload size specified by Particle.io is the limit.

Code Examples

Coordinates

In the following example, we send measurement data obtained via GPS from a Particle.io Asset Tracker to the Datacake Cloud.

AssetTracker t;
Particle.publish("gps",
String::format(
"(%f,%f);%f;%d;%d;%f;%f",
t.readLatDeg(),
t.readLonDeg(),
t.getAltitude(),
t.getSatellites(),
t.getTinyGPSPlus()->getHDOP().value(),
t.getTinyGPSPlus()->getSpeed().kmph(),
t.getAngle()
);

Create Dashboards

wip

Create Rules

wip

Invite People

wip