Package: i2cdevice
i2cdevicei2cdevice is a Python framework aimed at dealing with common SMBus/i2c device interaction patterns.This project aims to make group-up implementations of Python libraries for i2c devices easier, simpler and inherently self-documenting.It does this by separating a detailed description of the hardware registers and how they should be manipulated into a structured definition language.This project does not aim to help you make a public API for Python devices- that should be built on top of the fundamentals presented here.Using This LibraryYou should generally aim for a 1:1 representation of the hardware registers in the device you're implementing, even if you don't plan to use all the functionality. Having the full register set implemented allows for the easy addition of new features in future.Check out the libraries listed below for real-world examples.FeaturesClasses for describing devices, registers and individual bit fields within registers in a fashion which maps closely with the datasheetValue translation from real world numbers (such as512ms) to register values (such as0b111) and back againRead registers into a namedtuple of fields usinggetWrite multiple register fields in a transaction usingsetwith keyword argumentsSupport for treating multiple-bytes as a single value, or single register with multiple valuesBuilt With i2cdevicebme280 -https://github.com/pimoroni/bme280-pythonbmp280 -https://github.com/pimoroni/bmp280-pythonbh1745 -https://github.com/pimoroni/bh1745-pythonas7262 -https://github.com/pimoroni/as7262-pythonlsm303d -https://github.com/pimoroni/lsm303d-pythonltr559 -https://github.com/pimoroni/ltr559-pythonads1015 -https://github.com/pimoroni/ads1015-pythonExamplesThe below example defines theALS_CONTROLregister on an ltr559, with register address0x80.It has 3 fields; gain - which is mapped to real world values - and sw_reset/mode which are single bit flags.ALS_CONTROL=Register('ALS_CONTROL',0x80,fields=(BitField('gain',0b00011100,values_map={1:0b000,2:0b001,4:0b011,8:0b011,48:0b110,96:0b111}),BitField('sw_reset',0b00000010),BitField('mode',0b00000001)))A lookup table is not required for values, however, a function can be used to translate values from and to a format that the device understands.The below example usesi2cdevice._byte_swapto change the endianness of two 16bit values before they are stored/retrieved.# This will address 0x88, 0x89, 0x8A and 0x8B as a continuous 32bit registerALS_DATA=Register('ALS_DATA',0x88,fields=(BitField('ch1',0xFFFF0000,bitwidth=16,values_in=_byte_swap,values_out=_byte_swap),BitField('ch0',0x0000FFFF,bitwidth=16,values_in=_byte_swap,values_out=_byte_swap)),read_only=True,bitwidth=32)A "Register" and its "BitField"s define a set of rules and logic for detailing with the hardware register which is interpreted by the device class. Registers are declared on a device using theregisters=()keyword argument:I2C_ADDR=0x23ltr559=Device(I2C_ADDR,bit_width=8,registers=(ALS_CONTROL,ALS_DATA))Reading RegistersOne configured a register's fields can be read into a namedtuple using thegetmethod:register_values=ltr559.get('ALS_CONTROL')gain=register_values.gainsw_reset=register_values.sw_resetmode=register_values.modeWriting RegistersThe namedtuple returned fromgetis immutable and does not attempt to map values back to the hardware, in order to write one or more fields to a register you must usesetwith a keyword argument for each field:ltr559.set('ALS_CONTROL',gain=4,sw_reset=1)This will read the register state from the device, update the bitfields accordingly and write the result back.1.0.0Enhancement: Repackage to pyproject.toml/hatchlingSwitch i2c_dev fallback from smbus to smbus20.0.7BugFix: Prevent .get from reading multiple times (thanks @dkao)Enhancement: Better error output (thanks Kamil Klimek)0.0.6New API methods set and get0.0.5Bump to stable release0.0.4Bugfixes0.0.3Added License0.0.2Major Refactor0.0.1Initial Release