| Name | i2cpy JSON |
| Version |
0.1.3
JSON |
| download |
| home_page | None |
| Summary | Python I2C library supporting multiple driver implementations |
| upload_time | 2024-09-30 14:44:55 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | Copyright (c) 2024 Zhenyi Zhou Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
i2c
ch341
ch341a
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Python I2C library supporting multiple driver implementations
<div>
<img src="https://img.shields.io/badge/python-3.8+-blue.svg" alt="python"/>
<a href="https://pypi.org/project/i2cpy/"><img src="https://img.shields.io/pypi/v/i2cpy.svg" alt="pypi"/></a>
<a href="https://github.com/iynehz/i2cpy/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"/></a>
<img src="https://readthedocs.org/projects/i2cpy/badge/?version=latest" alt="docs"/>
<img src="https://github.com/iynehz/i2cpy/actions/workflows/lint.yml/badge.svg" alt="lint"/>
</div>
## Introduction
I2C is a two-wire protocol for communicating between devices. At the
physical level it consists of 2 wires: SCL and SDA, the clock and data lines
respectively.
I2C objects are created attached to a specific bus. They can be initialized
when created, or initialized later on.
This library is designed to support different I2C driver implementations. At
present below drivers are supported:
* CH341 (CH341A, etc)
The interface is similar to that of MicroPython’s [machine.I2C](https://docs.micropython.org/en/latest/library/machine.I2C.html)
Example usage:
```python
from i2cpy import I2C
i2c = I2C() # create I2C peripheral
i2c.writeto(42, b'123') # write 3 bytes to peripheral with 7-bit address 42
i2c.readfrom(42, 4) # read 4 bytes from peripheral with 7-bit address 42
i2c.readfrom_mem(42, 8, 3) # read 3 bytes from memory of peripheral 42,
# starting at memory address 8 in the peripheral
i2c.writeto_mem(42, 2, b'\x10') # write 1 byte to memory of peripheral 42,
# starting at memory address 2 in the peripheral
```
If you prefer an “int” interface to the “bytes” interface, you can easily write
wrapper functions youself. For example,
```python
# assume you already have a gloal i2c object
def i2c_write(addr: int, memaddr: int, *args):
i2c.writeto_mem(addr, memaddr, bytes(args))
def i2c_read(addr: int, memaddr: int, nbytes: int) -> list[int]:
got = i2c.readfrom_mem(addr, memaddr, nbytes)
return list(got)
```
## Installation
The i2cpy Python module itself can be simply pip installed,
```default
pip intall i2cpy
```
And for the underlying I2C implementations you still need to install their
corresponding drivers.
### ch341
The CH341 series chip (like CH341A) is USB bus converter which converts USB to UART, parallel
port, and common synchronous serial communication interfaces (I2C, SPI).
The chip is manufactured by the company [Qinheng Microelectronics](https://wch-ic.com/).
The ch341 driver shipped with this library is a Python interface to CH341’s
official DLLs.
You need the driver DLL files, which are downloadable from Qinheng’s website.
Windows: [https://www.wch-ic.com/downloads/CH341PAR_ZIP.html](https://www.wch-ic.com/downloads/CH341PAR_ZIP.html)
On Windows it’s recommended to place them
under Windows System32 folder. Or if you place them under a different directory,
you can add that directory to PATH environment variable.
Linux: [https://www.wch-ic.com/downloads/CH341PAR_LINUX_ZIP.html](https://www.wch-ic.com/downloads/CH341PAR_LINUX_ZIP.html)
On Linux you need to build the kernel module from source under the downloaded
zipball’s driver sub-directory like,
```bash
$ cd driver
$ sudo make && sudo make install
```
Also you need to either place the libch347.so file for your platform to system
supported path like /usr/local/lib, or you make the so file loadable by adding
its directory to LD_LIBRARY_PATH environment variable.
MacOS: [https://www.wch-ic.com/download/CH341SER_MAC_ZIP.html](https://www.wch-ic.com/download/CH341SER_MAC_ZIP.html)
I don’t use this library on Mac myself. But let me know if it does not work, and
I can give it a try on Mac.
Example usage:
```python
from i2cpy import I2C
i2c = I2C() # ch341 is the default driver
i2c = I2C(driver="ch341") # explicitly specify driver
i2c = I2C(0, driver="ch341") # override usb id on Windows
i2c = I2C("/dev/ch34x_pis0", driver="ch341") # override usb device on Linux
```
## Class I2C
### Constructor
#### I2C.\_\_init_\_(id=None, \*, driver=None, freq=400000, auto_init=True, \*\*kwargs)
Constructor.
* **Parameters:**
* **id** (`Union`[`str`, `int`, `None`]) – Identifies a particular I2C peripheral. Allowed values depend
on the particular driver implementation.
* **freq** (`int`) – I2C bus baudrate, defaults to 400000
* **driver** (`Optional`[`str`]) – I2C driver name. It corresponds to the I2C driver sub
module name shipped with this library. For example “foo” means module
“i2cpy.driver.foo”.
If not specified, it looks at environment variable “I2CPY_DRIVER”.
And if that’s not defined or empty, it finally falls back to “ch341”.
* **auto_init** (`bool`) – Call init() on object initialization, defaults to True
### General methods
#### I2C.init()
Initialize the I2C bus.
#### I2C.deinit()
Close the I2C bus.
#### I2C.scan(start=8, stop=119)
Scan all I2C addresses between start and stop inclusive
and return a list of those that respond.
A device responds if it pulls the SDA line low after its address
(including a write bit) is sent on the bus.
* **Parameters:**
* **start** (`int`) – start address, defaults to 0x08
* **stop** (`int`) – stop address, defaults to 0x77
* **Return type:**
`List`[`int`]
* **Returns:**
a list of addresses that respond to scan
### Standard bus operations
#### I2C.writeto(addr, buf, /)
Write the bytes from buf to the peripheral specified by addr.
* **Parameters:**
* **addr** (`int`) – I2C peripheral deivce address
* **buf** (`Buffer`) – bytes to write
#### I2C.readfrom(addr, nbytes, /)
Read nbytes from the peripheral specified by addr.
* **Parameters:**
* **addr** (`int`) – I2C peripheral device address
* **nbytes** (`int`) – number of bytes to read
* **Return type:**
`bytes`
* **Returns:**
the bytes read
### Memory operations
#### I2C.writeto_mem(addr, memaddr, buf, \*, addrsize=8)
Write buf to the peripheral specified by addr starting from the
memory address specified by memaddr.
* **Parameters:**
* **addr** (`int`) – I2C peripheral device address
* **memaddr** (`int`) – memory address
* **buf** (`Buffer`) – bytes to write
* **addrsize** (`int`) – \_description_, defaults to 8
#### I2C.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8)
Read *nbytes* from the peripheral specified by *addr* starting from
the memory address specified by *memaddr*.
* **Parameters:**
* **addr** (`int`) – I2C peripheral device address
* **memaddr** (`int`) – memory address
* **nbytes** (`int`) – number of bytes to read
* **addrsize** (`int`) – \_description_, defaults to 8
* **Return type:**
`bytes`
* **Returns:**
the bytes read
#### I2C.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8)
Read into buf from the peripheral specified by addr starting from the
memory address specified by memaddr. The number of bytes read is the
length of buf.
* **Parameters:**
* **addr** (`int`) – I2C peripheral device address
* **memaddr** (`int`) – memory address
* **buf** (`bytearray`) – buffer to store the bytes read
* **addrsize** (`int`) – \_description_, defaults to 8
Raw data
{
"_id": null,
"home_page": null,
"name": "i2cpy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "i2c, ch341, ch341a",
"author": null,
"author_email": "Zhenyi Zhou <iynehz@163.com>",
"download_url": "https://files.pythonhosted.org/packages/84/df/f30e481917d7f7f5e901f1c229c2a9320c576b48a850672b0a5336a988ec/i2cpy-0.1.3.tar.gz",
"platform": null,
"description": "# Python I2C library supporting multiple driver implementations\r\n\r\n<div>\r\n <img src=\"https://img.shields.io/badge/python-3.8+-blue.svg\" alt=\"python\"/>\r\n <a href=\"https://pypi.org/project/i2cpy/\"><img src=\"https://img.shields.io/pypi/v/i2cpy.svg\" alt=\"pypi\"/></a>\r\n <a href=\"https://github.com/iynehz/i2cpy/blob/main/LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"license\"/></a>\r\n <img src=\"https://readthedocs.org/projects/i2cpy/badge/?version=latest\" alt=\"docs\"/>\r\n <img src=\"https://github.com/iynehz/i2cpy/actions/workflows/lint.yml/badge.svg\" alt=\"lint\"/>\r\n</div>\r\n\r\n## Introduction\r\n\r\nI2C is a two-wire protocol for communicating between devices. At the\r\nphysical level it consists of 2 wires: SCL and SDA, the clock and data lines\r\nrespectively.\r\n\r\nI2C objects are created attached to a specific bus. They can be initialized\r\nwhen created, or initialized later on.\r\n\r\nThis library is designed to support different I2C driver implementations. At\r\npresent below drivers are supported:\r\n\r\n* CH341 (CH341A, etc)\r\n\r\nThe interface is similar to that of MicroPython\u2019s [machine.I2C](https://docs.micropython.org/en/latest/library/machine.I2C.html)\r\n\r\nExample usage:\r\n\r\n```python\r\nfrom i2cpy import I2C\r\n\r\ni2c = I2C() # create I2C peripheral\r\n\r\ni2c.writeto(42, b'123') # write 3 bytes to peripheral with 7-bit address 42\r\ni2c.readfrom(42, 4) # read 4 bytes from peripheral with 7-bit address 42\r\n\r\ni2c.readfrom_mem(42, 8, 3) # read 3 bytes from memory of peripheral 42,\r\n # starting at memory address 8 in the peripheral\r\ni2c.writeto_mem(42, 2, b'\\x10') # write 1 byte to memory of peripheral 42,\r\n # starting at memory address 2 in the peripheral\r\n```\r\n\r\nIf you prefer an \u201cint\u201d interface to the \u201cbytes\u201d interface, you can easily write\r\nwrapper functions youself. For example,\r\n\r\n```python\r\n# assume you already have a gloal i2c object\r\n\r\ndef i2c_write(addr: int, memaddr: int, *args):\r\n i2c.writeto_mem(addr, memaddr, bytes(args))\r\n\r\ndef i2c_read(addr: int, memaddr: int, nbytes: int) -> list[int]:\r\n got = i2c.readfrom_mem(addr, memaddr, nbytes)\r\n return list(got)\r\n```\r\n\r\n## Installation\r\n\r\nThe i2cpy Python module itself can be simply pip installed,\r\n\r\n```default\r\npip intall i2cpy\r\n```\r\n\r\nAnd for the underlying I2C implementations you still need to install their\r\ncorresponding drivers.\r\n\r\n### ch341\r\n\r\nThe CH341 series chip (like CH341A) is USB bus converter which converts USB to UART, parallel\r\nport, and common synchronous serial communication interfaces (I2C, SPI).\r\nThe chip is manufactured by the company [Qinheng Microelectronics](https://wch-ic.com/).\r\n\r\nThe ch341 driver shipped with this library is a Python interface to CH341\u2019s\r\nofficial DLLs.\r\n\r\nYou need the driver DLL files, which are downloadable from Qinheng\u2019s website.\r\n\r\nWindows: [https://www.wch-ic.com/downloads/CH341PAR_ZIP.html](https://www.wch-ic.com/downloads/CH341PAR_ZIP.html)\r\n\r\nOn Windows it\u2019s recommended to place them\r\nunder Windows System32 folder. Or if you place them under a different directory,\r\nyou can add that directory to PATH environment variable.\r\n\r\nLinux: [https://www.wch-ic.com/downloads/CH341PAR_LINUX_ZIP.html](https://www.wch-ic.com/downloads/CH341PAR_LINUX_ZIP.html)\r\n\r\nOn Linux you need to build the kernel module from source under the downloaded\r\nzipball\u2019s driver sub-directory like,\r\n\r\n```bash\r\n$ cd driver\r\n$ sudo make && sudo make install\r\n```\r\n\r\nAlso you need to either place the libch347.so file for your platform to system\r\nsupported path like /usr/local/lib, or you make the so file loadable by adding\r\nits directory to LD_LIBRARY_PATH environment variable.\r\n\r\nMacOS: [https://www.wch-ic.com/download/CH341SER_MAC_ZIP.html](https://www.wch-ic.com/download/CH341SER_MAC_ZIP.html)\r\n\r\nI don\u2019t use this library on Mac myself. But let me know if it does not work, and\r\nI can give it a try on Mac.\r\n\r\nExample usage:\r\n\r\n```python\r\nfrom i2cpy import I2C\r\n\r\ni2c = I2C() # ch341 is the default driver\r\ni2c = I2C(driver=\"ch341\") # explicitly specify driver\r\n\r\ni2c = I2C(0, driver=\"ch341\") # override usb id on Windows\r\n\r\ni2c = I2C(\"/dev/ch34x_pis0\", driver=\"ch341\") # override usb device on Linux\r\n```\r\n\r\n## Class I2C\r\n\r\n### Constructor\r\n\r\n#### I2C.\\_\\_init_\\_(id=None, \\*, driver=None, freq=400000, auto_init=True, \\*\\*kwargs)\r\n\r\nConstructor.\r\n\r\n* **Parameters:**\r\n * **id** (`Union`[`str`, `int`, `None`]) \u2013 Identifies a particular I2C peripheral. Allowed values depend\r\n on the particular driver implementation.\r\n * **freq** (`int`) \u2013 I2C bus baudrate, defaults to 400000\r\n * **driver** (`Optional`[`str`]) \u2013 I2C driver name. It corresponds to the I2C driver sub\r\n module name shipped with this library. For example \u201cfoo\u201d means module\r\n \u201ci2cpy.driver.foo\u201d.\r\n If not specified, it looks at environment variable \u201cI2CPY_DRIVER\u201d.\r\n And if that\u2019s not defined or empty, it finally falls back to \u201cch341\u201d.\r\n * **auto_init** (`bool`) \u2013 Call init() on object initialization, defaults to True\r\n\r\n### General methods\r\n\r\n#### I2C.init()\r\n\r\nInitialize the I2C bus.\r\n\r\n#### I2C.deinit()\r\n\r\nClose the I2C bus.\r\n\r\n#### I2C.scan(start=8, stop=119)\r\n\r\nScan all I2C addresses between start and stop inclusive\r\nand return a list of those that respond.\r\nA device responds if it pulls the SDA line low after its address\r\n(including a write bit) is sent on the bus.\r\n\r\n* **Parameters:**\r\n * **start** (`int`) \u2013 start address, defaults to 0x08\r\n * **stop** (`int`) \u2013 stop address, defaults to 0x77\r\n* **Return type:**\r\n `List`[`int`]\r\n* **Returns:**\r\n a list of addresses that respond to scan\r\n\r\n### Standard bus operations\r\n\r\n#### I2C.writeto(addr, buf, /)\r\n\r\nWrite the bytes from buf to the peripheral specified by addr.\r\n\r\n* **Parameters:**\r\n * **addr** (`int`) \u2013 I2C peripheral deivce address\r\n * **buf** (`Buffer`) \u2013 bytes to write\r\n\r\n#### I2C.readfrom(addr, nbytes, /)\r\n\r\nRead nbytes from the peripheral specified by addr.\r\n\r\n* **Parameters:**\r\n * **addr** (`int`) \u2013 I2C peripheral device address\r\n * **nbytes** (`int`) \u2013 number of bytes to read\r\n* **Return type:**\r\n `bytes`\r\n* **Returns:**\r\n the bytes read\r\n\r\n### Memory operations\r\n\r\n#### I2C.writeto_mem(addr, memaddr, buf, \\*, addrsize=8)\r\n\r\nWrite buf to the peripheral specified by addr starting from the\r\nmemory address specified by memaddr.\r\n\r\n* **Parameters:**\r\n * **addr** (`int`) \u2013 I2C peripheral device address\r\n * **memaddr** (`int`) \u2013 memory address\r\n * **buf** (`Buffer`) \u2013 bytes to write\r\n * **addrsize** (`int`) \u2013 \\_description_, defaults to 8\r\n\r\n#### I2C.readfrom_mem(addr, memaddr, nbytes, \\*, addrsize=8)\r\n\r\nRead *nbytes* from the peripheral specified by *addr* starting from\r\nthe memory address specified by *memaddr*.\r\n\r\n* **Parameters:**\r\n * **addr** (`int`) \u2013 I2C peripheral device address\r\n * **memaddr** (`int`) \u2013 memory address\r\n * **nbytes** (`int`) \u2013 number of bytes to read\r\n * **addrsize** (`int`) \u2013 \\_description_, defaults to 8\r\n* **Return type:**\r\n `bytes`\r\n* **Returns:**\r\n the bytes read\r\n\r\n#### I2C.readfrom_mem_into(addr, memaddr, buf, \\*, addrsize=8)\r\n\r\nRead into buf from the peripheral specified by addr starting from the\r\nmemory address specified by memaddr. The number of bytes read is the\r\nlength of buf.\r\n\r\n* **Parameters:**\r\n * **addr** (`int`) \u2013 I2C peripheral device address\r\n * **memaddr** (`int`) \u2013 memory address\r\n * **buf** (`bytearray`) \u2013 buffer to store the bytes read\r\n * **addrsize** (`int`) \u2013 \\_description_, defaults to 8\r\n",
"bugtrack_url": null,
"license": "Copyright (c) 2024 Zhenyi Zhou Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "Python I2C library supporting multiple driver implementations",
"version": "0.1.3",
"project_urls": {
"Documentation": "https://i2cpy.readthedocs.io/en/latest/",
"Homepage": "https://github.com/iynehz/i2cpy",
"Repository": "https://github.com/iynehz/i2cpy"
},
"split_keywords": [
"i2c",
" ch341",
" ch341a"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "72e660ef06efcf66227a5685398438a19ab54306965b36c0b227f55f756d8c34",
"md5": "34cd9c4517d94d290751d9c9225bbba3",
"sha256": "38b19bb9f1649df590d8cbfea33d837450d331df2241e83df9ef3575386d5638"
},
"downloads": -1,
"filename": "i2cpy-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "34cd9c4517d94d290751d9c9225bbba3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12601,
"upload_time": "2024-09-30T14:44:53",
"upload_time_iso_8601": "2024-09-30T14:44:53.429431Z",
"url": "https://files.pythonhosted.org/packages/72/e6/60ef06efcf66227a5685398438a19ab54306965b36c0b227f55f756d8c34/i2cpy-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "84dff30e481917d7f7f5e901f1c229c2a9320c576b48a850672b0a5336a988ec",
"md5": "9301037d5c4e37af1afb288a6a08e49c",
"sha256": "23e9547cb4a181d246b9fe575655dc49ad812c76646e5d82a9c25466b70e0c55"
},
"downloads": -1,
"filename": "i2cpy-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "9301037d5c4e37af1afb288a6a08e49c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13422,
"upload_time": "2024-09-30T14:44:55",
"upload_time_iso_8601": "2024-09-30T14:44:55.162836Z",
"url": "https://files.pythonhosted.org/packages/84/df/f30e481917d7f7f5e901f1c229c2a9320c576b48a850672b0a5336a988ec/i2cpy-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-30 14:44:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "iynehz",
"github_project": "i2cpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "i2cpy"
}
