About
ArduinoJson. Efficient JSON serialization for embedded C++.
What is ArduinoJson?
Today is Saturday, and this morning the postman delivered a package from the electronic store. You open the packet and carefully unwrap all the tiny components. There is an Arduino board, an LCD display, a few wires, some solder, a soldering iron, and an enclosure. Yes, you have everything you wanted to build your weather station!
“OK, it’s not as pretty as I imagined, but it should do it !”. That’s what you say after spending two hours in the basement assembling your new toy… and burning your fingertips. All you need now is to plug this USB jack in your computer and program the damn thing!
Back at your desk, you open the Arduino IDE and upload one of the example sketches, just to verify that the board is working. After reading the forums, you decide that your little weather station will connect to the OpenWeatherMap service because it’s free and simple. The first step is to make the HTTP query and read the response. Easy-peasy! You open an example from the Ethernet library, make a few changes, press upload, and boom: you have the response from OpenWeatherMap, a big text encoded with this JSON format that everyone is talking about.
OK. So, you have the JSON document, but what now?
I’ll tell you: your program needs to decode the JSON document and extract the information you want to display on the screen; for example, you could start with the current temperature. But how to do that? Well, that is precisely the job of ArduinoJson: it eats a JSON document and allows your program to extract the information you want.
Extracting information from a JSON document is what we call “deserialization.” Of course, ArduinoJson also knows how to perform the reverse operation, the “serialization,” which generates a JSON document. But that’s not all, ArduinoJson also supports the MessagePack format, an alternative to JSON that produces smaller documents.
Of course, ArduinoJson is not limited to weather stations. You can use ArduinoJson to simplify virtually any program that needs to connect to a web service (Twitter, Facebook, GitHub, etc). You can also use ArduinoJson to serialize configuration files, exchange information between boards…
What makes ArduinoJson different?
ArduinoJson represents the best compromise between ease-of-use, efficiency, and portability.
It’s easy to use because you just need a few lines of code to do the work; there is very little ceremony compared to other libraries. Moreover, it leverages all C++ features to offer an elegant syntax to manipulate JSON documents.
It’s efficient because it’s designed to work on small microcontrollers, like the ones in Arduino boards. Indeed, you don’t program an ATmega328 with 2KB of RAM the same way you program a PC with 32GB of RAM. Different problems require different solutions.
It’s portable because it works on any platform: Arduino, of course, but also on ESP8266, on ESP32… Yes! You can also use ArduinoJson on a PC, whether it’s Windows, macOS, or Linux. Does that sound silly after what you just read? On the contrary, being able to compile ArduinoJson on a PC allows running unit tests on your desktop machine before deploying to the microcontroller.
Why is ArduinoJson efficient?
“Efficient” means it uses fewer resources to do the same work.
Those resources are:
- RAM
- CPU cycles
- Program Memory
ArduinoJson uses less RAM because it avoids copies when possible. Indeed, you don’t want the same information to be present several times in memory, that would be a terrible use of the RAM.
ArduinoJson uses fewer CPU cycles because it uses an optimized memory allocator. It can even work exclusively with stack memory, allowing to run on devices with very little memory.
ArduinoJson compiles to a small executable, leaving plenty of room for your program. Indeed, you’ll see that after including two or three libraries in your Arduino sketch, the program memory becomes very scarce.
What’s the story behind ArduinoJson?
Like all good software component, ArduinoJson was born inside a project and then extracted to be a standalone library.
This project is an RFID terminal that allowed paying soda cans and ice-creams with a key ring. You can read more about this project in this blog post. The RFID terminal communicates with a backend server through a RESTful API, using the JSON format in the requests’ body.
In 2014, the only JSON library for Arduino, aJson, was not suitable for this project because it consumed too much RAM. Moreover, aJson has an outdated C-style API, which makes it rather unpleasant to use.
So, a custom JSON deserializer was written for the RFID terminal, and the project worked like a charm. Later, a library was extracted under the name ArduinoJsonParser and shared on GitHub. As the project grew in popularity, the serialization feature was added and the library changed its name to ArduinoJson.
In 2015, ArduinoJson overpassed aJson by the number of stargazers on GitHub; and in 2016, it became the most starred Arduino library.
In 2017, this very website, arduinojson.org, was created to offer better documentation and to host the “ArduinoJson Assistant,” an online tool that generates the code for you.
In 2018, the book “Mastering ArduinoJson” was published, providing a complete, high-quality user manual.
Who is behind ArduinoJson?
ArduinoJson was created and is maintained by Benoît Blanchon, an experienced C++ developer who, like you, enjoys playing with electronics from time to time.
Benoît lives in France and has a Master’s degree from the Institut Supérieur d’Electronique de Paris. He works as software developer, but he developed ArduinoJson on his personal time.
Benoît created other successful open-source software, the most famous being Winpooch, which was a precursor to Windows Defender. More recently, he created Disable Windows Keys, a simple app but very useful when you play video games on Windows.
He sometimes writes in his blog Good Code Smell, but you’re more likely to find interesting articles in C++ for Arduino, another blog he created for Arduino users.
Where to start?
Ready to use ArduinoJson in your projects?
Here is where you should start:
