# I2C interface modules for Cocotb
[](https://github.com/alexforencich/cocotbext-i2c/actions/workflows/regression-tests.yml)
[](https://codecov.io/gh/alexforencich/cocotbext-i2c)
[](https://pypi.org/project/cocotbext-i2c)
[](https://pepy.tech/project/cocotbext-i2c)
GitHub repository: https://github.com/alexforencich/cocotbext-i2c
## Introduction
I2C simulation models for [cocotb](https://github.com/cocotb/cocotb).
## Installation
Installation from pip (release version, stable):
$ pip install cocotbext-i2c
Installation from git (latest development version, potentially unstable):
$ pip install https://github.com/alexforencich/cocotbext-i2c/archive/master.zip
Installation for active development:
$ git clone https://github.com/alexforencich/cocotbext-i2c
$ pip install -e cocotbext-i2c
## Documentation and usage examples
See the `tests` directory, [taxi](https://github.com/fpganinja/taxi), and [verilog-i2c](https://github.com/alexforencich/verilog-i2c) for complete testbenches using these modules.
### I2C Master
The `I2cMaster` class can be used to issue read and write operations on an I2C bus.
Example:
from cocotbext.i2c import I2cMaster
i2c_master = I2cMaster(dut.sda_i, dut.sda_o, dut.scl_i, dut.scl_o, 400e3)
To issue I2C operations with an `I2cMaster`, call `read()` or `write()`. These are the preferred methods, as they will manage the bus state automatically. Lower-level methods must be called in the appropriate order. The `read()` and `write()` methods will leave the bus active, so call `send_stop()` to release the bus.
#### Constructor parameters:
* _sda_: serial data in/out
* _sda_o_: serial data output
* _scl_: clock in/out
* _scl_o_: clock output
* _speed_: nominal data rate in bits per second (default `400e3`)
#### Attributes:
* _speed_: nominal data rate in bits per second
#### Methods
* `write(addr, data)`: send _data_ to device at address `addr` (blocking)
* `read(addr, count)`: read _count_ bytes from device at address `addr` (blocking)
* `send_start()`: send a start condition on the bus
* `send_stop()`: send a stop condition and release the bus
* `send_byte()`: send a byte on the bus
* `recv_byte()`: read a byte from the bus
### I2C Device
The `I2cDevice` class emulates an I2C device. This class cannot be used directly, instead it should extended and the methods `handle_start()`, `handle_write()`, `handle_read()`, and `handle_stop()` implemented appropriately. See `I2cMem` for an example.
#### Constructor parameters:
* _sda_: serial data in/out
* _sda_o_: serial data output
* _scl_: clock in/out
* _scl_o_: clock output
### I2C Memory
The `I2cMemory` class emulates a simple memory like an I2C EEPROM.
Example:
from cocotbext.i2c import I2cMemory
i2c_mem = I2cMemory(dut.sda_i, dut.sda_o, dut.scl_i, dut.scl_o, 0x50, 256)
The memory can then be read/written via I2C operations on the bus, with the first bytes written after a start bit setting the address, and subsequent reads/writes advancing the internal address and reading/writing the memory. The memory can also be accessed via `read_mem()` and `write_mem()`.
#### Constructor parameters:
* _sda_: serial data in/out
* _sda_o_: serial data output
* _scl_: clock in/out
* _scl_o_: clock output
* _addr_: device address (default `0x50`)
* _size_: size in bytes (default `256`)
#### Methods
* `read_mem(addr, count)`: read _count_ bytes from memory, starting at `addr`
* `write_mem(addr, data)`: write _data_ to memory, starting at `addr`
Raw data
{
"_id": null,
"home_page": "https://github.com/alexforencich/cocotbext-i2c",
"name": "cocotbext-i2c",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "i2c, cocotb",
"author": "Alex Forencich",
"author_email": "alex@alexforencich.com",
"download_url": "https://files.pythonhosted.org/packages/55/a5/3936214377140bee2b582fc6326dd98df1f8c7b9ecbef8094044d69d52bf/cocotbext_i2c-0.1.2.tar.gz",
"platform": "any",
"description": "# I2C interface modules for Cocotb\n\n[](https://github.com/alexforencich/cocotbext-i2c/actions/workflows/regression-tests.yml)\n[](https://codecov.io/gh/alexforencich/cocotbext-i2c)\n[](https://pypi.org/project/cocotbext-i2c)\n[](https://pepy.tech/project/cocotbext-i2c)\n\nGitHub repository: https://github.com/alexforencich/cocotbext-i2c\n\n## Introduction\n\nI2C simulation models for [cocotb](https://github.com/cocotb/cocotb).\n\n## Installation\n\nInstallation from pip (release version, stable):\n\n $ pip install cocotbext-i2c\n\nInstallation from git (latest development version, potentially unstable):\n\n $ pip install https://github.com/alexforencich/cocotbext-i2c/archive/master.zip\n\nInstallation for active development:\n\n $ git clone https://github.com/alexforencich/cocotbext-i2c\n $ pip install -e cocotbext-i2c\n\n## Documentation and usage examples\n\nSee the `tests` directory, [taxi](https://github.com/fpganinja/taxi), and [verilog-i2c](https://github.com/alexforencich/verilog-i2c) for complete testbenches using these modules.\n\n### I2C Master\n\nThe `I2cMaster` class can be used to issue read and write operations on an I2C bus.\n\nExample:\n\n from cocotbext.i2c import I2cMaster\n\n i2c_master = I2cMaster(dut.sda_i, dut.sda_o, dut.scl_i, dut.scl_o, 400e3)\n\nTo issue I2C operations with an `I2cMaster`, call `read()` or `write()`. These are the preferred methods, as they will manage the bus state automatically. Lower-level methods must be called in the appropriate order. The `read()` and `write()` methods will leave the bus active, so call `send_stop()` to release the bus.\n\n#### Constructor parameters:\n\n* _sda_: serial data in/out\n* _sda_o_: serial data output\n* _scl_: clock in/out\n* _scl_o_: clock output\n* _speed_: nominal data rate in bits per second (default `400e3`)\n\n#### Attributes:\n\n* _speed_: nominal data rate in bits per second\n\n#### Methods\n\n* `write(addr, data)`: send _data_ to device at address `addr` (blocking)\n* `read(addr, count)`: read _count_ bytes from device at address `addr` (blocking)\n* `send_start()`: send a start condition on the bus\n* `send_stop()`: send a stop condition and release the bus\n* `send_byte()`: send a byte on the bus\n* `recv_byte()`: read a byte from the bus\n\n### I2C Device\n\nThe `I2cDevice` class emulates an I2C device. This class cannot be used directly, instead it should extended and the methods `handle_start()`, `handle_write()`, `handle_read()`, and `handle_stop()` implemented appropriately. See `I2cMem` for an example.\n\n#### Constructor parameters:\n\n* _sda_: serial data in/out\n* _sda_o_: serial data output\n* _scl_: clock in/out\n* _scl_o_: clock output\n\n### I2C Memory\n\nThe `I2cMemory` class emulates a simple memory like an I2C EEPROM.\n\nExample:\n\n from cocotbext.i2c import I2cMemory\n\n i2c_mem = I2cMemory(dut.sda_i, dut.sda_o, dut.scl_i, dut.scl_o, 0x50, 256)\n\nThe memory can then be read/written via I2C operations on the bus, with the first bytes written after a start bit setting the address, and subsequent reads/writes advancing the internal address and reading/writing the memory. The memory can also be accessed via `read_mem()` and `write_mem()`.\n\n#### Constructor parameters:\n\n* _sda_: serial data in/out\n* _sda_o_: serial data output\n* _scl_: clock in/out\n* _scl_o_: clock output\n* _addr_: device address (default `0x50`)\n* _size_: size in bytes (default `256`)\n\n#### Methods\n\n* `read_mem(addr, count)`: read _count_ bytes from memory, starting at `addr`\n* `write_mem(addr, data)`: write _data_ to memory, starting at `addr`\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "I2C modules for cocotb",
"version": "0.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/alexforencich/cocotbext-i2c/issues",
"Download": "https://github.com/alexforencich/cocotbext-i2c/tarball/master",
"Homepage": "https://github.com/alexforencich/cocotbext-i2c",
"Source Code": "https://github.com/alexforencich/cocotbext-i2c"
},
"split_keywords": [
"i2c",
" cocotb"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d2215e1d2b2b1b30431bec7461df6ccc267fb447629f780ea196b92f1c8b3f50",
"md5": "3c08d56fe0759f53d36d559206c02e30",
"sha256": "d50d1c5f86c0841bfa3456d0de6700bab9ceb1d26c9e672dfd637e02bc4f84e2"
},
"downloads": -1,
"filename": "cocotbext_i2c-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3c08d56fe0759f53d36d559206c02e30",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 9644,
"upload_time": "2025-09-07T19:35:23",
"upload_time_iso_8601": "2025-09-07T19:35:23.910876Z",
"url": "https://files.pythonhosted.org/packages/d2/21/5e1d2b2b1b30431bec7461df6ccc267fb447629f780ea196b92f1c8b3f50/cocotbext_i2c-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "55a53936214377140bee2b582fc6326dd98df1f8c7b9ecbef8094044d69d52bf",
"md5": "12c745ef01b6643c2faacff7cf05876c",
"sha256": "188c6ff9cc999858eeb50560b41a2c7af0040f334abefb0971f8c40bf8818867"
},
"downloads": -1,
"filename": "cocotbext_i2c-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "12c745ef01b6643c2faacff7cf05876c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 9491,
"upload_time": "2025-09-07T19:35:25",
"upload_time_iso_8601": "2025-09-07T19:35:25.358804Z",
"url": "https://files.pythonhosted.org/packages/55/a5/3936214377140bee2b582fc6326dd98df1f8c7b9ecbef8094044d69d52bf/cocotbext_i2c-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 19:35:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alexforencich",
"github_project": "cocotbext-i2c",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cocotbext-i2c"
}
JSON
