firmware-base/docs/json.md

title	description	keywords
JSON Utilities	JSON parsing utility functions for safe field extraction from ArduinoJSON objects	json parsing arduino utilities type safety

JSON Utilities

Path: src/json.h

Revision History: Initial documentation

A collection of inline utility functions for safe JSON field parsing with ArduinoJSON. These functions provide type checking, default value fallback, and graceful error handling for JSON data extraction.

REQUIREMENTS

• No specific hardware pins required
• ArduinoJSON library
• ArduinoLog library

FEATURES

• Safe type-checked JSON field parsing for uint32_t, uint8_t, and bool data types
• Graceful error handling with default value fallback
• Comprehensive logging with component and field name information
• Inline functions for optimal performance
• Robust null value handling

DEPENDENCIES

• ArduinoJSON
• ArduinoLog

graph TD
    json["JSON Utilities"] --> arduinojson[ArduinoJSON]
    json --> arduinolog[Arduino-Log]

BEHAVIOUR

graph TD
    jsonobject["JSON Object"] --> check["Type Check"]
    check --> valid["Valid"]
    check --> invalid["Invalid"]
    valid --> update["Update Target Value"]
    invalid --> logwarn[Log Warning]
    update --> complete["Completed"]
    logwarn --> complete

TODOS

PERFORMANCE

• Consider using function templates to reduce code duplication across data types
• Add support for floating and string data types
• Implement validation range checking for numeric types

SECURITY

• No immediate security risks identified
• JSON input injection attacks - explicit field and component names should be validated to prevent log injection
• Input sanitization recommended prior to working with JSON data

COMPLIANCE

• No specific compliance requirements
• C++17 minimal security practices

RECOMMENDATIONS

• Use with the correct component and field names in logging
• Provide reasonable default values for all fields
• Validate JSON structure before combining with these utilities
• Ensure adequate error handling in upper-layer application code

EXAMPLE

This example demonstrates the usage of the JSON extraction utilities:

using namespace JsonUtils;

void parseSettings(const char* jsonStr) {
    staticJsonDocument<512> doc;
    DeserializationError error = deserializeJson(doc, jsonStr);

    if (error) {
        Log.errorln("Failed to parse JSON: %s", error.f_str());
        return;
    }

    // Default values
    uint32_t baudRate = 115200;
    uint8_t retryCount = 3;
    bool debugEnabled = false;

    // Safe parsing with default fallback
    parseJsonFieldUint32(doc, "baud_rate", baudRate, "Baud Rate", "Settings");
    parseJsonFieldUint8(doc, "retry_count", retryCount, "Retry Count", "Settings");
    parseJsonFieldBool(doc, "debug_enabled", debugEnabled, "Debug Enabled", "Settings");

    // Use the parsed values
    Log.infoln(F("Settings loaded: Baud=%lu, Retry=%d, Debug=%s"),
               baudRate, retryCount, debugEnabled ? "YES" : "NO");
}

References

${DOXYGEN_PLACEHOLDER_COMMENT}

${ VENDOR_PLACEHOLDER_COMMENT}