| Name | pifaceio JSON |
| Version |
1.37
JSON |
| download |
| home_page | |
| Summary | Python interface to the Raspberry Pi PiFace board |
| upload_time | 2023-09-02 03:55:15 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.6 |
| license | GPLv3 |
| keywords |
piface
pifacedigitalio
spidev
raspberrypi
rpi
pi
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
### PIFACEIO
[](https://pypi.org/project/pifaceio/)
This package provides a Python interface to the [PiFace Digital][pifaceboard]
peripheral I/O board for the [Raspberry Pi][rpi].
A [PiFace Digital][pifaceboard] board offers 8 digital inputs and 8
digital outputs. This package allows a Python program to read the inputs
and write the outputs on the board via the Raspberry Pi SPI bus.
The newer [PiFace Digital 2][pifaceboard2] board is exactly compatible
with the original board and so is also supported by this package.
Multiple [PiFace Digital][pifaceboard] boards are supported, on either
or both of the RPi SPI bus chip selects. This pifaceio package is
focussed on simplicity and performance for polled implementations and is
an alternative to the official [pifacedigitalio][] Python package for
the [PiFace Digital][pifaceboard] board. In my simple benchmark of
polled reads and writes ([see next
section](#performance-benchmarks-against-pifacedigitalio)), pifaceio
performs an order of magnitude faster, and with much less overhead than
[pifacedigitalio][].
Interrupts are not supported. See [pifacedigitalio][] for interrupt and
other functionality.
The pifaceio package is implemented in pure Python code using only the
Python standard library, uses no external 3rd party packages, and is
compatible with Python version 3.6 and later.
#### Performance Benchmarks Against pifacedigitalio
A small [`benchmark`](benchmark) program is included in the
repository. It produces the following sample of simple polled read and
write performance comparisons between [pifacedigitalio][] and
[pifaceio][] on a Raspberry Pi2B.
|Function |`pifacedigitalio`|`pifaceio` |Speedup
|--------------------------------------|-----------------|-----------|--------
|Input reads per second |1740 |16317 |x 9.4
|Output writes per second |884 |11590 |x 13.1
|Input reads per second (classic API) |1773 |11128 |x 6.3
|Output reads per second (classic API) |889 |9140 |x 10.3
### INSTALLATION
The [pifaceio pypi package][pifaceio] is available from [PyPi][] so you
can install it using [pip][]. If [pip][] is not already installed run:
```sh
sudo apt-get install python3-pip
```
Then use pip to install the [pifaceio][] package:
```sh
sudo pip3 install -U pifaceio
```
To set up permissions/groups/udev etc for spidev device on RPi, run the
included script and then reboot.
```sh
sudo pifaceio-install-spidev.sh
```
### UPGRADE
```sh
sudo pip3 install -U pifaceio
```
### USAGE
Board addresses, input pins, and output pins are always numbered from 0.
In general, you start with a once-off allocation of a PiFace board
instance at startup with:
```python
pf = pifaceio.PiFace()
```
Default is first PiFace board (0). Optionally takes an argument 0 to 7
for up to 8 PiFace board addresses. Create multiple PiFace() instances
if you want to use multiple boards in parallel.
There are also other (rarely needed) options to disable the input pull
up resistors, and to invert the input and output bit polarities. See
pifaceio.py for details.
At each poll time, e.g. every part second, read all the inputs (i.e. the
single input byte) with:
```python
pf.read() # returns the input byte you can use directly if you prefer
```
Then read and write individual pins according to your logic with:
```python
in_val = pf.read_pin(pin_in)
# ..
pf.write_pin(pin_out, out_val)
# ..
```
Finally, write all the outputs at the end of processing (i.e. write the
single output byte) with:
```python
pf.write() # optionally, takes an output byte to write directly
```
Note that `read_pin()` is just a convenience method wrapping a bit
test around the previously read input byte from `read()` and
`write_pin()` is just a convenience method wrapping a bit set/clear
around the output byte pending it being written by `write()`. You don't
have to use `read_pin()` or `write_pin()` if you just want to read,
test/manipulate, and write the 8 bit input and/or output byte directly.
In that case you would just use `read()`, and `write()` only in your
application.
### EXAMPLES
Simple example to just reflect all PiFace 8 inputs to the 8 outputs
every 10 msec, on the default first PiFace board:
```python
import pifaceio, time
pf = pifaceio.PiFace()
while True:
pf.write(pf.read())
time.sleep(.01)
```
Same example, but do it across 4 PiFace boards:
```python
import pifaceio, time
pifaces = [pifaceio.PiFace(n) for n in range(4)]
while True:
for pf in pifaces:
pf.write(pf.read())
time.sleep(.01)
```
Simple example to test if both input pin 0 and 1 are on at same time,
and then set output pin 7 if true:
```python
import pifaceio
pf = pifaceio.PiFace()
...
# Fetch inputs (i.e. single byte)
pf.read()
first_two_inputs_on = pf.read_pin(0) and pf.read_pin(1)
# Now write that state to output pin 7
pf.write_pin(7, first_two_inputs_on)
# Do final (actual) write when all output pin states are set.
pf.write()
```
Simulated "interrupt" processing example by light-weight poll every 10 msecs:
```python
import pifaceio, time
pf = pifaceio.PiFace()
def process_change():
'On any changed inputs, read inputs and write outputs'
pf.write_pin(7, pf.read_pin(0) and pf.read_pin(1))
# .. etc .. do logic using pf.read_pin() and pf.write_pin()
# Loop forever polling inputs ..
last = None
while True:
data = pf.read()
# Do processing only on change
if last != data:
last = data
process_change()
pf.write() # note write() only writes if output changes
time.sleep(.01)
```
### PIFACE PACKAGE BACKWARDS COMPATIBILITY
As an alternative API, pifaceio also implements the "classic" API from
the [pifacedigitalio][] and it's predecessor [piface][] packages. The
classic API will work compatibly, but performance is slightly degraded
compared to reading and writing the single input and output bytes using
the canonical new and preferred pifaceio API described above. However,
performance is still significantly superior to the original
[pifacedigitalio][] and [piface][] packages as shown in the above
[performance
comparison](#performance-benchmarks-against-pifacedigitalio) section.
```python
#import piface.pfio as pf (change this line ..)
#import pifacedigitalio as pf (or this line .., to the following line)
import pifaceio as pf
# The following calls should be approximately compatible:
pf.init()
value = pf.digital_read(pin)
pf.digital_write(pin, value)
pf.deinit()
```
You can also use multiple boards with this compatibility interface, e.g.
as follows where board can be from 0 to 7.
```python
value = pf.digital_read(pin, board)
pf.digital_write(pin, value, board)
```
### LICENSE
Copyright (C) 2013 Mark Blakeney. This program is distributed under the
terms of the GNU General Public License.
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or any later
version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License at <http://www.gnu.org/licenses/> for more details.
[rpi]: http://www.raspberrypi.org
[pifaceboard]: http://www.piface.org.uk/products/piface_digital/
[pifaceboard2]: http://www.element14.com/community/docs/DOC-69001/l/piface-digital-2-for-raspberry-pi
[piface]: http://github.com/thomasmacpherson/piface
[pifacedigitalio]: http://github.com/piface/pifacedigitalio
[PyPi]: https://pypi.python.org/pypi
[pip]: http://www.pip-installer.org/en/latest
[pifaceio]: https://pypi.python.org/pypi/pifaceio
<!-- vim: se ai et syn=markdown: -->
Raw data
{
"_id": null,
"home_page": "",
"name": "pifaceio",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "piface,pifacedigitalio,spidev,raspberrypi,rpi,pi",
"author": "",
"author_email": "Mark Blakeney <mark.blakeney@bullet-systems.net>",
"download_url": "https://files.pythonhosted.org/packages/f8/ef/c4697824776246262e817ecba9d1d22a895160567977214d380d1c93919b/pifaceio-1.37.tar.gz",
"platform": null,
"description": "### PIFACEIO\n[](https://pypi.org/project/pifaceio/)\n\nThis package provides a Python interface to the [PiFace Digital][pifaceboard]\nperipheral I/O board for the [Raspberry Pi][rpi].\nA [PiFace Digital][pifaceboard] board offers 8 digital inputs and 8\ndigital outputs. This package allows a Python program to read the inputs\nand write the outputs on the board via the Raspberry Pi SPI bus.\n\nThe newer [PiFace Digital 2][pifaceboard2] board is exactly compatible\nwith the original board and so is also supported by this package.\n\nMultiple [PiFace Digital][pifaceboard] boards are supported, on either\nor both of the RPi SPI bus chip selects. This pifaceio package is\nfocussed on simplicity and performance for polled implementations and is\nan alternative to the official [pifacedigitalio][] Python package for\nthe [PiFace Digital][pifaceboard] board. In my simple benchmark of\npolled reads and writes ([see next\nsection](#performance-benchmarks-against-pifacedigitalio)), pifaceio\nperforms an order of magnitude faster, and with much less overhead than\n[pifacedigitalio][].\n\nInterrupts are not supported. See [pifacedigitalio][] for interrupt and\nother functionality.\n\nThe pifaceio package is implemented in pure Python code using only the\nPython standard library, uses no external 3rd party packages, and is\ncompatible with Python version 3.6 and later.\n\n#### Performance Benchmarks Against pifacedigitalio\n\nA small [`benchmark`](benchmark) program is included in the\nrepository. It produces the following sample of simple polled read and\nwrite performance comparisons between [pifacedigitalio][] and\n[pifaceio][] on a Raspberry Pi2B.\n\n|Function |`pifacedigitalio`|`pifaceio` |Speedup\n|--------------------------------------|-----------------|-----------|--------\n|Input reads per second |1740 |16317 |x 9.4\n|Output writes per second |884 |11590 |x 13.1\n|Input reads per second (classic API) |1773 |11128 |x 6.3\n|Output reads per second (classic API) |889 |9140 |x 10.3\n\n### INSTALLATION\n\nThe [pifaceio pypi package][pifaceio] is available from [PyPi][] so you\ncan install it using [pip][]. If [pip][] is not already installed run:\n\n```sh\nsudo apt-get install python3-pip\n```\n\nThen use pip to install the [pifaceio][] package:\n\n```sh\nsudo pip3 install -U pifaceio\n```\n\nTo set up permissions/groups/udev etc for spidev device on RPi, run the\nincluded script and then reboot.\n\n```sh\nsudo pifaceio-install-spidev.sh\n```\n\n### UPGRADE\n\n```sh\nsudo pip3 install -U pifaceio\n```\n\n### USAGE\n\nBoard addresses, input pins, and output pins are always numbered from 0.\n\nIn general, you start with a once-off allocation of a PiFace board\ninstance at startup with:\n\n```python\npf = pifaceio.PiFace()\n```\n\nDefault is first PiFace board (0). Optionally takes an argument 0 to 7\nfor up to 8 PiFace board addresses. Create multiple PiFace() instances\nif you want to use multiple boards in parallel.\n\nThere are also other (rarely needed) options to disable the input pull\nup resistors, and to invert the input and output bit polarities. See\npifaceio.py for details.\n\nAt each poll time, e.g. every part second, read all the inputs (i.e. the\nsingle input byte) with:\n\n```python\npf.read() # returns the input byte you can use directly if you prefer\n```\n\nThen read and write individual pins according to your logic with:\n\n```python\nin_val = pf.read_pin(pin_in)\n# ..\npf.write_pin(pin_out, out_val)\n# ..\n```\n\nFinally, write all the outputs at the end of processing (i.e. write the\nsingle output byte) with:\n\n```python\npf.write() # optionally, takes an output byte to write directly\n```\n\nNote that `read_pin()` is just a convenience method wrapping a bit\ntest around the previously read input byte from `read()` and\n`write_pin()` is just a convenience method wrapping a bit set/clear\naround the output byte pending it being written by `write()`. You don't\nhave to use `read_pin()` or `write_pin()` if you just want to read,\ntest/manipulate, and write the 8 bit input and/or output byte directly.\nIn that case you would just use `read()`, and `write()` only in your\napplication.\n\n### EXAMPLES\n\nSimple example to just reflect all PiFace 8 inputs to the 8 outputs\nevery 10 msec, on the default first PiFace board:\n\n```python\nimport pifaceio, time\npf = pifaceio.PiFace()\n\nwhile True:\n pf.write(pf.read())\n time.sleep(.01)\n```\n\nSame example, but do it across 4 PiFace boards:\n\n```python\nimport pifaceio, time\npifaces = [pifaceio.PiFace(n) for n in range(4)]\n\nwhile True:\n for pf in pifaces:\n pf.write(pf.read())\n time.sleep(.01)\n```\n\nSimple example to test if both input pin 0 and 1 are on at same time,\nand then set output pin 7 if true:\n\n```python\nimport pifaceio\npf = pifaceio.PiFace()\n...\n# Fetch inputs (i.e. single byte)\npf.read()\nfirst_two_inputs_on = pf.read_pin(0) and pf.read_pin(1)\n\n# Now write that state to output pin 7\npf.write_pin(7, first_two_inputs_on)\n\n# Do final (actual) write when all output pin states are set.\npf.write()\n```\n\nSimulated \"interrupt\" processing example by light-weight poll every 10 msecs:\n\n```python\nimport pifaceio, time\npf = pifaceio.PiFace()\n\ndef process_change():\n 'On any changed inputs, read inputs and write outputs'\n pf.write_pin(7, pf.read_pin(0) and pf.read_pin(1))\n\n # .. etc .. do logic using pf.read_pin() and pf.write_pin()\n\n# Loop forever polling inputs ..\nlast = None\nwhile True:\n data = pf.read()\n\n # Do processing only on change\n if last != data:\n last = data\n process_change()\n pf.write() # note write() only writes if output changes\n\n time.sleep(.01)\n```\n\n### PIFACE PACKAGE BACKWARDS COMPATIBILITY\n\nAs an alternative API, pifaceio also implements the \"classic\" API from\nthe [pifacedigitalio][] and it's predecessor [piface][] packages. The\nclassic API will work compatibly, but performance is slightly degraded\ncompared to reading and writing the single input and output bytes using\nthe canonical new and preferred pifaceio API described above. However,\nperformance is still significantly superior to the original\n[pifacedigitalio][] and [piface][] packages as shown in the above\n[performance\ncomparison](#performance-benchmarks-against-pifacedigitalio) section.\n\n```python\n#import piface.pfio as pf (change this line ..)\n#import pifacedigitalio as pf (or this line .., to the following line)\nimport pifaceio as pf\n\n# The following calls should be approximately compatible:\npf.init()\nvalue = pf.digital_read(pin)\npf.digital_write(pin, value)\npf.deinit()\n```\n\nYou can also use multiple boards with this compatibility interface, e.g.\nas follows where board can be from 0 to 7.\n\n```python\nvalue = pf.digital_read(pin, board)\npf.digital_write(pin, value, board)\n```\n\n### LICENSE\n\nCopyright (C) 2013 Mark Blakeney. This program is distributed under the\nterms of the GNU General Public License.\nThis program is free software: you can redistribute it and/or modify it\nunder the terms of the GNU General Public License as published by the\nFree Software Foundation, either version 3 of the License, or any later\nversion.\nThis program is distributed in the hope that it will be useful, but\nWITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General\nPublic License at <http://www.gnu.org/licenses/> for more details.\n\n[rpi]: http://www.raspberrypi.org\n[pifaceboard]: http://www.piface.org.uk/products/piface_digital/\n[pifaceboard2]: http://www.element14.com/community/docs/DOC-69001/l/piface-digital-2-for-raspberry-pi\n[piface]: http://github.com/thomasmacpherson/piface\n[pifacedigitalio]: http://github.com/piface/pifacedigitalio\n[PyPi]: https://pypi.python.org/pypi\n[pip]: http://www.pip-installer.org/en/latest\n[pifaceio]: https://pypi.python.org/pypi/pifaceio\n\n<!-- vim: se ai et syn=markdown: -->\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Python interface to the Raspberry Pi PiFace board",
"version": "1.37",
"project_urls": {
"Homepage": "https://github.com/bulletmark/pifaceio"
},
"split_keywords": [
"piface",
"pifacedigitalio",
"spidev",
"raspberrypi",
"rpi",
"pi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4d9278862483719632dd4961b2bee5008f7d80b5035e2a2d73cb57f9f8cc2980",
"md5": "73877e60d4661010045a6215572bf63b",
"sha256": "01ca9c8c08c654a2425db704232b8e32770a55864f81e0a0568ad553a3e31cea"
},
"downloads": -1,
"filename": "pifaceio-1.37-py3-none-any.whl",
"has_sig": false,
"md5_digest": "73877e60d4661010045a6215572bf63b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 8168,
"upload_time": "2023-09-02T03:55:13",
"upload_time_iso_8601": "2023-09-02T03:55:13.487538Z",
"url": "https://files.pythonhosted.org/packages/4d/92/78862483719632dd4961b2bee5008f7d80b5035e2a2d73cb57f9f8cc2980/pifaceio-1.37-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f8efc4697824776246262e817ecba9d1d22a895160567977214d380d1c93919b",
"md5": "86cc18a8311614ad63a3aae7c19b759f",
"sha256": "47ee35929829dbdf2456ba63ae3e982afaeb3bb0503415bb156decedcf155e34"
},
"downloads": -1,
"filename": "pifaceio-1.37.tar.gz",
"has_sig": false,
"md5_digest": "86cc18a8311614ad63a3aae7c19b759f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 8911,
"upload_time": "2023-09-02T03:55:15",
"upload_time_iso_8601": "2023-09-02T03:55:15.367817Z",
"url": "https://files.pythonhosted.org/packages/f8/ef/c4697824776246262e817ecba9d1d22a895160567977214d380d1c93919b/pifaceio-1.37.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-02 03:55:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bulletmark",
"github_project": "pifaceio",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pifaceio"
}
