Introduction: Making an Arduino Library for YouTube Sight
I’ve recently built a service called YouTube Sight that can extract subscribers data from YouTube Analytics API and give you more accurate subscriber counts since YouTube started to aggregate the results. With it, I’ve built an example sketch but I also wanted to make an Arduino library so people can more easily use it.
Step 1: What Is a Library?
A library is a piece of code that can handle a specific operation, process a type of data or can know how to interact with a specific hardware element. They allow us to easily extend the Arduino environment and there are a lot of them that come pre-installed with the Arduino IDE.
In cases like mine, where we want to add new possibilities to the Arduino, we can create our own libraries for other people to use them. All of the installed libraries live in a specific folder on our computer. In my case for the Windows PC, the libraries live under the Documents/Arduino folder. The full path will be specific for you, based on your username.
Step 2: Library Structure and Files
To start building our library, we first need to create a folder here with the name of it so I’ve created a folder called YouTube Sight. In the bare minimum version of the library, we must have at least two files.
The first one is a so-called “header” file that contains all of the definitions of the methods and properties our library provides, and the second one is the source file that will contain all of the source code.
The header files have an extension of “.h” while the source file has an extension of “.cpp” and they usually have the name of the library as the filename. In my case, the two files are called “YouTubeSight.h” and “YouTubeSight.cpp”.
The process of writing the library code can be a bit tedious and frustrating, especially when you are writing a library for the first time, but with a lot of trial and error, you can achieve the desired results. Because of that I will guide you through the finished code of the two files and explain it.
The full code and the library are available for download from GitHub on the following link:
Step 3: The Header File
Inside the header file, in the beginning, the entire file is wrapped inside an “ifndef” statement which checks if the variable specified is defined or not. This will prevent errors for anyone who uses the library if they include it twice in the same sketch by mistake.
Next, we need to include the base Arduino library and since we will be working with an HTTP client of some sort to send in the request to YouTube Sight we will also include the base Client library.
Before we start writing the content of our main class, we need to define any static variables and settings that we don’t want to be modified. In my case, there are two such variables. The main URL of the YouTube Sight service and the timeout variable that we will use to check for how long we read a value.
Also in this section, we can define any custom types that we want to use like this channelStatistics structure that we will save the results to.
The class structure definition is split into two parts. The first part is the definition of all of the public functions and properties and the second one is the definition of all of the private functions and properties. The difference between both is that the end-users of our library will not be able to use anything from the private section directly while they will be able to directly modify and use any of the properties and functions from the public part.
In the public section, we define the class constructor, the channelStats variable where we will store the results, the function that will get the data and a debug property that we can later use to check for cases where we might not get the expected results.
For the private properties, we will define one for storing the channel GUID, a pointer to the HTTP client we will use and a function that will split the returned string from YouTube Sight.
Step 4: The Source File
Now let’s look into the actual implementation of all this inside the source file.
The first step for us is to include our own header file that we just created and then we need to define the library constructor. In it, we pass two variables. The GUID is saved into the private variable that we defined earlier and the Client is passed by reference so we can then call the same instance that we got.
The main getData function of the library is defined next by first specifying the return type, followed by the library name and the function name. I will not go into detail of what every single line does in this function, but in general, the function opens up a connection to the YouTube Sight server, sends in the request to get the statistics and then parses the returned data with the help of the private getValue function.
The retrieved results are then set to the channelStats variable and an indicator is returned if we succeeded to retrieve the results or not and with that the core of our library is complete.
Step 5: Providing Example Sketches
Usually thou, every library provides examples that you can quickly load up and use to showcase what the library can do and how to do it. To provide such examples, we need to modify the library structure where now the header and the source file will be in an “src” folder and a new folder will be added under the library root called “examples”.
Any Arduino sketch that you place inside this folder will be served from the Arduino IDE as an example for your library and people can quickly explore it and learn how the library works.
Step 6: Publishing to the Library Manager
To use the library, people will need to simply include the header file of your library in their sketch and the Arduino IDE will build it together with it. But in order to do so, they will first need to install it on their machines.
A common way is to download the library from GitHub and install it through the ZIP installer in the IDE or simply place it inside the libraries folder as we did when we were creating it. However, the Arduino IDE also includes a tool, called the Library Manager that allows you to search for a library directly from the IDE.
To include your library in it, we first need to create an additional file in the root folder called “library.properties” and in it, we need to specify the library name, the current version and some additional info that will help the library manager to display better info about it.
With the file in place, an issue needs to be created on the Arduino GitHub page that simply asks for your library to be included in the index with the link to it and once it is approved and added by the Arduino staff, the Library manager will start to offer your library in the results. Additionally, the manager will look for any version tags in the GitHub repo in the future and offer an update to people using it once there are changes.
Step 7: Next Steps
I hope that after this Instructable, you have a better understanding of how Arduino libraries work, how you can create one and most importantly, I hope that you get inspired to start working on your next big idea.