The cl-gpio Reference Manual

This is the cl-gpio Reference Manual, version 1.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 08 17:01:52 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 cl-gpio

A library for the Linux GPIO kernel module as used on hobby kits such as the Raspberry Pi

Maintainer

Yukari Hafner <>

Author

Yukari Hafner <>

Home Page

https://Shinmera.github.io/cl-gpio/

Source Control

(GIT https://github.com/Shinmera/cl-gpio.git)

Bug Tracker

https://github.com/Shinmera/cl-gpio/issues

License

zlib

Version

1.1.0

Dependencies
  • documentation-utils (system).
  • cffi (system).
Source

cl-gpio.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 cl-gpio/cl-gpio.asd

Source

cl-gpio.asd.

Parent Component

cl-gpio (system).

ASDF Systems

cl-gpio.


3.1.2 cl-gpio/package.lisp

Source

cl-gpio.asd.

Parent Component

cl-gpio (system).

Packages

3.1.3 cl-gpio/low-level.lisp

Dependency

package.lisp (file).

Source

cl-gpio.asd.

Parent Component

cl-gpio (system).

Public Interface
Internals

3.1.4 cl-gpio/wrapper.lisp

Dependency

low-level.lisp (file).

Source

cl-gpio.asd.

Parent Component

cl-gpio (system).

Public Interface
Internals

3.1.5 cl-gpio/documentation.lisp

Dependency

wrapper.lisp (file).

Source

cl-gpio.asd.

Parent Component

cl-gpio (system).


4 Packages

Packages are listed by definition order.


4.1 cl-gpio

Source

package.lisp.

Nicknames
  • org.shirakumo.gpio
  • gpio
Use List

common-lisp.

Public Interface
Internals

4.2 cl-gpio-lli

Source

package.lisp.

Nickname

org.shirakumo.gpio.lli

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Special variables

Special Variable: *gpio-root*

The root directory of the GPIO system devices. Should be /sys/class/gpio/

Package

cl-gpio-lli.

Source

low-level.lisp.


5.1.2 Macros

Macro: with-pin-handler ((handler pin &optional edge active-low) &body body)

Shorthand to call a handler function on PIN value change during the evaluation of BODY.

See CALL-WITH-PIN-HANDLER

Package

cl-gpio.

Source

wrapper.lisp.


5.1.3 Compiler macros

Compiler Macro: value (pin)
Package

cl-gpio.

Source

wrapper.lisp.

Compiler Macro: (setf value) (pin)
Package

cl-gpio.

Source

wrapper.lisp.


5.1.4 Ordinary functions

Function: active-low (pin)

Accesses the pin’s I/O active-low.

If the pin does not yet exist or is not exported, it will be. The system GPIO’s value is not adjusted if the cached value is already the same as the value attempted to be set with this.

See ENSURE-PIN
See CL-GPIO-LLI:ACTIVE-LOW
See PIN-ACTIVE-LOW

Package

cl-gpio.

Source

wrapper.lisp.

Function: (setf active-low) (pin)
Package

cl-gpio.

Source

wrapper.lisp.

Function: active-low (pin)

Accessor to whether the GPIO pin has an active low.

The value should be either NIL or T.

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: (setf active-low) (pin)
Package

cl-gpio-lli.

Source

low-level.lisp.

Function: all-pins ()

Returns a list of PIN instances for all pins on the system.

See CL-GPIO-LLI:AVAILABLE-PINS
See ENSURE-PIN

Package

cl-gpio.

Source

wrapper.lisp.

Function: available-pins ()

Return a list of all available GPIO pins on the system.

Note that the pins are not necessarily accessible; they may need to be exported first.

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: await-value (pin &optional timeout)

Wait until the pin has a value that we can read.

If TIMEOUT is specified and reached before a value becomes accessible, NIL is returned. Otherwise, true is returned.

This function is available on the following implementations: * SBCL

See ENSURE-PIN

Package

cl-gpio.

Source

wrapper.lisp.

Function: base (chip)

Return the GPIO chip’s base pin number.

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: call-with-pin-handler (function handler pin &optional edge active-low)

Make the HANDLER function be called if the PIN changes value during the evaluation of FUNCTION.

The HANDLER is called with the corresponding PIN instance
and the new value as arguments.

This function is available on the following implementations:
* SBCL

See ENSURE-PIN
See EDGE
See ACTIVE-LOW

Package

cl-gpio.

Source

wrapper.lisp.

Function: chip (pin)

Returns the pin’s chip device name.

See PIN-CHIP

Package

cl-gpio.

Source

wrapper.lisp.

Function: chip-file (chip sub)

Returns a file for the specified GPIO chip.

See GPIO-FILE

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: chip-pins (chip)

Return a list of GPIO pin numbers on the chip.

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: chips ()

Returns a list of known GPIO chips.

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: direction (pin)

Accesses the pin’s I/O direction.

If the pin does not yet exist or is not exported, it will be. The system GPIO’s value is not adjusted if the cached value is already the same as the value attempted to be set with this.

See ENSURE-PIN
See CL-GPIO-LLI:DIRECTION
See PIN-DIRECTION

Package

cl-gpio.

Source

wrapper.lisp.

Function: (setf direction) (pin)
Package

cl-gpio.

Source

wrapper.lisp.

Function: direction (pin)

Accessor to the GPIO pin’s direction.

The value should be either :IN or :OUT.

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: (setf direction) (pin)
Package

cl-gpio-lli.

Source

low-level.lisp.

Function: edge (pin)

Accesses the pin’s I/O edge.

If the pin does not yet exist or is not exported, it will be. The system GPIO’s value is not adjusted if the cached value is already the same as the value attempted to be set with this.

See ENSURE-PIN
See CL-GPIO-LLI:EDGE
See PIN-EDGE

Package

cl-gpio.

Source

wrapper.lisp.

Function: (setf edge) (pin)
Package

cl-gpio.

Source

wrapper.lisp.

Function: edge (pin)

Accessor to the GPIO pin’s interrupt edge.

The value should be one of :NONE :RISING :FALLING :BOTH

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: (setf edge) (pin)
Package

cl-gpio-lli.

Source

low-level.lisp.

Function: ensure-pin (pin &optional refresh)

Ensure to get a PIN instance in return.

Accepts either a pin’s name/id number or a pin instance. If REFRESH is true, a fresh PIN instance is returned that has its values taken from the system’s GPIO values.

See *PIN-CACHE*
See MAKE-PIN
See PIN

Package

cl-gpio.

Source

wrapper.lisp.

Function: export (&rest pins)

Export the specified pins and return a list of according PIN instances.

See ENSURE-PIN
See CL-GPIO-LLI:EXPORT-PIN

Package

cl-gpio.

Source

wrapper.lisp.

Function: export-pin (&rest pins)

Export the specified pins so that they may be accessed from userspace.

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: exported-pins ()

Returns a list of GPIO pins that are accessible.

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: gpio-file (sub)

Returns an absolute path to the requested gpio file.

See *GPIO-ROOT*

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: label (chip)

Return the GPIO chip’s label.

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: name (pin)

Returns the pin’s name or ID.

See PIN-NAME

Package

cl-gpio.

Source

wrapper.lisp.

Function: ngpio (chip)

Return the number of GPIO pins on the chip.

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: pin-file (pin sub)

Returns a file for the specified GPIO pin.

See GPIO-FILE

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: pins ()

Returns a list of available/exported PIN instances.

See CL-GPIO-LLI:EXPORTED-PINS
See ENSURE-PIN

Package

cl-gpio.

Source

wrapper.lisp.

Function: unexport (&rest pins)

Unexport the specified pins and invalidate their cache.

See *PIN-CACHE*
See CL-GPIO-LLI:UNEXPORT-PIN

Package

cl-gpio.

Source

wrapper.lisp.

Function: unexport-pin (&rest pins)

Unexport the specified pins so that they can no longer be accessed from userspace.

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: value (pin)

Accesses the pin’s I/O value.

If the pin does not yet exist or is not exported, it will be. The pin’s I/O direction is automatically adjusted if necessary depending on whether the value is read or set by setf.
The value returned by this is never cached.

See ENSURE-PIN
See CL-GPIO-LLI:VALUE

Package

cl-gpio.

Source

wrapper.lisp.

Function: (setf value) (pin)
Package

cl-gpio.

Source

wrapper.lisp.

Function: value (pin)

Accessor to the GPIO pin’s value.

When reading, the pin’s direction should be :IN When setting, the pin’s direction should be :OUT

The value should be either NIL or T.

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: (setf value) (pin)
Package

cl-gpio-lli.

Source

low-level.lisp.


5.1.5 Standalone methods

Method: print-object ((pin pin) stream)
Source

wrapper.lisp.


5.1.6 Structures

Structure: pin

Representative type to encapsulate a GPIO pin.

This will cache current pin properties. Note that it will not be updated automatically should changes to the pin occur from elsewhere in the system. Only updates done through this high-level interface will be tracked.

See MAKE-PIN
See ENSURE-PIN
See NAME
See CHIP
See DIRECTION
See EDGE
See ACTIVE-LOW
See VALUE

Package

cl-gpio.

Source

wrapper.lisp.

Direct superclasses

structure-object.

Direct methods

print-object.

Direct slots
Slot: name
Type

integer

Initform

-1

Readers

pin-name.

Writers

This slot is read-only.

Slot: chip
Type

string

Initform

""

Readers

pin-chip.

Writers

This slot is read-only.

Slot: direction
Type

(member :in :out)

Initform

:in

Readers

pin-direction.

Writers

(setf pin-direction).

Slot: edge
Type

(member :none :rising :falling :both)

Initform

:none

Readers

pin-edge.

Writers

(setf pin-edge).

Slot: active-low
Type

boolean

Readers

pin-active-low.

Writers

(setf pin-active-low).


5.2 Internals


5.2.1 Special variables

Special Variable: *pin-cache*

Hash table to store cached PIN instances.

See PIN
See ENSURE-PIN

Package

cl-gpio.

Source

wrapper.lisp.


5.2.2 Macros

Macro: define-pin-accessor (name file &rest values)

Wrapper to define an accessor function for a GPIO pin property.

Package

cl-gpio-lli.

Source

low-level.lisp.


5.2.3 Compiler macros

Compiler Macro: write-to-file (string file)
Package

cl-gpio-lli.

Source

low-level.lisp.


5.2.4 Ordinary functions

Function: %make-pin (&key name chip direction edge active-low)

Direct constructor to make a PIN instance.

See PIN
See MAKE-PIN

Package

cl-gpio.

Source

wrapper.lisp.

Function: %write-to-file (sequence length file)
Package

cl-gpio-lli.

Source

low-level.lisp.

Function: cclose (stream)
Package

cl-gpio-lli.

Source

low-level.lisp.

Function: copen (filename mode)
Package

cl-gpio-lli.

Source

low-level.lisp.

Function: copy-pin (instance)
Package

cl-gpio.

Source

wrapper.lisp.

Function: cread (stream buffer length)
Package

cl-gpio-lli.

Source

low-level.lisp.

Function: cwrite (stream buffer length)
Package

cl-gpio-lli.

Source

low-level.lisp.

Function: directory-name (pathname)

Returns the name of the topmost directory, if any.

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: getc (stream)
Package

cl-gpio-lli.

Source

low-level.lisp.

Function: make-pin (pin)

Construct a new PIN instance.

If the pin has not been exported yet, it will be. If the pin does not exist, an error is signalled. The GPIO pin’s current properties are read out and stored into the respective slots of the pin instance.

See CL-GPIO-LLI:LABEL
See CL-GPIO-LLI:DIRECTION
See CL-GPIO-LLI:EDGE
See CL-GPIO-LLI:ACTIVE-LOW

Package

cl-gpio.

Source

wrapper.lisp.

Reader: pin-active-low (instance)

Direct accessor to the pin’s active-low.

Value must be a boolean.

See PIN
See ACTIVE-LOW

Package

cl-gpio.

Source

wrapper.lisp.

Target Slot

active-low.

Writer: (setf pin-active-low) (instance)
Package

cl-gpio.

Source

wrapper.lisp.

Target Slot

active-low.

Reader: pin-chip (instance)

Direct reader for the pin’s chip (or its label).

Value must be a string.

See PIN
See CHIP

Package

cl-gpio.

Source

wrapper.lisp.

Target Slot

chip.

Reader: pin-direction (instance)

Direct accessor to the pin’s I/O direction.

Value must be one of :IN :OUT

See PIN
See DIRECTION

Package

cl-gpio.

Source

wrapper.lisp.

Target Slot

direction.

Writer: (setf pin-direction) (instance)
Package

cl-gpio.

Source

wrapper.lisp.

Target Slot

direction.

Reader: pin-edge (instance)

Direct accessor to the pin’s edge.

Value must be one of :NONE :RISING :FALLING :BOTH

See PIN
See EDGE

Package

cl-gpio.

Source

wrapper.lisp.

Target Slot

edge.

Writer: (setf pin-edge) (instance)
Package

cl-gpio.

Source

wrapper.lisp.

Target Slot

edge.

Reader: pin-name (instance)

Direct reader for the pin’s ID or name.

Value must be an integer.

See PIN
See NAME

Package

cl-gpio.

Source

wrapper.lisp.

Target Slot

name.

Function: pin-p (object)
Package

cl-gpio.

Source

wrapper.lisp.

Function: pin-value (pin)
Package

cl-gpio.

Source

wrapper.lisp.

Function: (setf pin-value) (pin)
Package

cl-gpio.

Source

wrapper.lisp.

Function: read-byte-from-file (file)
Package

cl-gpio-lli.

Source

low-level.lisp.

Function: read-from-file (file)

Read the file into a string, trimmed from whitespace.

Package

cl-gpio-lli.

Source

low-level.lisp.

Function: write-to-file (string file)

Write the sequence to the specified file.

Package

cl-gpio-lli.

Source

low-level.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %   (  
A   B   C   D   E   F   G   L   M   N   P   R   U   V   W  
Index Entry  Section

%
%make-pin: Private ordinary functions
%write-to-file: Private ordinary functions

(
(setf active-low): Public ordinary functions
(setf active-low): Public ordinary functions
(setf direction): Public ordinary functions
(setf direction): Public ordinary functions
(setf edge): Public ordinary functions
(setf edge): Public ordinary functions
(setf pin-active-low): Private ordinary functions
(setf pin-direction): Private ordinary functions
(setf pin-edge): Private ordinary functions
(setf pin-value): Private ordinary functions
(setf value): Public compiler macros
(setf value): Public ordinary functions
(setf value): Public ordinary functions

A
active-low: Public ordinary functions
active-low: Public ordinary functions
all-pins: Public ordinary functions
available-pins: Public ordinary functions
await-value: Public ordinary functions

B
base: Public ordinary functions

C
call-with-pin-handler: Public ordinary functions
cclose: Private ordinary functions
chip: Public ordinary functions
chip-file: Public ordinary functions
chip-pins: Public ordinary functions
chips: Public ordinary functions
Compiler Macro, (setf value): Public compiler macros
Compiler Macro, value: Public compiler macros
Compiler Macro, write-to-file: Private compiler macros
copen: Private ordinary functions
copy-pin: Private ordinary functions
cread: Private ordinary functions
cwrite: Private ordinary functions

D
define-pin-accessor: Private macros
direction: Public ordinary functions
direction: Public ordinary functions
directory-name: Private ordinary functions

E
edge: Public ordinary functions
edge: Public ordinary functions
ensure-pin: Public ordinary functions
export: Public ordinary functions
export-pin: Public ordinary functions
exported-pins: Public ordinary functions

F
Function, %make-pin: Private ordinary functions
Function, %write-to-file: Private ordinary functions
Function, (setf active-low): Public ordinary functions
Function, (setf active-low): Public ordinary functions
Function, (setf direction): Public ordinary functions
Function, (setf direction): Public ordinary functions
Function, (setf edge): Public ordinary functions
Function, (setf edge): Public ordinary functions
Function, (setf pin-active-low): Private ordinary functions
Function, (setf pin-direction): Private ordinary functions
Function, (setf pin-edge): Private ordinary functions
Function, (setf pin-value): Private ordinary functions
Function, (setf value): Public ordinary functions
Function, (setf value): Public ordinary functions
Function, active-low: Public ordinary functions
Function, active-low: Public ordinary functions
Function, all-pins: Public ordinary functions
Function, available-pins: Public ordinary functions
Function, await-value: Public ordinary functions
Function, base: Public ordinary functions
Function, call-with-pin-handler: Public ordinary functions
Function, cclose: Private ordinary functions
Function, chip: Public ordinary functions
Function, chip-file: Public ordinary functions
Function, chip-pins: Public ordinary functions
Function, chips: Public ordinary functions
Function, copen: Private ordinary functions
Function, copy-pin: Private ordinary functions
Function, cread: Private ordinary functions
Function, cwrite: Private ordinary functions
Function, direction: Public ordinary functions
Function, direction: Public ordinary functions
Function, directory-name: Private ordinary functions
Function, edge: Public ordinary functions
Function, edge: Public ordinary functions
Function, ensure-pin: Public ordinary functions
Function, export: Public ordinary functions
Function, export-pin: Public ordinary functions
Function, exported-pins: Public ordinary functions
Function, getc: Private ordinary functions
Function, gpio-file: Public ordinary functions
Function, label: Public ordinary functions
Function, make-pin: Private ordinary functions
Function, name: Public ordinary functions
Function, ngpio: Public ordinary functions
Function, pin-active-low: Private ordinary functions
Function, pin-chip: Private ordinary functions
Function, pin-direction: Private ordinary functions
Function, pin-edge: Private ordinary functions
Function, pin-file: Public ordinary functions
Function, pin-name: Private ordinary functions
Function, pin-p: Private ordinary functions
Function, pin-value: Private ordinary functions
Function, pins: Public ordinary functions
Function, read-byte-from-file: Private ordinary functions
Function, read-from-file: Private ordinary functions
Function, unexport: Public ordinary functions
Function, unexport-pin: Public ordinary functions
Function, value: Public ordinary functions
Function, value: Public ordinary functions
Function, write-to-file: Private ordinary functions

G
getc: Private ordinary functions
gpio-file: Public ordinary functions

L
label: Public ordinary functions

M
Macro, define-pin-accessor: Private macros
Macro, with-pin-handler: Public macros
make-pin: Private ordinary functions
Method, print-object: Public standalone methods

N
name: Public ordinary functions
ngpio: Public ordinary functions

P
pin-active-low: Private ordinary functions
pin-chip: Private ordinary functions
pin-direction: Private ordinary functions
pin-edge: Private ordinary functions
pin-file: Public ordinary functions
pin-name: Private ordinary functions
pin-p: Private ordinary functions
pin-value: Private ordinary functions
pins: Public ordinary functions
print-object: Public standalone methods

R
read-byte-from-file: Private ordinary functions
read-from-file: Private ordinary functions

U
unexport: Public ordinary functions
unexport-pin: Public ordinary functions

V
value: Public compiler macros
value: Public ordinary functions
value: Public ordinary functions

W
with-pin-handler: Public macros
write-to-file: Private compiler macros
write-to-file: Private ordinary functions