The cl-piglow Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-piglow Reference Manual

This is the cl-piglow Reference Manual, version 0.0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 10:28:06 2020 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

cl-piglow, the PiGlow library for Common Lisp

What is this?

The PiGlow is a nice little £10 PCB for the Raspberry Pi with 18 coloured LEDs on it, which can be individually controlled via software -- and that's where cl-piglow comes in! This library lets you send commands to your PiGlow from the glorious Common Lisp programming language, using a relatively simple API.

The library works somewhat like the official Python library, so, if you've used that one before, this one should be pretty easy to pick up!

How to use

Compatibility note

This implementation only works with Clozure Common Lisp (CCL) and Steel Bank Common Lisp (SBCL). It was developed on CCL (and hasn't actually been tested with SBCL yet, but it should work!).

We recommend CCL -- also because, if you're going to run this on your Pi, CCL supports threading, whereas SBCL doesn't yet.

Installation instructions

  1. Download the library, and put it somewhere ASDF can find it. (For example, git clone-ing the repo into ~/common-lisp/ should do the trick.)
  2. Install the dependency osicat. (If Quicklisp is installed, running (ql:quickload :cl-piglow) in your Lisp REPL should do this, and load the library as well!)
  3. If you didn't do it with Quicklisp above, run (asdf:load-system :cl-piglow) and watch the compiler output scroll by.
  4. Next, you'll need to get the PiGlow I2C device working correctly. This varies from system to system -- if you've already figured this out, jump to step X. What follows is what I did for my Raspberry Pi Zero, running Arch Linux ARM.
  5. Ensure the line dtparam=i2c_arm=on is present in /boot/config.txt, and reboot if necessary.
  6. Check in /dev/ for some device called /dev/i2c-1 (or /dev/i2c-0 on older Pis). If you've got something there, great! (If not, I can't help you, sorry! Google is your friend...)
  7. Make sure that device file is writable by the user you're currently logged in as. On my system, this entailed putting SUBSYSTEM=="i2c-dev", MODE="0777" in /etc/udev/rules.d/99-i2c.rules, and rebooting.
  8. Run $ i2cdetect -y -q 1. You should see 54 somewhere in the output. (If not, something's wrong, or you need to substitute 1 for 0. Again, Google is your friend...)
  9. Go on to the instructions below about using the library!

Tip: Running the 'easy installer' for the official Python library might help with making sure the I2C device is set up correctly, if you're on Raspbian. However, I haven't tried it myself!

Basic usage

Set up the library with OPEN-PIGLOW (specifying the number of your I2C device, if it isn't 1, as the first argument):

CL-USER> (piglow:open-piglow)
#<BASIC-BINARY-IO-STREAM ISO-8859-1 (CHARACTER-SPECIAL/9) #x15237676>
CL-USER> (piglow:open-piglow 0) ; for older Raspberry Pi revisions only

Then, use the commands piglow-set-colour COLOUR VALUE, piglow-set-leg LEG VALUE, and piglow-set-led LED VALUE to make the lights turn off and on.

Available colours are :red, :orange, :yellow, :green, :blue, :white, and :all. LEDs are numbered according to this chart.

NB: You need to call piglow-show after issuing any commands if you want the lights to actually change (which enables you to draw a pattern and then show it without any flickering as the pattern is drawn). If you don't like this behaviour, set the value of *piglow-show-automatically* to T, and it'll be called automatically.

Example session:

CL-USER> (piglow:piglow-set-colour :green 10) ; turn the green ring on
                                              ; with brightness 10
NIL
CL-USER> (piglow:piglow-show)                 ; make changes visible
NIL
CL-USER> (setf piglow:*piglow-show-automatically* t) ; automatically make changes visible from now on
T
CL-USER> (piglow:piglow-set-colour :red 10)   ; turn the red ring on
NIL
CL-USER> (piglow:piglow-set-leg 1 10)         ; turn the second (rightmost) leg on
NIL
CL-USER> (piglow:piglow-set-led 7 255)        ; turn LED 7 (the rightmost red LED) on
NIL
CL-USER> (piglow:piglow-set-colour :all 0)    ; turn everything off
NIL

Demo functions

There are currently two pretty demos that make your PiGlow light up in various ways to demonstrate the library's functionality. These are:

Feel free to try them out! (The maximum brightness is adjustable as the piglow:*demo-max-brightness* value, if you want to tone it down a bit.)

Documentation

Is currently in the form of docstrings. Use the Source, Luke! (Seriously, I've actually written some somewhat coherent docstrings. Docstrings are good.)

License

MIT


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 cl-piglow

Author

eta <https://theta.eu.org>

License

MIT

Description

A Pimoroni PiGlow library for Common Lisp

Version

0.0.1

Dependency

osicat

Source

cl-piglow.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-piglow.asd

Location

cl-piglow.asd

Systems

cl-piglow (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-piglow/packages.lisp

Parent

cl-piglow (system)

Location

packages.lisp

Packages

cl-piglow


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 cl-piglow/piglow.lisp

Dependency

packages.lisp (file)

Parent

cl-piglow (system)

Location

piglow.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 cl-piglow/demos.lisp

Dependency

piglow.lisp (file)

Parent

cl-piglow (system)

Location

demos.lisp

Exported Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-piglow

Source

packages.lisp (file)

Nickname

piglow

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *demo-max-brightness*

Maximum brightness to be used in demos (to avoid burning your eyes out).

Package

cl-piglow

Source

demos.lisp (file)

Special Variable: *piglow*

Global variable to store the PiGlow I2C stream in.

Package

cl-piglow

Source

piglow.lisp (file)

Special Variable: *piglow-show-automatically*

Controls whether PIGLOW-SHOW is automatically called at the end of any PiGlow operation, immediately making the results of that operation visible. If T, PIGLOW-SHOW will be called automatically.
If NIL, PIGLOW-SHOW must be called in order for the results of PiGlow operations to become visible.

Package

cl-piglow

Source

piglow.lisp (file)

Special Variable: +i2c-slave+

ioctl() argument I2C_SLAVE

Package

cl-piglow

Source

piglow.lisp (file)

Special Variable: +led-addresses+

Vector of SN3218 LED addresses for LEDs on the PiGlow.

Package

cl-piglow

Source

piglow.lisp (file)

Special Variable: +led-colour-names+

Vector of LED colour names, from the outmost to the inmost ring.

Package

cl-piglow

Source

piglow.lisp (file)

Special Variable: +led-colours+

Association list mapping colour names to indices of the +LED-ADDRESSES+ array.

Package

cl-piglow

Source

piglow.lisp (file)

Special Variable: +piglow-address+

I2C address of a typical PiGlow.

Package

cl-piglow

Source

piglow.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: demo-circular-colours ()

Like DEMO-CYCLE-COLOURS, but fades each LED in a coloured ring individually as well.

Package

cl-piglow

Source

demos.lisp (file)

Function: demo-cycle-colours ()

Fades colours up and down, starting from red and ending with white.

Package

cl-piglow

Source

demos.lisp (file)

Function: demo-fade-each-led ()

Fades each LED up and down in turn.

Package

cl-piglow

Source

demos.lisp (file)

Function: i2cize-stream ST I2C-ADDRESS

Configure the stream ST to support I2C commands addressed to I2C-ADDRESS.

Package

cl-piglow

Source

piglow.lisp (file)

Function: open-i2c-device DEVID I2C-ADDRESS

Open the I2C device /dev/i2c-DEVID, returning a stream supporting I2C commands addressed to I2C-ADDRESS.

Package

cl-piglow

Source

piglow.lisp (file)

Function: open-piglow &optional DEVID ADDRESS UPDATE-GLOBAL-VARIABLE

Open a connection to the PiGlow represented by I2C device /dev/i2c-DEVID, returning a stream used to write commands to it. If UPDATE-GLOBAL-VARIABLE is T, updates the value of *PIGLOW* with the new stream.

Package

cl-piglow

Source

piglow.lisp (file)

Function: piglow-reset &optional STREAM

Reset all the LEDs on the PiGlow by reinitalizing the device.
WARNING: Has immediate effect, regardless of the value of ‘*PIGLOW-SHOW-AUTOMATICALLY*’. If you just want to turn everything off, try ‘(piglow-set-colour STREAM :all 0)’

Package

cl-piglow

Source

piglow.lisp (file)

Function: piglow-set-colour COLOUR VALUE &optional STREAM

Sets all LEDS of colour COLOUR (a key of the alist +LED-COLOURS+) to VALUE (0-255) on the PiGlow. Signals an error if the colour supplied doesn’t exist.

Package

cl-piglow

Source

piglow.lisp (file)

Function: piglow-set-led LED VALUE &optional STREAM

Sets LED (an index into +LED-ADDRESSES+) to VALUE (0-255) on the PiGlow. Signals an error if the LED supplied doesn’t exist.

Package

cl-piglow

Source

piglow.lisp (file)

Function: piglow-set-leg LEG VALUE &optional STREAM

Sets all LEDS on leg LEG (an integer from 0 to 2) to VALUE (0-255) on the PiGlow. Signals an error if the value of LEG is invalid.

Package

cl-piglow

Source

piglow.lisp (file)

Function: piglow-show &optional STREAM

Make the PiGlow do what you just told it to; i.e. execute any pending commands.
See also: the *PIGLOW-SHOW-AUTOMATICALLY* variable, which controls whether this function gets called for you.

Package

cl-piglow

Source

piglow.lisp (file)

Function: write-i2c-octet DEVICE REGISTER VALUE

Write the value VALUE to the I2C register REGISTER, using DEVICE.

Package

cl-piglow

Source

piglow.lisp (file)

Function: write-i2c-octets DEVICE ALIST

Write each (register, value) pair in ALIST to I2C device DEVICE.

Package

cl-piglow

Source

piglow.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: +enable-leds-1+
Package

cl-piglow

Source

piglow.lisp (file)

Special Variable: +enable-leds-2+
Package

cl-piglow

Source

piglow.lisp (file)

Special Variable: +enable-leds-3+
Package

cl-piglow

Source

piglow.lisp (file)

Special Variable: +enable-output+
Package

cl-piglow

Source

piglow.lisp (file)

Special Variable: +piglow-reset-sequence+

Sequence of I2C commands used to reset the PiGlow.

Package

cl-piglow

Source

piglow.lisp (file)

Special Variable: +reset+
Package

cl-piglow

Source

piglow.lisp (file)

Special Variable: +update+
Package

cl-piglow

Source

piglow.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: close-piglow &optional STREAM

Close the connection to the PiGlow specified by STREAM.

Package

cl-piglow

Source

piglow.lisp (file)

Function: piglow-maybe-show-automatically &optional STREAM
Package

cl-piglow

Source

piglow.lisp (file)

Function: stream-fd STRM

Get the underlying file descriptor for the stream STRM. XXX: This only works on SBCL and CCL for now (!)

Package

cl-piglow

Source

piglow.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-piglow.asd: The cl-piglow․asd file
cl-piglow/demos.lisp: The cl-piglow/demos․lisp file
cl-piglow/packages.lisp: The cl-piglow/packages․lisp file
cl-piglow/piglow.lisp: The cl-piglow/piglow․lisp file

F
File, Lisp, cl-piglow.asd: The cl-piglow․asd file
File, Lisp, cl-piglow/demos.lisp: The cl-piglow/demos․lisp file
File, Lisp, cl-piglow/packages.lisp: The cl-piglow/packages․lisp file
File, Lisp, cl-piglow/piglow.lisp: The cl-piglow/piglow․lisp file

L
Lisp File, cl-piglow.asd: The cl-piglow․asd file
Lisp File, cl-piglow/demos.lisp: The cl-piglow/demos․lisp file
Lisp File, cl-piglow/packages.lisp: The cl-piglow/packages․lisp file
Lisp File, cl-piglow/piglow.lisp: The cl-piglow/piglow․lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   C   D   F   I   O   P   S   W  
Index Entry  Section

C
close-piglow: Internal functions

D
demo-circular-colours: Exported functions
demo-cycle-colours: Exported functions
demo-fade-each-led: Exported functions

F
Function, close-piglow: Internal functions
Function, demo-circular-colours: Exported functions
Function, demo-cycle-colours: Exported functions
Function, demo-fade-each-led: Exported functions
Function, i2cize-stream: Exported functions
Function, open-i2c-device: Exported functions
Function, open-piglow: Exported functions
Function, piglow-maybe-show-automatically: Internal functions
Function, piglow-reset: Exported functions
Function, piglow-set-colour: Exported functions
Function, piglow-set-led: Exported functions
Function, piglow-set-leg: Exported functions
Function, piglow-show: Exported functions
Function, stream-fd: Internal functions
Function, write-i2c-octet: Exported functions
Function, write-i2c-octets: Exported functions

I
i2cize-stream: Exported functions

O
open-i2c-device: Exported functions
open-piglow: Exported functions

P
piglow-maybe-show-automatically: Internal functions
piglow-reset: Exported functions
piglow-set-colour: Exported functions
piglow-set-led: Exported functions
piglow-set-leg: Exported functions
piglow-show: Exported functions

S
stream-fd: Internal functions

W
write-i2c-octet: Exported functions
write-i2c-octets: Exported functions

Jump to:   C   D   F   I   O   P   S   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *   +  
S  
Index Entry  Section

*
*demo-max-brightness*: Exported special variables
*piglow*: Exported special variables
*piglow-show-automatically*: Exported special variables

+
+enable-leds-1+: Internal special variables
+enable-leds-2+: Internal special variables
+enable-leds-3+: Internal special variables
+enable-output+: Internal special variables
+i2c-slave+: Exported special variables
+led-addresses+: Exported special variables
+led-colour-names+: Exported special variables
+led-colours+: Exported special variables
+piglow-address+: Exported special variables
+piglow-reset-sequence+: Internal special variables
+reset+: Internal special variables
+update+: Internal special variables

S
Special Variable, *demo-max-brightness*: Exported special variables
Special Variable, *piglow*: Exported special variables
Special Variable, *piglow-show-automatically*: Exported special variables
Special Variable, +enable-leds-1+: Internal special variables
Special Variable, +enable-leds-2+: Internal special variables
Special Variable, +enable-leds-3+: Internal special variables
Special Variable, +enable-output+: Internal special variables
Special Variable, +i2c-slave+: Exported special variables
Special Variable, +led-addresses+: Exported special variables
Special Variable, +led-colour-names+: Exported special variables
Special Variable, +led-colours+: Exported special variables
Special Variable, +piglow-address+: Exported special variables
Special Variable, +piglow-reset-sequence+: Internal special variables
Special Variable, +reset+: Internal special variables
Special Variable, +update+: Internal special variables

Jump to:   *   +  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-piglow: The cl-piglow system
cl-piglow: The cl-piglow package

P
Package, cl-piglow: The cl-piglow package

S
System, cl-piglow: The cl-piglow system

Jump to:   C   P   S