max1704x_smbus.register

Register fields of an I²C device.

Provides the RegisterField class for representing device registers or arbitrary subfields within them. A field can cover the entire 16-bit register, a single byte, any group of bits, or just one bit. Helper functions (RWRegister(), RORegister(), RWBit(), ROBit()) are included for the most common cases.

Constants

The following constants are provided for the used_bytes parameter:

  • USED_BYTES_MSB (-1): Use only the most significant byte.

  • USED_BYTES_BOTH (0): Use both bytes (the full 16-bit register).

  • USED_BYTES_LSB (1): Use only the least significant byte.

Examples

Create a read-write 16-bit register (unsigned):

>>> reg = RWRegister(0x0A, used_bytes=USED_BYTES_BOTH)
>>> # 0x0A: [OOOOOOOO] 0x0B [OOOOOOOO]

Create a read-only 8-bit register (signed) on the first byte:

>>> reg = RORegister(0x0A, used_bytes=USED_BYTES_MSB, signed=True)
>>> # 0x0A: [OOOOOOOO] 0x0B [--------]

Create a read-only status bit:

>>> flag = ROBit(0x04, bit=13)
>>> # 0x04: [--O-----] 0x05 [--------]

Create a 3-bit read-only field from bit 7 to bit 5 (signed):

>>> mode = RegisterField(0x0C, num_bits=3, lowest_bit=5, signed=True, read_only=True)
>>> # 0x0C: [--------] 0x0D [OOO-----]

All registers are interpreted as big-endian.

class max1704x_smbus.register.RegisterField(register_address, num_bits, lowest_bit=0, signed=False, independent_bytes=False, read_only=False)

Read-write field within a register.

Represents a subfield inside a 16-bit device register accessed over I²C. Handles masking, shifting, and optional sign extension so that field values can be read and written directly as Python integers, without manual bit manipulation.

__init__(register_address, num_bits, lowest_bit=0, signed=False, independent_bytes=False, read_only=False)

Initialize the read-write register field.

Parameters:

  • register_address (int) – I²C register address where the field is located.

  • num_bits (int) – Number of bits used by the field.

  • lowest_bit (int, optional) – Position of the least significant bit of the field within the register. Defaults to 0.

  • signed (bool, optional) – Whether the field value is signed. Defaults to False.

  • independent_bytes (bool, optional) – If True, the field can be accessed using only the individual byte that contains it, instead of always requiring a 2-byte transaction. Defaults to False.

  • read_only (bool, optional) – If True, the field is read-only and any attempt to assign a value will raise an AttributeError. Defaults to False.

Raises:

  • ValueError – If the register address is not even.

  • ValueError – If num_bits is not in the range 1-16.

  • ValueError – If lowest_bit is not in the range 0-15.

  • ValueError – If the field size (lowest_bit + num_bits) exceeds 16 bits.

__get__(obj, objtype=None)

Read the current field value from the register.

Parameters:

  • obj (I2CDeviceDriver) – Instance containing the i2c_device for communication.

  • objtype (Optional[Type[I2CDeviceDriver]], optional) – The type of the obj instance.

Returns:

Value of the field extracted from the register.

Return type:

int

__set__(obj, value)

Write a value to the field within the register.

Parameters:

  • obj (I2CDeviceDriver) – Instance containing the i2c_device for communication.

  • value (int) – Field value to write into the register.

Raises:

  • AttributeError – If attempting to write to a read-only register field.

  • OverflowError – If attempting to write a value outside the valid logical bounds.

Return type:

None

static _convert_signed_unsigned(value, num_bits, unsigned_to_signed=True)

Convert an integer between signed and unsigned representations.

This helper interprets a limited-width integer either as signed or unsigned, depending on the unsigned_to_signed param. It can be used to reinterpret raw register values or to encode signed values for transmission.

Parameters:

  • value (int) – Integer value to convert.

  • num_bits (int) – Number of valid bits in the value (bit width).

  • unsigned_to_signed (bool, optional) – If True (default), interprets the unsigned input as signed. If False, converts a signed input to its unsigned representation.

Returns:

Converted integer in the requested representation.

Return type:

int

Raises:

ValueError – If the value is out of range for the specified bit width.

max1704x_smbus.register.RWRegister(register_address, used_bytes, signed=False, independent_bytes=False)

Create a read-write register field representing one or two bytes.

Parameters:

  • register_address (int) – The register address to read from or write to.

  • used_bytes (int) –

    Which byte(s) of the register to access:

    • USED_BYTES_MSB (-1): Use only the most significant byte (first byte)

    • USED_BYTES_BOTH (0): Use both bytes (the full 16-bit register).

    • USED_BYTES_LSB (1): Use only the least significant byte (second byte).

  • signed (bool, optional) – Whether the register should be interpreted as signed. Defaults to False.

  • independent_bytes (bool, optional) – If True, the register can be accessed using only the individual byte that contains it, instead of always requiring access to the full 16-bit register. Defaults to False.

Returns:

A new RegisterField instance.

Return type:

RegisterField

See also

RegisterField

Notes

All registers are assumed to use big-endian ordering: the first byte is the MSB and the second byte is the LSB.

max1704x_smbus.register.RORegister(register_address, used_bytes, signed=False, independent_bytes=False)

Create a read-only register field representing one or two bytes.

Parameters:

  • register_address (int) – The register address to read from.

  • used_bytes (int) –

    Which byte(s) of the register to access:

    • USED_BYTES_MSB (-1): Use only the most significant byte (first byte)

    • USED_BYTES_BOTH (0): Use both bytes (the full 16-bit register).

    • USED_BYTES_LSB (1): Use only the least significant byte (second byte).

  • signed (bool, optional) – Whether the register should be interpreted as signed. Defaults to False.

  • independent_bytes (bool, optional) – If True, the register can be accessed using only the individual byte that contains it, instead of always requiring access to the full 16-bit register. Defaults to False.

Returns:

A new RegisterField instance.

Return type:

RegisterField

See also

RegisterField

Notes

All registers are assumed to use big-endian ordering: the first byte is the MSB and the second byte is the LSB.

max1704x_smbus.register.RWBit(register_address, bit, independent_bytes=False)

Create a read-write register field representing a single bit.

Parameters:

  • register_address (int) – The register address to read from or write to.

  • bit (int) – Which bit of the register to access.

  • independent_bytes (bool, optional) – If True, the register can be accessed using only the individual byte that contains it, instead of always requiring access to the full 16-bit register. Defaults to False.

Returns:

A new RegisterField instance.

Return type:

RegisterField

See also

RegisterField

Notes

All registers are assumed to use big-endian ordering.

max1704x_smbus.register.ROBit(register_address, bit, independent_bytes=False)

Create a read-only register field representing a single bit.

Parameters:

  • register_address (int) – The register address to read from.

  • bit (int) – Which bit of the register to access.

  • independent_bytes (bool, optional) – If True, the register can be accessed using only the individual byte that contains it, instead of always requiring access to the full 16-bit register. Defaults to False.

Returns:

A new RegisterField instance.

Return type:

RegisterField

See also

RegisterField

Notes

All registers are assumed to use big-endian ordering.