玩转ArduinoJson库 V5版本

时间 2019-11-18

标签 arduinojson v5 版本繁體版

原文原文链接

1.前言

一直以来，博主的事例代码中都一直使用到JSON数据格式。而不少初学者一直对JSON格式有很大疑惑，因此博主特地分出一篇博文来重点讲解Arduino平台下的JSON库——ArduinoJSON。
读者须要注意一下几点：git

ArduinoJSON的Github地址请参考 wiki。
ArduinoJSON说明文档能够参考 wiki，博主强烈建议读者能够尝试去阅读这些文档，确定获益匪浅。
ArduinoJSON目前分为两个大版本 V5 和 V6版本（估计不少初学者会常常看到Arduino IDE提示本身升级ArduinoJSON库版本），博主也会分别讲解两个版本。
下载完库以后，只须要包含如下头文件便可使用

#include <ArduinoJson.h>

废话少说，请读者认真如下干货内容。github

2.JSON基础介绍

2.1 什么是Json？

Json 指的是JavaScript对象表示法（JavaScript Object Notation）。
Json 是轻量级的文本数据交换格式，相似于XML，比XML更小、更快，更容易解析。
Json 独立于语言。
Json 具备自我描述性，容易理解。

2.2 具体使用例子

2.2.1 JSON对象例子

JSON对象描述：json

{
    "motor": {
        "left": 100,
        "right": 20
    },
    "servo": {
        "servo_1": 90
    }
}

JSON对象语法说明：api

这里分别有两个对象（对象是用{}区分），对象分别是motor、servo。
对于对象motor来讲，有两个字段 left 和 right，它们的值类型是int型，值分别是100和20；
对于对象servo来讲，有一个字段servo_1,它的值类型是int型，值是90。

2.2.2 JSON对象数组

JSON数组描述：数组

{
    "employees": [
        {
            "firstName": "Bill",
            "lastName": "Gates"
        },
        {
            "firstName": "George",
            "lastName": "Bush"
        },
        {
            "firstName": "Thomas",
            "lastName": "Carter"
        }
    ]
}

JSON数组语法说明：数据结构

这里有一个对象数组（数组用[]区分）employees。
每一个对象里面有两个字段firstName和lastName，它们的值类型都是String。

重点：app

不管是JSON对象仍是JSON数组，它们的核心都是键值对，也就是key-value形式。

3.ArduinoJson库

上面说到，ArduinoJson库有两个大版本 —— V5 和 V6。
不论是V5仍是V6版本，在编码以前，请到Arduino IDE的管理库去下载：
函数

请读者按照本身的需求分别去下载不一样版本（固然博主建议用新不用旧，毕竟通常新版本都是通过旧版本升级优化）。
不论是V5 仍是 V6版本，对于开发者来讲有三个概念是共通的：工具

JsonObject —— json对象（存储key-value键值对的集合，每个key是一个字符串，每个value是一个JsonVariant）
JsonArray —— json对象数组（存储一个JsonVariant的数组）
JsonVariant —— json变体（存储能够放在json文件中的任意类型数据，包括int，float，数组，对象，开发者能够认为它是一个抽象的对象概念，底层内容，读者理解便可）

除了理解上面的三个概念，博主认为读者还必须注意如下两点：oop

构造json数据，必定是从最外层开始构造，从外到里一层层构造；
解析json数据，虽然是交给arduinojson库处理，可是咱们获取数据也是从最外层开始获取，从外到里一层层获取；

记住上面的黑体内容，接下来，咱们针对不一样版本的ArduinoJson库来说解使用以及注意事项。

3.1 ArduinoJson V5版本

假设读者下载的V5版本的，那么能够参考这里的API说明。读者须要注意一下jsonBuffer，由于V5版本的json操做都是在它上面。
对于开发者来讲，使用JSON无非就是编码或者解码，因此博主也会分出两种状况来说解。
首先咱们来看看V5版本经常使用的百度脑图：

能够看出，方法主要分为三大类：

JsonBuffer相关，这是整个json库的入口，它负责高效管理内存以及调用json解析器；
JsonObject相关；
JsonArray相关；

3.1.1 JsonBuffer

JsonBuffer做为整个V5版本ArduinoJson库的入口，负责处理整个json数据的内存管理以及构造解析工做，这是咱们须要首先重点关注的内容。
它包括两个实现类：

DynamicJsonBuffer，内存分配在heap区，无固定大小，能够自动增加所需空间，方法调用完自动回收；
StaticJsonBuffer，内存分配在stack区，有固定大小，大小值由开发者定义，方法调用完自动回收；

对于一些内存使用比较紧缺的机器，博主建议尽可能用固定大小的StaticJsonBuffer（这个须要提早预知内容的大小，而这个内容大小能够经过计算得来，请点 wiki 参考）。

那么，咱们开发者可能会关心如下几个常见问题：

1. 问题1，如何去肯定buffer的大小？

假设整个json数据结构是固定的，开发者可使用StaticJsonBuffer。举个例子：

{"sensor":"gps","time":1351824120,"data":[48.756080,2.302038]}

那么经过JSON_OBJECT_SIZE(n)和JSON_ARRAY_SIZE(n)能够计算出内存大小：

const int BUFFER_SIZE = JSON_OBJECT_SIZE(3) + JSON_ARRAY_SIZE(2);
StaticJsonBuffer<BUFFER_SIZE> jsonBuffer;

固然咱们能够借助工具来帮咱们计算内存大小，具体能够参考 ArduinoJson Assistant。

假设整个json数据结构是非固定的，开发者可使用DynamicJsonBuffer，能够动态增加（动态增加就意味着可能会内存溢出，整个是须要开发者去考虑的），固然尽可能给DynamicJsonBuffer一个足够大的初始值，能够减小调用malloc()方法去分配内存。
json解析器根据输入的内容会有不一样的策略字符串。若是输入的内容是可写内容，好比 char* 或者 char[]，解析器不会申请额外的内存空间，也就是“zero-copy”模式。若是输入的内容是自读内容，好比 const char* 或者字符串或者steam流，解析器会从新拷贝一份该字符串做为可写操做，这样就意味着JsonBuffer大小可能和咱们预想的不同。因此，博主建议开发者尽可能是char* 或者 char[]。

2. StaticJsonBuffer 和 DynamicJsonBuffer的区别？

具体参考 wiki

3. 如何去重用一个JsonBuffer？

要重用JsonBuffer，开发者的版本必须大于5.11.0，而且使用clear方法去重用，固然json库的开发者建议不要去重用jsonbuffer，容易出问题。直接看个例子：

// STEP1: parse input
StaticJsonBuffer<200> jsonBuffer;
JsonObject& inputObject = jsonBuffer.parseObject(inputJson);

...etc...

// STEP2: generate output
jsonBuffer.clear();
JsonObject& outputObject = jsonBuffer.createObject();
outputObject["hello"] = inputObject["world"];

看起来没有什么问题，但实际上有访问错误，请看分析：

inputObject是一个json对象的指针，由JsonBuffer管理内存；
clear方法重置了jsonbuffer内存池，运行从新使用inputObject的内存空间；
outputObject对象被建立，其地址和inputObject同样；
到这一步你们应该知道会发生什么问题了吧，inputObject变成了一个危险指针，其内容是没法预知的；

那么要怎么解决这个问题呢？有两种解决方案：

使用更大的JsonBuffer

// STEP1: parse input
StaticJsonBuffer<400> jsonBuffer;
JsonObject& inputObject = jsonBuffer.parseObject(inputJson);

...etc...

// STEP2: generate output
JsonObject& outputObject = jsonBuffer.createObject();
outputObject["hello"] = inputObject["world"];

使用第二个JsonBuffer：

// STEP1: parse input
StaticJsonBuffer<200> jsonBuffer1;
JsonObject& inputObject = jsonBuffer1.parseObject(inputJson);

...etc...

// STEP2: generate output
StaticJsonBuffer<200> jsonBuffer2;
JsonObject& outputObject = jsonBuffer2.createObject();
outputObject["hello"] = inputObject["world"];

4. 为何不要去用一个全局的JsonBuffer？

具体能够参考 wiki。
博主认为最重要的缘由仍是通常咱们用完json就应该释放掉它，全局jsonbuffer会一直占用着内存空间。

接下来，看看JsonBuffer的一些经常使用方法：

3.1.1.1 clear —— 重置内存指针，复用内存空间，慎用

函数说明：

/**
 * 重置内存指针，复用内存空间，慎用
 */
void clear();

例子说明：

StaticJsonBuffer<200> jb;

JsonObject& obj1 = jb.parseObject(json1);
// we can use obj1 here...

jb.clear();
// now obj1 is dangling!!!

// ...but we can reuse the JsonBuffer
JsonObject& obj2 = jb.parseObject(json2);

注意：

重要说三遍，慎用，慎用，慎用；
一旦你调用 JsonBuffer::clear()，全部以前分配的jsonobject或者jsonbuffer都会变成无效；

3.1.1.2 createArray —— 建立空json数组，并为它分配内存空间

函数说明：

/**
 * 建立空json数组，并为它分配内存空间
 * @return json数组地址
 * @Note 若是分配失败，会提示分配失败
 */
JsonArray& createArray();

例子说明：

StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
array.add("hello");
array.add("world");

3.1.1.3 createObject —— 建立空json对象，并为它分配内存空间

函数说明：

/**
 * 建立空json对象，并为它分配内存空间
 * @return json对象地址
 * @Note 若是分配失败，会提示分配失败
 */
JsonObject createObject();

例子说明：

StaticJsonBuffer<200> jsonBuffer;
JsonObject& object = jsonBuffer.createObject();
object["hello"] = "world";

3.1.1.4 parse —— 解析json（数组或者对象）字符串

函数说明：

/**
 * 解析json（数组或者对象）字符串
 * @param json json字符串
 * @param nestingLimit json深度限制
 * @return jsonVariant对象
 * @Note 此方法用于不可预知json格式的前提下使用的
 */
// The first overload, which accepts a modifiable array of chars, is the most efficient
// since it allows the zero-copy feature.
JsonVariant parse(char* json, uint8_t nestingLimit=10);

// The following overloads, which accept read-only strings, require a bigger JsonBuffer
// because parts of the JSON input has to be copied.
JsonVariant parse(const char* json, uint8_t nestingLimit=10);
JsonVariant parse(const String& json, uint8_t nestingLimit=10);
JsonVariant parse(const std::string& json, uint8_t nestingLimit=10);
JsonVariant parse(const __FlashStringHelper* json, uint8_t nestingLimit=10);

// The two last overloads, which accept input streams, make copy of the input too.
JsonVariant parse(Stream& json, uint8_t nestingLimit=10);
JsonVariant parse(std::istream& json, uint8_t nestingLimit=10);

例子说明：

char json[] = "[\"hello\",\"world\"]";

StaticJsonBuffer<200> jsonBuffer;
JsonVariant variant = jsonBuffer.parse(json);

if (variant.is<JsonArray>()) // true in this example
{
    JsonArray& array = variant;
    const char* hello = array[0];
    const char* world = array[1];

}

3.1.1.5 parseArray —— 解析json数组字符串

函数说明：

/**
 * 解析json数组字符串
 * @param json json字符串
 * @param nestingLimit json深度限制
 * @return jsonArray对象
 * @Note 此方法用于预知json格式是jsonArray的前提下使用的
 */
// The first overload, which accepts a modifiable array of chars, is the most efficient
// since it allows the zero-copy feature.
JsonArray& parseArray(char* json, uint8_t nestingLimit=10);

// The following overloads, which accept read-only strings, require a bigger JsonBuffer
// because parts of the JSON input has to be copied.
JsonArray& parseArray(const char* json, uint8_t nestingLimit=10);
JsonArray& parseArray(const String& json, uint8_t nestingLimit=10);
JsonArray& parseArray(const std::string& json, uint8_t nestingLimit=10);
JsonArray& parseArray(const __FlashStringHelper* json, uint8_t nestingLimit=10);

// The two last overloads, which accept input streams, make copy of the input too.
JsonArray& parseArray(Stream& json, uint8_t nestingLimit=10);
JsonArray& parseArray(std::istream& json, uint8_t nestingLimit=10);

例子说明：

char json[] = "[\"hello\",\"world\"]";
StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.parseArray(json);
const char* hello = array[0];
const char* world = array[1];

3.1.1.6 parseObject —— 解析json对象字符串

函数说明：

/**
 * 解析json对象字符串
 * @param json json字符串
 * @param nestingLimit json深度限制
 * @return json对象
 * @Note 此方法用于预知json格式是jsonObject的前提下使用的
 */
// The first overload, which accepts a modifiable array of chars, is the most efficient
// since it allows the zero-copy feature.
JsonObject& parseObject(char* json, uint8_t nestingLimit=10);

// The following overloads, which accept read-only strings, require a bigger JsonBuffer
// because parts of the JSON input has to be copied.
JsonObject& parseObject(const char* json, uint8_t nestingLimit=10);
JsonObject& parseObject(const String& json, uint8_t nestingLimit=10);
JsonObject& parseObject(const std::string& json, uint8_t nestingLimit=10);
JsonObject& parseObject(const __FlashStringHelper* json, uint8_t nestingLimit=10);

// The two last overloads, which accept input streams, make copy of the input too.
JsonObject& parseObject(Stream& json, uint8_t nestingLimit=10);
JsonObject& parseObject(std::istream& json, uint8_t nestingLimit=10);

例子说明：

char json[] = "{\"hello\":\"world\"}";
StaticJsonBuffer<200> jsonBuffer;
JsonObject& object = jsonBuffer.parseObject(json);
const char* world = object["hello"];

3.1.1.7 size —— JsonBuffer当前已用大小

函数说明：

/**
 * JsonBuffer当前已用大小
 * @return 当前已用大小
 */
size_t size() const;

例子说明：

StaticJsonBuffer<200> jsonBuffer;
Serial.println(jsonBuffer.size());
jsonBuffer.createObject();
Serial.println(jsonBuffer.size());
jsonBuffer.createArray();
Serial.println(jsonBuffer.size());

在8位单片机中会打印：

0
4
8

3.1.2 JsonObject

在JsonBuffer所构造出来的内存空间中，Json对象的入口就是JsonObject。
让咱们看看它的经常使用操做方法：

3.1.2.1 begin / end —— 返回一个迭代器,可用于对象中的全部键值对

函数说明：

/**
 * 返回一个迭代器,可用于对象中的全部键值对
 * @return iterator  iterator包括key和value
 */
JsonObject::iterator begin();
JsonObject::iterator end();
JsonObject::const_iterator begin() const;
JsonObject::const_iterator end() const;

例子说明：

char json[] = "{\"first\":\"hello\",\"second\":\"world\"}";
DynamicJsonBuffer jsonBuffer;
JsonObject& root = jsonBuffer.parseObject(json);

// using C++11 syntax (preferred):
for (auto kv : root) {
    Serial.println(kv.key);
    Serial.println(kv.value.as<char*>());
}

// using C++98 syntax (for older compilers):
for (JsonObject::iterator it=root.begin(); it!=root.end(); ++it) {
    Serial.println(it->key);
    Serial.println(it->value.as<char*>());
}

测试结果：

first
hello
second
world

3.1.2.2 containsKey —— 判断对象是否包含某一个key

函数说明：

/**
 * 判断对象是否包含某一个key
 * @param key key名字
 * @return bool
 */
bool containsKey(const char* key) const;
bool containsKey(const String& key) const;
bool containsKey(const std::string& key) const;
bool containsKey(const __FlashStringHelper& key) const;

例子说明：

StaticJsonBuffer<256> jsonBuffer;
JsonObject& root = jsonBuffer.createObject();
root["city"] = "Paris";

bool hasCity = root.containsKey("city"); // true
bool hasCountry = root.containsKey("country"); // false

注意:

json库的开发者不建议使用该方法，由于就算没有值也会返回一个空值。库开发者给了例子建议：

if (root.containsKey("error"))
{
  const char* error = root["error"]
  Serial.println(error);
  return;
}

能够改为：

JsonVariant error = root["error"];
if (error.success()) 
{
  Serial.println(error.as<char*>());
  return;
}

或者更加简单快速的方法：

const char* error = root["error"];
if (error) 
{
  Serial.println(error);
  return;
}

3.1.2.3 createNestedArray —— 在当前对象中添加子key，子value为json数组

函数说明：

/**
 * 在当前对象中添加子key，子value为json数组
 * @param key key名字
 * @return JsonArray
 */
JsonArray& createNestedArray(const char* key) const;
JsonArray& createNestedArray(char* key) const; // see Remarks
JsonArray& createNestedArray(const String& key) const; // see Remarks
JsonArray& createNestedArray(const std::string& key) const; // see Remarks
JsonArray& createNestedArray(const __FlashStringHelper* key) const; // see Remarks

例子说明：

StaticJsonBuffer<256> jsonBuffer;
JsonObject& root = jsonBuffer.createObject();
root["status"] = "on";
JsonArray& levels = root.createNestedArray("levels");
levels.add(10);
levels.add(30);
root.prettyPrintTo(Serial);

打印结果：

{
  "status": "on",
  "levels": [
    10,
    20
  ]
}

3.1.2.4 createNestedObject —— 在当前对象中添加子key，子value为json对象

函数说明：

/**
 * 在当前对象中添加子key，子value为json对象
 * @param key key名字
 * @return JsonObject对象
 */
JsonObject& createNestedObject(const char* key) const;
JsonObject& createNestedObject(char* key) const; // see Remarks
JsonObject& createNestedObject(const String& key) const; // see Remarks
JsonObject& createNestedObject(const std::string& key) const; // see Remarks
JsonObject& createNestedObject(const __FlashStringHelper* key) const; // see Remarks

例子说明：

StaticJsonBuffer<256> jsonBuffer;
JsonObject& root = jsonBuffer.createObject();
root["city"] = "Paris";
JsonObject& weather = root.createNestedObject("weather");
weather["temp"] = 14.2;
weather["cond"] = "cloudy";
root.prettyPrintTo(Serial);

打印结果：

{
  "city": "Paris",
  "weather": {
    "temp": 14.20,
    "cond": "cloudy"
  }
}

3.1.2.5 get —— 获取某一个key的值，T表示值类型

函数说明：

/**
 * 获取某一个key的值，T表示值类型
 * @param key key名字
 * @return 值
 */
bool            get<bool>           (TString key) const;
const char*     get<const char*>    (TString key) const;
double          get<double>         (TString key) const;
float           get<float>          (TString key) const;
JsonVariant     get<JsonVariant>    (TString key) const;
signed char     get<signed char>    (TString key) const;
signed int      get<signed int>     (TString key) const;
signed long     get<signed long>    (TString key) const;
signed short    get<signed short>   (TString key) const;
std::string     get<std::string>    (TString key) const;
String          get<String>         (TString key) const;
unsigned char   get<unsigned char>  (TString key) const;
unsigned int    get<unsigned int>   (TString key) const;
unsigned long   get<unsigned long>  (TString key) const;
unsigned short  get<unsigned short> (TString key) const;

例子说明：

char json[] = "{\"pi\":3.14}";
StaticJsonBuffer<256> jsonBuffer;
JsonObject& object = jsonBuffer.parseObject(json);
float pi = object.get<float>("pi"); // template version of get()
const char* value2 = object.get<const char*>("toto"); // returns NULL

3.1.2.6 is —— 判断某一个key的值是不是T类型

函数说明：

/**
 * 判断某一个key的值是不是T类型
 * @param key key名字
 * @return bool
 *         true 为T类型
 *         false 不是T类型
 */
bool is<bool>              (TString key) const;

bool is<const char*>       (TString key) const;
bool is<char*>             (TString key) const;

bool is<double>            (TString key) const;
bool is<float>             (TString key) const;

bool is<signed char>       (TString key) const;
bool is<signed int>        (TString key) const;
bool is<signed long>       (TString key) const;
bool is<signed short>      (TString key) const;
bool is<unsigned char>     (TString key) const;
bool is<unsigned int>      (TString key) const;
bool is<unsigned long>     (TString key) const;
bool is<unsigned short>    (TString key) const;
bool is<signed long long>  (TString key) const;   // <- may require ARDUINOJSON_USE_LONG_LONG
bool is<unsigned long long>(TString key) const;   // <- may require ARDUINOJSON_USE_LONG_LONG

bool is<JsonArray>         (TString key) const;
bool is<JsonObject>        (TString key) const;

例子说明：

char json[] = "{\"name\":\"toto\",\"pi\":3.14}";
StaticJsonBuffer<256> jsonBuffer;
JsonObject& obj = jsonBuffer.parseObject(json);

bool nameIsString = obj.is<char*>("name"); // <- true
bool piIsFloat = obj.is<float>("pi"); // <- true

// but we could also use JsonVariant.is<T>(), like that:
nameIsString = obj["name"].is<char*>(); // <- true
piIsFloat = obj["pi"].is<float>(); // <- true

3.1.2.7 measureLength —— 计算当前对象经过printTo打印出来的长度

函数说明：

/**
 * 计算当前对象经过printTo打印出来的长度
 * @return size_t 长度值
 * @Note 跟 JsonObject::printTo() 关联，此方法一般用于http协议中的 Content-Length头
 */
size_t measureLength() const

例子说明：

// Send headers
client.println("Content-Type: application/json");
client.print("Content-Length: ");
client.println(root.measureLength());

// Terminate headers
client.println();

// Send body
root.printTo(client);

3.1.2.8 measurePrettyLength —— 计算当前对象经过prettyPrintTo打印出来的长度

函数说明：

/**
 * 计算当前对象经过prettyPrintTo打印出来的长度
 * @return size_t 长度值
 * @Note 跟 JsonObject::prettyPrintTo() 关联，此方法一般用于http协议中的 Content-Length头
 */
size_t measurePrettyLength() const

例子说明：

// Send headers
client.println("Content-Type: application/json");
client.print("Content-Length: ");
client.println(root.measurePrettyLength());

// Terminate headers
client.println();

// Send body
root.prettyPrintTo(client);

3.1.2.9 prettyPrintTo —— 格式化输出json字符串

函数说明：

/**
 * 格式化输出json字符串
 * @param buffer 内容输出到内存区
 * @param size 内存区的大小
 * @param Print 打印流 好比 Serial
 * @param String 打印到字符串
 * @return 返回已写大小
 */
size_t prettyPrintTo(char* buffer, size_t size) const;
size_t prettyPrintTo(char buffer[size]) const;
size_t prettyPrintTo(Print &) const;
size_t prettyPrintTo(String &) const;
size_t prettyPrintTo(std::string &) const;

例子说明：

StaticJsonBuffer<200> jsonBuffer;
JsonObject& object = jsonBuffer.createObject();
object["hello"] = "world";
object.prettyPrintTo(Serial);

打印结果：

{
  "hello": "world"
}

3.1.2.10 printTo —— 压缩式输出json字符串

函数说明：

/**
 * 压缩式输出json字符串
 * @param buffer 内容输出到内存区
 * @param size 内存区的大小
 * @param Print 打印流 好比 Serial
 * @param String 打印到字符串
 * @return 返回已写大小
 */
size_t printTo(char* buffer, size_t size) const;
size_t printTo(char buffer[size]) const;
size_t printTo(Print &) const;
size_t printTo(String &) const;
size_t printTo(std::string &) const;

例子说明：

StaticJsonBuffer<200> jsonBuffer;
JsonObject& object = jsonBuffer.createObject();
object["hello"] = "world";
object.printTo(Serial);

打印结果：

{"hello":"world"}

注意：

该方法属于压缩式输出，能够节省空间；

3.1.2.11 remove —— 移除特定key和value

函数说明：

/**
 * 移除特定key和value
 * @param key key名
 */
void remove(const char* key);
void remove(const String& key);
void remove(const std::string& key);
void remove(const __FlashStringHelper* key);

例子说明：

JsonObject& object = jsonBuffer.createObject();
object["A"] = 1;
object["B"] = 2;
object["C"] = 3;
object.remove("B");
object.printTo(Serial);

打印结果：

{"A":1,"C":3}

注意：

该方法只会移除key-value，可是并不会释放key-value对应的jsonbuffer空间，也不建议在循环中同时add和remove key-value；

3.1.2.12 set —— 设置特定key的值

函数说明：

/**
 * 设置特定key的值
 * @param key key名
 * @param value 值
 * @return bool 是否设置成功
 */
bool set(TString key, bool value);
bool set(TString key, float value);
bool set(TString key, double value);
bool set(TString key, signed char value);
bool set(TString key, signed long value);
bool set(TString key, signed int value);
bool set(TString key, signed short value);
bool set(TString key, unsigned char value);
bool set(TString key, unsigned long value);
bool set(TString key, unsigned int value);
bool set(TString key, unsigned short value);
bool set(TString key, const char *value);
bool set(TString key, char *value); // see Remarks
bool set(TString key, const String &value); // see Remarks
bool set(TString key, const std::string &value); // see Remarks
bool set(TString key, const __FlashStringHelper* value); // see Remarks
bool set(TString key, JsonArray &array);
bool set(TString key, JsonObject &object);
bool set(TString key, const JsonVariant &value);

例子说明：

StaticJsonBuffer<200> jsonBuffer;
JsonObject& object = jsonBuffer.createObject();
object.set("hello","world");
object.printTo(Serial);

打印结果：

{"hello":"world"}

3.1.2.13 size —— 返回对象键值对的个数

函数说明：

/**
 * 返回对象键值对的个数
 * @return size_t 个数
 */
size_t size() const;

例子说明：

JsonObject& object = jsonBuffer.createObject();
object["hello"] = "world";
Serial.println(object.size()); // 1

3.1.2.14 operator[] —— get/set的快捷方式

函数说明：

/**
 * get/set的快捷方式
 */
JsonVariant& operator[](const char* key);
JsonVariant& operator[](char* key); // see Remarks
JsonVariant& operator[](const String& key); // see Remarks
JsonVariant& operator[](const std::string& key); // see Remarks
JsonVariant& operator[](const __FlashStringHelper* key); // see Remarks

const JsonVariant& operator[](const char* key) const;
const JsonVariant& operator[](const String& key) const;
const JsonVariant& operator[](const std::string& key) const;
const JsonVariant& operator[](const __FlashStringHelper* key) const;

例子说明：

JsonObject& object = jsonBuffer.createObject();
object["hello"] = "world";
const char* world = object["hello"];

3.1.2.15 success —— 判断对象是不是有效

函数说明：

/**
 * 判断对象是不是有效(解析或者分配内存)
 * @return bool
 */
bool success() const;

例子说明：

//Example 1: parsing success:
StaticJsonBuffer<200> jsonBuffer;
JsonObject& object = jsonBuffer.parseObject("{\"hello\":\"world\"}");
Serial.println(object.success()); // true

//Example 2: parsing failure:
StaticJsonBuffer<200> jsonBuffer;
JsonObject& object = jsonBuffer.parseObject("[\"hello\",\"world\"]");
Serial.println(object.success()); // false

//Example 3: allocation success:
StaticJsonBuffer<200> jsonBuffer;
JsonObject& object = jsonBuffer.createObject();
Serial.println(object.success()); // true

//Example 4: allocation failure:
StaticJsonBuffer<1> jsonBuffer;
JsonObject& object = jsonBuffer.createObject();
Serial.println(object.success()); // false

3.1.3 JsonArray

在JsonBuffer所构造出来的内存空间中，Json数组的入口就是JsonArray。
让咱们看看它的经常使用操做方法：

3.1.3.1 add —— 往数组中加入value

函数说明：

/**
 * 往数组中加入value
 * @param value 值
 * @return bool 是否添加成功，若是返回false通常都是jsonbuffer没有足够的空间
 */
bool add(bool value);
bool add(float value);
bool add(double value);
bool add(signed char value);
bool add(signed long value);
bool add(signed int value);
bool add(signed short value);
bool add(unsigned char value);
bool add(unsigned long value);
bool add(unsigned int value);
bool add(unsigned short value);
bool add(const char *value);
bool add(char *value); // see Remarks
bool add(const String &value); // see Remarks
bool add(const std::string &value); // see Remarks
bool add(const __FlashStringHelper *value); // see Remarks
bool add(JsonArray &array);
bool add(JsonObject &object);
bool add(const JsonVariant &variant);

例子说明：

StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
array.add("hello");
array.add(3.14156);
array.printTo(Serial);

打印结果：

["hello",3.14156]

3.1.3.2 begin/end —— 返回一个迭代器,可用于数组中的全部对象

函数说明：

/**
 * 返回一个迭代器,可用于数组中的全部对象
 * @return iterator
 */
JsonObject::iterator begin();
JsonObject::iterator end();
JsonObject::const_iterator begin() const;
JsonObject::const_iterator end() const;

例子说明：

char json[] = "[\"one\",\"two\",\"three\"]";
DynamicJsonBuffer jsonBuffer;
JsonArray& arr = jsonBuffer.parseArray(json);

// using C++11 syntax (preferred):
for (auto value : arr) {
    Serial.println(value.as<char*>());
}

// using C++98 syntax (for older compilers):
for (JsonArray::iterator it=arr.begin(); it!=arr.end(); ++it) {
    Serial.println(it->as<char*>());
}

打印结果：

one
two
three

3.1.3.3 copyFrom —— 把c数组转成json数组

函数说明：

/**
 * 把c数组转成json数组
 * @param array 数组
 * @param len 数组大小
 */
// 1D arrays
JsonArray::copyFrom(T array[len]);
JsonArray::copyFrom(T* array, size_t len);

// 2D arrays
JsonArray::copyFrom(T array[][]);

例子说明：

int values[] = {1, 2, 3};

StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
array.copyFrom(values);
array.printTo(Serial);

打印结果：

[1,2,3]

3.1.3.4 copyTo —— 把json数组转成c数组

函数说明：

/**
 * 把json数组转成c数组
 * @param array 数组
 */
JsonArray::copyTo(int array[]);
JsonArray::copyTo(double array[]);
JsonArray::copyTo(const char* array[]);

例子说明：

int values[3];

StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.parseArray("[1,2,3]");
array.copyTo(values);//如今values变成1,2,3

3.1.3.5 createNestedArray —— 添加json数组

函数说明：

/**
 * 添加json数组
 * @return  JsonArray json数组
 */
JsonArray& createNestedArray();

例子说明：

StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
array.add("hello");
JsonArray& nested = array.createNestedArray();
nested.add("world");
array.printTo(Serial);

打印结果：

["hello",["world"]]

3.1.3.6 createNestedObject —— 添加json对象

函数说明：

/**
 * 添加json对象
 * @return  JsonObject json对象
 */
JsonObject& createNestedObject();

例子说明：

StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
JsonObject& nested = array.createNestedObject();
nested["hello"] = "world";
array.printTo(Serial);

打印结果：

[{"hello":"world"}]

3.1.3.7 get —— 获取具体index的值

函数说明：

/**
 * 获取具体index的值
 * @param  index 索引
 * @return  T 返回索引对应的值
 */
bool            get<bool>           (size_t index) const;
const char*     get<const char*>    (size_t index) const;
const char*     get<char*>          (size_t index) const;
double          get<double>         (size_t index) const;
float           get<float>          (size_t index) const;
signed char     get<signed char>    (size_t index) const;
signed int      get<signed int>     (size_t index) const;
signed long     get<signed long>    (size_t index) const;
signed short    get<signed short>   (size_t index) const;
unsigned char   get<unsigned char>  (size_t index) const;
unsigned int    get<unsigned int>   (size_t index) const;
unsigned long   get<unsigned long>  (size_t index) const;
unsigned short  get<unsigned short> (size_t index) const;
JsonVariant     get<JsonVariant>    (size_t index) const;
std::string     get<std::string>    (size_t index) const;
String          get<String>         (size_t index) const;

例子说明：

char json[] = "[1,3.14]";
StaticJsonBuffer<256> jsonBuffer;
JsonArray& array = jsonBuffer.parseArray(json);
int value0 = array.get(0); // implicit cast of the JsonVariant
float value1 = array.get<float>(1); // template version of get()
const char* value2 = array.get(2); // returns NULL

注意：

integer默认值是0
double默认值是0.0
char* 默认是是NULL

3.1.3.8 is —— 判断具体index的值是否为T类型

函数说明：

/**
 * 判断具体index的值是否为T类型
 * @return  bool 是不是目标类型
 */
bool is<bool>              (size_t index) const;

bool is<const char*>       (size_t index) const;
bool is<char*>             (size_t index) const;

bool is<double>            (size_t index) const;
bool is<float>             (size_t index) const;

bool is<signed char>       (size_t index) const;
bool is<signed int>        (size_t index) const;
bool is<signed long>       (size_t index) const;
bool is<signed short>      (size_t index) const;
bool is<unsigned char>     (size_t index) const;
bool is<unsigned int>      (size_t index) const;
bool is<unsigned long>     (size_t index) const;
bool is<unsigned short>    (size_t index) const;
bool is<signed long long>  (size_t index) const;   // <- may require ARDUINOJSON_USE_LONG_LONG
bool is<unsigned long long>(size_t index) const;   // <- may require ARDUINOJSON_USE_LONG_LONG

bool is<JsonArray>         (size_t index) const;
bool is<JsonObject>        (size_t index) const;

例子说明：

char json[] = "[\"pi\",3.14]";
StaticJsonBuffer<256> jsonBuffer;
JsonArray& array = jsonBuffer.parseArray(json);

bool firstIsString = array.is<char*>(0); // <- true
bool secondIsFloat = array.is<float>(1); // <- true

// but we could also use JsonVariant.is<T>(), like that:
firstIsString = array[0].is<char*>(); // <- true
secondIsFloat = array[1].is<float>(); // <- true

3.1.3.9 measureLength —— 计算当前json数组经过printTo打印出来的长度

函数说明：

/**
 * 计算当前json数组经过printTo打印出来的长度
 * @return size_t 长度值
 * @Note 跟 JsonArray::printTo() 关联，此方法一般用于http协议中的 Content-Length头
 */
size_t measureLength() const

例子说明：

// Send headers
client.println("Content-Type: application/json");
client.print("Content-Length: ");
client.println(root.measureLength());

// Terminate headers
client.println();

// Send body
root.printTo(client);

3.1.3.10 measurePrettyLength —— 计算当前json数组经过prettyPrintTo打印出来的长度

函数说明：

/**
 * 计算当前json数组经过prettyPrintTo打印出来的长度
 * @return size_t 长度值
 * @Note 跟 JsonArray::prettyPrintTo() 关联，此方法一般用于http协议中的 Content-Length头
 */
size_t measurePrettyLength() const

例子说明：

// Send headers
client.println("Content-Type: application/json");
client.print("Content-Length: ");
client.println(root.measurePrettyLength());

// Terminate headers
client.println();

// Send body
root.prettyPrintTo(client);

3.1.3.11 prettyPrintTo —— 格式化输出json数组字符串

函数说明：

/**
 * 格式化输出json数组字符串
 * @param buffer 内容输出到内存区
 * @param size 内存区的大小
 * @param Print 打印流 好比 Serial
 * @param String 打印到字符串
 * @return 返回已写大小
 */
size_t prettyPrintTo(char* buffer, size_t size) const;
size_t prettyPrintTo(char buffer[size]) const;
size_t prettyPrintTo(Print &) const;
size_t prettyPrintTo(String &) const;
size_t prettyPrintTo(std::string &) const;

例子说明：

StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
array.add("hello");
array.add("world");
array.prettyPrintTo(Serial);

打印结果：

[
  "hello",
  "world"
]

3.1.3.12 printTo —— 压缩式输出json数组字符串

函数说明：

/**
 * 压缩式输出json数组字符串
 * @param buffer 内容输出到内存区
 * @param size 内存区的大小
 * @param Print 打印流 好比 Serial
 * @param String 打印到字符串
 * @return 返回已写大小
 */
size_t printTo(char* buffer, size_t size) const;
size_t printTo(char buffer[size]) const;
size_t printTo(Print &) const;
size_t printTo(String &) const;
size_t printTo(std::string &) const;

例子说明：

StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
array.add("hello");
array.add("world");
array.printTo(Serial);

打印结果：

["hello","world"]

注意：

该方法属于压缩式输出，能够节省空间；

3.1.3.13 remove —— 移除某一个index位置的元素

函数说明：

/**
 * 移除某一个index位置的元素
 * @param index 索引
 */
void remove(size_t index);

例子说明：

JsonArray& array = jsonBuffer.createArray();
array.add("A");
array.add("B");
array.add("C");
array.remove(1);
array.printTo(Serial);

打印结果：

["A","C"]

注意：

该方法只会移除索引对应的value，可是并不会释放对应的jsonbuffer空间，也不建议在循环中同时add和remove；

3.1.3.14 set —— 设置某一个index位置的值

函数说明：

/**
 * 设置某一个index位置的值
 * @param index 索引位置
 * @param value 值
 * @return bool 是否设置成功
 */
bool set(size_t index, bool value);
bool set(size_t index, double value);
bool set(size_t index, float value);
bool set(size_t index, signed char value);
bool set(size_t index, signed int value);
bool set(size_t index, signed long value);
bool set(size_t index, signed short value);
bool set(size_t index, unsigned char value);
bool set(size_t index, unsigned int value);
bool set(size_t index, unsigned long value);
bool set(size_t index, unsigned short value);
bool set(size_t index, const char *value);
bool set(size_t index, char *value); // see Remarks
bool set(size_t index, const std::string &value); // see Remarks
bool set(size_t index, const String &value); // see Remarks
bool set(size_t index, const __FlashStringHelper *value); // see Remarks
bool set(size_t index, JsonArray &array);
bool set(size_t index, JsonObject &object);
bool set(size_t index, const JsonVariant &value);

例子说明：

StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();

// increase the size of the array
array.add(666);
array.add(666);

// replace the values
array.set(0, "hello");
array.add(1, 3.14156);

// serialize
array.printTo(Serial);

打印结果：

["hello",3.14156]

3.1.3.15 size —— 返回json数组元素的个数

函数说明：

/**
 * 返回json数组元素的个数
 * @return size_t 个数
 */
size_t size() const;

例子说明：

JsonArray& array = jsonBuffer.createArray();
array.add("hello");
array.add("world");
Serial.println(array.size()); // 2

3.1.3.16 operator[] —— get/set 快捷快捷方式

函数说明：

/**
 * get/set的快捷方式
 */
JsonVariant& operator[](size_t index);
const JsonVariant& operator[](size_t index) const;

例子说明：

JsonArray& array = jsonBuffer.createArray();
array.add(42);
int value = array[0];
array[0] = 666;

3.1.3.17 success —— 判断json数组是否成功分配内存或者解析

函数说明：

/**
 * 判断json数组是否成功分配内存或者解析
 * @return bool
 */
bool success() const;

例子说明：

//Example 1: parsing success:
StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.parseArray("[1,2]");
Serial.println(array.success()); // true

//Example 2: parsing failure:
StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.parseArray("{1,2}");
Serial.println(array.success()); // false

//Example 3: allocation success:
StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
Serial.println(array.success()); // true

//Example 4: allocation failure:
StaticJsonBuffer<1> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
Serial.println(array.success()); // false

3.1.4 编码Json字符串

讲完理论知识，咱们开始用具体例子来验证。

实验材料：

Arduino板子，博主这里用Mega2560

例子代码：

/**
 * 构造json例子
 * @author 单片机菜鸟
 * @date 2019/06/01
 */
#include <ArduinoJson.h>

void setup() {
  Serial.begin(115200);
  while (!Serial) continue;
  // Json对象对象树的内存工具 静态buffer 
  // 200 是大小 若是这个Json对象更加复杂，那么就须要根据须要去增长这个值.
  StaticJsonBuffer<200> jsonBuffer;
  // StaticJsonBuffer 在栈区分配内存   它也能够被 DynamicJsonBuffer（内存在堆区分配） 代替
  // DynamicJsonBuffer  jsonBuffer;
  //建立最外层的json对象 —— root对象，顶节点
  JsonObject& root = jsonBuffer.createObject();
  //给最外层json对象添加属性
  root["sensor"] = "gps";
  root["time"] = 1351824120;
  //在root对象中加入data数组
  JsonArray& data = root.createNestedArray("data");
  data.add(48.756080);
  data.add(2.302038);
  //在串口中打印，printTo方法不会格式化json
  root.printTo(Serial);
  // This prints:
  // {"sensor":"gps","time":1351824120,"data":[48.756080,2.302038]}

  Serial.println();
  //在串口中打印，prettyPrintTo方法会格式化json
  root.prettyPrintTo(Serial);
  // This prints:
  // {
  //   "sensor": "gps",
  //   "time": 1351824120,
  //   "data": [
  //     48.756080,
  //     2.302038
  //   ]
  // }
}

void loop() {
  // not used in this example
}

运行结果：

3.1.5 解码Json字符串

实验材料：

Arduino板子，博主这里用Mega2560

例子代码：

/**
 * 解码Json字符串
 * @author 单片机菜鸟
 * @date 2019/06/02
 */
#include <ArduinoJson.h>

void setup() {
  Serial.begin(115200);
  while (!Serial) continue;
  // Json对象对象树的内存工具 静态buffer 
  // 200 是大小 若是这个Json对象更加复杂，那么就须要根据须要去增长这个值.
  StaticJsonBuffer<200> jsonBuffer;
  // StaticJsonBuffer 在栈区分配内存   它也能够被 DynamicJsonBuffer（内存在堆区分配） 代替
  // DynamicJsonBuffer  jsonBuffer;
  char json[] =
      "{\"sensor\":\"gps\",\"time\":1351824120,\"data\":[48.756080,2.302038]}";
  JsonObject& root = jsonBuffer.parseObject(json);

  // Test if parsing succeeds.
  if (!root.success()) {
    Serial.println("parseObject() failed");
    return;
  }

  // Fetch values.
  //
  // Most of the time, you can rely on the implicit casts.
  // In other case, you can do root["time"].as<long>();
  const char* sensor = root["sensor"];
  long time = root["time"];
  double latitude = root["data"][0];
  double longitude = root["data"][1];

  // Print values.
  Serial.println(sensor);
  Serial.println(time);
  Serial.println(latitude, 6);
  Serial.println(longitude, 6);    
}

void loop() {
  // not used in this example
}

注意：

解析失败一般有以下三个缘由：

Json字符串非法（格式不对）
Json字符串产生对象
JsonBuffer过小

3.2 ArduinoJson V5版本编译配置

3.2.1 ARDUINOJSON_VERSION —— 当前ArduinoJson库的具体版本

好比，若是开发者当前版本为 5.13.2，那么就会有：

#define ARDUINOJSON_VERSION "5.13.2" //完整版本号
#define ARDUINOJSON_VERSION_MAJOR 5 //大版本
#define ARDUINOJSON_VERSION_MINOR 13 //小版本
#define ARDUINOJSON_VERSION_REVISION 2 //小小版本

咱们能够经过Serial打印版本号：

Serial.print("Using ArduinoJson version ");
Serial.println(ARDUINOJSON_VERSION);

经过它，咱们能够作一些事情，好比：

判断是否安装了ArduinoJson库

#ifndef ARDUINOJSON_VERSION
#error ArduinoJson not found, please include ArduinoJson.h in your .ino file
#endif

判断某一个版本

#if ARDUINOJSON_VERSION_MAJOR!=5 || ARDUINOJSON_VERSION_MINOR<13
#error ArduinoJson 5.13+ is required
#endif

3.2.2 ARDUINOJSON_DEFAULT_NESTING_LIMIT —— Json数据的嵌套层数

该选项用来配置 JsonBuffer::parseArray() 和 JsonBuffer::parseObject()的最大解析层数
ARDUINO 上默认是10层，通常来讲不用改

3.2.3 ARDUINOJSON_ENABLE_ARDUINO_STRING —— 是否使能Arduino字符串功能

默认true，建议不要动它

3.2.4 ARDUINOJSON_ENABLE_PROGMEM —— 是否使能Arduino F函数功能

默认true，建议不要动它

3.2.5 ARDUINOJSON_ENABLE_PROGMEM —— 是否使能Arduino F函数功能

默认true，建议不要动它

4.总结

整体上，Json属于一种数据交换格式，不会说太难。本篇属于简单介绍了ArduinoJson V5库的使用，更加复杂的使用请直接去到ArduinoJson的主页去查阅。