There are several ways to deserialize a JSON document; in this tutorial, we’ll only see the simplest.

The example

For our example, we’ll consider the following JSON document:

{"sensor":"gps","time":1351824120,"data":[48.756080,2.302038]}

The steps

1. Include ArduinoJson

Before writing any code, don’t forget to include the header:

#include <ArduinoJson.h>

2. Place the JSON document in memory

In this tutorial, we use ArduinoJson in the zero-copy mode, so the input must be writable.

We’ll place the document in stack memory with the following statement:

char json[] = "{\"sensor\":\"gps\",\"time\":1351824120,\"data\":[48.756080,2.302038]}";

3. Allocate a JsonBuffer

ArduinoJson uses a memory pool, the JsonBuffer, to perform all memory allocations.

In this tutorial, we create a 200-byte pool in the stack, with the following statement:

StaticJsonBuffer<200> jsonBuffer;

You can learn more on this topic in the page “ArduinoJson memory model”.

4. Deserialize the JSON document

To deserialize a JSON object, you need to call JsonBuffer::parseObject(). This function takes the JSON document as input and returns a reference to a JsonObject.

JsonObject& root = jsonBuffer.parseObject(json);

It’s important to understand that the JsonObject resides in the JsonBuffer and will be destructed with it.

5. Check if deserialization succeeded

To check if the parsing was successful, you call JsonObject::success():

if (!root.success()) {
  // Parsing failed :-(
}

There are only a few reasons why parsing can fail; please read Why parsing fails?.

6. Retrieve the values

JsonObject provides an in-memory representation of the JSON document; you can use it to extract values from the document.

In most case, you can simply use JsonObject::operator[]:

const char* sensor = root["sensor"];
long time = root["time"];
double latitude  = root["data"][0];
double longitude = root["data"][1];

However, if the same array is used many times, it’s faster to extract a reference to the JsonArray:

JsonArray& data = root["data"];
double latitude  = data[0];
double longitude = data[1];

Complete source code

// Step 1
#include <ArduinoJson.h>

void setup() {
  Serial.begin(9600);
  while (!Serial) continue;

  // Step 2
  char json[] =
      "{\"sensor\":\"gps\",\"time\":1351824120,\"data\":[48.756080,2.302038]}";

  // Step 3
  StaticJsonBuffer<200> jsonBuffer;

  // Step 4
  JsonObject& root = jsonBuffer.parseObject(json);

  // Step 5
  if (!root.success()) {
    Serial.println("parseObject() failed");
    return;
  }

  // Step 6
  const char* sensor = root["sensor"];
  long time = root["time"];
  double latitude = root["data"][0];
  double longitude = root["data"][1];

  Serial.println(sensor);
  Serial.println(time);
  Serial.println(latitude, 6);
  Serial.println(longitude, 6);
}

void loop() {}

See also

Keep learning

Mastering ArduinoJson

This tutorial was only a quickstart introduction to the library. For a complete course on ArduinoJson, I strongly recommend reading the book “Mastering ArduinoJson”.

Chapter 3 is a much longer tutorial on deserialization. It starts with a simple example, like this one, but then gradually adds complexity to show all the features of the library. At the end of the chapter, we see how to download weather forecast from Yahoo Weather.

Chapter 2 is a quick C++ course to catch up with concepts like stack and heap memory, pointer, reference… I know from experience that new users of ArduinoJson have more difficulties with the language than with the library; that’s why the book starts with this course.

If you want to see what’s more in “Mastering ArduinoJson”, please check out the Table of Content.