feedc0de/ArduinoJson
1
0
Fork 0
forked from bblanchon/ArduinoJson
Code Pull Requests Activity

Minor corrections to the doc

Browse Source
This commit is contained in:
Benoit Blanchon
2014-11-29 09:30:11 +01:00
parent 33654a480b
commit a61fc5b836
5 changed files with 47 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
doc/Avoiding pitfalls.md
View File

@ -1,7 +1,7 @@
Avoiding common pitfalls in Arduino JSON
========================================
As `StaticJsonBuffer` is the corner stone of this library, you'll see that every pitfall listed here is related to a wrong understanding of the memory model.
As `StaticJsonBuffer` is the corner stone of this library, you'll see that every pitfall listed here are related to a wrong understanding of the memory model.
Make sure you read [Arduino JSON memory model](Memory model.md) before going further.
@ -14,29 +14,29 @@ There are basically two reasons why they may fail:
1. the JSON string is invalid,
2. the JSON string contains more values that the buffer can store.
So, if you are sure the JSON string is correct and you still can't parse it, you should slightly increase the number of token of the parser.
So, if you are sure the JSON string is correct and you still can't parse it, you should try to increase the size of the `StaticJsonBuffer`.
## 2. Make sure everything fits in memory
You may go into unpredictable trouble if you allocate more memory than your processor really has.
It's a very common issue in embedded development.
It's a very common issue in embedded development.
To diagnose this, look at every big objects in you code and sum their size to check that they fit in RAM.
For example, don't do this:
char json[1024]; // 1 KB
JsonParser<512> parser; // 514 B
char json[1024]; // 1 KB
StaticJsonBuffer<512> buffer; // 514 B
because it may be too big for a processor with only 2 KB: you need free memory to store other variables and the call stack.
That is why an 8-bit processor is not able to parse long and complex JSON strings.
## 3. Keep the `StaticJsonBuffer` in memory long enough
## 3. Keep the `StaticJsonBuffer` in memory long enough
Remember that the function of `StaticJsonBuffer` return references.
References don't store data, they are just pointer to the actual.
This will only work if the data actual is still in memory.
Remember that `StaticJsonBuffer`'s function return references.
References don't contain data, they are just pointer to the actual.
So they can only work if the actual data is in memory.
For example, don't do this:
@ -48,12 +48,13 @@ For example, don't do this:
because the local variable `buffer` will be *removed* from memory when the function `parseArray()` returns, and the `JsonArray&` will point to an invalid location.
## 4. Don't make `StaticJsonBuffer` global
## 4. Don't reuse the same `StaticJsonBuffer`
If you read the previous point, you may come to the idea of using a global variable for your `StaticJsonBuffer`.
This is probably a bad idea because `StaticJsonBuffer` can be quite big (depending on your requirement) and would be eating a lot of memory, even when you don't use it.
During is lifetime a `StaticJsonBuffer` growth until it's discarded. If you try to reuse the same instance several time, it will rapidly get full.
There are some cases were a `StaticJsonBuffer` can be a global variable, but must of the time you should declare it in a local scope, in a function which unique role is to handle the JSON serialization.
For this reason, you should not use a global variable for your `StaticJsonBuffer`. I don't think there is any scenario in which a global `StaticJsonBuffer` would be a valid option.
The best practice is to declare it in a local scope, so that it's discarded as soon as possible. My advice it to declare it in a function which unique role is to handle the JSON serialization.
## 5. Keep the JSON string in memory long enough
@ -69,21 +70,21 @@ For instance, let's imagine that you parse `["hello","world"]`, like this:
const char* first = array[0];
const char* second = array[1];
In that case, both `first` and `second` are pointer to the content of the original string `json`.
In that case, both `first` and `second` are pointers to the content of the original string `json`.
So this will only work if `json` is still in memory.
## 6. JSON string is altered
If you read carefully the previous pitfall, you may I come to the conclusion that the JSON parser modifies the JSON string.
If you read carefully the previous section, you may have come to the conclusion that the JSON parser modifies the JSON string.
Indeed, the parser modifies the string for two reasons:
1. it inserts `\0` to terminate substrings,
2. it translate escaped characters like `\n` or `\t`.
Most of the time this wont be an issue, but it there are some corner case that can be problematic.
Most of the time this wont be an issue, but there are some corner cases that can be problematic.
Let take the example above:
Let take the example bellow:
char[] json = "[\"hello\",\"world\"]";
StaticJsonBuffer<32> buffer;
@ -97,5 +98,5 @@ If you replace it by:
Depending on your platform, you may have an exception because the parser tries to write at a location that is read-only.
In the first case `char json[]` declares an array of `char` initialized to the specified string.
In the second case `char* json` declares a pointer to a read only string, in fact it should be a `const char*` instead of a `char*`.
In the second case `char* json` declares a pointer to a read-only string, in fact it should be a `const char*` instead of a `char*`.

2
doc/Contributing.md
View File

@ -7,7 +7,7 @@ If you want to contribute to the project, please:
2. Follow the coding conventions
3. Write tests
About the coding conventions: I try to follow the [Google C++ Style Guide](http://google-styleguide.googlecode.com/svn/trunk/cppguide.html) which few variations to match the Arduino conventions.
About the coding conventions: I try to follow the [Google C++ Style Guide](http://google-styleguide.googlecode.com/svn/trunk/cppguide.html) with few variations to match the Arduino conventions.
I use [ClangFormat](http://clang.llvm.org/docs/ClangFormat.html) to format the code for me.
I use [CppLint](http://google-styleguide.googlecode.com/svn/trunk/cpplint/cpplint.py) to detect non-compliant stuff.

24
doc/Decoding JSON.md
View File

@ -1,6 +1,12 @@
Decoding JSON with Arduino JSON
===============================
Before writing any code, don't forget to include the header:
#include <ArduinoJson.h>
For instructions on how to install the library, please read [Using the library with Arduino](Using the library with Arduino.md) or [Using the library without Arduino](Using the library without Arduino.md).
## Example
Here an example that parse the string `{"sensor":"gps","time":1351824120,"data":[48.756080,2.302038]}`:
@ -17,7 +23,7 @@ Here an example that parse the string `{"sensor":"gps","time":1351824120,"data":
//
JsonObject& root = jsonBuffer.parseObject(json);
if (!root.success())
if (!root.success())
{
Serial.println("parseObject() failed");
return;
@ -39,14 +45,14 @@ Before continuing please read the page [Arduino JSON memory model](Memory model.
## Step 2: Parse the JSON string
You call the JSON parser through the instance of `StaticJsonBuffer`.
It exposes two function for parsing JSON:
You invoke the JSON parser through the instance of `StaticJsonBuffer`.
It exposes two functions for parsing JSON:
1. parseArray() that returns a reference to a `JsonArray`
2. parseObject() that returns a reference to a `JsonObject`
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:
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]}";
@ -90,7 +96,7 @@ 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];
@ -121,14 +127,14 @@ If the actual value doesn't match the target type, a default value will be retur
If you want to know if some value is present, call `containsKey()`:
if (root.contains("extra"))
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&>())
if (root["extra"].is<JsonArray&>())
{
// root["extra"] is an array
}

23
doc/Encoding JSON.md
View File

@ -5,7 +5,7 @@ Before writing any code, don't forget to include the header:
#include <ArduinoJson.h>
If your not using the Arduino IDE, please read [Using the library without Arduino](Using the library without Arduino.md).
For instructions on how to install the library, please read [Using the library with Arduino](Using the library with Arduino.md) or [Using the library without Arduino](Using the library without Arduino.md).
## Example
@ -50,7 +50,7 @@ You create an array like this:
Don't forget the `&` after `JsonArray`, it needs to be a reference to the array.
Then you can add strings, integer, booleans, etc:
Then you can add strings, integer, booleans, etc:
array.add("bazinga!");
array.add(42);
@ -58,14 +58,13 @@ Then you can add strings, integer, booleans, etc:
There are two syntaxes for floating point values:
array.add<4>(3.1415); // 4 digits: "3.1415"
array.add(3.1415, 4); // 4 digits: "3.1415"
array.add(3.1415); // 2 digits: "3.14"
> ##### About floating point precision
> The overload of `add()` with 2 parameters allows you to specify the number of decimals to save in the JSON string.
> When you use the overload with one parameter, you use the default number of decimals which is two.
> Note that this behavior is the exact same as Arduino's `Print::print(double,int);` which is implemented by `Serial`.
> So you may already be familiar with it.
> The overload of `add()` with 2 parameters allows you to specify the number of decimals to save in the JSON string.
> When you use the overload with one parameter, you use the default number of decimals which is 2.
> Note that this behavior is the exact same as Arduino's `Print::print(double,int);` which is implemented by `Serial`, so you may already be familiar with this behavior.
You can add a nested array or object if you have a reference to it.
Or simpler, you can create nested array or nested objects from the array:
@ -75,13 +74,13 @@ Or simpler, you can create nested array or nested objects from the array:
#### Objects
You create an array like this:
You create an object like this:
JsonObject& object = jsonBuffer.createObject();
Again, don't forget the `&` after `JsonObject`, it needs to be a reference to the object.
Then you can add strings, integer, booleans, etc:
Then you can add strings, integer, booleans, etc:
object["key1"] = "bazinga!";
object["key2"] = 42;
@ -89,7 +88,7 @@ Then you can add strings, integer, booleans, etc:
As for the arrays, there are two syntaxes for the floating point values:
object["key4"].set<4>(3.1415); // 4 digits "3.1415"
object["key4"].set(3.1415, 4); // 4 digits "3.1415"
object["key5"] = 3.1415; // default: 2 digits "3.14"
You can add a nested array or object if you have a reference to it.
@ -136,6 +135,6 @@ And, of course if you need an indented JSON string:
array.prettyPrintTo(Serial);
> ##### About the Print interface
> The library is designed to send the JSON string to an implementation of the `Print` interface that is part of Arduino.
> In the example above we used `Serial`, but they are many other implementation that would work as well, including: `HardwareSerial`, `SoftwareSerial`, `LiquidCrystal`, `EthernetClient`, `WiFiClient`, `Wire`...
> The library is designed to send the JSON string to an implementation of the `Print` interface that is part of Arduino.
> In the example above we used `Serial`, but they are many other implementations that would work as well, including: `HardwareSerial`, `SoftwareSerial`, `LiquidCrystal`, `EthernetClient`, `WiFiClient`, `Wire`...
> When you use this library out of the Arduino environment, it will use it's own implementation of `Print` and everything will be the same.

2
doc/Memory model.md
View File

@ -17,7 +17,7 @@ The bigger the buffer is, the more complex the object tree can be, but also the
### How to determine the buffer size?
So the big question you should have in mind right now is *How can I determine the 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: