What happens when you have a random chip or sensor you want to interface with an Arduino, but don’t know how? You search for a pre-existing library of course. And where are many libraries hosted and available from? A place where eager developers hack together code, post updates, and collaborate with others: Github!
Installing a library
Many Arduino libraries are available from GitHub. It really fosters the spirit of Open Source work. If you come across a library you need on GitHub, getting it into the Arduino IDE is relatively simple. However, if you’re new to GitHub (or the Arduino IDE) you might miss the simple steps.
Step 1: Arduino IDE
Make sure you are running at least 1.0.5 or 1.5.x of the Arduino IDE (note: now 1.6.x contains all.)
1.5.x is the more “experimental” branch of the IDE. At the time of this posting, it has become much more stable, but still focused on the more advanced Arduino boards: Yún, (Intel)Galieo, and Due. So if you have a Nano, Uno, or Mega board, you may want to stick with the 1.0.x branch.
The reason you need these version of the IDE is because it adds support for the critical “Add Library…” function.
Step 2: Download the Library
You might notice on the GitHub page you can navigate through the various files of a library. It may be tempting to just download the .cpp and .h files then figure out where to put them. There’s a couple of other files that are included in an Arduino library, so this isn’t really the best option. Instead, on the project page look for the “Download ZIP” button.
This downloads the latest version of the files in the correct directories as a ZIP file.
Step 3: Rename the Library!
Okay, this step is bound to trip people up. In this example, we’re using the Adafruit NeoPixel library, which when downloaded becomes “Adafruit_NeoPixel-master.zip”.
That’s going to be a problem, because the Arduino IDE doesn’t like characters like “_” and “-“.
Step 3A) un-zip the library and rename the Folder
Use whatever unzip your OS requires and then rename the folder to remove the “_” and “-” characters. The IDE says it only wants “Basic ASCII” which is way to say “letters and numbers only.”[optional] Also, GitHub adds the word “master.” Remove that too.
Once done, you should have a folder (or directory) just called “AdafruitNeoPixel”.
Step 4: Install the Library
In the past, this Step was difficult to get right. That’s why the IDE now has a “Add Library” option.
For this step, just do “Add Library” and navigate to you new library directory.
Step 5: Restart the IDE [optional]
Even though this step may be optional, I’ve found it is a good idea. Restart the IDE so that it properly loads the KEYWORD file, Examples, and adds the Library to the Library Menu.
If you get the following error, go back to Step 3.
You’re probably trying to import that ZIP file directly (which contains the “bad” directory name) or the library doesn’t support the “Add File…” option. If that’s the case, post a link to the project below and see if someone can help.
I’m having a problem with libraries in general. How do I use the variables in them? In the library, HMC5883L.h, I’m trying to use the variables to access the heading in the compass module. How do I find the variables created by the library and how do I use them? This is the first section of a project I’m working on.
hi there can someone please help me to get my self balancing robot to work please
Hi James, thanks for the article.
I’m new to GitHub and unsure how to download certain files.
I am looking to download ‘I2CDev’ library for my Arduino project from here: https://github.com/jrowberg/i2cdevlib/tree/master/Arduino/MPU6050
The problem is, I don’t see an option to download the library and I don’t know what else can I do here?
Are you able to advice how to download libraries from GitHub please?
Thanks in advance!
Back up to the project’s root: https://github.com/jrowberg/i2cdevlib
Hi, I was trying the exact same library download as above. I went up to project root and downloaded. If I just try and install the whole root I get an error “Specified folder/zip file does not contain a valid library” if I unzip the MPU6050 folder and try and install like above I dont have the “Import library” Option. Only Add zip and manage. If I try and manually unzip that folder to the library I get a similar error “A subfolder of your sketchbook is not a valid library”
Sorry bit new to Arduino. Any advice greatly appreciated.
What do you do if it is not a zipped file but the h. file code? There’s no .cpp file of others? Like this one: https://github.com/esp8266/Arduino/blob/master/tools/sdk/include/queue.h
That isn’t a library intended for the IDE. It’s part of the ESP8266 core, which is located at https://github.com/esp8266/Arduino.
Hi. Well done. Very interesting article. If you want we can share projects and ideas. I have done such similar tutorials on my site. A similar one can be found here http://www.buonevacanze.org/ArduinoDevEnvironment.html . It talks about the dev environment in general but also it talks about libraries. If you want we can chat about our projects. I will send you my private address
HEY many thanks !! i did it in 60 seconds,YOU MADE IT so easy to understanD !