# smbus2
A drop-in replacement for smbus-cffi/smbus-python in pure Python
[](https://github.com/kplindegaard/smbus2/actions/workflows/python-build-test.yml)
[](http://smbus2.readthedocs.io/en/latest/?badge=latest)
[](https://sonarcloud.io/dashboard?id=kplindegaard_smbus2)
[](https://pypi.org/project/smbus2/)
[](https://pypi.org/project/smbus2/)
# Introduction
smbus2 is (yet another) pure Python implementation of the [python-smbus](http://www.lm-sensors.org/browser/i2c-tools/trunk/py-smbus/) package.
It was designed from the ground up with two goals in mind:
1. It should be a drop-in replacement of smbus. The syntax shall be the same.
2. Use the inherent i2c structs and unions to a greater extent than other pure Python implementations like [pysmbus](https://github.com/bjornt/pysmbus) does. By doing so, it will be more feature complete and easier to extend.
Currently supported features are:
* Get i2c capabilities (I2C_FUNCS)
* SMBus Packet Error Checking (PEC) support
* 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*
It is developed on Python 2.7 but works without any modifications in Python 3.X too.
More information about updates and general changes are recorded in the [change log](https://github.com/kplindegaard/smbus2/blob/master/CHANGELOG.md).
# SMBus code examples
smbus2 installs next to smbus as the package, so it's not really a 100% replacement. You must change the module name.
## Example 1a: Read a byte
```python
from smbus2 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 will be closed automatically when exiting the with block.
```python
from smbus2 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.
```python
from smbus2 import SMBus
with SMBus(1) as bus:
bus.pec = 1 # Enable PEC
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.
```python
from smbus2 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
```python
from smbus2 import SMBus
with SMBus(1) as bus:
# Write a byte to address 80, offset 0
data = 45
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 I have found that error-prone. Write less and add a delay in between if you run into trouble.
```python
from smbus2 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)
```
# I2C
Starting with v0.2, the smbus2 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.
1. 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
```python
from smbus2 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:
```python
from smbus2 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: Access i2c_msg data
All data is contained in the i2c_msg instances. Here are some data access alternatives.
```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 instructions
From [PyPi](https://pypi.org/) with `pip`:
```
pip install smbus2
```
From [conda-forge](https://anaconda.org/conda-forge) using `conda`:
```
conda install -c conda-forge smbus2
```
Installation from source code is straight forward:
```
python setup.py install
```
Raw data
{
"_id": null,
"home_page": "https://github.com/kplindegaard/smbus2",
"name": "smbus2",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "smbus,smbus2,python,i2c,raspberrypi,linux",
"author": "Karl-Petter Lindegaard",
"author_email": "kp.lindegaard@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/98/17/9663936e52a348b3ad1c85e6ca6071d2abf00a5f64f2df50bec8dcca6e16/smbus2-0.4.3.tar.gz",
"platform": null,
"description": "# smbus2\nA drop-in replacement for smbus-cffi/smbus-python in pure Python\n\n[](https://github.com/kplindegaard/smbus2/actions/workflows/python-build-test.yml)\n[](http://smbus2.readthedocs.io/en/latest/?badge=latest)\n\n[](https://sonarcloud.io/dashboard?id=kplindegaard_smbus2)\n\n\n[](https://pypi.org/project/smbus2/)\n[](https://pypi.org/project/smbus2/)\n\n# Introduction\n\nsmbus2 is (yet another) pure Python implementation of the [python-smbus](http://www.lm-sensors.org/browser/i2c-tools/trunk/py-smbus/) package.\n\nIt was designed from the ground up with two goals in mind:\n\n1. It should be a drop-in replacement of smbus. The syntax shall be the same.\n2. Use the inherent i2c structs and unions to a greater extent than other pure Python implementations like [pysmbus](https://github.com/bjornt/pysmbus) does. By doing so, it will be more feature complete and easier to extend.\n\nCurrently supported features are:\n\n* Get i2c capabilities (I2C_FUNCS)\n* SMBus Packet Error Checking (PEC) support\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 start*\n\nIt is developed on Python 2.7 but works without any modifications in Python 3.X too.\n\nMore information about updates and general changes are recorded in the [change log](https://github.com/kplindegaard/smbus2/blob/master/CHANGELOG.md).\n\n# SMBus code examples\n\nsmbus2 installs next to smbus as the package, so it's not really a 100% replacement. You must change the module name.\n\n## Example 1a: Read a byte\n\n```python\nfrom smbus2 import SMBus\n\n# Open i2c bus 1 and read one byte from address 80, offset 0\nbus = SMBus(1)\nb = bus.read_byte_data(80, 0)\nprint(b)\nbus.close()\n```\n\n## Example 1b: Read a byte using 'with'\n\nThis is the very same example but safer to use since the smbus will be closed automatically when exiting the with block.\n\n```python\nfrom smbus2 import SMBus\n\nwith SMBus(1) as bus:\n b = bus.read_byte_data(80, 0)\n print(b)\n```\n\n## Example 1c: Read a byte with PEC enabled\n\nSame example with Packet Error Checking enabled.\n\n```python\nfrom smbus2 import SMBus\n\nwith SMBus(1) as bus:\n bus.pec = 1 # Enable PEC\n b = bus.read_byte_data(80, 0)\n print(b)\n```\n\n## Example 2: Read a block of data\n\nYou can read up to 32 bytes at once.\n\n```python\nfrom smbus2 import SMBus\n\nwith 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```\n\n## Example 3: Write a byte\n\n```python\nfrom smbus2 import SMBus\n\nwith SMBus(1) as bus:\n # Write a byte to address 80, offset 0\n data = 45\n bus.write_byte_data(80, 0, data)\n```\n\n## Example 4: Write a block of data\n\nIt is possible to write 32 bytes at the time, but I have found that error-prone. Write less and add a delay in between if you run into trouble.\n\n```python\nfrom smbus2 import SMBus\n\nwith 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\n# I2C\n\nStarting with v0.2, the smbus2 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:\n\n1. read or write bulks of data larger than SMBus' 32 bytes limit.\n1. write some data and then read from the slave with a repeated start and no stop bit between.\n\nEach operation is represented by a *i2c_msg* message object.\n\n\n## Example 5: Single i2c_rdwr\n\n```python\nfrom smbus2 import SMBus, i2c_msg\n\nwith 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```\n\n## Example 6: Dual i2c_rdwr\n\nTo perform dual operations just add more i2c_msg instances to the bus call:\n\n```python\nfrom smbus2 import SMBus, i2c_msg\n\n# Single transaction writing two bytes then read two at address 80\nwrite = i2c_msg.write(80, [40, 50])\nread = i2c_msg.read(80, 2)\nwith SMBus(1) as bus:\n bus.i2c_rdwr(write, read)\n```\n\n## Example 7: Access i2c_msg data\n\nAll data is contained in the i2c_msg instances. Here are some data access alternatives.\n\n```python\n# 1: Convert message content to list\nmsg = i2c_msg.write(60, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])\ndata = list(msg) # data = [1, 2, 3, ...]\nprint(len(data)) # => 10\n\n# 2: i2c_msg is iterable\nfor value in msg:\n print(value)\n\n# 3: Through i2c_msg properties\nfor k in range(msg.len):\n print(msg.buf[k])\n```\n\n# Installation instructions\n\nFrom [PyPi](https://pypi.org/) with `pip`:\n\n```\npip install smbus2\n```\n\nFrom [conda-forge](https://anaconda.org/conda-forge) using `conda`:\n\n```\nconda install -c conda-forge smbus2\n```\n\nInstallation from source code is straight forward:\n\n```\npython setup.py install\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "smbus2 is a drop-in replacement for smbus-cffi/smbus-python in pure Python",
"version": "0.4.3",
"project_urls": {
"Homepage": "https://github.com/kplindegaard/smbus2"
},
"split_keywords": [
"smbus",
"smbus2",
"python",
"i2c",
"raspberrypi",
"linux"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d65b3ada173f07b4ec9bfa03b779e59ecada48eb7cb1a29f51cfce70edce7f3f",
"md5": "56aff25f186cc5d7af2d5b4274622c0d",
"sha256": "a2fc29cfda4081ead2ed61ef2c4fc041d71dd40a8d917e85216f44786fca2d1d"
},
"downloads": -1,
"filename": "smbus2-0.4.3-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "56aff25f186cc5d7af2d5b4274622c0d",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 11553,
"upload_time": "2023-08-25T19:55:23",
"upload_time_iso_8601": "2023-08-25T19:55:23.170110Z",
"url": "https://files.pythonhosted.org/packages/d6/5b/3ada173f07b4ec9bfa03b779e59ecada48eb7cb1a29f51cfce70edce7f3f/smbus2-0.4.3-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "98179663936e52a348b3ad1c85e6ca6071d2abf00a5f64f2df50bec8dcca6e16",
"md5": "ab83d83e9eb3bd1d0bef8d6fd64b1398",
"sha256": "36f2288a8e1a363cb7a7b2244ec98d880eb5a728a2494ac9c71e9de7bf6a803a"
},
"downloads": -1,
"filename": "smbus2-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "ab83d83e9eb3bd1d0bef8d6fd64b1398",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16801,
"upload_time": "2023-08-25T19:55:24",
"upload_time_iso_8601": "2023-08-25T19:55:24.099410Z",
"url": "https://files.pythonhosted.org/packages/98/17/9663936e52a348b3ad1c85e6ca6071d2abf00a5f64f2df50bec8dcca6e16/smbus2-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-25 19:55:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kplindegaard",
"github_project": "smbus2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "smbus2"
}
JSON
