|build-and-test| |codeql| |docs| |coverage|
|versions| |package| |commits-since| |license|
.. |build-and-test| image:: https://github.com/eindiran/smbus3/actions/workflows/python-build-and-test.yml/badge.svg?branch=master
:target: https://github.com/eindiran/smbus3/actions/workflows/python-build-and-test.yml
:alt: Build and tests
.. |codeql| image:: https://github.com/eindiran/smbus3/actions/workflows/codeql-analysis.yml/badge.svg?branch=master
:target: https://github.com/eindiran/smbus3/actions/workflows/codeql-analysis.yml
:alt: CodeQL security analysis
.. |docs| image:: https://readthedocs.org/projects/smbus3/badge/?version=latest
:target: https://smbus3.readthedocs.io/en/latest/
:alt: Documentation
.. |coverage| image:: https://raw.githubusercontent.com/eindiran/smbus3/badges/.github/badges/coverage.svg
:target: https://github.com/eindiran/smbus3/actions/workflows/coverage-master.yml
:alt: Test coverage on master
.. |versions| image:: https://img.shields.io/pypi/pyversions/smbus3.svg
:alt: Python versions
.. |package| image:: https://img.shields.io/pypi/v/smbus3.svg
:target: ttps://pypi.org/project/smbus3/
:alt: PyPI package
.. |commits-since| image:: https://img.shields.io/github/commits-since/eindiran/smbus3/latest.svg?color=green
:target: https://github.com/eindiran/smbus3/releases/latest
:alt: Commits on master since release
.. |license| image:: https://img.shields.io/badge/License-MIT-blue.svg
:target: https://opensource.org/license/MIT
:alt: MIT
What is `smbus3`
================
A drop-in replacement for `smbus2 <https://pypi.org/project/smbus2/>`__,
`smbus-cffi <https://pypi.org/project/smbus-cffi/>`__, or
`smbus-python <https://pypi.org/project/smbus/>`__ written in pure
Python and intended for use with Python 3.8+.
This library was forked from @kplindegaard’s excellent
`smbus2 <https://github.com/kplindegaard/smbus2>`__. If you need a
package that works with Python 2.7 - 3.7, smbus2 is the way to go.
Introduction
------------
smbus3 is a Python 3 implementation of the SMBus interface for use in
Python 3. It should be a drop-in replacement of both the original
`smbus package <https://pypi.org/project/smbus/>`__, the C-FFI
`smbus-cffi package <https://pypi.org/project/smbus-cffi/>`__ and
the pure Python `smbus2
package <https://pypi.org/project/smbus2/>`__. The interfaces will be
shared for backwards compatibility with ``smbus2``.
Currently supported features are:
- Context manager-like control of ``SMBus`` objects
- SMBus Packet Error Checking (PEC) support
- ``enable_pec()``
- 10bit addressing support
- ``enable_tenbit()``
- Manual control over retries and timeouts
- ``set_retries()``
- ``set_timeout()``
- Create raw ``i2c_msg`` messages
- ``read_byte()``
- ``write_byte()``
- ``read_byte_data()``
- ``write_byte_data()``
- ``read_word_data()``
- ``write_word_data()``
- ``read_i2c_block_data()``
- ``write_i2c_block_data()``
- ``write_quick()``
- ``process_call()``
- ``read_block_data()``
- ``write_block_data()``
- ``block_process_call()``
- ``i2c_rdwr()`` - *combined write/read transactions with repeated
start*
- ``i2c_rd()`` - single read via ``i2c_rdwr``
- ``i2c_wr()`` - single write via ``i2c_rdwr``
- Get i2c capabilities (``I2C_FUNCS``)
It is developed for Python 3.8+.
More information about updates and general changes are recorded in the
`change
log <https://github.com/eindiran/smbus3/blob/master/CHANGELOG.md>`__.
**NOTE:** this library leverages the ``ioctl`` syscall on Unix-like
operating systems. It **WILL NOT** work on Windows and Windows will
never be supported.
OSes leveraging the Linux kernel are the primary testbed for the
library, but if you try it out on \*BSD and find a bug or problem,
please `open an issue <https://github.com/eindiran/smbus3/issues>`__.
SMBus code examples
-------------------
smbus3 installs next to smbus / smbus2 as the package, so it’s not
really a 100% replacement. You must change the module name.
Example 1a: Read a byte
~~~~~~~~~~~~~~~~~~~~~~~
.. code:: python
from smbus3 import SMBus
# Open i2c bus 1 and read one byte from address 80, offset 0
bus = SMBus(1)
b = bus.read_byte_data(80, 0)
print(b)
bus.close()
Example 1b: Read a byte using ``with``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the very same example but safer to use since the ``SMBus``
object will be closed automatically when exiting the ``with`` block.
.. code:: python
from smbus3 import SMBus
with SMBus(1) as bus:
b = bus.read_byte_data(80, 0)
print(b)
Example 1c: Read a byte with PEC enabled
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Same example with Packet Error Checking enabled.
.. code:: python
from smbus3 import SMBus
with SMBus(1) as bus:
bus.pec = 1 # Enable PEC
b = bus.read_byte_data(80, 0)
print(b)
Example 1d: Read a byte with 10bit addressing enabled
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code:: python
from smbus3 import SMBus
with SMBus(1) as bus:
bus.tenbit = 1 # Enable 10bit addressing
b = bus.read_byte_data(80, 0)
print(b)
Example 1e: Read a byte with manually specified timeout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Timeout can be specified in units of 10ms:
.. code:: python
from smbus3 import SMBus
with SMBus(1) as bus:
bus.set_timeout(30) # Specify a timeout of 300ms
b = bus.read_byte_data(80, 0)
print(b)
Example 1f: Read a byte with manually specified retries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retries can be specified using ``set_retries()``:
.. code:: python
from smbus3 import SMBus
with SMBus(1) as bus:
bus.set_retries(5) # Retry up to 5 times
b = bus.read_byte_data(80, 0)
print(b)
Example 2: Read a block of data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can read up to 32 bytes at once.
.. code:: python
from smbus3 import SMBus
with SMBus(1) as bus:
# Read a block of 16 bytes from address 80, offset 0
block = bus.read_i2c_block_data(80, 0, 16)
# Returned value is a list of 16 bytes
print(block)
Example 3: Write a byte
~~~~~~~~~~~~~~~~~~~~~~~
.. code:: python
from smbus3 import SMBus
with SMBus(1) as bus:
# Write 3 bytes to address 80, offset 0:
data = 45
bus.write_byte_data(80, 0, data)
data = 0x1F
bus.write_byte_data(80, 0, data)
data = b"\x00"
bus.write_byte_data(80, 0, data)
Example 4: Write a block of data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is possible to write 32 bytes at the time, but that may be
error-prone on some platforms.
Write fewer bytes and add a delay in between if you run into trouble.
.. code:: python
from smbus3 import SMBus
with SMBus(1) as bus:
# Write a block of 8 bytes to address 80 from offset 0
data = [1, 2, 3, 4, 5, 6, 7, 8]
bus.write_i2c_block_data(80, 0, data)
with SMBus(1) as bus:
# Write a block of the maximum size (32 bytes) to address 80 from offset 0:
data = [_ for _ in range(1, 32 + 1)]
bus.write_i2c_block_data(80, 0, data)
with SMBus(1) as bus:
# THIS WILL FAIL WITH ValueError, AS IT EXCEEDS I2C_SMBUS_BLOCK_MAX!
data = [_ for _ in range(1, 33 + 1)]
bus.write_i2c_block_data(80, 0, data)
I2C
---
The smbus3 library also has support for combined read and write
transactions. ``i2c_rdwr`` is not really a SMBus feature but comes in
handy when the master needs to:
1. Read or write bulks of data larger than SMBus’ 32 bytes limit.
2. Write some data and then read from the slave with a repeated start
and no stop bit between.
Each operation is represented by a ``i2c_msg`` message object.
Example 5: Single ``i2c_rdwr``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To perform a single read or write, simply create a message using
``i2c_msg.read()`` or ``i2c_msg.write()``, then pass the message to the
``i2c_rdwr()`` method on the bus:
.. code:: python
from smbus3 import SMBus, i2c_msg
with SMBus(1) as bus:
# Read 64 bytes from address 80
msg = i2c_msg.read(80, 64)
bus.i2c_rdwr(msg)
# Write a single byte to address 80
msg = i2c_msg.write(80, [65])
bus.i2c_rdwr(msg)
# Write some bytes to address 80
msg = i2c_msg.write(80, [65, 66, 67, 68])
bus.i2c_rdwr(msg)
Example 6: Dual ``i2c_rdwr``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To perform dual operations just add more ``i2c_msg`` instances to the
bus call:
.. code:: python
from smbus3 import SMBus, i2c_msg
# Single transaction writing two bytes then read two at address 80
write = i2c_msg.write(80, [40, 50])
read = i2c_msg.read(80, 2)
with SMBus(1) as bus:
bus.i2c_rdwr(write, read)
Example 7: Single ``i2c_rd``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To perform a single read (combining ``i2c_msg`` creation and calling
``i2c_rdwr`` on a single message into a single method call):
.. code:: python
from smbus3 import SMBus
with SMBus(1) as bus:
# Read 64 bytes from address 80
bus.i2c_rd(80, 64)
Example 8: Single ``i2c_wr``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To perform a single write (combining ``i2c_msg`` creation and calling
``i2c_rdwr`` on a single message into a single function call):
.. code:: python
from smbus3 import SMBus
with SMBus(1) as bus:
# Write a single byte to address 80
bus.i2c_wr(80, [65])
# Write some bytes to address 80
bus.i2c_wr(80, [65, 66, 67, 68])
Example 9: Access ``i2c_msg`` data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
All data is contained in the ``i2c_msg`` instances. Here are some data
access alternatives.
.. code:: python
# 1: Convert message content to list
msg = i2c_msg.write(60, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
data = list(msg) # data = [1, 2, 3, ...]
print(len(data)) # => 10
# 2: i2c_msg is iterable
for value in msg:
print(value)
# 3: Through i2c_msg properties
for k in range(msg.len):
print(msg.buf[k])
Installation
------------
To install from PyPI, use ``pip``:
::
pip3 install smbus3
To install from source, simply run the following command from the top of the repo:
::
pip3 install .
Local development
-----------------
For local development, you can use the included ``Makefile`` to perform
tasks:
::
# EG:
make all
# To show available commands, you can use:
make help
# Or alternatively bare make:
make
Currently available targets:
- ``all``: softclean the directory, then create the venv if it doesn’t exist, and run all common development tasks (install commit hooks, lint, format, typecheck, coverage, and then build documentation).
- ``buildpkg``: hardclean the directory, then run pre-build tests, then build the ``.whl``
- ``buildsdist``: build source distribution only
- ``buildwhl``: build wheel binary distribution only
- ``check_coverage``: check current test coverage, fails if below 90%
- ``clean``: fully clean repo dir, including artifacts and ``.venv``
- ``coverage``: generate coverage info on the CLI
- ``coverage_html_report``: generate coverage info as an HTML document
- ``coverage_xml_report``: generate coverage info as a XML document
- ``docs``: generate the man page and HTML docs
- ``docs_html``: generate the HTML docs
- ``docs_man_page``: generate the man page
- ``format``: format the code and tests with Ruff
- ``lint``: lint the code and tests with Ruff
- ``precommit``: install precommit hooks
- ``softclean``: clean up artifacts without removing ``.venv``
- ``test``: run the unit tests
- ``testpkg``: hardclean, ``buildpkg``, then install and test with the installed version
- ``testreleased``: install released version of the package with ``pip``, then run tests
- ``typecheck``: run mypy typechecking on the smbus3 library
- ``venv``: build a venv
Acknowledgements
----------------
This project is built entirely on the foundation of the
`smbus2 <https://github.com/kplindegaard/smbus2>`__ library for Python 2
& 3, written by Karl-Petter Lindegaard (@kplindegaard).
Changelog
=========
Notable changes to `smbus3 <https://github.com/eindiran/smbus3>`__ are
recorded here.
[0.5.5] - 2024-06-28
--------------------
- Fix Twine issues with importlib-metadata (see issue `here <https://github.com/pypa/twine/issues/1125>`__).
- Enable Python3.8 support
[0.5.4] - 2024-06-14
--------------------
- Expand typing stubs with more accurate defaults
- Expanded ``Makefile`` tasks with better control over ``pip cache purge`` and ``pip uninstall smbus3``, more options for building the wheel or sdist only
- Improve packaging metadata
- Specify minimum Python version and suggest platforms
- Test vs ``smbus3`` library version matching test
- Development tooling support: create issue templates, add support for validating GitHub Actions workflows with ``action-validator`` pre-commit hook.
[0.5.3] - 2024-06-13
--------------------
- Fix broken ``setup.cfg``
- Purge ``pip`` cache on ``testreleased``
[0.5.2] - 2024-06-13
--------------------
- BROKEN DO NOT USE
- Switch to using ``setup.cfg`` for configuration metadata.
- Ensure packages are generated without ``bdist_wheel`` option ``universal``, as Python 2 and Windows aren't supported.
- Add testing option in Makefile for using the PyPI package
- Update documentation with current Makefile tasks
[0.5.1] - 2024-06-13
--------------------
- Documentation updates.
- Remove MANIFEST.in
[0.5.0] - 2024-06-13
--------------------
- Initial version of ``smbus3`` published.
- Split from `smbus2 <https://github.com/kplindegaard/smbus2>`__ and
refactor.
- Remove Python 2 support and no longer list pre-3.9 Python 3s.
- Add automated local dev tooling.
- Reach 100% coverage in unit tests.
- Add support for 10bit addressing.
- Add support for setting retry count manually.
- Add support for setting timeout manually.
- Update type stubs.
Raw data
{
"_id": null,
"home_page": "https://github.com/eindiran/smbus3",
"name": "smbus3",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "smbus, smbus2, smbus3, python, i2c, raspberrypi, linux",
"author": "Elliott Indiran",
"author_email": "elliott.indiran@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/75/39/4b7fe2b7cfb42a39e5bb4ef2970a3befc0febbf2b5b8ef85fac04ca6dcb3/smbus3-0.5.5.tar.gz",
"platform": "linux",
"description": "\n|build-and-test| |codeql| |docs| |coverage|\n\n|versions| |package| |commits-since| |license|\n\n.. |build-and-test| image:: https://github.com/eindiran/smbus3/actions/workflows/python-build-and-test.yml/badge.svg?branch=master\n :target: https://github.com/eindiran/smbus3/actions/workflows/python-build-and-test.yml\n :alt: Build and tests\n.. |codeql| image:: https://github.com/eindiran/smbus3/actions/workflows/codeql-analysis.yml/badge.svg?branch=master\n :target: https://github.com/eindiran/smbus3/actions/workflows/codeql-analysis.yml\n :alt: CodeQL security analysis\n.. |docs| image:: https://readthedocs.org/projects/smbus3/badge/?version=latest\n :target: https://smbus3.readthedocs.io/en/latest/\n :alt: Documentation\n.. |coverage| image:: https://raw.githubusercontent.com/eindiran/smbus3/badges/.github/badges/coverage.svg\n :target: https://github.com/eindiran/smbus3/actions/workflows/coverage-master.yml\n :alt: Test coverage on master\n.. |versions| image:: https://img.shields.io/pypi/pyversions/smbus3.svg\n :alt: Python versions\n.. |package| image:: https://img.shields.io/pypi/v/smbus3.svg\n :target: ttps://pypi.org/project/smbus3/\n :alt: PyPI package\n.. |commits-since| image:: https://img.shields.io/github/commits-since/eindiran/smbus3/latest.svg?color=green\n :target: https://github.com/eindiran/smbus3/releases/latest\n :alt: Commits on master since release\n.. |license| image:: https://img.shields.io/badge/License-MIT-blue.svg\n :target: https://opensource.org/license/MIT\n :alt: MIT\n\n\nWhat is `smbus3`\n================\n\n\nA drop-in replacement for `smbus2 <https://pypi.org/project/smbus2/>`__,\n`smbus-cffi <https://pypi.org/project/smbus-cffi/>`__, or\n`smbus-python <https://pypi.org/project/smbus/>`__ written in pure\nPython and intended for use with Python 3.8+.\n\nThis library was forked from @kplindegaard\u2019s excellent\n`smbus2 <https://github.com/kplindegaard/smbus2>`__. If you need a\npackage that works with Python 2.7 - 3.7, smbus2 is the way to go.\n\n\nIntroduction\n------------\n\nsmbus3 is a Python 3 implementation of the SMBus interface for use in\nPython 3. It should be a drop-in replacement of both the original\n`smbus package <https://pypi.org/project/smbus/>`__, the C-FFI\n`smbus-cffi package <https://pypi.org/project/smbus-cffi/>`__ and\nthe pure Python `smbus2\npackage <https://pypi.org/project/smbus2/>`__. The interfaces will be\nshared for backwards compatibility with ``smbus2``.\n\nCurrently supported features are:\n\n- Context manager-like control of ``SMBus`` objects\n- SMBus Packet Error Checking (PEC) support\n\n - ``enable_pec()``\n\n- 10bit addressing support\n\n - ``enable_tenbit()``\n\n- Manual control over retries and timeouts\n\n - ``set_retries()``\n - ``set_timeout()``\n\n- Create raw ``i2c_msg`` messages\n- ``read_byte()``\n- ``write_byte()``\n- ``read_byte_data()``\n- ``write_byte_data()``\n- ``read_word_data()``\n- ``write_word_data()``\n- ``read_i2c_block_data()``\n- ``write_i2c_block_data()``\n- ``write_quick()``\n- ``process_call()``\n- ``read_block_data()``\n- ``write_block_data()``\n- ``block_process_call()``\n- ``i2c_rdwr()`` - *combined write/read transactions with repeated\n start*\n- ``i2c_rd()`` - single read via ``i2c_rdwr``\n- ``i2c_wr()`` - single write via ``i2c_rdwr``\n- Get i2c capabilities (``I2C_FUNCS``)\n\nIt is developed for Python 3.8+.\n\nMore information about updates and general changes are recorded in the\n`change\nlog <https://github.com/eindiran/smbus3/blob/master/CHANGELOG.md>`__.\n\n**NOTE:** this library leverages the ``ioctl`` syscall on Unix-like\noperating systems. It **WILL NOT** work on Windows and Windows will\nnever be supported.\n\nOSes leveraging the Linux kernel are the primary testbed for the\nlibrary, but if you try it out on \\*BSD and find a bug or problem,\nplease `open an issue <https://github.com/eindiran/smbus3/issues>`__.\n\nSMBus code examples\n-------------------\n\nsmbus3 installs next to smbus / smbus2 as the package, so it\u2019s not\nreally a 100% replacement. You must change the module name.\n\nExample 1a: Read a byte\n~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code:: python\n\n from smbus3 import SMBus\n\n # Open i2c bus 1 and read one byte from address 80, offset 0\n bus = SMBus(1)\n b = bus.read_byte_data(80, 0)\n print(b)\n bus.close()\n\nExample 1b: Read a byte using ``with``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThis is the very same example but safer to use since the ``SMBus``\nobject will be closed automatically when exiting the ``with`` block.\n\n.. code:: python\n\n from smbus3 import SMBus\n\n with SMBus(1) as bus:\n b = bus.read_byte_data(80, 0)\n print(b)\n\nExample 1c: Read a byte with PEC enabled\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nSame example with Packet Error Checking enabled.\n\n.. code:: python\n\n from smbus3 import SMBus\n\n with SMBus(1) as bus:\n bus.pec = 1 # Enable PEC\n b = bus.read_byte_data(80, 0)\n print(b)\n\nExample 1d: Read a byte with 10bit addressing enabled\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code:: python\n\n from smbus3 import SMBus\n\n with SMBus(1) as bus:\n bus.tenbit = 1 # Enable 10bit addressing\n b = bus.read_byte_data(80, 0)\n print(b)\n\nExample 1e: Read a byte with manually specified timeout\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTimeout can be specified in units of 10ms:\n\n.. code:: python\n\n from smbus3 import SMBus\n\n with SMBus(1) as bus:\n bus.set_timeout(30) # Specify a timeout of 300ms\n b = bus.read_byte_data(80, 0)\n print(b)\n\nExample 1f: Read a byte with manually specified retries\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nRetries can be specified using ``set_retries()``:\n\n.. code:: python\n\n from smbus3 import SMBus\n\n with SMBus(1) as bus:\n bus.set_retries(5) # Retry up to 5 times\n b = bus.read_byte_data(80, 0)\n print(b)\n\nExample 2: Read a block of data\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nYou can read up to 32 bytes at once.\n\n.. code:: python\n\n from smbus3 import SMBus\n\n with SMBus(1) as bus:\n # Read a block of 16 bytes from address 80, offset 0\n block = bus.read_i2c_block_data(80, 0, 16)\n # Returned value is a list of 16 bytes\n print(block)\n\nExample 3: Write a byte\n~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code:: python\n\n from smbus3 import SMBus\n\n with SMBus(1) as bus:\n # Write 3 bytes to address 80, offset 0:\n data = 45\n bus.write_byte_data(80, 0, data)\n data = 0x1F\n bus.write_byte_data(80, 0, data)\n data = b\"\\x00\"\n bus.write_byte_data(80, 0, data)\n\nExample 4: Write a block of data\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nIt is possible to write 32 bytes at the time, but that may be\nerror-prone on some platforms.\n\nWrite fewer bytes and add a delay in between if you run into trouble.\n\n.. code:: python\n\n from smbus3 import SMBus\n\n with SMBus(1) as bus:\n # Write a block of 8 bytes to address 80 from offset 0\n data = [1, 2, 3, 4, 5, 6, 7, 8]\n bus.write_i2c_block_data(80, 0, data)\n\n with SMBus(1) as bus:\n # Write a block of the maximum size (32 bytes) to address 80 from offset 0:\n data = [_ for _ in range(1, 32 + 1)]\n bus.write_i2c_block_data(80, 0, data)\n\n with SMBus(1) as bus:\n # THIS WILL FAIL WITH ValueError, AS IT EXCEEDS I2C_SMBUS_BLOCK_MAX!\n data = [_ for _ in range(1, 33 + 1)]\n bus.write_i2c_block_data(80, 0, data)\n\nI2C\n---\n\nThe smbus3 library also has support for combined read and write\ntransactions. ``i2c_rdwr`` is not really a SMBus feature but comes in\nhandy when the master needs to:\n\n1. Read or write bulks of data larger than SMBus\u2019 32 bytes limit.\n2. Write some data and then read from the slave with a repeated start\n and no stop bit between.\n\nEach operation is represented by a ``i2c_msg`` message object.\n\nExample 5: Single ``i2c_rdwr``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTo perform a single read or write, simply create a message using\n``i2c_msg.read()`` or ``i2c_msg.write()``, then pass the message to the\n``i2c_rdwr()`` method on the bus:\n\n.. code:: python\n\n from smbus3 import SMBus, i2c_msg\n\n with SMBus(1) as bus:\n # Read 64 bytes from address 80\n msg = i2c_msg.read(80, 64)\n bus.i2c_rdwr(msg)\n\n # Write a single byte to address 80\n msg = i2c_msg.write(80, [65])\n bus.i2c_rdwr(msg)\n\n # Write some bytes to address 80\n msg = i2c_msg.write(80, [65, 66, 67, 68])\n bus.i2c_rdwr(msg)\n\nExample 6: Dual ``i2c_rdwr``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTo perform dual operations just add more ``i2c_msg`` instances to the\nbus call:\n\n.. code:: python\n\n from smbus3 import SMBus, i2c_msg\n\n # Single transaction writing two bytes then read two at address 80\n write = i2c_msg.write(80, [40, 50])\n read = i2c_msg.read(80, 2)\n with SMBus(1) as bus:\n bus.i2c_rdwr(write, read)\n\nExample 7: Single ``i2c_rd``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTo perform a single read (combining ``i2c_msg`` creation and calling\n``i2c_rdwr`` on a single message into a single method call):\n\n.. code:: python\n\n from smbus3 import SMBus\n\n with SMBus(1) as bus:\n # Read 64 bytes from address 80\n bus.i2c_rd(80, 64)\n\nExample 8: Single ``i2c_wr``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTo perform a single write (combining ``i2c_msg`` creation and calling\n``i2c_rdwr`` on a single message into a single function call):\n\n.. code:: python\n\n from smbus3 import SMBus\n\n with SMBus(1) as bus:\n # Write a single byte to address 80\n bus.i2c_wr(80, [65])\n\n # Write some bytes to address 80\n bus.i2c_wr(80, [65, 66, 67, 68])\n\nExample 9: Access ``i2c_msg`` data\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nAll data is contained in the ``i2c_msg`` instances. Here are some data\naccess alternatives.\n\n.. code:: python\n\n # 1: Convert message content to list\n msg = i2c_msg.write(60, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])\n data = list(msg) # data = [1, 2, 3, ...]\n print(len(data)) # => 10\n\n # 2: i2c_msg is iterable\n for value in msg:\n print(value)\n\n # 3: Through i2c_msg properties\n for k in range(msg.len):\n print(msg.buf[k])\n\nInstallation\n------------\n\nTo install from PyPI, use ``pip``:\n\n::\n\n pip3 install smbus3\n\n\nTo install from source, simply run the following command from the top of the repo:\n\n::\n\n pip3 install .\n\nLocal development\n-----------------\n\nFor local development, you can use the included ``Makefile`` to perform\ntasks:\n\n::\n\n # EG:\n make all\n # To show available commands, you can use:\n make help\n # Or alternatively bare make:\n make\n\nCurrently available targets:\n\n- ``all``: softclean the directory, then create the venv if it doesn\u2019t exist, and run all common development tasks (install commit hooks, lint, format, typecheck, coverage, and then build documentation).\n- ``buildpkg``: hardclean the directory, then run pre-build tests, then build the ``.whl``\n- ``buildsdist``: build source distribution only\n- ``buildwhl``: build wheel binary distribution only\n- ``check_coverage``: check current test coverage, fails if below 90%\n- ``clean``: fully clean repo dir, including artifacts and ``.venv``\n- ``coverage``: generate coverage info on the CLI\n- ``coverage_html_report``: generate coverage info as an HTML document\n- ``coverage_xml_report``: generate coverage info as a XML document\n- ``docs``: generate the man page and HTML docs\n- ``docs_html``: generate the HTML docs\n- ``docs_man_page``: generate the man page\n- ``format``: format the code and tests with Ruff\n- ``lint``: lint the code and tests with Ruff\n- ``precommit``: install precommit hooks\n- ``softclean``: clean up artifacts without removing ``.venv``\n- ``test``: run the unit tests\n- ``testpkg``: hardclean, ``buildpkg``, then install and test with the installed version\n- ``testreleased``: install released version of the package with ``pip``, then run tests\n- ``typecheck``: run mypy typechecking on the smbus3 library\n- ``venv``: build a venv\n\n\nAcknowledgements\n----------------\n\nThis project is built entirely on the foundation of the\n`smbus2 <https://github.com/kplindegaard/smbus2>`__ library for Python 2\n& 3, written by Karl-Petter Lindegaard (@kplindegaard).\n\nChangelog\n=========\n\nNotable changes to `smbus3 <https://github.com/eindiran/smbus3>`__ are\nrecorded here.\n\n[0.5.5] - 2024-06-28\n--------------------\n\n- Fix Twine issues with importlib-metadata (see issue `here <https://github.com/pypa/twine/issues/1125>`__).\n- Enable Python3.8 support\n\n[0.5.4] - 2024-06-14\n--------------------\n\n- Expand typing stubs with more accurate defaults\n- Expanded ``Makefile`` tasks with better control over ``pip cache purge`` and ``pip uninstall smbus3``, more options for building the wheel or sdist only\n- Improve packaging metadata\n- Specify minimum Python version and suggest platforms\n- Test vs ``smbus3`` library version matching test\n- Development tooling support: create issue templates, add support for validating GitHub Actions workflows with ``action-validator`` pre-commit hook.\n\n[0.5.3] - 2024-06-13\n--------------------\n\n- Fix broken ``setup.cfg``\n- Purge ``pip`` cache on ``testreleased``\n\n[0.5.2] - 2024-06-13\n--------------------\n\n- BROKEN DO NOT USE\n- Switch to using ``setup.cfg`` for configuration metadata.\n- Ensure packages are generated without ``bdist_wheel`` option ``universal``, as Python 2 and Windows aren't supported.\n- Add testing option in Makefile for using the PyPI package\n- Update documentation with current Makefile tasks\n\n[0.5.1] - 2024-06-13\n--------------------\n\n- Documentation updates.\n- Remove MANIFEST.in\n\n[0.5.0] - 2024-06-13\n--------------------\n\n- Initial version of ``smbus3`` published.\n- Split from `smbus2 <https://github.com/kplindegaard/smbus2>`__ and\n refactor.\n- Remove Python 2 support and no longer list pre-3.9 Python 3s.\n- Add automated local dev tooling.\n- Reach 100% coverage in unit tests.\n- Add support for 10bit addressing.\n- Add support for setting retry count manually.\n- Add support for setting timeout manually.\n- Update type stubs.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "smbus3 is a drop-in replacement for smbus2, smbus-cffi, smbus-python written in pure Python, intended for use with Python 3.8+ on Unix-like systems",
"version": "0.5.5",
"project_urls": {
"Homepage": "https://github.com/eindiran/smbus3"
},
"split_keywords": [
"smbus",
" smbus2",
" smbus3",
" python",
" i2c",
" raspberrypi",
" linux"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f5cfa0cfae35dac3e3d0b1b4242c8ba184616a47550f8c727b0df654d4338e2d",
"md5": "bce0b4fba664135a60404cd612bb6564",
"sha256": "7f4cc169975543e67e4b7404168ce918e656f6f8daca5de2bd30527298058083"
},
"downloads": -1,
"filename": "smbus3-0.5.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bce0b4fba664135a60404cd612bb6564",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13616,
"upload_time": "2024-06-29T01:55:16",
"upload_time_iso_8601": "2024-06-29T01:55:16.434150Z",
"url": "https://files.pythonhosted.org/packages/f5/cf/a0cfae35dac3e3d0b1b4242c8ba184616a47550f8c727b0df654d4338e2d/smbus3-0.5.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "75394b7fe2b7cfb42a39e5bb4ef2970a3befc0febbf2b5b8ef85fac04ca6dcb3",
"md5": "b91ad60fc68ec197204a5ca2113554ae",
"sha256": "91eed38fb6b7d2f893fbfc3f37006aa41e6913fdda5b3a9a79238b353760f92e"
},
"downloads": -1,
"filename": "smbus3-0.5.5.tar.gz",
"has_sig": false,
"md5_digest": "b91ad60fc68ec197204a5ca2113554ae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22100,
"upload_time": "2024-06-29T01:55:18",
"upload_time_iso_8601": "2024-06-29T01:55:18.214448Z",
"url": "https://files.pythonhosted.org/packages/75/39/4b7fe2b7cfb42a39e5bb4ef2970a3befc0febbf2b5b8ef85fac04ca6dcb3/smbus3-0.5.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-29 01:55:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eindiran",
"github_project": "smbus3",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "smbus3"
}
JSON
