ArduinoJson: read and write JSON on an Arduino or ESP32
ArduinoJson, by Beno卯t Blanchon, is the standard way to handle JSON on a microcontroller: parse an API鈥檚 reply into values you can index like doc["main"]["temp"], or build an object and print it to Serial, a web page or an MQTT message. It works the same on an Uno as on an ESP32, though the Uno鈥檚 2 KB of RAM limits how big a document can be.
Built in on Mokxi: #include <ArduinoJson.h> and it builds, with nothing to install. Free, and no account needed.
What ArduinoJson does
Version 7 has one type, JsonDocument, which grows as needed. Version 6, which many tutorials still show, made you choose StaticJsonDocument<200> or DynamicJsonDocument(1024) with a fixed capacity, and createNestedArray() instead of doc["data"].to<JsonArray>(). Code written for one version mostly compiles on the other, but the capacity numbers in 6.x examples are what cause "NoMemory" when an input grows.
Reading is deserializeJson(doc, input), where input can be a char array, a String, Serial, a WiFiClient or a File, and it returns a DeserializationError you should test before using anything in the document.
| Library Manager name | ArduinoJson |
|---|---|
| Author | Benoit Blanchon |
| Include | #include <ArduinoJson.h> |
| Boards | every board Mokxi compiles for but ATtiny85 |
| In the simulator | Simulated: it runs against the part the way it does on the bench. |
Install it
It builds on every board Mokxi compiles for but ATtiny85.
In Mokxi it is built in: #include <ArduinoJson.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "ArduinoJson" by Benoit Blanchon from the Arduino IDE鈥檚 Library Manager (Sketch, Include Library, Manage Libraries), or add ArduinoJson to lib_deps in PlatformIO. Mokxi follows the calls of release 7.3.0, so a sketch written here builds there too.
What to know in the simulator: Integers are 32 bits. A document鈥檚 capacity is not enforced: it takes what the heap gives. A filtered read keeps what the filter names once the whole input is read, rather than skipping the rest as it goes.
ESP32-C3 路 Arduino Uno 路 Arduino Nano 路 Arduino Mega 2560 路 Arduino Leonardo 路 SparkFun Pro Micro 路 Arduino Micro 路 ESP32-C6 路 Raspberry Pi Pico 路 Raspberry Pi Pico W 路 Seeed XIAO SAMD21 路 STM32 路 STM32 Nucleo-F411RE 路 STM32 Blue Pill 路 micro:bit V2 路 Arduino Uno R4 路 ESP32 DevKit 路 ESP32-S3-DevKitC-1 路 ESP8266 NodeMCU 路 Arduino Pro Mini 3.3 V 路 Seeed XIAO ESP32-C3 路 ESP32-C3 SuperMini 路 Seeed XIAO ESP32-C6 路 ESP32-DevKitC V4 路 LOLIN32 Lite 路 Wemos D1 R32 路 Cheap Yellow Display 路 TTGO T-Display 路 Seeed XIAO ESP32-S3 路 Arduino Nano ESP32 路 Arduino Nano RP2040 Connect 路 Seeed XIAO RP2040 路 Waveshare RP2040-Zero 路 Arduino Uno R4 WiFi
The calls you will use
In the order a sketch meets them.
JsonDocument doc
A document that holds a whole JSON tree. In 6.x write StaticJsonDocument<256> doc; with a capacity in bytes.
DeserializationError error = deserializeJson(doc, json)
Parses JSON text into the document. error is false on success; error.c_str() gives the reason, such as InvalidInput or NoMemory.
DeserializationError error = deserializeJson(doc, http.getString());
if (error) {
Serial.println(error.c_str());
return;
}float temp = doc["main"]["temp"]
Reads a value by key and index. The assignment converts it; a missing key gives 0 or a null pointer instead of crashing.
doc["sensor"] = "gps"
Adds or replaces a member. Numbers, booleans, strings and nested objects all work.
JsonArray data = doc["data"].to<JsonArray>()
Creates a nested array; data.add(48.75) appends to it. createNestedArray("data") is the 6.x spelling.
serializeJson(doc, Serial)
Writes the document as compact JSON to any Print: Serial, a String, a client or a file. serializeJsonPretty() adds line breaks and indents.
measureJson(doc)
The length the serialized JSON will have, for a Content-Length header or a buffer size.
doc.containsKey("error")
True when the member exists, which tells "missing" apart from a value that happens to be 0.
Example: Write and read JSON
On the Arduino Uno R3. It runs in the browser exactly as printed.
#include <ArduinoJson.h>
void setup() {
Serial.begin(9600);
// Write: a document, a nested array, out to the serial monitor.
JsonDocument doc;
doc["sensor"] = "gps";
doc["time"] = 1351824120;
JsonArray data = doc["data"].to<JsonArray>();
data.add(48.75608);
data.add(2.302038);
serializeJson(doc, Serial);
Serial.println();
// Read it back, the way a sketch reads a reply from a web service.
char json[] = "{\"sensor\":\"gps\",\"time\":1351824120,\"data\":[48.75608,2.302038],\"ok\":true}";
JsonDocument in;
DeserializationError error = deserializeJson(in, json);
if (error) {
Serial.print("deserializeJson() failed: ");
Serial.println(error.c_str());
return;
}
const char *sensor = in["sensor"];
long time = in["time"];
double latitude = in["data"][0];
bool ok = in["ok"] | false;
Serial.print("sensor ");
Serial.println(sensor);
Serial.print("time ");
Serial.println(time);
Serial.print("latitude ");
Serial.println(latitude, 5);
Serial.print("ok ");
Serial.println(ok ? "yes" : "no");
serializeJsonPretty(in["data"], Serial);
Serial.println();
}
void loop() {}Common errors and how to fix them
deserializeJson() failed: NoMemory
In 6.x the document鈥檚 capacity is too small for the input: raise the number in StaticJsonDocument<N>, or use the ArduinoJson Assistant to size it. In 7.x it means the heap is full, so filter the input or use a board with more RAM.
deserializeJson() failed: InvalidInput
What you passed is not JSON: often an HTTP error page, a reply cut short, or bytes left over from a previous read. Print the input first and check the status code before parsing.
A string read from the document turns into garbage later
A const char* taken from doc["name"] points into the document, so it is only valid while the document lives and is not cleared. Copy it into a String or a char array if you need it after that.
Questions and answers
ArduinoJson or Arduino_JSON?
ArduinoJson is faster, smaller and documented in depth, and most libraries that take JSON expect it. Arduino_JSON feels like JavaScript (JSONVar, JSON.parse) and suits short ESP32 web examples. Do not mix them in one sketch.
Keep going
Try ArduinoJson without installing anything
Open the example, change the sketch, and keep your version in a free account.