aJson – Handle JSON with Arduino

August 14, 2010

in Internet of Things

The JSON data structure

Update: There has bee a major API change in Version 1.0 refer to the dedicated aJson page.

Exchanging data with other computers can be a daunting task with Arduino. No matter if you just want to pass some information to Processing, to a Web Service or something else – You always have to encode the data and decode the answer.

There always have been solutions like XML for structured data. But XML is hard to decode, complicated an takes up a lot of space. And then there is JSON. JSON is an easy and efficient way to transfer data. A complex data structure can for example represented as
{
"name": "Jack (\"Bee\") Nimble",
"format": {
"type": "rect",
"width": 1920,
"height": 1080,
"interlace": false,
"frame rate": 24
}
}

aJson is an Arduino library to enable JSON processing with Arduino. It easily enables you to decode, create, manipulate and encode JSON directly from and to data structures. By this you don’t have to bother with data encoding and decoding – this will hand aJson for you. It is based on the cJSON implementation, reduced in size and removing one or two features.

Using aJson

To use aJson get it from the git repository or download the latest version. Unpack the zip file (or the git files) into an Folder ‘aJson’ in the Arduino library directory ‘libraries\’. Due to the early stage of this library you can encounter problems. Simply submit a ticket and it will fix it as soon as possible. On github you will also find a simple Arduino sketch to test the library, or as a starting point.

To parse the above structure with aJson you simply convert it to a object tree:

 aJsonObject* jsonObject = aJson.parse(json_string);

(assuming you got the JSON string in the variable json_string – as a char*). This is an object. We’re in C. We don’t have objects. But we do have structs. Therefore the objects are translated into structs, with all the drawbacks it brings. Now we can e.g. retrieve the value for name:

 aJsonObject* name = aJson.getObjectItem(root, "name");

The value of name can be retrieved via:

Serial.println(name->value.valuestring);

Note that the aJsonObject has a union ‘value’ which holds all possible value types as overlays – you can get only useful data for the type which you have at hand. You can get the type as

 name->type

which can be either aJson_False, aJson_True, aJson_NULL, aJson_Number, aJson_String, aJson_Array or aJson_Object. For aJson_Number you can use value.number.valueint or value.number.valuedouble, for aJson_String you can use value.valuestring, for True or False, you can use value.valuebool.

If you want to change the name, you can do so by

aJson.getObjectItem(jsonObject,"name")->value.valuestring="a new name";

To render the object back to a string you can simply call

 char *json_String=aJson.print(jsonObject);

Finished? Delete the root (this takes care of everything else).

 aJson.delete(root);

This deletes the objects and all values referenced by it. So take care for your string, you directly assigned. They are deleted too.  If you want to see how you’d build this struct in code?

aJsonObject *root,*fmt;
root=aJson.createObject();
aJson.addItemToObject(root, "name", aJson.createString("Jack (\"Bee\") Nimble"));
aJson.addItemToObject(root, "format", fmt = aJson.createObject());
aJson.addStringToObject(fmt,"type",        "rect");
aJson.addNumberToObject(fmt,"width",        1920);
aJson.addNumberToObject(fmt,"height",        1080);
aJson.addFalseToObject (fmt,"interlace");
aJson.addNumberToObject(fmt,"frame rate",    24);

The whole library (nicely provided by cJSON) is optimized for easy usage. You can create and modify the object as easy as possible.

Limitations of aJson

Unfortunately everything comes for a price and complex data structures and text processing is not really the primary domain for Arduino. So some simplifications had to be made:

  • aJson is not really suitable for ATmega168 based Arduinos – there is just not enough RAM – and the library itself eats up toe 80% of the flash memory.
  • aJson cannot handle Unicode.
  • Lists and Objects can only handle up to 256 entries.
  • All strings are case sensitive, this is no real problem for values. But if you want to find a name you have keep in mind that it works case sensitive.

A lot of these limitations will be gone in the future versions of aJson.

Further Development of aJson

Currently aJson is considered to be in a beta phase. It is usable, but it can get better. The most important task is to further reduce the memory footprint. Therefore the API may change a bit in next versions. When the library is better tested and more evolved it will be package as real Arduino library.

I hope that many people will use and test the library. So go ahead and download aJson!

{ 15 comments… read them below or add one }

Jordi August 19, 2010 at 16:09

Great work, I’ve been waiting for months. I started a very simple parser a few days ago but was too heavy and decided to do de parsing in processing instead and send the data back to the arduino via serial.

I hope your lib will make it easier!! ;)

Reply

EllisGL August 24, 2010 at 22:44

Man – I was looking for this last year.. I’ll have to play with later.

Reply

Marcus August 25, 2010 at 10:38

I hope it helps. Just report any irregularities as an issue

Reply

Pat Cullen November 1, 2010 at 18:02

I looked so hard for a JSON parser a few months back.. I also started one but never quite got round to finishing it. Consider this favorited and bookmarked. Thanks for sharing. :)

Reply

Marcus November 1, 2010 at 18:24

And as a bonus expect a much better version 1.0 very soon (one memory leak left)

Reply

Janno Schouwenburg November 17, 2010 at 20:31

Hello, it is great to have found aJson! On my first try I have some beginner problems and it’s probably my own fault but I can not get the test.pde to compile. I used the v1.0 package. Compiling stops with the following messages:

test.cpp: In function ‘void setup()’:
test:101: error: ‘struct aJsonObject’ has no member named ‘value’

Line 101 contains: Serial.println(name->value.valuestring);

Any help or hints would be greatly appreciated.

Reply

Marcus November 18, 2010 at 06:52

oops,

forgot to update the test scripts.

Will do it on the weekend and remove this comment then, is that OK fro you?

Reply

Janno Schouwenburg November 20, 2010 at 10:00

No problem. Btw, I already used the library and it works great (except the test script that is).

c December 5, 2010 at 22:27

Hi – your copyright date in the README says 2001 when you probably meant 2010 -thx for the hard work -c

Reply

Marcus December 6, 2010 at 12:40

Will fix it. Thanks for the hint

Reply

TM June 11, 2011 at 19:04

Hi, Could you increase size off Lists and Objects up to 512b or more?

Reply

Marcus June 11, 2011 at 19:48

Nope,
But I will make it configurable ASAP. Hope that helps.

Reply

Francis February 29, 2012 at 04:07

Assuming this json string
String json_string = {“result”:”success”,”ip”:”1.2.3.4″}
char* JSON;
json_string.toCharArray(JSON,255);

aJsonObject* jsonObject = aJson.parse(JSON);
aJsonObject* result_val = aJson.getObjectItem(jsonObject, “result”);
aJsonObject* myip = aJson.getObjectItem(jsonObject, “ip”);
Serial.print(result_val->valuestring);
is printing ?ÖÿÏ»òÈÐÑú¶=)÷X;ß?[׏?ÿ»ißëoý׺ü÷Æ

Serial.print(result_val->value.valuestring);
is returning an error: ‘struct aJsonObject’ has no member named ‘value’

Maybe I’m doing something wrong…

Reply

jds3d August 24, 2013 at 19:22

Hi, I’ve a question

{“array”:[1,2,3,4,5]}

How should I proceed do be able to convert this to an array I can use in arduino?

Reply

lisasf December 13, 2013 at 22:08

Hello!

Thanks to this and other tutorials using aJson my application is run;
However the arduino is sending the object aJson only twice, then is not sending.

I thought it was the lack of command:
“aJson.delete (root);”
But when I wrote the class aJson not recognize. : (
I tried “aJson.remove (root);”
But it also does not work.

Anyone know how to delete this object * of the arduino memory?

Since already thank you very much! *. *

Reply

Leave a Comment

{ 3 trackbacks }