Python3 LPD8806 LED Library 🐍💡

Credit to Sh4d and adammhaile for the initial Python2 implementation:

• https://github.com/Sh4d/LPD8806
• https://github.com/adammhaile/RPi-LPD8806

Changes

• Python3 compatibility via 2to3 utility
• Fixed inaccurate color mapping
• Includes CLI for LED controls
• Control LED's via simple JSON config files

Install

git clone git@github.com:edmundpf/LPD8806_Python3.git
cd LPD8806_Python3/
pip3 install -r requirements.txt

Install CLI

cd /usr/bin/
sudo bash -c 'cat > led'
cd /YOUR_REPO_PATH && py ledMaster.py "$@"

• Hit enter then ctrl+c to save

sudo chmod +x led

• Now you can use the CLI anywhere on the system via the led command

Usage

Without CLI installed (must be called within root directory i.e. LPD8806_Python3/)

python3 ledMaster.py -f actions/rainbow.json

With CLI installed (can be called system-wide)

led -f actions/rainbow.json

CLI flags

• -f, --file
  • Choose config file by entering relative or absolute file path
  • -f /mydir/example.json
• -d, --duration
  • Choose action sleep duration in seconds
  • Only applies to config files with a single action
  • A duration of 0 will not include any sleep
  • Useful for turning LED's off at a certain time (can be paired with cron for automation)
  • -d 300
• -l, --loops
  • Choose number of loops
  • Only applies to config files with a single action
  • A loops value of -1 will run indefinitely until a keyboard interrupt (ctrl+c)
  • Loops with values 0 and 1 will run once, loops of 2 or greater will run the respective amount
  • -l 4
• -a, --args
  • Modify arguments in config file
  • Applies to all actions
  • Can input multiple args, config file args will be overwritten in order of arguments
  • For example let's look at the color.json preset config file:

    [
      {
        "duration": 0,
        "loops": 0,
        "action": "color",
        "args": {"color": null}
      }
    ]

  • This config file expects one argument for "color": "args": {"color": null} as a hex color code
  • The default null value will be overwritten with the argument you entered
  • -a 0000FF
• Presets
  • --off
    • Turns all LED's off
    • led --off
  • --color
    • Sets LED's a static color until keyboard interrupt
    • led --color 00FF00
    • Alternatively, choose preset colors listed in /raspledstrip/colorPresets.py led --color RED
  • --rainbow
    • Plays rainbow animation until keyboard interrupt
    • led --rainbow
• Any number of these args can be combined to customize your config files
  • led -f actions/color.json -a FF0000 -l 0 -d 3600
• The CLI args are meant for modifying config files with a single action, config files with multiple actions should have all their respective args hard-coded and should only include the file argument in the CLI
  • led /mydir/multi-action.json

Config File

• The config file is a list of actions
• Each action includes the following attributes:
  • duration
    • Duration of script in seconds
  • loops
    • Number of loops
  • action
    • Action type
    • TO-DO: add more actions to CLI
  • args
    • Required arguments for the respective action (name-sensitive)
    • Set to empty: "args": {} for actions with no arguments
    • TO-DO: define and document action names for respective actions
  • Action types
    • off
      • Turns all LED's off
    • color
      • Sets LED's a static color
      • Turns off after execution
      • Args
        • color
          • Hexadecimal color code: "args": {"color": "FF0000"}
    • rainbow
      • LED's change color from end-to-end in a rainbow sequence
      • Turns off after execution
  • Single Actions
    • duration, loops, and args can be modified via CLI

    [
      {
        "duration": 0,
        "loops": -1,
        "action": "rainbow",
        "args": {}
      }
    ]

  • Multiple Actions
    • Arguments CANNOT be modified via CLI (just call the config file name)

    [
      {
        "duration": 4,
        "loops": 2,
        "action": "color",
        "args": {"color": "A833FF"}
      },
      {
        "duration": 6,
        "loops": 1,
        "action": "color",
        "args": {"color": "33FF8D"}
      }
    ]

LED Configuration

• RGB Configuration
  • Some LED strips do not have an RGB color scheme, and thus will display unexpected colors
  • To choose the correct color scheme for you LED strip, edit /raspledstrip/ledstrip.py
  • Replace self.c_order = ChannelOrder.RGB with your color scheme i.e. self.c_order = ChannelOrder.GRB
• Master Brightness
  • You may find your RGB strip is too bright. To choose a master brightness, edit /raspledstrip/ledstrip.py
  • Replace self.masterBrightness = 1.0 with your preferred brightness i.e. self.masterBrightness = 0.5

Contributing

• If you wish to contribute to the project (add more actions, add more example .JSON configs, improve stability, etc.) please submit a pull request! Thanks!