Main Menu

search

You are here

Home

Installing Contributed Arduino Libraries

[last updated: 2024-09-02]
Arduino home page
Libraries
-----

  • Three ways to add new libraries:
    • in IDE; library manager
    • In IDE: Sketch > include library > add zip
    • Completely manually

  • Note: Contributed libraries will be placed in your Sketchbook folder.

  • Note: No matter which method you use, ALWAYS RESTART THE IDE after adding a library.

------------------------------------------------------------

  • Library Manager:
    • This is probably the easiest and most foolproof method, but a lot of libraries are not available with this method.
      ------------------------------------------------------------
    • In IDE:
      Tools > Manage Libraries
    • The Library Manager dialogue box opens
      Click in the "Filter your search" field (top right of box)
      and type in the name, or some portion of it, of the library you need.
    • Scroll through the libraries that are listed.
    • If the library you want is there, hover over it.
      An Install button will be available (unless it's already installed), as well as perhaps a version drop-down.
    • Select the version you want, then click Install.

    ------------------------------------------------------------

  • The next two methods require you to Get a zip file of the library:
    • Broadly, you will be downloading a zip file from some online source to some arbitrary location on your PC.

    • The online source might be the manufacturer/vendor page for the hardware you need the library for,
      If so, it may have a "Download" button. Click it and tell it where you want the zip file saved.
      Choose an arbitrary, temporary location. I typically just put them on the desktop for easy access.

    • Your search for the library that you want may take you to (link to:) github, a very popular repository of all things software.
      On the github site, click "Clone or download", or click "Code", then "Download zip",
      and again tell it where you want the zip file to be placed.

    • The downloaded zip file will have a -master or -main suffix in the filename. Rename the file to remove that.
      Now that you have the zip file of the library, proceed to one of the next two steps.

    ------------------------------------------------------------

  • In IDE, with Sketch > Include Library > Add .ZIP Library:

    • Open IDE
      Sketch > Include library > Add .zip library...
      In the dialogue box that opens, browse to location of the zip file you're adding, select zip file, and click OK (or double-click the library.zip file)
    • In the IDE, the bottom blue message bar should say "Library added..."
        However you may get an error: "Specified folder/zip file does not contain a valid library."
        This happened when trying to add rf-nano-master.zip which has a non-standard directory structure.
        I did get the library added, by digging through the folders and finding the library files and installing them manually as described below.

    • in IDE: File > Preferences to find the name of your SketchBook folder
    • Browse to your [Sketchbook] / libraries folder.
      Note that a new folder has been created for your newly installed library.
      Rename new library folder by removing the "-master" or "-main" in the name
    • Close & re-open IDE
      Sketch > Include Library
      Scroll down to Contributed Libraries.
      Your new library should be there, correctly named.

    ------------------------------------------------------------

  • Completely manually:
    • Starting with a zipped file:
      • Navigate to zip file location, double-click on the zip file
        click extract
      • navigate to [sketchbook] / libraries folder
        click extract, then click close, then close window
      • open file manager to [sketchbook] / libraries folder
        rename library to remove the "-master"
              Also remove any other extraneous words, like eg. "Library" in the library name,
              and change hyphen to underscore if necessary...
      • move the zip file off the desktop into the library folder or wherever else for archive saving

    • To install a library that's already unzipped:
      • for example: The printf.h library is needed for the nRF24 program.
        It's located in nRF24/examples/pingpair directory
      • However if you just #include "printf.h" in your sketch,
        the IDE will not find it and will fail to compile.
      • Do this:
        Create a directory named "printf" in your [Sketchbook]/libraries folder
        Copy the extracted printf.h into this folder
        Close and re-open the IDE
        Your program should now find it and compile successfully.
      • Use the same procedure if your unzipped library contains several files (as most do).
        That is, create a directory with the name of the primary .h file,
        and move all the unzipped files into this directory.
        This will often include .h, .cpp, .c or other files, as well as "examples" or other sub-directories.
        Copy/move them all into your newly created directory.

      • In summary:
        If you want to include a library named libName.h,
        then the IDE will expect to find the library (the .h and associated files) in the root (or src sub-directory) of a directory named libName
        that is located in your [Sketchbook]/libraries folder.

    ------------------------------------------------------------

  • Problems:
    • If you need a particular library, and you search and find it on github, it will sometimes happen that
      the repository with all its libraries and associated files may have a complicated directory structure,
      such that finding/copying your specific desired library is convoluted at best.
        I have struggled and hacked my way through installation of such libraries,
      mostly by first creating a folder in libraries with the name of the library I'm installing (per instructions above)
      and just copying what I hope are all the needed files into it.
          It happens, however, that often the desired library has a dependency or whatever
      and also requires an additional library that is located elsewhere.

    ------------------------------------------------------------

  • From: (link to:) Adafruit

    See these tips: (link to:) adafruit tips

.

.

.

eof

Powered by Drupal