How to Create a Base64 Encoded String in ArduinoJson for ESP32

The Short Answer: Encoding Base64 for ArduinoJson

ArduinoJson is strictly a JSON serialization library; it does not natively encode or decode binary data into Base64. To create a Base64 encoded string in ArduinoJson, you must first encode your binary payload using a dedicated Base64 library, then assign the resulting C-string to your JsonDocument object. Attempting to pass raw binary bytes directly into a JSON string field will result in null-byte truncation or invalid JSON syntax errors on the receiving server.

Because microcontrollers have limited SRAM, the 33% size expansion inherent to Base64 encoding frequently triggers heap exhaustion. Below is the decision path to select the right encoding library for your specific silicon.

Base64 Library Decision Tree

Hardware & Software Bill of Materials

To demonstrate this in a real-world scenario, we will encode binary audio data captured from an I2S MEMS microphone into a JSON payload for cloud transmission.

Parts List

• Microcontroller: ESP32 DevKit V1 (ESP32-WROOM-32, 4MB Flash, 520KB SRAM)
• Sensor: INMP441 Omnidirectional I2S MEMS Microphone Module
• Wiring: 20 AWG silicone jumper wires (breadboard compatible)
• Power: 5V 2A USB-C power supply (to prevent brownouts during WiFi transmission)

Software Requirements

• Arduino IDE 2.x or PlatformIO
• ESP32 Board Package v3.x (Espressif Systems)
• ArduinoJson v7.0+ by Benoit Blanchon (Install via Library Manager)

Difficulty Rating: Intermediate. The wiring is trivial, but managing heap memory during the Base64 conversion requires strict discipline to avoid watchdog resets.

Pin Mapping: INMP441 I2S Binary Source

The INMP441 outputs raw binary PCM audio data via the I2S protocol. The ESP32's I2S peripheral handles the heavy lifting, dumping the binary bytes into a RAM buffer that we will subsequently encode.

Complete Compilable Code: ESP32 Base64 to JSON

The following code initializes the I2S peripheral, reads a 512-byte block of raw binary audio, encodes it to Base64, and packages it into an ArduinoJson document. It includes explicit error handling for serialization failures.

#include <ArduinoJson.h>
#include <base64.h> // Native ESP32 library
#include <driver/i2s.h>

// Target: ESP32 DevKit V1 (ESP32-WROOM-32)
// ArduinoJson v7.x

#define I2S_WS 25
#define I2S_SCK 26
#define I2S_SD 22
#define I2S_PORT I2S_NUM_0
#define BUFFER_SIZE 512 // Bytes of raw binary data

void setup() {
  Serial.begin(115200);
  delay(1000);
  Serial.println("Initializing I2S and JSON Encoder...");

  // Configure I2S for INMP441 Microphone
  i2s_config_t i2s_config = {
    .mode = (i2s_mode_t)(I2S_MODE_MASTER | I2S_MODE_RX),
    .sample_rate = 16000,
    .bits_per_sample = I2S_BITS_PER_SAMPLE_16BIT,
    .channel_format = I2S_CHANNEL_FMT_ONLY_LEFT,
    .communication_format = I2S_COMM_FORMAT_STAND_I2S,
    .intr_alloc_flags = ESP_INTR_FLAG_LEVEL1,
    .dma_buf_count = 4,
    .dma_buf_len = 1024,
    .use_apll = false
  };

  i2s_pin_config_t pin_config = {
    .bck_io_num = I2S_SCK,
    .ws_io_num = I2S_WS,
    .data_out_num = I2S_PIN_NO_CHANGE,
    .data_in_num = I2S_SD
  };

  i2s_driver_install(I2S_PORT, &i2s_config, 0, NULL);
  i2s_set_pin(I2S_PORT, &pin_config);
  i2s_zero_dma_buffer(I2S_PORT);
}

void loop() {
  uint8_t rawBuffer[BUFFER_SIZE];
  size_t bytesRead = 0;

  // 1. Read raw binary data from I2S sensor
  i2s_read(I2S_PORT, rawBuffer, BUFFER_SIZE, &bytesRead, portMAX_DELAY);

  if (bytesRead > 0) {
    // 2. Encode binary to Base64 string
    // base64::encode returns a String object in ESP32 core
    String b64String = base64::encode(rawBuffer, bytesRead);

    // 3. Create ArduinoJson Document
    // ArduinoJson v7 automatically sizes the document, but we can reserve capacity
    JsonDocument doc;
    doc["device_id"] = "ESP32_Audio_Node_01";
    doc["sample_rate"] = 16000;
    
    // Assign the Base64 string to the JSON object
    doc["audio_payload"] = b64String;

    // 4. Serialize and transmit with error handling
    size_t jsonLen = measureJson(doc);
    Serial.printf("JSON Payload Size: %u bytes\n", jsonLen);
    
    // Serialize to Serial (replace with HTTP client stream in production)
    size_t written = serializeJson(doc, Serial);
    
    if (written == 0) {
      Serial.println("\n[ERROR] JSON Serialization failed. Check heap memory.");
    } else {
      Serial.println("\n[SUCCESS] JSON transmitted.");
    }
    
    // 5. Clear the String buffer to prevent heap fragmentation
    b64String = String(); 
  }

  delay(2000); // Simulate telemetry interval
}

Debugging: Exact Errors and Heap Corruption

Base64 encoding is notorious for crashing microcontrollers. A 10KB binary image becomes a 13.3KB Base64 string. When wrapped in JSON, you are holding the raw buffer, the Base64 string, and the JSON document in RAM simultaneously. Here is how to debug the inevitable failures.

The First Three Things to Check When It Fails

1. Heap Fragmentation: Call ESP.getFreeHeap() and ESP.getMaxAllocHeap() before encoding. If free heap is 40KB but max alloc is only 2KB, your RAM is fragmented. The base64::encode() function will fail to allocate contiguous memory and return an empty string.
2. Null-Termination and Padding: If your receiving server throws a syntax error, check if your Base64 library is appending PEM-style newlines (\n every 76 characters). ArduinoJson handles newlines, but many lightweight cloud parsers do not. The ESP32 native library does not insert newlines, which is why it is preferred.
3. ArduinoJson Version Mismatch: If you get compiler errors on JsonDocument doc;, you are using ArduinoJson v6. Upgrade to v7 via the Library Manager. In v6, you had to use DynamicJsonDocument doc(2048); and manually calculate the 33% Base64 overhead.

Ranked Causes for Exact Error Strings

Extending and Simplifying the Build

Depending on your cloud infrastructure, wrapping Base64 in JSON might be unnecessary overhead. Use this framework to decide how to scale your project.

How to Simplify: Drop the JSON Wrapper

If your backend API supports application/octet-stream or raw text, skip ArduinoJson entirely. Send the Base64 string directly via HTTP POST. This eliminates the JSON overhead (keys, braces, quotes) and saves roughly 10-15% of your payload size and CPU cycles during serialization.
Default Recommendation: Only use JSON if you must transmit metadata (like device_id or timestamp) alongside the binary payload in a single request.

How to Extend: Chunked Encoding for Large Payloads

If you need to transmit a 200KB JPEG image from an OV2640 camera, the ESP32's internal SRAM cannot hold the raw image, the Base64 string, and the JSON document simultaneously. You must extend the build using chunked streaming:

1. Read the camera buffer in 3KB chunks (which aligns perfectly with Base64's 3-byte to 4-character ratio).
2. Encode each 3KB chunk to Base64 independently.
3. Use ArduinoJson's serializeJson(doc, client) to stream the JSON directly to the WiFi client socket, appending the Base64 chunks to the payload key sequentially.
4. This keeps peak RAM usage under 15KB, completely eliminating heap corruption risks.

For deeper memory profiling, consult the Espressif Heap Memory Allocation documentation to understand how the ESP32 splits memory between IRAM and DRAM, and review the ArduinoJson v7 JsonDocument API for advanced serialization techniques.