Package: adafruit-circuitpython-register
IntroductionThis library provides a variety of data descriptor class forAdafruit
CircuitPythonthat makes it really
simple to write a device drivers for a I2C and SPI register based devices. Data
descriptors act like basic attributes from the outside which makes using them
really easy to use.DependenciesThis driver depends on:Adafruit CircuitPythonPlease ensure all dependencies are available on the CircuitPython filesystem.
This is easily achieved by downloadingthe Adafruit library and driver bundle.Installing from PyPIOn supported GNU/Linux systems like the Raspberry Pi, you can install the driver locallyfrom
PyPI. To install for current user:pip3installadafruit-circuitpython-registerTo install system-wide (this may be required in some cases):sudopip3installadafruit-circuitpython-registerTo install in a virtual environment in your current project:mkdirproject-name&&cdproject-namepython3-mvenv.venvsource.venv/bin/activatepip3installadafruit-circuitpython-registerUsage ExampleCreating a driverCreating a driver with the register library is really easy. First, import the
register modules you need from theavailable modules:fromadafruit_registerimporti2c_bitfromadafruit_bus_deviceimporti2c_deviceNext, define where the bit is located in the device’s memory map:classHelloWorldDevice:"""Device with two bits to control when the words 'hello' and 'world' are lit."""hello=i2c_bit.RWBit(0x0,0x0)"""Bit to indicate if hello is lit."""world=i2c_bit.RWBit(0x1,0x0)"""Bit to indicate if world is lit."""Lastly, we need to add ani2c_devicemember of typeI2CDevicethat manages sharing the I2C bus for us. Make sure the name is exact, otherwise
the registers will not be able to find it. Also, make sure that the i2c device
implements thebusio.I2Cinterface.def__init__(self,i2c,device_address=0x0):self.i2c_device=i2c_device.I2CDevice(i2c,device_address)Thats it! Now we have a class we can use to talk to those registers:importbusiofromboardimport*withbusio.I2C(SCL,SDA)asi2c:device=HelloWorldDevice(i2c)device.hello=Truedevice.world=TrueAdding register typesAdding a new register type is a little more complicated because you need to be
careful and minimize the amount of memory the class will take. If you don’t,
then a driver with five registers of your type could take up five times more
extra memory.First, determine whether the new register class should go in an existing module
or not. When in doubt choose a new module. The more finer grained the modules
are, the fewer extra classes a driver needs to load in.Here is the start of theRWBitclass:classRWBit:"""
    Single bit register that is readable and writeable.

    Values are `bool`

    :param int register_address: The register address to read the bit from
    :param type bit: The bit index within the byte at ``register_address``
    """def__init__(self,register_address,bit):self.bit_mask=1<<bitself.buffer=bytearray(2)self.buffer[0]=register_addressThe first thing done is writing an RST formatted class comment that explains the
functionality of the register class and any requirements of the register layout.
It also documents the parameters passed into the constructor (__init__) which
configure the register location in the device map. It does not include the
device address or the i2c object because its shared on the device class instance
instead. That way if you have multiple of the same device on the same bus, the
register classes will be shared.In__init__we only use two member variable because each costs 8 bytes of
memory plus the memory for the value. And remember this gets multiplied by the
number of registers of this type in a driver! Thats why we pack both the
register address and data byte into one bytearray. We could use two byte arrays
of size one but each MicroPython object is 16 bytes minimum due to the garbage
collector. So, by sharing a byte array we keep it to the 16 byte minimum instead
of 32 bytes. Eachmemoryviewalso costs 16 bytes minimum so we avoid them too.Another thing we could do is allocate thebytearrayonly when we need it. This
has the advantage of taking less memory up front but the cost of allocating it
every access and risking it failing. If you want to add a version ofFoothat
lazily allocates the underlying buffer call itFooLazy.Ok, onward. To make adata descriptorwe must implement__get__and__set__.def__get__(self,obj,objtype=None):withobj.i2c_deviceasi2c:i2c.write_then_readinto(self.buffer,self.buffer,out_end=1,in_start=1)returnbool(self.buffer[1]&self.bit_mask)def__set__(self,obj,value):withobj.i2c_deviceasi2c:i2c.write_then_readinto(self.buffer,self.buffer,out_end=1,in_start=1)ifvalue:self.buffer[1]|=self.bit_maskelse:self.buffer[1]&=~self.bit_maskobj.i2c_device.write(self.buffer)As you can see, we have two places to get state from. First,selfstores the
register class members which locate the register within the device memory map.
Second,objis the driver class that uses the register class which must by
definition provide aI2CDevicecompatible
object asi2c_device. This object does two thing for us:Waits for the bus to free, locks it as we use it and frees it after.Saves the device address and other settings so we don’t have to.Note that we take heavy advantage of thestartandendparameters to the
i2c functions to slice the buffer without actually allocating anything extra.
They function just likeself.buffer[start:end]without the extra allocation.Thats it! Now you can use your new register class like the example above. Just
remember to keep the number of members to a minimum because the class may be
used a bunch of times.DocumentationAPI documentation for this library can be found onRead the Docs.For information on building library documentation, please check outthis guide.ContributingContributions are welcome! Please read ourCode of Conductbefore contributing to help this project stay welcoming.