Getting Started

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. Using our C SDKs, all it takes is a few lines of code to save and retrieve data from the Parse Server.

We provide two open source reference implementations for embedded environments:

1. Embedded C SDK - Targeted for Linux. This can be adapted to target OSes like Ubuntu, Debian, and others.
2. Embedded RTOS C SDK - Targeted for Real Time OSes. This can be adapted for other embedded RTOS environments.

Both these SDKs provide a consistent interface to interact with the Parse REST API, but with different underlying implementations.

On Parse, you create an App for each of your mobile and embedded applications. Each App has its own application ID and client key that you apply to your SDK install. Your account on Parse can accommodate multiple Apps. This is useful even if you have one application, since you can deploy different versions for test and production.

Install the SDK on your device

Install a few tools

Run the following lines in your Linux terminal:

sudo apt-get update
sudo apt-get install autoconf automake libtool
sudo apt-get install libcurl4-openssl-dev uuid-dev

Download the SDK

git clone https://github.com/parse-community/parse-embedded-sdks.git

Build the SDK

Next, navigate to the newly downloaded directory and run a few commands to build the SDK. After this, the C library will be available globally on device.

cd parse-embedded-sdks
touch README
autoreconf -fi
./configure --prefix=/usr
make
sudo make install

Initialization

In order for Parse to know which app is associated with the connected device, simply specify the application ID and client key in the device code:

ParseClient client = parseInitialize("${APPLICATION_ID}", "${CLIENT_KEY}");

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

Objects

The Parse Object

Storing data through the Parse REST API is built around a JSON encoding of the object’s 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 the 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.

Data Types

So far we’ve used values with type double and bool. The Parse REST API also supports strings, arrays, dates, and more. Read more about representing these and other types as JSON in the REST API Guide.

Requests

The main way you’ll be interacting with Parse is through the parseSendRequest function, which sends a request to the REST API. For example, here’s how to save an object with some data:

char data[] = "{ \"temperature\": 165 }"; parseSendRequest(client, "POST", "/parse/classes/Temperature", data, NULL);

For some requests you will be interested in data returned for the request. In such a case you need to setup a callback and pass it to parseSendRequest.

void mySaveCallback(ParseClient client, int error, int httpStatus, const char* httpResponseBody) {
	if (error == 0 && httpResponseBody != NULL) {
		// httpResponseBody holds the response to the request
	}
}

parseSendRequest(client, "GET", "/parse/classes/TestObject/gsMHOY3MAx", NULL, myCallback);

Using this function, you have full access to the REST API to create objects, delete objects, send analytics events, and more. Take a look at the REST API Guide to find out all the details.

Users & 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.

You can sign in users via the REST API, but we do not recommend doing so unless your hardware device actually provides user keyboard input. In some cases, you may want to have a companion mobile or desktop app that lets the user sign up, and, that app creates a restricted session for the device running the embedded SDK. During your hardware device provisioning process, the phone can send this restricted session’s token to the device. You can read more about users in our REST API or one of our other SDK guides.

Once you have a session token, you can use it to act on the behalf of a particular user. The session token used by the SDK can be set withparseSetSessionToken:

char token[] = "r:olqZkbv8fefVFNjWegyIXIggd";
parseSetSessionToken(client, token);

Once the session token is set, it will be associated with the current installation if it is not already associated with an installation. This association can be done only once and is automatically done by the SDK.

A session token is tied to a specific installation (specified by the installationId field on the Session object). Attempts to use a session token for another installation will result in errors.

If a session token is set before an installation is set, the SDK will create an installation for you. Thus, if you have a specific pair of installation ID and session token you need to use, you should set the installation ID first.

The session token can be cleared withparseClearSessionToken function. Once the token is cleared, the device will not be authenticated as the user anymore:

parseClearSessionToken(client);

One can get the current session token by doing:

char* session_token = parseGetSessionToken(client);

The session token will be persistent across reboots. Note that we highly recommend using Restricted Sessions on hardware devices, especially ones that do not provide a high level of client security. For more details, check out the guide on Sessions.

Push Notifications

Using Push Notifications, you’ll be able to send realtime notifications to your device. 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 in conjunction with your hardware device. You can generate an installation ID (random lowercase UUID) elsewhere (e.g. phone), send that to your hardware device during initial provisioning, then set the installation ID on the hardward device:

char data[] = "ab946c14-757a-4448-8b77-69704b01bb7b";
parseSetInstallationId(client, data);

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 device will automatically create an Installation object with this installation ID.

If you do not pass in an installation ID, the SDK will automatically generate an installation ID for you, and create an Installation object with it upon the first request sent to Parse. There are several events that will trigger this:parseGetInstallationId,parseSetSessionToken,parseSendRequest, andparseStartPushService.

You can retrieve your installation ID with theparseGetInstallationId function:

char* installation_id = parseGetInstallationId(client);

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 embedded devices 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

In order to subscribe to push notifications, you’ll need to start the push service and define how your device will handle a push when it is received.

First, we define the push callback function:

void myPushCallback(ParseClient client, int error, const char *buffer) {
	if (error == 0 && buffer != NULL) {
		printf("push: '%s'\n", buffer);
	}
}

Then, we set the callback and start the push service loop:

parseSetPushCallback(client, myPushCallback);
parseStartPushService(client);
parseRunPushLoop(client);

In cases where there is already an explicit application loop, we can integrate push into it using a file handle obtained with theparseGetPushSelectHandle function. Then we call theparseProcessNextPushEvent function on each iteration of the loop (not only when there is data on the file descriptor). TheparseProcessNextPushEvent function will call the push callback if there is a new push message.

To do this we must first include the respective libraries:

#include <sys/time.h>

Then add the following logic to your method:

// ...
parseSetPushCallback(client, myPushCallback);
parseStartPushService(client);
int socket = parseGetPushSocket(client);
while(1) {
	struct timeval tv;
	fd_set receive, send, error;

	// tv_sec defines the interval at which the method is executed.
	// The lower the value the more responsive it will be to notifications.

	tv.tv_sec = 10;
	tv.tv_usec= 0;
	FD_ZERO(&receive);
	FD_ZERO(&send);
	FD_ZERO(&error);
	FD_SET(socket, &error);
	FD_SET(socket, &receive);
	select(socket + 1, &receive, &send, &error, &tv);

	// ...

	parseProcessNextPushNotification(client);
}

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

void myCloudFunctionCallback(ParseClient client, int error, int httpStatus, const char* httpResponseBody) {
	if (error == 0 && httpResponseBody != NULL) {
		// httpResponseBody holds the Cloud Function response
	}
}
parseSendRequest(client, "POST", "/parse/functions/hello", "{\"value\":\"echo\"}", myCloudFunctionCallback);

Sample App

We prepared a sample app that demonstrates how to provision connected devices using a companion phone app such that connected devices can securely access user-specific data on Parse Server. This sample app also demonstrates how to send push notifications between the phone app and connected devices.

Handling Errors

There are two main ways an error from the SDK can be propagated to the caller - as a return result of the method call, or through the request and push callbacks.

All functions that return a result will return 0 on success and a non-zero value on error. The error value will be an OS-specific error (for example, socket errors).

The errors passed through callbacks are again OS-specific errors. The one exception is if there is an HTTP error status (4xx or 5xx) for a request, in which case, the HTTP status will be passed as separate parameters to the request callback.

In the case of an HTTP error status, you should also check the request body. If the request body contains a valid JSON document, the document will contain a Parse error code, as defined by the REST API documentation.

For a list of all possible error codes, scroll down to Error Codes.

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.