116 lines
3.2 KiB
Markdown
116 lines
3.2 KiB
Markdown
---
|
|
title: "JSON Utilities"
|
|
description: "JSON parsing utility functions for safe field extraction from ArduinoJSON objects"
|
|
keywords: ["json", "parsing", "arduino", "utilities", "type safety"]
|
|
---
|
|
|
|
# JSON Utilities
|
|
|
|
**Path**: [`src/json.h`](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](https://github.com/bblanchard/ArduinoJSON)
|
|
- [ArduinoLog](https://github.com/thijse/Arduino-Log)
|
|
|
|
```mermaid
|
|
graph TD
|
|
json["JSON Utilities"] --> arduinojson[ArduinoJSON]
|
|
json --> arduinolog[Arduino-Log]
|
|
```
|
|
|
|
## BEHAVIOUR
|
|
|
|
```mermaid
|
|
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:
|
|
|
|
```cpp
|
|
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}
|