helins.linux.gpio — io.helins/linux.gpio 2.0.0

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).

close clj

(close resource)

Closes a GPIO resource such as a device or a handle.

It may be easier to use the standard with-open macro.

default+ clj

Default values for argument options.

describe-chip clj

(describe-chip device)

Requests a description of the given GPIO device.

Returns a map containing :

:gpio/label (optional) Cf. Namespace description

:gpio/n-lines Number of available lines for that chip.

:gpio/name (optional) Cf. Namespace description.

describe-line clj

(describe-line device line-number)

Requests a description of the given line.

Returns a map which may contain :

:gpio/active-low? :gpio/consumer (optional) :gpio/direction Cf. Namespace description

:gpio/line-number Number of the line.

:gpio/name (optional) :gpio/open-drain? :gpio/open-source? Cf. Namespace description

:gpio/used? Is this line currently in use ?

device clj

(device device-path)

Opens a GPIO device either by specifying a full path or by giving the number of the device.

Those devices are located at '/dev/gpiochip$X' where $X is a number.

Read permission must be granted, which is enough even for writing to outputs.

Attention, closing a GPIO device does not close related handles and watchers.

handle clj

(handle device lines-number->line-option+)

(handle device line-number->line-option+ handle-option+)

Given a GPIO device, requests a handle for one or several lines which can then be used to read and/or write the state of lines.

Implements IHandle.

line-number->line-option+ is a map where keys are line numbers and values are maps which may contain :

:gpio/state :gpio/tag Cf. Namespace description

handle-option+ is an optional map which may contain :

:gpio/active-low? :gpio/consumer :gpio/direction :gpio/open-drain? :gpio/open-source? Cf. Namespace description

Ex. (handle some-device {17 {:gpio/tag :red-led} 27 {:gpio/tag :green-led :gpio/state true}} {:gpio/direction :output})

IBuffer clj protocol

Reading or writing the state of lines in a buffer before or after doing some IO.

Ex. (write some-handle (-> some-buffer (clear-line+) (set-line+ {:green-led true :red-led false})))

clear-line+ clj

(clear-line+ buffer)

Sets all lines of the given buffer to LOW (false).

get-line clj

(get-line buffer tag)

Retrieves the state of a single line from the given buffer.

get-line+ clj

(get-line+ buffer)

(get-line+ buffer tags)

Retrieves the state of several lines (or all of them if nothing is specified) from the given buffer.

Returns a map of tag -> state.

set-line clj

(set-line buffer tag state)

Sets the state of a single line in the given buffer.

set-line+ clj

(set-line+ buffer tag->state)

Sets the state of several lines in the given buffer.

toggle-line clj

(toggle-line buffer tag)

Toggles the state of a single line in the given buffer.

toggle-line+ clj

(toggle-line+ buffer)

(toggle-line+ buffer tags)

Toggles the state of several lines in the given buffer.

IBuffereable clj protocol

For objects that can work with a GPIO buffer.

buffer clj

(buffer this)

Produces a GPIO buffer representing the state of up to 64 lines.

It implements IBuffer and works with tags associated with this.

It does not do any IO on its own as it is meant to be used in conjunction with a handle or a watcher.

IHandle clj protocol

IO using a GPIO handle and a associated buffer.

Reading or writing the state of lines happens virtually at once for all of them. Whether it happens exactly at the same time depends on the underlying driver and this fact is opaque. In any case, driving several lines using a single handle is more efficient than using a handle for each line.

read clj

(read handle buffer)

Using a handle, reads the current state of lines into the given buffer.

write clj

(write handle buffer)

Using a handle, writes the current state of lines using the given buffer.

IWatcher clj protocol

IO using a watcher.

event clj

(event watcher)

(event watcher timeout-ms)

Using a watcher, efficiently blocks until the state of one of the monitored inputs switches to a relevant one or the timeout elapses.

A timeout of -1 will block forever until something happens.

poll clj

(poll watcher buffer tag)

Using a watcher, reads the current state of a line.

watcher clj

(watcher device line-number->watch-option+)

Given a GPIO device, produces a watcher which can then be used to efficiently monitor inputs for changes or poll their current values.

Implements IWatcher.

line-number->watch-option+ is a map where keys are line numbers and values are maps which may contain :

:gpio/active-low? :gpio/consumer :gpio/direction :gpio/open-drain? :gpio/open-source? :gpio/state :gpio/tag Cf. Namespace description

Ex. (watcher some-device {18 {:gpio/tag :left-button :gpio/direction :input} 23 {:gpio/tag :right-button :gpio/direction :output}})