forked from bblanchon/ArduinoJson
Writing documentation...
This commit is contained in:
Benoit Blanchon
@ -28,52 +28,9 @@ Here is an example to generate `{"sensor":"gps","time":1351824120,"data":[48.756
|
||||
|
||||
## Step 1: Reserve memory space
|
||||
|
||||
#### Introducing `StaticJsonBuffer`
|
||||
|
||||
Arduino JSON uses a preallocated memory pool to store the object tree, this is done by the `StaticJsonBuffer`.
|
||||
|
||||
Before using any function of the library you need to create a `StaticJsonBuffer`. Then you can use this instance to create arrays and objects, or parse a JSON string.
|
||||
|
||||
`StaticJsonBuffer` has a template parameter that determines the number of bytes that it contains. For example, the following line create a `StaticJsonBuffer` containing 200 bytes on the stack:
|
||||
|
||||
StaticJsonBuffer<200> jsonBuffer;
|
||||
|
||||
The bigger the buffer is, the more complex the object tree can be, but also the more memory you need.
|
||||
|
||||
#### How to determine the buffer size?
|
||||
|
||||
So the big question you should have in mind right now is *How can I determine the size?*.
|
||||
|
||||
There are basically two approaches here:
|
||||
|
||||
1. either you can predict the content of the object tree,
|
||||
2. or, you know how much memory is available.
|
||||
|
||||
In the first case, you know some constraints on the object tree. For instance, let's say that your know in advance (and by that I mean "at compilation time") that you want to generate an object with 3 values, one of them being an array with 2 values, like the following:
|
||||
|
||||
{"sensor":"gps","time":1351824120,"data":[48.756080,2.302038]}
|
||||
|
||||
To determine the memory usage of this object tree, you use the two macros `JSON_ARRAY_SIZE(n)` `JSON_OBJECT_SIZE(n)`, both take the number of elements as a parameter.
|
||||
For the example above, it would be:
|
||||
|
||||
const int BUFFER_SIZE = JSON_OBJECT_SIZE(3) + JSON_ARRAY_SIZE(2);
|
||||
StaticJsonBuffer<BUFFER_SIZE> jsonBuffer;
|
||||
|
||||
In the second case, let's say you dynamically generate a JSON object tree of a random complexity so you can't put a limit base on that. But on the other hand, you don't want your program to crash because the object tree doesn't fit in memory.
|
||||
The solution here is to determine how much memory is available, or in other words how much memory you can afford for the JSON generation.
|
||||
|
||||
#### Why choosing fixed allocation?
|
||||
|
||||
This fixed allocation approach may seem a bit strange, especially if your a desktop app developer used to dynamic allocation, but it make a lot of sense in an embedded context:
|
||||
|
||||
1. the code is smaller
|
||||
2. it uses less memory
|
||||
3. it doesn't create memory fragmentation
|
||||
4. it predictable
|
||||
|
||||
Don't forget that, the memory is "freed" as soon as the `StaticJsonBuffer` is out of scope, like any other variable. It only hold the memory for a short amount of time.
|
||||
|
||||
For that reason, you should never use a `StaticJsonBuffer` as a **global variable** because it would hold a lot of memory for the whole life of the program.
|
||||
Before continuing please read the page [Arduino JSON memory model](Memory model.md) that explains everything you need to know about `StaticJsonBuffer`.
|
||||
|
||||
## Step 2: Build object tree in memory
|
||||
|
||||
|
||||
0
doc/Installing for Arduino.md
Normal file
0
doc/Installing for Arduino.md
Normal file
51
doc/Memory model.md
Normal file
51
doc/Memory model.md
Normal file
@ -0,0 +1,51 @@
|
||||
Arduino JSON memory model
|
||||
=========================
|
||||
|
||||
## Fixed memory allocation
|
||||
|
||||
### Introducing `StaticJsonBuffer`
|
||||
|
||||
Arduino JSON uses a preallocated memory pool to store the object tree, this is done by the `StaticJsonBuffer`.
|
||||
|
||||
Before using any function of the library you need to create a `StaticJsonBuffer`. Then you can use this instance to create arrays and objects, or parse a JSON string.
|
||||
|
||||
`StaticJsonBuffer` has a template parameter that determines the number of bytes that it contains. For example, the following line create a `StaticJsonBuffer` containing 200 bytes on the stack:
|
||||
|
||||
StaticJsonBuffer<200> jsonBuffer;
|
||||
|
||||
The bigger the buffer is, the more complex the object tree can be, but also the more memory you need.
|
||||
|
||||
### How to determine the buffer size?
|
||||
|
||||
So the big question you should have in mind right now is *How can I determine the size?*.
|
||||
|
||||
There are basically two approaches here:
|
||||
|
||||
1. either you can predict the content of the object tree,
|
||||
2. or, you know how much memory is available.
|
||||
|
||||
In the first case, you know some constraints on the object tree. For instance, let's say that your know in advance (and by that I mean "at compilation time") that you want to generate an object with 3 values, one of them being an array with 2 values, like the following:
|
||||
|
||||
{"sensor":"gps","time":1351824120,"data":[48.756080,2.302038]}
|
||||
|
||||
To determine the memory usage of this object tree, you use the two macros `JSON_ARRAY_SIZE(n)` `JSON_OBJECT_SIZE(n)`, both take the number of elements as a parameter.
|
||||
For the example above, it would be:
|
||||
|
||||
const int BUFFER_SIZE = JSON_OBJECT_SIZE(3) + JSON_ARRAY_SIZE(2);
|
||||
StaticJsonBuffer<BUFFER_SIZE> jsonBuffer;
|
||||
|
||||
In the second case, let's say you dynamically generate a JSON object tree of a random complexity so you can't put a limit base on that. But on the other hand, you don't want your program to crash because the object tree doesn't fit in memory.
|
||||
The solution here is to determine how much memory is available, or in other words how much memory you can afford for the JSON generation.
|
||||
|
||||
### Why choosing fixed allocation?
|
||||
|
||||
This fixed allocation approach may seem a bit strange, especially if your a desktop app developer used to dynamic allocation, but it make a lot of sense in an embedded context:
|
||||
|
||||
1. the code is smaller
|
||||
2. it uses less memory
|
||||
3. it doesn't create memory fragmentation
|
||||
4. it predictable
|
||||
|
||||
Don't forget that, the memory is "freed" as soon as the `StaticJsonBuffer` is out of scope, like any other variable. It only hold the memory for a short amount of time.
|
||||
|
||||
For that reason, you should never use a `StaticJsonBuffer` as a **global variable** because it would hold a lot of memory for the whole life of the program.
|
||||
@ -0,0 +1,142 @@
|
||||
Parsing JSON with Arduino JSON
|
||||
==============================
|
||||
|
||||
## Example
|
||||
|
||||
Here an example that parse the string `{"sensor":"gps","time":1351824120,"data":[48.756080,2.302038]}`:
|
||||
|
||||
char json[] = "{\"sensor\":\"gps\",\"time\":1351824120,\"data\":[48.756080,2.302038]}";
|
||||
|
||||
//
|
||||
// Step 1: Reserve memory space
|
||||
//
|
||||
StaticJsonBuffer<200> jsonBuffer;
|
||||
|
||||
//
|
||||
// Step 2: Deserialize the JSON string
|
||||
//
|
||||
JsonObject& root = jsonBuffer.parseObject(json);
|
||||
|
||||
if (!root.success())
|
||||
{
|
||||
Serial.println("parseObject() failed");
|
||||
return;
|
||||
}
|
||||
|
||||
//
|
||||
// Step 3: Retrieve the values
|
||||
//
|
||||
const char* sensor = root["sensor"];
|
||||
long time = root["time"];
|
||||
double latitude = root["data"][0];
|
||||
double longitude = root["data"][1];
|
||||
|
||||
## Step 1: Reserve memory space
|
||||
|
||||
Arduino JSON uses a preallocated memory pool to store the object tree, this is done by the `StaticJsonBuffer`.
|
||||
|
||||
Before continuing please read the page [Arduino JSON memory model](Memory model.md) that explains everything you need to know about `StaticJsonBuffer`.
|
||||
|
||||
## Step 2: Parse the JSON string
|
||||
|
||||
You call the JSON parser through the instance of `StaticJsonBuffer`.
|
||||
It exposes two function for parsing JSON:
|
||||
|
||||
1. parseArray() that returns a reference to a `JsonArray`
|
||||
2. parseObject() that returns a reference to a `JsonObject`
|
||||
|
||||
Let's see an example.
|
||||
Say we want to parse `{"sensor":"gps","time":1351824120,"data":[48.756080,2.302038]}`, it's an object so we call `parseObject` as follows:
|
||||
|
||||
char json[] = "{\"sensor\":\"gps\",\"time\":1351824120,\"data\":[48.756080,2.302038]}";
|
||||
|
||||
JsonObject& root = jsonBuffer.parseObject(json);
|
||||
|
||||
As you can see `parseObject()` takes a `char*` as a parameter.
|
||||
Be careful, it's not a `const char*`, the memory must be writable.
|
||||
Indeed, the parser will modify the string in two cases:
|
||||
|
||||
1. to insert string endings (character `\0`),
|
||||
2. to translate escaped characters (like `\n` or `\t`).
|
||||
|
||||
Another thing that you must keep in mind is that the string (`char json[]` in the example above) must stay in memory during the whole parsing process.
|
||||
That is because the in memory object tree will store pointer to chunks of the string, so as to avoid any memory duplication.
|
||||
|
||||
Now, to check if the parsing was successful, you can call `JsonObject::success()`:
|
||||
|
||||
if (!root.success())
|
||||
{
|
||||
// Parsing fail
|
||||
}
|
||||
|
||||
The result can be `false` for tree reasons:
|
||||
|
||||
1. the JSON string is invalid,
|
||||
2. the JSON string doesn't represent an object,
|
||||
3. the `StaticJsonBuffer` is too small.
|
||||
|
||||
We just saw how to parse an object, there is nothing more to say for arrays, the procedure is exactly the same.
|
||||
|
||||
## Step 3: Retrieve the values
|
||||
|
||||
Now that the object or array is in memory, you can extract the data very easily.
|
||||
|
||||
In this section, we'll see how to do it with a `JsonObject`.
|
||||
Once again, there is nothing more to say about arrays, `JsonArray` works exactly the same as `JsonObject`.
|
||||
|
||||
#### Subscript operator
|
||||
|
||||
The simplest way is to use the subscript operator of `JsonObject`:
|
||||
|
||||
const char* sensor = root["sensor"];
|
||||
long time = root["time"];
|
||||
|
||||
You can chain the subscript operator if you have nested arrays or objects:
|
||||
|
||||
double latitude = root["data"][0];
|
||||
double longitude = root["data"][1];
|
||||
|
||||
But alternatively, you can get a reference to the nested array:
|
||||
|
||||
JsonArray& nestedArray = root["data"];
|
||||
|
||||
#### Casting values
|
||||
|
||||
In the previous examples, the values were implicitly casted to the target type.
|
||||
You can also do this explicitly
|
||||
|
||||
const char* sensor = root["sensor"].asString();
|
||||
long time = root["time"].as<long>();
|
||||
JsonArray& nestedArray = root["data"].asArray();
|
||||
|
||||
If the actual value doesn't match the target type, a default value will be return:
|
||||
|
||||
1. `false` for boolean values
|
||||
2. `0` for integer values
|
||||
3. `NULL` for string values
|
||||
4. `JsonArray::invalid()` for nested arrays
|
||||
5. `JsonObject::invalid()` for nested object
|
||||
|
||||
#### Check values
|
||||
|
||||
If you want to know if some value is present, call `containsKey()`:
|
||||
|
||||
if (root.contains("extra"))
|
||||
{
|
||||
// root["extra"] is valid
|
||||
}
|
||||
|
||||
If you want to check the type value has a certain type, call `is<T>()`:
|
||||
|
||||
if (root["extra"].is<JsonArray&>())
|
||||
{
|
||||
// root["extra"] is an array
|
||||
}
|
||||
|
||||
You can also iterate through the key-value pairs of the object:
|
||||
|
||||
for (JsonObject::itertor it=root.begin(); it!=root.end(); ++it)
|
||||
{
|
||||
Serial.println(it->key);
|
||||
Serial.println(i->value.asString());
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user