⚠️ The Arduino SDK has been retired due to a lack of contribution and use. If you intent to continue using this SDK you can still fork the repo. If you are interested in maintaining it please make yourself known and we would be happy to unarchive it.

Getting Started

If you haven’t installed the SDK yet, please head over to the Arduino SDK repository to install the SDK in the Arduino IDE. Note that this SDK requires the Arduino Yún and the Arduino IDE v1.6.0+.

The Parse platform provides a complete backend solution for your hardware device. Our goal is to totally eliminate the need for writing server code or maintaining servers.

Note that the Arduino SDK only contains a subset of Parse features found in mobile and desktop. This allows the SDK to be smaller in size and more performant, making it suitable for constrained embedded environments. The Arduino SDK is fully open source, and anyone can contribute to make it better, or make their own changes if necessary. Check out the GitHub repository for more information.

Initialization

In order for Parse to know which app is associated with the Arduino device, simply specify the application ID and client key in your setup function:

void setup() {
	Parse.begin("${APPLICATION_ID}", "${CLIENT_KEY}");
	// ...
}

After this, all calls to the Parse Server will use the specified app.

In order for the Arduino device to know where the Parse server is located, specify the URL in your setup function:

void setup() {
	Parse.begin("${APPLICATION_ID}", "${CLIENT_KEY}");
	Parse.setServerURL("parseapi.back4app.com");
	// ...
}

When the Arduino attempts to connect to the Parse server, it will need to know whether or not to connect using SSL. It is recommended to use SSL whenever possible.

Option 1: SSL

SSL requires that the Arduino know the server fingerprint. The server fingerprint can be found using the Chrome browser. Browse the secure server URL, press ctrl+shift+i, select security tab, click view certificate, and get the thumbprint from the details tab. Specify this as well in your setup function:

void setup() {
	Parse.begin("${APPLICATION_ID}", "${CLIENT_KEY}");
	Parse.setServerURL("parseapi.back4app.com");
	Parse.setHostFingerprint("${HOST_THUMBPRINT}");
	// ...
}

Option 2: Insecure

The Arduino can connect to Parse over an insecure connection if desired, but must be specified in your setup function:

void setup() {
	Parse.begin("${APPLICATION_ID}", "${CLIENT_KEY}");
	Parse.setServerURL("parseapi.back4app.com");
	Parse.setClientInsecure();
	// ...
}

Parse is now initialized and ready to make calls to the Parse server.

Objects

The Parse Object

Storing data on Parse is built around the Parse Object. Each Parse Object contains key-value pairs of JSON-compatible data. This data is schemaless, which means that you don’t need to specify ahead of time what keys exist on each object. You simply set whatever key-value pairs you want, and our backend will store it.

For example, let’s say you’re tracking data for your smart toaster. A single Parse Object could contain:

temperature: 175.0, leverDown: true

Keys must be alphanumeric strings. Values can be strings, numbers, booleans, or even arrays and dictionaries - anything that can be JSON-encoded.

Each object has a class name that you can use to distinguish different sorts of data. For example, we store the temperature data in a class called Temperature. We recommend that you NameYourClassesLikeThis and nameYourKeysLikeThis, just to keep your code looking pretty.

Saving Objects

Let’s say you want to save the Temperature described above to your Parse Server. You would do the following:

ParseObjectCreate create;
create.setClassName("Temperature");
create.add("temperature", 175.0);
create.add("leverDown", true);
ParseResponse response = create.send();
if (!response.getErrorCode()) {
	// The object has been saved
} else {
	// There was a problem, check response.
	getErrorCode();
}
response.close(); // Free the resource

After this code runs, you will probably be wondering if anything really happened. To make sure the data was saved, you can look at the Data Browser in your app on Parse. You should see something like this:

{
  "objectId": "xWMyZ4YEGZ",
  "score": 1337,
  "playerName": "Sean Plott",
  "cheatMode": false,
  "createdAt":"2022-01-01T12:23:45.678Z",
  "updatedAt":"2022-01-01T12:23:45.678Z"
}

There are two things to note here. You didn’t have to configure or set up a new Class called Temperature before running this code. Your Parse app lazily creates this Class for you when it first encounters it.

There are also a few fields you don’t need to specify that are provided as a convenience. objectId is a unique identifier for each saved object. createdAt andupdatedAt represent the time that each object was created and last modified in your Parse Server. Each of these fields is filled in by Parse, so they don’t exist on a Parse Object until a save operation has completed.

Retrieving Objects

Saving data to the cloud is fun, but it’s even more fun to get that data out again. If the object has been uploaded to the server, you can use the objectId to retrieve it using a query:

ParseObjectGet get;
get.setClassName("Temperature");
get.setObjectId("xWMyZ4YEGZ");
ParseResponse response = get.send();
double temp = response.getDouble("temperature");
Serial.println(temp);
response.close(); // Free the resource

Updating Objects

Updating an object is very similar to creating one. Assuming you have saved the object and have the objectId, can do the following:

ParseObjectUpdate update;
update.setClassName("Temperature");
update.setObjectId("xWMyZ4YEGZ");
update.add("temperature", 100);
update.send();

Deleting Objects

To delete an object from the cloud:

ParseObjectDelete del;
del.setClassName("Temperature");
del.setObjectId("xWMyZ4YEGZ");
del.send();

Data Types

So far we’ve used values with type string, double, and bool. The Parse Arduino SDK also supports GeoPoints (latitude and longitude). In addition, you can set values on objects via JSON and be able to represent Arrays, Objects, Dates, and more. Read more about representing these types as JSON in the REST API guide.

Overall, the following types are allowed for each field in your object:

• String => string
• Number => integer, double
• Boolean => bool
• Array => JSON Array
• Object => JSON Object
• Date => JSON Date
• File => ParseFile
• Pointer => other ParseObject
• Relation => ParseRelation

The type JSON Object simply denotes that each value can be composed of nested objects that are JSON-encodable. Keys including the characters $ or ., along with the key __type key, are reserved for the framework to handle additional types, so don’t use those yourself.

Some examples:

ParseObjectCreate create;
create.setClassName("TestObject");
create.add("number", 42.0);
create.add("foo", "bar");
create.addGeoPoint("location", 40.0, -30.0);
create.addJSONValue("dateField", "{ \"__type\": \"Date\", \"iso\": \"2022-01-01T12:23:45.678Z\" }"); create.addJSONValue("arrayField", "[ 30, \"string\" ]");
create.addJSONValue("objectField", "{ \"number\": 30, \"string\": \"baz\" }");
create.addJSONValue("emptyField", "null");
create.send();

We do not recommend storing large pieces of binary data like images or documents in a ParseObject. We recommend you use ParseFiles to store images, documents, and other types of files. You can do so by instantiating a ParseFile object and setting it on a field. See the Files section in the REST documentation for more details.

For more information about how Parse handles data, check out our documentation on Data.

Queries

We’ve already seen how a ParseObjectGet with an objectId can retrieve a single object from Parse. There are many other ways to retrieve data with ParseQuery – you can retrieve many objects at once, put conditions on the objects you wish to retrieve, and more.

Basic Queries

The general pattern is to create a ParseQuery, put conditions on it, and then retrieve objects from the response. For example, to retrieve temperature data at a particular temperature, use thewhereEqualToInt function to constrain the value for a key.

ParseQuery query;
query.setClassName("Temperature");
query.whereEqualTo("temperature", 100.0);
ParseResponse response = query.send();
int countOfResults = response.count();
Serial.println(countOfResults);
while(response.nextObject()) {
	Serial.println(response.getJSONBody());
	Serial.println(response.getDouble("temperature"));
	Serial.println(response.getString("createdAt"));
}
response.close(); // Free the resource

Query Constraints

Your query should have at least one constraint. There are several ways to put constraints on the objects found by a query. You can filter out objects with a particular key-value pair with:

query.whereNotEqualTo("toaster", "foo");

You can give multiple constraints, and objects will only be in the results if they match all of the constraints. In other words, it’s like an AND of constraints.

query.whereEqualTo("leverDown", true);
query.whereEqualTo("temperature", 100.0);

You can limit the number of results by setting a limit. By default, results are limited to 100. In the old Parse hosted backend, the maximum limit was 1,000, but Parse Server removed that constraint:

query.setLimit(10);

You can skip the first results by setting skip. In the old Parse hosted backend, the maximum skip value was 10,000, but Parse Server removed that constraint. This can be useful for pagination:

query.setSkip(10);

For sortable types like numbers and strings, you can control the order in which results are returned:

// Sorts the results in ascending order by the temperature field
query.orderBy("temperature");
// Sorts the results in descending order by the temperature field
query.orderBy("-temperature");

You can sort by multiple keys as follows:

query.orderBy("temperature,name");

For sortable types, you can also use comparisons in queries:

// Restricts to temperatures < 50
query.whereLessThan("temperature", 50.0);
// Restricts to temperatures > 50 query.
whereGreaterThan("temperature", 50.0);
// Restricts to temperatures >= 50 query.
whereGreaterThanOrEqualTo("temperature", 50.0);

You can restrict the fields returned by calling setKeys with a list of keys as a string. To retrieve objects that contain only the temperature field (and also special built-in fields such asobjectId,createdAt, andupdatedAt):

query.setKeys("temperature");

This is useful if the object has fields which are not required by the device. Since the Arduino is a constrained environment, we recommend using a combination of setKeys andsetLimit to reduce processing and memory overhead.

Requests

Because the Arduino SDK was designed to minimize memory footprint, it doesn’t provide direct functions for all the Parse features that are present in the mobile SDKs. However, it does have the capability to call the REST API, which offers the full range of functionality.

For example, you could sign up a user from Arduino through a REST call:

ParseResponse response = Parse.sendRequest("POST", "/parse/users", "{\"username\":\"cooldude6\",\"password\":\"p_n7!-e8\"}", "");

In this case, the response will contain the objectId of the created user, assuming it was created successfully.

Head on over to the REST API documentation to discover what’s possible. For each code sample, you can switch it to cURL to see what the endpoint and payload would look like.

Users and Sessions

At the core of many apps, there is a notion of user accounts that lets users access their information in a secure manner. In our other SDKs, we provide a specialized user class that automatically handles much of the functionality required for user account management. Users are a special class of Parse Objects and has all the same features, such as flexible schema, automatic persistence, and a key value interface.

The Arduino SDK does not provide methods to directly sign in as a user. If you want to have the Arduino device act on behalf of a user, you will need to create a Session through a companion app or another Parse SDK and pass a Restricted Session to the device. You can read more about users in our REST API or one of our other SDK guides.

Setting a Session

Once you have created a Restricted Session via the companion app or through the REST API, you can send the Session Token to the Arduino using push notifications, BLE, or some other appropriate method. After that, you can set it:

Parse.setSessionToken("r:olqZkbv8fefVFNjWegyIXIggd");

From then on, the device will act on behalf of the user.

User Security

Parse uses ACLs to make sure objects can be accessed by users who are authorized with access. When creating objects, you can set the ACL field of the object to restrict access to a set of users. Read about this and more in the REST API documentation.

Push Notifications

Using Push Notifications, you’ll be able to send realtime notifications to your Arduino. This can be triggered by changes in your data, custom code in Cloud Code, a companion mobile app, and much more.

Installations

Every Parse application installed on a device registered for push notifications has an associated Installation object. The Installation object is where you store all the data needed to target push notifications. For example, you could send a connected thermostat a push to change the desired temperature.

There are two ways to create an Installation for the Arduino. You can generate an installation ID (random lowercase UUID) elsewhere (e.g. phone), send that to your arduino during initial provisioning, then set the installation ID on the arduino:

// In this example, we associate this device with a pre-generated installation ID
Parse.setInstallationId("ab946c14-757a-4448-8b77-69704b01bb7b");

The installation ID is a unique identifier for the device, so you should make sure to assign different installation IDs to different devices (i.e. your UUID generator has enough randomness). After you do the above, the arduino will automatically create an Installation object with this installation ID.

If you do not pass in an installation ID, theParseClient will automatically generate an installation ID for you, and create an Installation object with it upon the first request sent to Parse.

You can retrieve your installation ID with thegetInstallationId function:

String installationId = Parse.getInstallationId();

The installation ID is persisted across reboots.

The Installation class has several special fields that help you manage and target devices. The relevant ones for Arduino are:

• channels: An array of the channels to which a device is currently subscribed.
• deviceType: The type of device, “ios”, “android”, “winrt”, “winphone”, “dotnet”, or “embedded” (readonly).
• installationId: Universally Unique Identifier (UUID) for the device used by Parse. It must be unique across all of an app’s installations.(readonly).
• appName: The display name of the client application to which this installation belongs.
• appVersion: The version string of the client application to which this installation belongs.
• parseVersion: The version of the Parse SDK which this installation uses.

Subscribing to Pushes

To subscribe to push notifications, make the following call in yoursetup function:

Parse.startPushService();

Then, in your loop function:

if (Parse.pushAvailable()) {
	ParsePush push = Parse.nextPush();
	// Print whole JSON body
	String message = push.getJSONBody();
	Serial.print("New push message size: ");
	Serial.println(message.length());
	Serial.print("New push message content: ");
	Serial.println(message);
	// Do something with the push
	// IMPORTANT, close your push message
	push.close();
}

Sending Pushes

There are many ways to send a push notification. It’s possible to send from the Arduino SDK via a call to the REST API, but you’ll most likely be sending from another environment. Read here for more information on how to send pushes.

Analytics

Some examples:

ParseTrackEvent trackEvent;
trackEvent.setEventName("ButtonPress");
trackEvent.send();

Cloud Functions

Cloud Functions allow you to run custom app logic on your Parse Server. This is especially useful for running complex app logic in the cloud so that you can reduce the memory footprint of your code on the IoT device. In a Cloud Function, you can query/save Parse data, send push notifications, and log analytics events.

You write your Cloud Code in JavaScript using the Parse JavaScript SDK. We provide a command-line tool to help you deploy your Cloud Code. See our Cloud Code guide for details.

For example, you define a Cloud Function as below.

Parse.Cloud.define("hello", request => {
	return request.body;
});

Then you can invoke this Cloud Function from your device:

ParseCloudFunction cloudFunction;
cloudFunction.setFunctionName("hello");
cloudFunction.add("value", "echo from hello");
ParseResponse response = cloudFunction.send();

Error Codes

The following is a list of all the error codes that can be returned by the Parse API. You may also refer to RFC2616 for a list of http error codes. Make sure to check the error message for more details.

API Issues

Push related errors

File related errors

Installation related errors

Purchase related errors

User related errors

Linked services errors

Client-only errors

Operational issues

Other issues

Error Code Ranges

In order to provide better organization and avoid conflicts with Parse Platform’s built-in Parse.Error codes, the following ranges are defined:

Parse Server and Related Modules

• Error code range: <= 4999 (including negative numbers)
• This range is reserved exclusively for errors generated by Parse Server and its directly related modules. It includes all predefined errors listed in the documentation.

Reserved

• Error code range: >= 5000 and <= 8999
• This range is currently reserved for future use and should not be used by anyone.

App Developers (Custom App Errors)

• Error code range: >= 9000 and <= 9999
• Developers may use this range for defining custom errors specific to their applications. This range is reserved to ensure that custom application errors do not conflict with those defined by Parse Server and its modules.

3rd Party Providers of Parse Platform Components

• We discourage from introducing new custom error codes in 3rd party components, as they may conflict with either of the reserved ranges mentioned above. Instead, use the general internal Parse Server error code 1 and add any specific information in the error message, or use another pre-defined error code of Parse Platform.