- Request some information about the GPIO device or a specific GPIO line.
- Request a handle for driving one or several lines at once.
- Request a watcher for efficiently monitoring one or several lines.

This namespace provides utilities for handling a GPIO device. Compatible with Linux 4.8 and higher.

Access to a GPIO device can be obtained by using the `device` function. Three things can then be accomplished 

    - Request some information about the GPIO device or a specific GPIO line.
    - Request a handle for driving one or several lines at once.
    - Request a watcher for efficiently monitoring one or several lines.

A handle controls all the lines it is responsible for at once. Whether those lines are actually driven exactly at
the same time, atomically, depends on the underlying driver and is opaque to this library. Once a handle is created
with the `handle` function on the appropriate GPIO device, one or several dedicated buffers can be created with the
`buffer` function. The purpose of a buffer is to represent and/or manipulate the state of the lines controlled by a
handle (up to 64). The state of a line can either be HIGH (true) or LOW (false).

A watcher is used essentially for interrupts. Requested events, such as a line transitioning from LOW to HIGH, are
queued by the kernel until read. However, Linux not being a real-time OS, such "interrupts" are imperfect and should
not be used for critical tasks where a simple microcontroller will be of a better fit.

Lines are abstracted by associating a line number with a tag (ie. any value meant to be more representative of what the
line does, often a keyword).

As usual, all IO functions might throw if anything goes wrong and do not forget to use `close` or the "with-open idiom"
on all acquired IO resources. Closing a GPIO device do not close related handles and watchers.


Here is a description of the keywords typically used throughout this library :

 :gpio/active-low?
   Lines are typically active-high, meaning they become active when HIGH (true) and inactive when LOW (false). Active-low
   lines reverse this logical flow. They become active when LOW and inactive when HIGH.

 :gpio/consumer
   An arbitrary string can be supplied when creating a handle. If a line is in use and associated with a consumer, it will
   show up when querying its state using `describe-line`. It allows for tracking who is using what.

 :gpio/direction
   A line can either be used as :input or :output, never both at the same time. All lines associated
   with a handle must be of the same direction.

 :gpio/label
   The operating system might associate a GPIO device and individual lines with string labels.

 :gpio/line-number
   A single GPIO device can represent at most 64 lines. Hence, a line number is between 0 and 63 inclusive.

 :gpio/name
   The operating system might associate a GPIO device and individual lines with string names.

 :gpio/open-drain?
   Lines can act as open drains (ie. can only be driven to LOW).

 :gpio/open-source?
   Lines can be open sources (ie. can only be driven to HIGH).

 :gpio/state
   The state of a line can either be logical HIGH (true) or logical LOW (false).

 :gpio/tag
   Instead of using raw line numbers which don't really mean anything, they can be associated with any value such
   as a string or a keyword. Besides being more descriptive, the program remains valid when the user dedices to use
   different lines while creating a handle (as long as tags remain the same).