pylibi2c

https://pypi.org/project/pylibi2c/
Admin
pylibi2c is a Linux userspace I2C library that provides C/C++ and Python interfaces for reading and...
Tokens:6,180
Snippets:56
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install pylibi2c

Source: https://pypi.org/project/pylibi2c

Instructions for installing the pylibi2c library using pip or compiling from source.

```bash
pip install pylibi2c
```

```bash
sudo python setup.py install
```

```bash
sudo make install
```

```bash
sudo make install PYTHON=pythonX.X
```

--------------------------------

### Python Usage: Buffer Creation

Source: https://pypi.org/project/pylibi2c

Provides examples of creating byte buffers for data transfer in both Python 2 and Python 3 environments.

```python
# Python2
buf = bytes(bytearray(256))

# Python3
buf = bytes(256)
```

--------------------------------

### C/C++ Usage: Open I2C Bus

Source: https://pypi.org/project/pylibi2c/0.2.1

Example demonstrating how to open an I2C bus using the `i2c_open` function and handle potential errors.

```c
int bus;

/* Open i2c bus /dev/i2c-0 */
if ((bus = i2c_open("/dev/i2c-0")) == -1) {

	/* Error process */
}

```

--------------------------------

### Python Buffer Creation

Source: https://pypi.org/project/pylibi2c/0.2.1

Provides examples of creating byte buffers in Python for data transfer, showing differences between Python 2 and Python 3.

```python
# Python2
buf = bytes(bytearray(256))

# Python3
buf = bytes(256)

```

--------------------------------

### C/C++ Usage: Read I2C Device Data

Source: https://pypi.org/project/pylibi2c/0.2.1

Example showing how to read data from an I2C device using the `i2c_read` function and handle read errors.

```c
unsigned char buffer[256];
ssize_t size = sizeof(buffer);
memset(buffer, 0, sizeof(buffer));

/* From i2c 0x0 address read 256 bytes data to buffer */
if ((i2c_read(&device, 0x0, buffer, size)) != size) {

	/* Error process */
}

```

--------------------------------

### Python Usage: Initialize I2CDevice

Source: https://pypi.org/project/pylibi2c

Shows how to instantiate an `I2CDevice` object in Python for interacting with I2C devices. Optional arguments allow configuration of internal address bytes, delay, page size, and flags.

```python
import ctypes
import pylibi2c

# Open i2c device @/dev/i2c-0, addr 0x50.
i2c = pylibi2c.I2CDevice('/dev/i2c-0', 0x50)

# Open i2c device @/dev/i2c-0, addr 0x50, 16bits internal address
i2c = pylibi2c.I2CDevice('/dev/i2c-0', 0x50, iaddr_bytes=2)

# Set delay
i2c.delay = 10

# Set page_bytes
i2c.page_bytes = 16

# Set flags
i2c.flags = pylibi2c.I2C_M_IGNORE_NAK
```

--------------------------------

### Python I2CDevice Object Initialization

Source: https://pypi.org/project/pylibi2c/0.2.1

Shows how to instantiate the `I2CDevice` object in Python, including options for specifying bus, address, and device characteristics.

```python
import ctypes
import pylibi2c

# Open i2c device @/dev/i2c-0, addr 0x50.
i2c = pylibi2c.I2CDevice('/dev/i2c-0', 0x50)

# Open i2c device @/dev/i2c-0, addr 0x50, 16bits internal address
i2c = pylibi2c.I2CDevice('/dev/i2c-0', 0x50, iaddr_bytes=2)

```

--------------------------------

### C/C++ Usage: Prepare I2CDevice Structure

Source: https://pypi.org/project/pylibi2c/0.2.1

Illustrates how to initialize and populate the `I2CDevice` structure for a specific I2C device, like a 24C04.

```c
I2CDevice device;
memset(&device, 0, sizeof(device));

/* 24C04 */
device.bus = bus;	/* Bus 0 */
device.addr = 0x50;	/* Slave address is 0x50, 7-bit */
device.iaddr_bytes = 1;	/* Device internal address is 1 byte */
device.page_bytes = 16; /* Device are capable of 16 bytes per page */

```

--------------------------------

### C/C++ Usage: Configure I2CDevice

Source: https://pypi.org/project/pylibi2c

Shows how to initialize and populate the `I2CDevice` structure for a specific I2C device, such as a 24C04 EEPROM.

```c
I2CDevice device;
memset(&device, 0, sizeof(device));

/* 24C04 */
device.bus = bus;    /* Bus 0 */
device.addr = 0x50;    /* Slave address is 0x50, 7-bit */
device.iaddr_bytes = 1;    /* Device internal address is 1 byte */
device.page_bytes = 16; /* Device are capable of 16 bytes per page */
```

--------------------------------

### C/C++ Usage: Open I2C Bus

Source: https://pypi.org/project/pylibi2c

Demonstrates how to open an I2C bus using the `i2c_open` function. Error handling for failed opening is included.

```c
int bus;

/* Open i2c bus /dev/i2c-0 */
if ((bus = i2c_open("/dev/i2c-0")) == -1) {

	/* Error process */
}
```

--------------------------------

### Python I2CDevice Object Attributes

Source: https://pypi.org/project/pylibi2c/0.2.1

Demonstrates setting various attributes of the `I2CDevice` object in Python, such as delay, page size, and I2C flags.

```python
# Set delay
i2c.delay = 10

# Set page_bytes
i2c.page_bytes = 16

# Set flags
i2c.flags = pylibi2c.I2C_M_IGNORE_NAK

```

--------------------------------

### C/C++ Interface Functions

Source: https://pypi.org/project/pylibi2c

Provides the C/C++ function signatures for interacting with I2C devices, including opening, closing, reading, and writing operations.

```APIDOC
## C/C++ Interface

### Close i2c bus
```c
void i2c_close(int bus);
```

### Open i2c bus, return i2c bus fd
```c
int i2c_open(const char *bus_name);
```

### I2C file I/O read, write
```c
ssize_t i2c_read(const I2CDevice *device, unsigned int iaddr, void *buf, size_t len);
ssize_t i2c_write(const I2CDevice *device, unsigned int iaddr, const void *buf, size_t len);
```

### I2c ioctl read, write can set i2c flags
```c
ssize_t i2c_ioctl_read(const I2CDevice *device, unsigned int iaddr, void *buf, size_t len);
ssize_t i2c_ioctl_write(const I2CDevice *device, unsigned int iaddr, const void *buf, size_t len);
```
```

--------------------------------

### Python I2CDevice Class

Source: https://pypi.org/project/pylibi2c

Details the constructor and attributes of the I2CDevice class in Python for configuring and interacting with I2C devices.

```APIDOC
## Python Usage

### I2CDevice object
```python
I2CDevice(bus, addr, tenbit=False, iaddr_bytes=1, page_bytes=8, delay=1, flags=0)
```

**Description:**
Initializes an I2CDevice object.

**Parameters:**
- **bus** (str): The I2C bus name (e.g., '/dev/i2c-0').
- **addr** (int): The I2C device (slave) address.
- **tenbit** (bool, optional): Set to True for 10-bit slave address. Defaults to False (7-bit).
- **iaddr_bytes** (int, optional): The number of bytes for the device's internal address. Defaults to 1.
- **page_bytes** (int, optional): The maximum number of bytes per page for write operations. Defaults to 8.
- **delay** (int, optional): The delay in milliseconds between I2C operations. Defaults to 1.
- **flags** (int, optional): Flags to control I2C behavior (e.g., `pylibi2c.I2C_M_IGNORE_NAK`). Defaults to 0.

**Attributes:**
`tenbit`, `delay`, `flags`, `page_bytes`, `iaddr_bytes` can be set after initialization.
```

--------------------------------

### C/C++ Usage: Read from I2C Device

Source: https://pypi.org/project/pylibi2c

Illustrates reading data from an I2C device using the `i2c_read` function. Ensure proper buffer allocation and error checking.

```c
unsigned char buffer[256];
ssize_t size = sizeof(buffer);
memset(buffer, 0, sizeof(buffer));

/* From i2c 0x0 address read 256 bytes data to buffer */
if ((i2c_read(&device, 0x0, buffer, size)) != size) {

	/* Error process */
}
```

--------------------------------

### C/C++ Interface Functions

Source: https://pypi.org/project/pylibi2c/0.2.1

Provides C/C++ functions for opening, closing, reading, and writing to I2C devices, including ioctl-based operations for more advanced control.

```APIDOC
## C/C++ Interface Functions

### Description
Functions for interacting with I2C devices at the C/C++ level.

### Functions

- `void i2c_close(int bus);`
  - Closes the specified I2C bus.

- `int i2c_open(const char *bus_name);`
  - Opens an I2C bus and returns a file descriptor.
  - Parameters:
    - `bus_name` (const char *): The name of the I2C bus (e.g., "/dev/i2c-0").
  - Returns: An integer representing the I2C bus file descriptor, or -1 on error.

- `ssize_t i2c_read(const I2CDevice *device, unsigned int iaddr, void *buf, size_t len);`
  - Reads data from an I2C device.
  - Parameters:
    - `device` (const I2CDevice *): Pointer to the I2CDevice structure.
    - `iaddr` (unsigned int): The internal address within the I2C device.
    - `buf` (void *): Buffer to store the read data.
    - `len` (size_t): The number of bytes to read.
  - Returns: The number of bytes read, or -1 on error.

- `ssize_t i2c_write(const I2CDevice *device, unsigned int iaddr, const void *buf, size_t len);`
  - Writes data to an I2C device.
  - Parameters:
    - `device` (const I2CDevice *): Pointer to the I2CDevice structure.
    - `iaddr` (unsigned int): The internal address within the I2C device.
    - `buf` (const void *): Buffer containing the data to write.
    - `len` (size_t): The number of bytes to write.
  - Returns: The number of bytes written, or -1 on error.

- `ssize_t i2c_ioctl_read(const I2CDevice *device, unsigned int iaddr, void *buf, size_t len);`
  - Performs an I2C read operation using ioctl, allowing for flags.
  - Parameters:
    - `device` (const I2CDevice *): Pointer to the I2CDevice structure.
    - `iaddr` (unsigned int): The internal address within the I2C device.
    - `buf` (void *): Buffer to store the read data.
    - `len` (size_t): The number of bytes to read.
  - Returns: The number of bytes read, or -1 on error.

- `ssize_t i2c_ioctl_write(const I2CDevice *device, unsigned int iaddr, const void *buf, size_t len);`
  - Performs an I2C write operation using ioctl, allowing for flags.
  - Parameters:
    - `device` (const I2CDevice *): Pointer to the I2CDevice structure.
    - `iaddr` (unsigned int): The internal address within the I2C device.
    - `buf` (const void *): Buffer containing the data to write.
    - `len` (size_t): The number of bytes to write.
  - Returns: The number of bytes written, or -1 on error.
```

--------------------------------

### Python Interface Class

Source: https://pypi.org/project/pylibi2c/0.2.1

Provides a Python class for interacting with I2C devices, offering a convenient object-oriented interface.

```APIDOC
## Python Interface Class

### Description
Provides a Python class `I2CDevice` for interacting with I2C devices.

### Class

`I2CDevice(bus, addr, tenbit=False, iaddr_bytes=1, page_bytes=8, delay=1, flags=0)`

- **Parameters:**
  - `bus` (str): The I2C bus path (e.g., '/dev/i2c-0').
  - `addr` (int): The I2C slave device address.
  - `tenbit` (bool, optional): Set to True for 10-bit device addresses. Defaults to False (7-bit).
  - `iaddr_bytes` (int, optional): The number of bytes for the internal address of the device. Defaults to 1.
  - `page_bytes` (int, optional): The maximum number of bytes per page for write operations. Defaults to 8.
  - `delay` (int, optional): The delay in milliseconds between I2C operations. Defaults to 1.
  - `flags` (int, optional): Flags to control I2C behavior (e.g., `pylibi2c.I2C_M_IGNORE_NAK`). Defaults to 0.

### Attributes

- `delay` (int): Get or set the delay in milliseconds.
- `page_bytes` (int): Get or set the page size in bytes.
- `flags` (int): Get or set the I2C flags.

### Example Usage
```python
import pylibi2c

# Open an I2C device at /dev/i2c-0 with address 0x50
i2c = pylibi2c.I2CDevice('/dev/i2c-0', 0x50)

# Open with 16-bit internal address
i2c_16bit = pylibi2c.I2CDevice('/dev/i2c-0', 0x50, iaddr_bytes=2)

# Set delay
i2c.delay = 10

# Set page_bytes
i2c.page_bytes = 16

# Set flags (e.g., ignore NAK)
i2c.flags = pylibi2c.I2C_M_IGNORE_NAK

# Read/Write operations would follow using methods not detailed here.
```
```

--------------------------------

### C/C++ I2CDevice Structure

Source: https://pypi.org/project/pylibi2c

Defines the structure used to configure an I2C device, including bus file descriptor, slave address, and device-specific parameters like internal address bytes and page size.

```c
typedef struct i2c_device {
	int bus;            /* I2C Bus fd, return from i2c_open */
	unsigned short addr;        /* I2C device(slave) address */
	unsigned char tenbit;       /* I2C is 10 bit device address */
	unsigned char delay;        /* I2C internal operate delay, unit millisecond */
	unsigned short flags;       /* I2C i2c_ioctl_read/write flags */
	unsigned int page_bytes;      /* I2C max number of bytes per page, 1K/2K 8, 4K/8K/16K 16, 32K/64K 32 etc */
	unsigned int iaddr_bytes;   /* I2C device internal(word) address bytes, such as: 24C04 1 byte, 24C64 2 bytes */
}I2CDevice;
```

--------------------------------

### C/C++ Interface Functions

Source: https://pypi.org/project/pylibi2c

Defines the C/C++ functions for opening, closing, reading, and writing to I2C devices. Note that i2c_ioctl_write is more efficient for single writes up to 16 bytes compared to i2c_write.

```c
/* Close i2c bus */
void i2c_close(int bus);
```

```c
/* Open i2c bus, return i2c bus fd */
int i2c_open(const char *bus_name);
```

```c
/* I2C file I/O read, write */
ssize_t i2c_read(const I2CDevice *device, unsigned int iaddr, void *buf, size_t len);
```

```c
ssize_t i2c_write(const I2CDevice *device, unsigned int iaddr, const void *buf, size_t len);
```

```c
/* I2c ioctl read, write can set i2c flags */
ssize_t i2c_ioctl_read(const I2CDevice *device, unsigned int iaddr, void *buf, size_t len);
```

```c
ssize_t i2c_ioctl_write(const I2CDevice *device, unsigned int iaddr, const void *buf, size_t len);
```

--------------------------------

### C/C++ I2CDevice Structure

Source: https://pypi.org/project/pylibi2c/0.2.1

Defines the structure used to hold I2C device information, including bus, address, and operational flags.

```c
typedef struct i2c_device {
	int bus;			/* I2C Bus fd, return from i2c_open */
	unsigned short addr;		/* I2C device(slave) address */
	unsigned char tenbit;		/* I2C is 10 bit device address */
	unsigned char delay;		/* I2C internal operate delay, unit millisecond */
	unsigned short flags;		/* I2C i2c_ioctl_read/write flags */
	unsigned int page_bytes;	/* I2C max number of bytes per page, 1K/2K 8, 4K/8K/16K 16, 32K/64K 32 etc */
	unsigned int iaddr_bytes;	/* I2C device internal(word) address bytes, such as: 24C04 1 byte, 24C64 2 bytes */
}I2CDevice;

```

--------------------------------

### C/C++ Usage: Close I2C Bus

Source: https://pypi.org/project/pylibi2c

Demonstrates the final step of closing the I2C bus connection using `i2c_close`.

```c
i2c_close(bus);
```

--------------------------------

### I2C read/write for devices without internal address

Source: https://pypi.org/project/pylibi2c/0.2.1

Use `i2c_ioctl_read/write` when the I2C device does not have an internal address. Set `iaddr_bytes=0` in this case.

```python
# If i2c device do not have internal address, please use `i2c_ioctl_read/write` function for read/write, set`'iaddr_bytes=0`.
```

--------------------------------

### C/C++ Usage: Close I2C Bus

Source: https://pypi.org/project/pylibi2c/0.2.1

Demonstrates the final step of closing the I2C bus connection using the `i2c_close` function.

```c
i2c_close(bus);

```

--------------------------------

### Write Data to I2C Device

Source: https://pypi.org/project/pylibi2c

Use this function to write data to an I2C device. The `buf` parameter must be a read-only type. The function returns the number of bytes written.

```python
size = i2c.write(0x0, buf)
```

--------------------------------

### Read Data from I2C Device using ioctl_read

Source: https://pypi.org/project/pylibi2c

Read a specified number of bytes from an I2C device using the `ioctl_read` method. This is useful for devices with internal addresses, such as the internal address 0x0.

```python
data = i2c.ioctl_read(0x0, 256)
```

--------------------------------

### Ignore I2C NAK signal

Source: https://pypi.org/project/pylibi2c/0.2.1

To ignore the I2C device NAK signal, use the `i2c_ioctl_read/write` function and set `I2CDevice.falgs` to `I2C_M_IGNORE_NAK`.

```python
# If want ignore i2c device nak signal, please use `i2c_ioctl_read/write` function, set I2CDevice.falgs as `I2C_M_IGNORE_NAK`.
```

--------------------------------

### Ignore I2C NAK Signal

Source: https://pypi.org/project/pylibi2c

To ignore the I2C device NAK signal, use the `i2c_ioctl_read/write` function and set the `I2CDevice.falgs` attribute to `I2C_M_IGNORE_NAK`.

```python
I2CDevice.falgs = I2C_M_IGNORE_NAK
```

--------------------------------

### I2C Read/Write without Internal Address

Source: https://pypi.org/project/pylibi2c

When an I2C device does not have an internal address, use `i2c_ioctl_read/write` and set `iaddr_bytes=0`.

```python
i2c.i2c_ioctl_read(0x0, 256, iaddr_bytes=0)
```
Tokens:
Raw