# Pizazz
**A utility class to leverage 74HC595 shift register chips with a Raspberry Pi.**
[](https://badge.fury.io/py/pizazz)
[](https://pizazz.readthedocs.io/en/latest/?badge=latest)
[](https://pepy.tech/project/pizazz)
[![pre-commit][pre-commit-image]][pre-commit-url]
[![Imports: isort][isort-image]][isort-url]
[![Code style: black][black-image]][black-url]
[![Checked with mypy][mypy-image]][mypy-url]
[![security: bandit][bandit-image]][bandit-url]
[![licence: mit][mit-license-image]][mit-license-url]
The 74HC595 shift register is an incredibly useful chip. A single chip has 8 output pins which can be
controlled with only 3 input pins (excluding Vcc and Gnd of course).
That is great in itself however 595's can be daisy-chained together to give you multiples of 8 pin outputs yet still
always controlled by only 3 input pins! Wow!
If you are not sure why this is useful then let me explain.
I had a requirement to create a LED "Status Board" for a monitoring and automation application that I am also writing.
The status board would reflect the current operation status of things like Jenkins jobs, Github Actions, Linux services etc etc.
I needed a minimum of 16 LEDs. Now there already exists a [**status board**][status-board-url] HAT. However it only tracks 5 items (that is 10 LED's). However, each LED requires it's own GPIO and the HAT masks all other pins making them unavailable.
Using the Raspberry [**RPi.GPIO**][rpi-gpio-url] library it is possible to individually switch the 27 GPIO pins. However each LED would require
a wire from the GPIO pin. This is very physically unwieldy and clunky to control in Python.
Enter the 74HC595...
This class enables you to individually control any number of LEDS (or other output devices) with only 3 GPIO pins.
### Basic Wiring of the 74HC595 8-bit shift register to a Raspberry Pi
| Pin | Tag | Description |
| ----- | ------- | ----------------------------- |
| 1 - 7 | Q1 - Q7 | Parallel Data output pins 1-7 |
| 8 | Gnd | Ground |
| 9 | Q7-> | Serial data output pin |
| 10 | MR | Master Reset |
| 11 | SH | Clock pin |
| 12 | ST | Latch pin |
| 13 | OE | Output enable |
| 14 | DS | Serial data input |
| 15 | Q0 | Parallel data output pin 0 |
| 16 | Vcc | Positive voltage supply |
### Chaining 2 or more shift registers together
### How the register works
The 595 has two registers (which can be thought of as “memory containers”), each with just 8 bits of data.
1. The Shift Register
2. The Storage Register
Whenever we apply a clock pulse to a 595, two things happen:
1. The bits in the Shift Register move one step to the left. For example, Bit 7 accepts the value that was previously in bit 6, bit 6 gets the value of bit 5 etc.
2. Bit 0 in the Shift Register accepts the current value on DATA pin. At the rising edge of the pulse, if the data pin is high, then a 1 gets pushed into the shift register. Otherwise, it is a 0.
On enabling the Latch pin, the contents of Shift Register are copied into the Storage Register.
Each bit of the Storage Register is connected to one of the output pins Q0–Q7 of the IC, so in general, when the value in the Storage Register changes, so do the outputs.
## Installation
---
Raspberry Pi:
```sh
pip3 install pizazz
```
## Connecting the Raspberry Pi
---
The 40 pins of the Raspberry Pi are GPIO, 5v, 3.3V and ground. Some of the GPIO pins can have special purposes.
However, all of them can be controlled by the RPi.GPIO Python Library.
The RPi.GPIO requires that you specify how you will identify the pins that you use. There are 2 ways:
1. **GPIO.BOARD:** option specifies that you are referring to the pins by the number of the pin.
2. **BCM:** option means that you are referring to the pins by the "Broadcom SOC channel" number, these are
the numbers after "GPIO"
So referring to the diagram below: BCM mode GPIO2 is the same as BOARD mode pin 2
Connect any GPIO's to the clock, latch and data pins of the register and connect the the 5v supply and earth
as indicated in the register diagram.
If you are connecting the outputs to LED's then you need to wire 330 ohm resistors serially to protect them in the usual way.
## Library Usage examples
---
_For more examples and usage, please refer to the [Wiki][wiki]._
https://user-images.githubusercontent.com/33905365/220999848-e6062e9d-af53-4c91-8db8-0f8b5fdf1ff3.mp4
Import the library
```sh
from pizazz.pizazz import HC595
```
Instantiate the library passing the initialisation arguments
```sh
shifter = HC595(mode="BCM", data=17, clock=27, latch=18, ics=2)
```
the 'ics' parameter defines the number of registers daisey-chained together.
There are four public methods in the library:
| Method | Description |
| ------------- | ---------------------------------------- |
| clear() | sets shift and storage registers to zero |
| test() | Cycles sequentially through all outputs |
| set_output() | explicitly sets specific pin outputs |
| set_pattern() | sets output using a bit pattern |
### 1. Using the set_output(output, mask) method
Args:
**output** (int) - decimal value of the binary bits you want to set to "on"
**mask** (int) - decimal value of the binary bits to consider in this operation.
Consider the following setup:
Using a mask has 2 benefits:
1. It enables the library to explicitly turn LEDS 'off'. e.g. sending an output value of 16 means turn pin 5 'on'. it has no concept of turning pin 6 'off'. Using a mask facilitates this.
2. It isolates the pins to consider in the update. For a status board this is important. The inputs from the sensors can now be considered in isolation from the other sensors making asynchronous updates possible.
Consider sensor 2:
| method values | LED3 | LED4 |
| ------------------ | ---- | ---- |
| set_output(0, 12) | OFF | OFF |
| set_output(4, 12) | ON | OFF |
| set_output(8, 12) | OFF | ON |
| set_output(12, 12) | ON | ON |
**NOTE: All other LED outputs remain the same and are untouched by these operations**
This now makes programming the shift register a simple process. e.g. consider a Jenkins job
```sh
jenkins_mask = 48
jenkins_pass = 16
jenkins_fail = 32
# 'sensor' receives a failing indication
shifter.set_output(jenkins_fail, jenkins_mask)
# 'sensor' receives a passing indication
shifter.set_output(jenkins_pass, jenkins_mask)
```
The second value is the bit mask (similar to an IP bit mask) - Explained later
### 2. Using the set_pattern(chip_pattern) method
Args:
**chip_pattern** (List or Nested List) - Bit pattern representing the pins to set 'on' or 'off'. If more than two registers are used then the pattern should be a nested list.
Using the bit pattern (for a two chip configuration)
```sh
shifter.set_pattern([[0, 0, 1, 1, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 0, 0]])
```
For a single chip a simple list should be used:
```sh
shifter.set_pattern([0, 0, 1, 1, 0, 0, 0, 0])
```
## Documentation
---
[**Read the Docs**](https://pizazz.readthedocs.io/en/latest/?)
- [**Example Usage**](https://pizazz.readthedocs.io/en/latest/example.html)
- [**Credits**](https://pizazz.readthedocs.io/en/latest/example.html)
- [**Changelog**](https://pizazz.readthedocs.io/en/latest/changelog.html)
- [**API Reference**](https://pizazz.readthedocs.io/en/latest/autoapi/index.html)
[**Wiki**][wiki]
## Meta
---
[](https://www.linkedin.com/in/sr-king)
[](https://github.com/Stephen-RA-King/Stephen-RA-King)
[](https://pypi.org/project/pizazz)
[](https://www.justpython.tech)
[](mailto:sking.github@gmail.com)
Stephen R A King : [sking.github@gmail.com](mailto:sking.github@gmail.com)
Created with Cookiecutter template: [![pydough][pydough-image]][pydough-url] version 1.2.2
Digital object identifier: [](https://zenodo.org/badge/latestdoi/462683559)
<!-- Markdown link & img dfn's -->
[pydough-url]: https://github.com/Stephen-RA-King/pydough
[rpi-gpio-url]: https://pypi.org/project/RPi.GPIO/
[status-board-url]: https://thepihut.com/products/status-board-pro
[pre-commit-image]: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
[pre-commit-url]: https://github.com/pre-commit/pre-commit
[isort-image]: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336
[isort-url]: https://pycqa.github.io/isort/
[black-image]: https://img.shields.io/badge/code%20style-black-000000.svg
[black-url]: https://github.com/psf/black
[bandit-image]: https://img.shields.io/badge/security-bandit-yellow.svg
[bandit-url]: https://github.com/PyCQA/bandit
[mypy-image]: http://www.mypy-lang.org/static/mypy_badge.svg
[mypy-url]: http://mypy-lang.org/
[license-image]: https://img.shields.io/pypi/l/pizazz
[license-url]: https://github.com/Stephen-RA-King/pizazz/blob/main/LICENSE
[mit-license-image]: https://img.shields.io/badge/license-MIT-blue
[mit-license-url]: https://choosealicense.com/licenses/mit/
[pydough-image]: https://img.shields.io/badge/pydough-2023-orange
[pydough-url]: https://github.com/Stephen-RA-King/pydough
[wiki]: https://github.com/stephen-ra-king/pizazz/wiki
Raw data
{
"_id": null,
"home_page": "https://github.com/stephen-ra-king/pizazz",
"name": "pizazz",
"maintainer": "Stephen R A King",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "sking.github@gmail.com",
"keywords": "utility,74HC595,GPIO,Raspberry,Pi",
"author": "Stephen R A King",
"author_email": "sking.github@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/35/54/7784d4c78c56f290f04590a8f42765fe76ffb171767edad19dc87fc86661/pizazz-1.3.5.tar.gz",
"platform": "Linux",
"description": "# Pizazz\r\n\r\n**A utility class to leverage 74HC595 shift register chips with a Raspberry Pi.**\r\n\r\n[](https://badge.fury.io/py/pizazz)\r\n[](https://pizazz.readthedocs.io/en/latest/?badge=latest)\r\n[](https://pepy.tech/project/pizazz)\r\n[![pre-commit][pre-commit-image]][pre-commit-url]\r\n[![Imports: isort][isort-image]][isort-url]\r\n[![Code style: black][black-image]][black-url]\r\n[![Checked with mypy][mypy-image]][mypy-url]\r\n[![security: bandit][bandit-image]][bandit-url]\r\n[![licence: mit][mit-license-image]][mit-license-url]\r\n\r\n\r\n\r\nThe 74HC595 shift register is an incredibly useful chip. A single chip has 8 output pins which can be\r\ncontrolled with only 3 input pins (excluding Vcc and Gnd of course).\r\nThat is great in itself however 595's can be daisy-chained together to give you multiples of 8 pin outputs yet still\r\nalways controlled by only 3 input pins! Wow!\r\n\r\nIf you are not sure why this is useful then let me explain.\r\n\r\nI had a requirement to create a LED \"Status Board\" for a monitoring and automation application that I am also writing.\r\nThe status board would reflect the current operation status of things like Jenkins jobs, Github Actions, Linux services etc etc.\r\nI needed a minimum of 16 LEDs. Now there already exists a [**status board**][status-board-url] HAT. However it only tracks 5 items (that is 10 LED's). However, each LED requires it's own GPIO and the HAT masks all other pins making them unavailable.\r\n\r\nUsing the Raspberry [**RPi.GPIO**][rpi-gpio-url] library it is possible to individually switch the 27 GPIO pins. However each LED would require\r\na wire from the GPIO pin. This is very physically unwieldy and clunky to control in Python.\r\n\r\nEnter the 74HC595...\r\n\r\nThis class enables you to individually control any number of LEDS (or other output devices) with only 3 GPIO pins.\r\n\r\n### Basic Wiring of the 74HC595 8-bit shift register to a Raspberry Pi\r\n\r\n\r\n\r\n| Pin | Tag | Description |\r\n| ----- | ------- | ----------------------------- |\r\n| 1 - 7 | Q1 - Q7 | Parallel Data output pins 1-7 |\r\n| 8 | Gnd | Ground |\r\n| 9 | Q7-> | Serial data output pin |\r\n| 10 | MR | Master Reset |\r\n| 11 | SH | Clock pin |\r\n| 12 | ST | Latch pin |\r\n| 13 | OE | Output enable |\r\n| 14 | DS | Serial data input |\r\n| 15 | Q0 | Parallel data output pin 0 |\r\n| 16 | Vcc | Positive voltage supply |\r\n\r\n### Chaining 2 or more shift registers together\r\n\r\n\r\n\r\n### How the register works\r\n\r\nThe 595 has two registers (which can be thought of as \u201cmemory containers\u201d), each with just 8 bits of data.\r\n\r\n1. The Shift Register\r\n2. The Storage Register\r\n\r\nWhenever we apply a clock pulse to a 595, two things happen:\r\n\r\n1. The bits in the Shift Register move one step to the left. For example, Bit 7 accepts the value that was previously in bit 6, bit 6 gets the value of bit 5 etc.\r\n\r\n2. Bit 0 in the Shift Register accepts the current value on DATA pin. At the rising edge of the pulse, if the data pin is high, then a 1 gets pushed into the shift register. Otherwise, it is a 0.\r\n\r\nOn enabling the Latch pin, the contents of Shift Register are copied into the Storage Register.\r\nEach bit of the Storage Register is connected to one of the output pins Q0\u2013Q7 of the IC, so in general, when the value in the Storage Register changes, so do the outputs.\r\n\r\n## Installation\r\n\r\n---\r\n\r\nRaspberry Pi:\r\n\r\n```sh\r\npip3 install pizazz\r\n```\r\n\r\n## Connecting the Raspberry Pi\r\n\r\n---\r\n\r\nThe 40 pins of the Raspberry Pi are GPIO, 5v, 3.3V and ground. Some of the GPIO pins can have special purposes.\r\nHowever, all of them can be controlled by the RPi.GPIO Python Library.\r\nThe RPi.GPIO requires that you specify how you will identify the pins that you use. There are 2 ways:\r\n\r\n1. **GPIO.BOARD:** option specifies that you are referring to the pins by the number of the pin.\r\n\r\n2. **BCM:** option means that you are referring to the pins by the \"Broadcom SOC channel\" number, these are\r\n the numbers after \"GPIO\"\r\n\r\nSo referring to the diagram below: BCM mode GPIO2 is the same as BOARD mode pin 2\r\n\r\n\r\n\r\nConnect any GPIO's to the clock, latch and data pins of the register and connect the the 5v supply and earth\r\nas indicated in the register diagram.\r\nIf you are connecting the outputs to LED's then you need to wire 330 ohm resistors serially to protect them in the usual way.\r\n\r\n## Library Usage examples\r\n\r\n---\r\n\r\n_For more examples and usage, please refer to the [Wiki][wiki]._\r\n\r\nhttps://user-images.githubusercontent.com/33905365/220999848-e6062e9d-af53-4c91-8db8-0f8b5fdf1ff3.mp4\r\n\r\nImport the library\r\n\r\n```sh\r\nfrom pizazz.pizazz import HC595\r\n```\r\n\r\nInstantiate the library passing the initialisation arguments\r\n\r\n```sh\r\nshifter = HC595(mode=\"BCM\", data=17, clock=27, latch=18, ics=2)\r\n```\r\n\r\nthe 'ics' parameter defines the number of registers daisey-chained together.\r\n\r\nThere are four public methods in the library:\r\n\r\n| Method | Description |\r\n| ------------- | ---------------------------------------- |\r\n| clear() | sets shift and storage registers to zero |\r\n| test() | Cycles sequentially through all outputs |\r\n| set_output() | explicitly sets specific pin outputs |\r\n| set_pattern() | sets output using a bit pattern |\r\n\r\n### 1. Using the set_output(output, mask) method\r\n\r\nArgs:\r\n\r\n**output** (int) - decimal value of the binary bits you want to set to \"on\"\r\n\r\n**mask** (int) - decimal value of the binary bits to consider in this operation.\r\n\r\nConsider the following setup:\r\n\r\n\r\n\r\nUsing a mask has 2 benefits:\r\n\r\n1. It enables the library to explicitly turn LEDS 'off'. e.g. sending an output value of 16 means turn pin 5 'on'. it has no concept of turning pin 6 'off'. Using a mask facilitates this.\r\n2. It isolates the pins to consider in the update. For a status board this is important. The inputs from the sensors can now be considered in isolation from the other sensors making asynchronous updates possible.\r\n\r\nConsider sensor 2:\r\n\r\n| method values | LED3 | LED4 |\r\n| ------------------ | ---- | ---- |\r\n| set_output(0, 12) | OFF | OFF |\r\n| set_output(4, 12) | ON | OFF |\r\n| set_output(8, 12) | OFF | ON |\r\n| set_output(12, 12) | ON | ON |\r\n\r\n**NOTE: All other LED outputs remain the same and are untouched by these operations**\r\n\r\nThis now makes programming the shift register a simple process. e.g. consider a Jenkins job\r\n\r\n```sh\r\njenkins_mask = 48\r\njenkins_pass = 16\r\njenkins_fail = 32\r\n\r\n# 'sensor' receives a failing indication\r\nshifter.set_output(jenkins_fail, jenkins_mask)\r\n\r\n# 'sensor' receives a passing indication\r\nshifter.set_output(jenkins_pass, jenkins_mask)\r\n\r\n```\r\n\r\nThe second value is the bit mask (similar to an IP bit mask) - Explained later\r\n\r\n### 2. Using the set_pattern(chip_pattern) method\r\n\r\nArgs:\r\n\r\n**chip_pattern** (List or Nested List) - Bit pattern representing the pins to set 'on' or 'off'. If more than two registers are used then the pattern should be a nested list.\r\n\r\nUsing the bit pattern (for a two chip configuration)\r\n\r\n```sh\r\nshifter.set_pattern([[0, 0, 1, 1, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 0, 0]])\r\n```\r\n\r\nFor a single chip a simple list should be used:\r\n\r\n```sh\r\nshifter.set_pattern([0, 0, 1, 1, 0, 0, 0, 0])\r\n```\r\n\r\n## Documentation\r\n\r\n---\r\n\r\n[**Read the Docs**](https://pizazz.readthedocs.io/en/latest/?)\r\n\r\n- [**Example Usage**](https://pizazz.readthedocs.io/en/latest/example.html)\r\n- [**Credits**](https://pizazz.readthedocs.io/en/latest/example.html)\r\n- [**Changelog**](https://pizazz.readthedocs.io/en/latest/changelog.html)\r\n- [**API Reference**](https://pizazz.readthedocs.io/en/latest/autoapi/index.html)\r\n\r\n[**Wiki**][wiki]\r\n\r\n## Meta\r\n\r\n---\r\n\r\n[](https://www.linkedin.com/in/sr-king)\r\n[](https://github.com/Stephen-RA-King/Stephen-RA-King)\r\n[](https://pypi.org/project/pizazz)\r\n[](https://www.justpython.tech)\r\n[](mailto:sking.github@gmail.com)\r\n\r\nStephen R A King : [sking.github@gmail.com](mailto:sking.github@gmail.com)\r\n\r\nCreated with Cookiecutter template: [![pydough][pydough-image]][pydough-url] version 1.2.2\r\n\r\nDigital object identifier: [](https://zenodo.org/badge/latestdoi/462683559)\r\n\r\n<!-- Markdown link & img dfn's -->\r\n\r\n[pydough-url]: https://github.com/Stephen-RA-King/pydough\r\n[rpi-gpio-url]: https://pypi.org/project/RPi.GPIO/\r\n[status-board-url]: https://thepihut.com/products/status-board-pro\r\n[pre-commit-image]: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white\r\n[pre-commit-url]: https://github.com/pre-commit/pre-commit\r\n[isort-image]: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336\r\n[isort-url]: https://pycqa.github.io/isort/\r\n[black-image]: https://img.shields.io/badge/code%20style-black-000000.svg\r\n[black-url]: https://github.com/psf/black\r\n[bandit-image]: https://img.shields.io/badge/security-bandit-yellow.svg\r\n[bandit-url]: https://github.com/PyCQA/bandit\r\n[mypy-image]: http://www.mypy-lang.org/static/mypy_badge.svg\r\n[mypy-url]: http://mypy-lang.org/\r\n[license-image]: https://img.shields.io/pypi/l/pizazz\r\n[license-url]: https://github.com/Stephen-RA-King/pizazz/blob/main/LICENSE\r\n[mit-license-image]: https://img.shields.io/badge/license-MIT-blue\r\n[mit-license-url]: https://choosealicense.com/licenses/mit/\r\n[pydough-image]: https://img.shields.io/badge/pydough-2023-orange\r\n[pydough-url]: https://github.com/Stephen-RA-King/pydough\r\n[wiki]: https://github.com/stephen-ra-king/pizazz/wiki\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Easy configuration and control of 74HC595 Shift Registers on a Raspberry Pi",
"version": "1.3.5",
"project_urls": {
"Homepage": "https://github.com/stephen-ra-king/pizazz"
},
"split_keywords": [
"utility",
"74hc595",
"gpio",
"raspberry",
"pi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f4c79b272a203d948de39d36f1ee2ab00158adeefd73864e4d34d667663031e3",
"md5": "32f3e117383da54d5b120a50e019d594",
"sha256": "cd2ddfd0b9292394b287234465b49429548b117b09501777aa7d297778ac4bea"
},
"downloads": -1,
"filename": "pizazz-1.3.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "32f3e117383da54d5b120a50e019d594",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9379,
"upload_time": "2023-07-06T07:01:15",
"upload_time_iso_8601": "2023-07-06T07:01:15.954819Z",
"url": "https://files.pythonhosted.org/packages/f4/c7/9b272a203d948de39d36f1ee2ab00158adeefd73864e4d34d667663031e3/pizazz-1.3.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "35547784d4c78c56f290f04590a8f42765fe76ffb171767edad19dc87fc86661",
"md5": "18f3a6bab743e7d15bacf561abfd5988",
"sha256": "bec417f7c39cd277badb222b1beb575b6815fcda9ab7dc949ab75121c733090f"
},
"downloads": -1,
"filename": "pizazz-1.3.5.tar.gz",
"has_sig": false,
"md5_digest": "18f3a6bab743e7d15bacf561abfd5988",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14874,
"upload_time": "2023-07-06T07:01:17",
"upload_time_iso_8601": "2023-07-06T07:01:17.264524Z",
"url": "https://files.pythonhosted.org/packages/35/54/7784d4c78c56f290f04590a8f42765fe76ffb171767edad19dc87fc86661/pizazz-1.3.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-06 07:01:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stephen-ra-king",
"github_project": "pizazz",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"tox": true,
"lcname": "pizazz"
}
JSON
