Arduino JSON Parsing: ESP32 API Debugging & Code Guide

The Verdict: Which Arduino JSON Library to Pick

If you are pulling API data, parsing MQTT payloads, or formatting telemetry on a microcontroller, you need a JSON library that respects RAM limits and handles nested objects without crashing. The direct answer: use ArduinoJson v7 by Benoit Blanchon for 95% of ESP32 and Arduino projects. It is the undisputed industry standard for embedded C++ JSON manipulation.

Here is the decision path to confirm this is the right pick for your specific build:

Hardware Spec Sheet and Pin Mapping

This guide targets the ESP32-DevKitC V4 (specifically the ESP32-WROOM-32 module). The ESP32's dual-core 240MHz processor and 520KB of SRAM make it ideal for JSON serialization tasks that would choke an ATmega328P. We will parse a mock API response and render the extracted values to a local display.

Parts List

• MCU: ESP32-DevKitC V4 (ESP32-WROOM-32) — ~$6.00
• Display: 0.96" SSD1306 I2C OLED (128x64, 3.3V logic) — ~$4.50
• Wiring: 22 AWG solid core jumper wires, half-size breadboard
• Libraries Required: ArduinoJson (v7.x), Adafruit SSD1306, Adafruit GFX

Pin Mapping Table

Step-by-Step: Parsing and Generating JSON on the ESP32

Below is the complete, compilable firmware. To isolate the JSON logic from WiFi credential debugging, this code uses a hardcoded raw JSON string simulating an OpenWeatherMap-style API response. In a production build, you would pipe the HTTPClient payload stream directly into the deserializer.

#include <ArduinoJson.h>
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

// --- PIN DEFINITIONS ---
#define PIN_STATUS_LED 2
#define I2C_SDA 21
#define I2C_SCL 22

// --- DISPLAY CONFIG ---
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1
#define SCREEN_ADDRESS 0x3C

Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

// Mock API payload (simulating an HTTP GET response)
const char* mock_api_response = R"({
  "location": {
    "city": "Austin",
    "region": "TX"
  },
  "current": {
    "temp_c": 28.5,
    "humidity": 62,
    "condition": "Partly Cloudy",
    "alerts": ["Heat Advisory", "Ozone Warning"]
  },
  "timestamp": 1715623400
})";

void setup() {
  Serial.begin(115200);
  pinMode(PIN_STATUS_LED, OUTPUT);
  digitalWrite(PIN_STATUS_LED, LOW);

  // Initialize I2C and OLED
  Wire.begin(I2C_SDA, I2C_SCL);
  if(!display.begin(SSD1306_SWITCHCAPVCC, SCREEN_ADDRESS)) {
    Serial.println(F("SSD1306 allocation failed"));
    for(;;); // Halt execution
  }
  display.clearDisplay();
  display.setTextSize(1);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0,0);
  display.println("Booting JSON Parser...");
  display.display();
  delay(1000);

  parseAndGenerateJson();
}

void loop() {
  // Main loop idle; parsing handled in setup for this demo
  delay(10000);
}

void parseAndGenerateJson() {
  // 1. Parse the incoming JSON (v7 syntax)
  JsonDocument incomingDoc;
  DeserializationError error = deserializeJson(incomingDoc, mock_api_response);

  if (error) {
    Serial.print(F("deserializeJson() failed: "));
    Serial.println(error.f_str());
    display.clearDisplay();
    display.setCursor(0,0);
    display.print("ERR: ");
    display.println(error.f_str());
    display.display();
    return;
  }

  // 2. Extract values safely
  const char* city = incomingDoc["location"]["city"]; // "Austin"
  float temp = incomingDoc["current"]["temp_c"];      // 28.5
  int humidity = incomingDoc["current"]["humidity"];  // 62
  
  // Extracting array elements
  const char* first_alert = incomingDoc["current"]["alerts"][0]; // "Heat Advisory"

  // 3. Render to OLED
  display.clearDisplay();
  display.setCursor(0,0);
  display.printf("City: %s\n", city);
  display.printf("Temp: %.1f C\n", temp);
  display.printf("Hum: %d%%\n", humidity);
  display.printf("Alert: %s\n", first_alert);
  display.display();

  // 4. Generate a new JSON telemetry payload to send back
  JsonDocument outgoingDoc;
  outgoingDoc["device_id"] = "ESP32_Node_01";
  outgoingDoc["status"] = "nominal";
  outgoingDoc["metrics"]["temp"] = temp;
  outgoingDoc["metrics"]["uptime_ms"] = millis();

  Serial.println(F("\n--- Outgoing Telemetry ---"));
  serializeJsonPretty(outgoingDoc, Serial);
  
  digitalWrite(PIN_STATUS_LED, HIGH); // Flash LED on success
}

Debugging: Exact Error Strings and Ranked Fixes

When deserializeJson() fails, it returns a DeserializationError enum. Do not guess what went wrong; print error.f_str() to the Serial monitor and match it against this decision tree.

The First Three Things to Check

1. Validate the raw string: Copy the exact payload from your Serial monitor and paste it into JSONLint. Look for trailing commas, unescaped quotes, or single quotes instead of double quotes.
2. Check stream termination: If reading from an HTTP stream, ensure the server isn't closing the connection before the payload finishes transmitting.
3. Verify baud rate mismatches: If your Serial monitor is set to 9600 but the code uses 115200, the garbage characters you see aren't bad JSON; they are corrupted bytes.

Exact Error Strings and Ranked Causes

Extending the Build: MQTT and Dynamic Payloads

The code above isolates the parsing logic, but real-world IoT nodes need to pull data from the network and push telemetry over MQTT. Here is how to extend or simplify this architecture.

How to Simplify (Resource Constrained)

If you are porting this to an ATtiny85 or an Arduino Nano and running out of flash memory:

• Drop the Adafruit GFX/SSD1306 libraries (they consume ~15KB of flash).
• Use serializeJson(doc, Serial) instead of serializeJsonPretty to save string formatting overhead.
• Use the ArduinoJson filtering feature to ignore nested objects you don't need, drastically reducing RAM overhead during deserialization.

How to Extend (Production IoT Node)

To turn this into a live MQTT telemetry node, swap the mock string for a live stream and integrate PubSubClient:

1. Fetch via HTTP: Use WiFiClientSecure and HTTPClient. Pass the client object directly into deserializeJson(doc, client). This streams the JSON directly from the network buffer into the parser, avoiding the need to store the entire raw string in RAM first.
2. Publish via MQTT: Create a JsonDocument for your sensor readings. Use serializeJson(doc, mqtt_buffer, sizeof(mqtt_buffer)) to write the payload into a character array, then pass that array to client.publish("home/sensors/node01", mqtt_buffer).
3. Handle Deep Sleep: If running on battery, wrap the parsing logic in a function, trigger esp_deep_sleep_start() immediately after the MQTT publish completes, and use the ESP32's RTC memory to retain state across reboots.

For detailed memory profiling and advanced allocator configurations, refer to the ArduinoJson ESP32 PSRAM guide and the Espressif Memory Allocation documentation. By standardizing on ArduinoJson v7 and respecting the ESP32's heap boundaries, your embedded API integrations will remain stable across months of continuous uptime.