[144] | 1 | aJson v1.0
|
---|
| 2 | ================
|
---|
| 3 | Copyright (c) 2010, Interactive Matter, Marcus Nowotny
|
---|
| 4 |
|
---|
| 5 | Based on the cJSON Library, Copyright (C) 2009 Dave Gamble
|
---|
| 6 |
|
---|
| 7 | Permission is hereby granted, free of charge, to any person obtaining a copy
|
---|
| 8 | of this software and associated documentation files (the "Software"), to deal
|
---|
| 9 | in the Software without restriction, including without limitation the rights
|
---|
| 10 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
---|
| 11 | copies of the Software, and to permit persons to whom the Software is
|
---|
| 12 | furnished to do so, subject to the following conditions:
|
---|
| 13 |
|
---|
| 14 | The above copyright notice and this permission notice shall be included in
|
---|
| 15 | all copies or substantial portions of the Software.
|
---|
| 16 |
|
---|
| 17 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
---|
| 18 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
---|
| 19 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
---|
| 20 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
---|
| 21 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
---|
| 22 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
---|
| 23 | THE SOFTWARE.
|
---|
| 24 |
|
---|
| 25 | Welcome to aJson.
|
---|
| 26 | ================
|
---|
| 27 |
|
---|
| 28 | aJson is the attempt to port a complete JSON implementation to Arduino. It is based on the cJSON implementation, reduced in size and removing one or two features:
|
---|
| 29 |
|
---|
| 30 | - The code has very limited support on ATmega168 - there is just not enough memory and
|
---|
| 31 | memory fragmentation is a serious problem
|
---|
| 32 | - Arrays and Lists are max 255 elements big
|
---|
| 33 | - There is no proper Unicode handling in this code
|
---|
| 34 | - There is an internal buffer eating up 256 bytes of ram
|
---|
| 35 |
|
---|
| 36 | Most of the limitation will be gone in one of the future releases.
|
---|
| 37 |
|
---|
| 38 | JSON is described best here: http://www.json.org/
|
---|
| 39 | It's like XML, but fat-free. You use it to move data around, store things, or just
|
---|
| 40 | generally represent your program's state.
|
---|
| 41 | JSON is especially useful to exchange data efficiently with e.g. JavaScript, Java, C++,
|
---|
| 42 | Processing or anything else
|
---|
| 43 |
|
---|
| 44 | aJson is a library to receive, understand, create or modify JSON strings directly in the
|
---|
| 45 | Arduino. JSON is quite a standard, so that is perfect for exchanging data with other
|
---|
| 46 | applications. I combination with HTTP it is suitable to implement REST Web Services.
|
---|
| 47 |
|
---|
| 48 | aJson provides functions to parse JSON strings to object models. Handle, search and
|
---|
| 49 | create and modify JSON Object structures.
|
---|
| 50 |
|
---|
| 51 | This is some JSON from this page: http://www.json.org/fatfree.html
|
---|
| 52 |
|
---|
| 53 | ```javascript
|
---|
| 54 | {
|
---|
| 55 | "name": "Jack (\"Bee\") Nimble",
|
---|
| 56 | "format": {
|
---|
| 57 | "type": "rect",
|
---|
| 58 | "width": 1920,
|
---|
| 59 | "height": 1080,
|
---|
| 60 | "interlace": false,
|
---|
| 61 | "frame rate": 24
|
---|
| 62 | }
|
---|
| 63 | }
|
---|
| 64 |
|
---|
| 65 | ```
|
---|
| 66 |
|
---|
| 67 | Parsing JSON
|
---|
| 68 | ================
|
---|
| 69 |
|
---|
| 70 | To parse such a structure with aJson you simply convert it to a object tree:
|
---|
| 71 |
|
---|
| 72 | ```c
|
---|
| 73 | aJsonObject* jsonObject = aJson.parse(json_string);
|
---|
| 74 | ```
|
---|
| 75 |
|
---|
| 76 | (assuming you got the JSON string in the variable json_string - as a char*)
|
---|
| 77 |
|
---|
| 78 | This is an object. We're in C. We don't have objects. But we do have structs.
|
---|
| 79 | Therefore the objects are translated into structs, with all the drawbacks it brings.s
|
---|
| 80 |
|
---|
| 81 | Now we can e.g. retrieve the value for name:
|
---|
| 82 |
|
---|
| 83 | ```c
|
---|
| 84 | aJsonObject* name = aJson.getObjectItem(root, "name");
|
---|
| 85 | ```
|
---|
| 86 |
|
---|
| 87 | The value of name can be retrieved via:
|
---|
| 88 |
|
---|
| 89 | ```c
|
---|
| 90 | Serial.println(name->valuestring);
|
---|
| 91 | ```
|
---|
| 92 |
|
---|
| 93 | Note that the aJsonObject has a union which holds all possible value types as
|
---|
| 94 | overlays - you can get only useful data for the type which you have at hand. You can get
|
---|
| 95 | the type as
|
---|
| 96 |
|
---|
| 97 | ```c
|
---|
| 98 | name->type
|
---|
| 99 | ```
|
---|
| 100 |
|
---|
| 101 | which can be either aJson_False, aJson_True, aJson_NULL, aJson_Number, aJson_String, aJson_Array
|
---|
| 102 | or aJson_Object. For aJson_Number you can use value.number.valueint or value.number.valuedouble, for aJson_String
|
---|
| 103 | you can use value.valuestring, for True or False, you can use value.valuebool.
|
---|
| 104 |
|
---|
| 105 | To render the object back to a string you can simply call
|
---|
| 106 |
|
---|
| 107 | ```c
|
---|
| 108 | char *json_String=aJson.print(jsonObject);
|
---|
| 109 | ```
|
---|
| 110 |
|
---|
| 111 | Finished? Delete the root (this takes care of everything else).
|
---|
| 112 |
|
---|
| 113 | ```c
|
---|
| 114 | aJson.deleteItem(root);
|
---|
| 115 | ```
|
---|
| 116 |
|
---|
| 117 | This deletes the objects and all values referenced by it.
|
---|
| 118 |
|
---|
| 119 | Parsing streams
|
---|
| 120 | --------------
|
---|
| 121 |
|
---|
| 122 | As you can see this will eat up lots of memory. Storing the original string and the JSON object is a bit too much
|
---|
| 123 | for your Arduino - it will most likely use up all the memory. Therefore it is better to parse streams instead of strings.
|
---|
| 124 | A stream in C is a FILE* - on Arduino there are some special streams, but later adapters will be provided.
|
---|
| 125 | So if you for example read from a FILE* stream you can simply call
|
---|
| 126 |
|
---|
| 127 | ```c
|
---|
| 128 | aJsonObject* jsonObject = aJson.parse(file);
|
---|
| 129 | ```
|
---|
| 130 |
|
---|
| 131 | By that you will not have to store the JSON string in memory.
|
---|
| 132 |
|
---|
| 133 | Filtering while parsing
|
---|
| 134 | --------------
|
---|
| 135 |
|
---|
| 136 | Any JSON respond can have object name/value pairs your code either does not understand or is not interested in.
|
---|
| 137 | To avoid those values going into your memory you can simply add filters to your parsing request.
|
---|
| 138 | A set of filter is just a list of names you are interested in, ended by a null value. If you are
|
---|
| 139 | only interested in "name", "format", "height" and "width" in the above example you can do it like:
|
---|
| 140 |
|
---|
| 141 | ```c
|
---|
| 142 | char** jsonFilter = {"name,"format","height","width",NULL};
|
---|
| 143 | aJsonObject* jsonObject = aJson.parse(json_string,jsonFilter);
|
---|
| 144 | ```
|
---|
| 145 | (assuming you got the JSON string in the variable json_string - as a char*)
|
---|
| 146 |
|
---|
| 147 | By that only the following structure is parsed - the rest will be ignored:
|
---|
| 148 |
|
---|
| 149 | ```javascript
|
---|
| 150 | {
|
---|
| 151 | "name": "Jack (\"Bee\") Nimble",
|
---|
| 152 | "format": {
|
---|
| 153 | "width": 1920,
|
---|
| 154 | "height": 1080,
|
---|
| 155 | }
|
---|
| 156 | }
|
---|
| 157 | ```
|
---|
| 158 |
|
---|
| 159 | It is good practice to always use the filtering feature to parse JSON answers, to avoid unknown objects swamping your
|
---|
| 160 | memory.
|
---|
| 161 |
|
---|
| 162 | Creating JSON Objects from code
|
---|
| 163 | ================
|
---|
| 164 |
|
---|
| 165 | If you want to see how you'd build this struct in code?
|
---|
| 166 |
|
---|
| 167 | ```c
|
---|
| 168 | aJsonObject *root,*fmt;
|
---|
| 169 | root=aJson.createObject();
|
---|
| 170 | aJson.addItemToObject(root, "name", aJson.createItem("Jack (\"Bee\") Nimble"));
|
---|
| 171 | aJson.addItemToObject(root, "format", fmt = aJson.createObject());
|
---|
| 172 | aJson.addStringToObject(fmt,"type", "rect");
|
---|
| 173 | aJson.addNumberToObject(fmt,"width", 1920);
|
---|
| 174 | aJson.addNumberToObject(fmt,"height", 1080);
|
---|
| 175 | aJson.addFalseToObject (fmt,"interlace");
|
---|
| 176 | aJson.addNumberToObject(fmt,"frame rate", 24);
|
---|
| 177 | ```
|
---|
| 178 |
|
---|
| 179 | The root object has: Object Type and a Child
|
---|
| 180 | The Child has name "name", with value "Jack ("Bee") Nimble", and a sibling:
|
---|
| 181 | Sibling has type Object, name "format", and a child.
|
---|
| 182 | That child has type String, name "type", value "rect", and a sibling:
|
---|
| 183 | Sibling has type Number, name "width", value 1920, and a sibling:
|
---|
| 184 | Sibling has type Number, name "height", value 1080, and a sibling:
|
---|
| 185 | Sibling hs type False, name "interlace", and a sibling:
|
---|
| 186 | Sibling has type Number, name "frame rate", value 24
|
---|
| 187 |
|
---|
| 188 | If you want to create an array it works nearly the same way:
|
---|
| 189 |
|
---|
| 190 | ```c
|
---|
| 191 | aJsonObject* root = aJson.createArray();
|
---|
| 192 |
|
---|
| 193 | aJsonObject* day;
|
---|
| 194 | day=aJson.createItem("Monday");
|
---|
| 195 | aJson.addItemToArray(root, day);
|
---|
| 196 | day=aJson.createItem("Tuesday");
|
---|
| 197 | aJson.addItemToArray(root, day);
|
---|
| 198 | day=aJson.createItem("Wednesday");
|
---|
| 199 | aJson.addItemToArray(root, day);
|
---|
| 200 | day=aJson.createItem("Thursday");
|
---|
| 201 | aJson.addItemToArray(root, day);
|
---|
| 202 | day=aJson.createItem("Friday");
|
---|
| 203 | aJson.addItemToArray(root, day);
|
---|
| 204 | day=aJson.createItem("Saturday");
|
---|
| 205 | aJson.addItemToArray(root, day);
|
---|
| 206 | day=aJson.createItem("Sunday");
|
---|
| 207 | aJson.addItemToArray(root, day);
|
---|
| 208 | ```
|
---|
| 209 |
|
---|
| 210 |
|
---|
| 211 | The whole library (nicely provided by cJSON) is optimized for easy usage. You can create and modify
|
---|
| 212 | the object as easy as possible.
|
---|
| 213 |
|
---|
| 214 | aJson Data Structures
|
---|
| 215 | ================
|
---|
| 216 |
|
---|
| 217 | aJson stores JSON objects in struct objects:
|
---|
| 218 |
|
---|
| 219 | ```c
|
---|
| 220 | // The aJson structure:
|
---|
| 221 | typedef struct aJsonObject {
|
---|
| 222 | char *name; // The item's name string, if this item is the child of, or is in the list of subitems of an object.
|
---|
| 223 | struct aJsonObject *next, *prev; // next/prev allow you to walk array/object chains. Alternatively, use GetArraySize/GetArrayItem/GetObjectItem
|
---|
| 224 | struct aJsonObject *child; // An array or object item will have a child pointer pointing to a chain of the items in the array/object.
|
---|
| 225 |
|
---|
| 226 | char type; // The type of the item, as above.
|
---|
| 227 |
|
---|
| 228 | union {
|
---|
| 229 | char *valuestring; // The item's string, if type==aJson_String
|
---|
| 230 | char valuebool; //the items value for true & false
|
---|
| 231 | int valueint; // The item's number, if type==aJson_Number
|
---|
| 232 | float valuefloat; // The item's number, if type==aJson_Number
|
---|
| 233 | };
|
---|
| 234 | } aJsonObject;
|
---|
| 235 | ```
|
---|
| 236 |
|
---|
| 237 | By default all values are 0 unless set by virtue of being meaningful.
|
---|
| 238 |
|
---|
| 239 | Note that the aJsonObject has a union 'value' which holds all possible value types as
|
---|
| 240 | overlays - you can get only useful data for the type which you have at hand. You can get
|
---|
| 241 | the type as
|
---|
| 242 |
|
---|
| 243 | ```c
|
---|
| 244 | name->type
|
---|
| 245 | ```
|
---|
| 246 |
|
---|
| 247 | which can be either aJson_False, aJson_True, aJson_NULL, aJson_Number, aJson_String, aJson_Array
|
---|
| 248 | or aJson_Object. For aJson_Number you can use value.number.valueint or value.number.valuedouble.
|
---|
| 249 | If you're expecting an int, read valueint, if not read valuedouble. For aJson_String
|
---|
| 250 | you can use value.valuestring, for True or False, you can use value.valuebool.
|
---|
| 251 |
|
---|
| 252 | next/prev is a doubly linked list of siblings. next takes you to your sibling,
|
---|
| 253 | prev takes you back from your sibling to you.
|
---|
| 254 | Only objects and arrays have a "child", and it's the head of the doubly linked list.
|
---|
| 255 | A "child" entry will have prev==0, but next potentially points on. The last sibling has next=0.
|
---|
| 256 | The type expresses Null/True/False/Number/String/Array/Object, all of which are #defined in
|
---|
| 257 | aJson.h
|
---|
| 258 |
|
---|
| 259 | Any entry which is in the linked list which is the child of an object will have a "string"
|
---|
| 260 | which is the "name" of the entry. When I said "name" in the above example, that's "string".
|
---|
| 261 | "string" is the JSON name for the 'variable name' if you will.
|
---|
| 262 |
|
---|
| 263 | Now you can trivially walk the lists, recursively, and parse as you please.
|
---|
| 264 | You can invoke aJson.parse to get aJson to parse for you, and then you can take
|
---|
| 265 | the root object, and traverse the structure (which is, formally, an N-tree),
|
---|
| 266 | and tokenise as you please.
|
---|
| 267 |
|
---|
| 268 | Lists in aJson
|
---|
| 269 | ================
|
---|
| 270 |
|
---|
| 271 | Lists are easily handled in aJson, to create a list you can simply use the provided API functions:
|
---|
| 272 |
|
---|
| 273 | ```c
|
---|
| 274 | aJson.create<TYPE>Array(objects,24);
|
---|
| 275 | ```
|
---|
| 276 |
|
---|
| 277 | You simply pass a array of the respective type: char*[], int[] and so on.
|
---|
| 278 |
|
---|
| 279 | aJSON doesn't make any assumptions about what order you create things in.
|
---|
| 280 | You can attach the objects, as above, and later add children to each
|
---|
| 281 | of those objects with
|
---|
| 282 |
|
---|
| 283 | ```c
|
---|
| 284 | aJson.addItemToArray()
|
---|
| 285 | ```
|
---|
| 286 |
|
---|
| 287 | or remove them with
|
---|
| 288 |
|
---|
| 289 | ```c
|
---|
| 290 | aJson.deleteItemFromArray() - which also deletes the objects, or
|
---|
| 291 | aJson.detachItemFromArray() - which does not free the memory
|
---|
| 292 | ```
|
---|
| 293 |
|
---|
| 294 | As soon as you call aJson.print(), it renders the structure to text.
|
---|
| 295 |
|
---|
| 296 |
|
---|
| 297 | Have Fun!
|
---|