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!
|
---|