NOTE: This gem is the underpinning for Arli — command line Arduino Library manager.
This library offers a ruby model representing an Arduino Library, including field validation, reading and writing the
library.properties file, or searching for libraries in the official database.
Searching for a library will transparently download and cache the Arduino-maintained JSON database of official libraries locally, so that future searches are fast.
The library also provides validation functionality for the
library.properties file for your custom libraries you would like to open source.
Add this line to your application's Gemfile:
And then execute:
Or install it yourself as:
$ gem install arduino-library
Current version only contains Ruby-based API and is meant to be consumed by other projects (in particularly, check out Arli — a command-line tool and an Arduino Library Manager and installer). This project is invaluable if you are you using, for example, arduino-cmake project to build and upload your Arduino Code.
Please take a look at the following screencast:
The gem database can be configured to download the default database from a custom URL, and to cache it in a local file. Next time the lookup is invoked local file is checked first. Library automatically checks the size of the remote index file, and re-downloads it if the file has changed.
You can modify the source of the default database and the local cache location using one of two methods:
- By settin the environment variables before invoking the gem;
- Or by configuring the
Setting Environment Variables
ARDUINO_CUSTOM_LIBRARY_PATHcan be used to change local top-level path to the libraries folder.
ARDUINO_LIBRARY_INDEX_PATHcan be used to change the location of the cached index file.
Change Class Variables for
The following class variables can be changed, like so:
::::. = ''
library_index_url— URL to download compressed JSON index.
library_index_path— local path to the cached compressed JSON index.
library_path— local top-level folder where your Arduino libraries are.
If you change any of the above, please reload the database with:
Please review the
library.rb file to understand how these variables are resolved.
Finding and Resolving Arduino Libraries
The primary module
Arduino::Library provides a convenient Facáde into all of the library functionality. Therefore you can use the library by calling these methods directly, such as
Arduino::Library.library_from(..) or by including the module in your current context.
Below we'll include the top level module, and use the shortcut methods to explore available functionality. That said, if you prefer not to include the top level module, you can call the same functions directly on the module itself.
There are two ways to include the DSL in your context:
require 'arduino/library' class Foo include :: end
Or, perhaps even easier:
class Foo require 'arduino/library/include' end
This method returns an instance of the
Arduino::Library::Database from the provided source:
db_from('library_index.json').size # => 16 db_from('library_index.json.gz').size # => 16 db_from('http://downloads.arduino.cc/libraries/library_index.json.gz').size # => 3653 # This required downloading a 400K gzipped file into a temp file, and reading from there.
This method downloads and returns the official Arduino-maintained index of Arduino libraries.
db_default.size # => 3653
This method reads from a source that can be of many formats (see below) and returns an instantiated
Arduino::Library::Model for this library. You can then get all library attributes via corresponding methods:
library_from('spec/fixtures/audio_zero.json').name # => 'AudioZero' library_from('~/Documents/Arduino/Libraries/AudioZero/library.properties').name #=> 'AudioZero' library_from('https://raw.githubusercontent.com/PaulStoffregen/DS1307RTC/master/library.properties').name #=> 'DS1307RTC'
In the next section you will read about the search, but the truth is that the
library_from method actualy will fall back to search if you provide a partial hash. The allowed values in the hash are:
name, checksum, archiveFileName. Since these keys often uniquely identify a library, the gem attempts to find it for you.
require 'arduino/library/include' #=> true library_from(name: 'AudioZero') => #<Arduino::Library::Model name="AudioZero" version="1.1.1" author="Arduino" maintainer="Arduino <[email protected]>" ..........> library_from(checksum: 'SHA-256:4604a3b92b9f4a7dd92534eb09247443fa5078e6bd0e7a2c5f3060eaba2ad974') => #<Arduino::Library::Model name="AudioZero" version="1.1.1" author="Arduino" maintainer="Arduino <[email protected]>" ..........>
search is, perhaps, some of the most powerful functionality in this gem. It allows constructing very flexible and precise queries, to match any number of library attributes.
The method has the following signature:
search(database = db_default, **opts)
opts is a Hash that you can use to pass attributes with matchers. All matching results are returned as an array of models.
Here is searching for 'AudioZero' and sorting results by the version number:
search(name: 'AudioZero').sort.first.version #=> "1.0.0" search(name: 'AudioZero').sort.last.version #=> "1.1.1"
You can search by any attribute, not just name and number:
results = search( # direct string equality name: 'AudioZero', # regexp matching is fully supported author: /konstantin/i, # array is matched if it's a subset or equality, or if library has '*' architectures: [ 'avr' ], # or a proc for max flexibility version: proc do |value| value.start_with?('1.') end ) results.size #=> <whatever number of matches returned>
Note that multiple attributes must ALL match for the library to be included in the result set.
The Facade is the recommended way to use library. Below we briefly describe the low-level API of the underlying classes.
Downloading the index of all libraries, and searching for a library.
You can load libraries from a local JSON file, or from a remote URL, eg:
require 'arduino/library' database = ::::.from( 'http://downloads.arduino.cc/libraries/library_index.json.gz')
or, since the above link happens to be the default location of Arduino-maintained librarie index file, you can use the
default method instead:
database = ::::.
or, load the list from a local JSON file, that can be optionally gzipped (just like the URL):
database = ::::.from('library_index.json.gz')
Once the library is initialized, the following operations are supported:
database.search(name: 'AudioZero', version: '1.0.1') do |audio_zero| audio_zero.website #=> http://arduino.cc/en/Reference/Audio audio_zero.architectures #=> [ 'samd' ] end
You can pass any of the attributes to #search, and the value can be a
String (in which case only equality matches), or a regular expression, eg:
database.search(author: 'Paul Stoffregen').size #=> 21 database.search(author: /stoffregen/i).size #=> 33
You interate over multiple using either a block:
database.search(name: 'AudioZero') do |match| puts match.name # => 'AudioZero' puts match.version # => will print all versions of the library available end
or, just grab the return value from
#search, which is always an array.
all_versions = database.search(name: 'AudioZero') # => [ Arduino::Library::Model<name: AudioZero, version: '1.0.1',... >, .. ]
Use this class to operate on a single library.
Reading Library from an External Source using
You can use an intelligent class method
.from that attempts to auto-detect the type of file or URL you are passing as an argument, and use an appropriate parser for each type.
For example, to read from a JSON file:
json_file = 'spec/fixtures/audio_zero.json' model = ::::.(json_file) model.name #=> 'AudioZero'
Or to read from the
properties_file = 'spec/fixtures/audio_zero.properties' model = ::::.(properties_file) model.name #=> 'AudioZero'
Presenters are there to convert to and from a particular format.
props = ::::::.(model). File.open('/tmp/audio_zero.properties', 'w') do |f| f.write(props) end # this creates a file in the format: # name=AudioZero # version=1.0.1 # etc.
After checking out the repo, run
bin/setup to install dependencies. Then, run
rake spec to run the tests. You can also run
bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run
bundle exec rake install. To release a new version, update the version number in
version.rb, and then run
bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the
.gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/kigster/arduino-library.
The gem is available as open source under the terms of the MIT License.