Experimental new API endpoints

[Gadgetoid]

This changeset introduces a new set and get method for i2cdevice. The purpose of these methods is to provide a less-bonkers approach to writing and reading values than the current (MicroPython incompatible) system of overriding getattribute and redirecting attribute lookups to our internal register dictionary.

Get

The get method accepts a register name, reads the register and returns a namedtuple of all the available fields. These changes turn accessing multiple registers from:

with device.REGISTER_NAME as REGISTER_NAME:
    status = REGISTER_NAME.get_status()
    interrupt = REGISTER_NAME.get_interrupt()

To:

my_register= device.get('REGISTER_NAME')
my_register.status
my_register.interrupt

Note: It is important to understand that my_register is, at this point, a stateless namedtuple that's disconnected from the hardware. If it's a non-volatile register (IE: it never changes) then you can keep this object for the lifetime of your program. If you want to read it again (in the case of a volatile register) then you must call device.get('REGISTER_NAME') again.

Set

Set cleans up the current conflation of read and write whereupon using this pattern:

with device.REGISTER_NAME as REGISTER_NAME:
    REGISTER_NAME.set_status(status)
    REGISTER_NAME.set_interrupt(interrupt)
    REGISTER_NAME.write()

Could result in errors where the user (me, usually) forgets to call write() and their expected register changes are thus never written. set is explicit about the fact it's for writing to a register, and thus does not allow for this mistake, the above code would become:

device.set('REGISTER_NAME',
                status=status,
                interrupt=interrupt)

This still allows for multi-register writes, but it is disambiguated from the get method and ensures your changes are always written to device. Under the hood this function reads the current register state, locks it, updates all the fields you have supplied, writes the changed register value(s) back to the device, and unlocks the register.

This change should come with a deadline for deprication of the existing, confusing and fragile API methods- removing the pattern device.REGISTER_NAME.get_field_name() in favour of device.get('REGISTER_NAME').field_name. This is a subtle aesthetic change on the face of it, but under the hood the latter method does not rely on any fragile and overzealous getattribute trickery.

@rabid-inventor and @Septolum - since you've both worked with i2cdevice I'd appreciate your feedback here. All of our libraries can, and should be migrated over to this new style pretty easily and this will - hopefully (@Septolum correct me if I'm wrong) facilitate MicroPython compatibility without having to use the ugly (and non read/write combining) device.set_field('REGISTER_NAME', 'FIELD_NAME', value) and `device.get_field('REGISTER_NAME', 'FIELD_NAME') approach.

[coveralls]

Pull Request Test Coverage Report for Build 23

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 3 unchanged lines in 1 file lost coverage.
• Overall coverage increased (+0.2%) to 98.565%

---

Files with Coverage Reduction	New Missed Lines	%
i2cdevice/init.py	3	98.37%

Totals
Change from base Build 13:	0.2%
Covered Lines:	206
Relevant Lines:	209

---

💛 - Coveralls

[Gadgetoid]

A possible flaw in this approach may be the instability of namedtuple in CircuitPython. See: https://circuitpython.readthedocs.io/en/3.x/docs/library/collections.html

There's nothing particularly special about namedtuple as a return type, it's just a fancy class that implements a property for each register field. However, reimplimenting it to avoid potential issues with CircuitPython's namedtyple might result in us bumping into the same problems that made the getattribute overloading approach untenable.

[Gadgetoid]

Libraries using i2cdevice -

• lsm303d-python - Port to new i2cdevice API lsm303d-python#3 - release https://github.com/pimoroni/lsm303d-python/releases/tag/v0.0.4
• bme280-python - Port to new i2cdevice API bme280-python#2 - release https://github.com/pimoroni/bme280-python/releases/tag/v0.0.2
• bmp280-python - Port to new i2cdevice API bmp280-python#4 - release https://github.com/pimoroni/bmp280-python/releases/tag/v0.0.3
• veml6075-python - Port to new i2cdevice API veml6075-python#1 - release https://github.com/pimoroni/veml6075-python/releases/tag/v0.0.2
• ht0740-python - Port to new i2cdevice API ht0740-python#1 - release https://github.com/pimoroni/ht0740-python/releases/tag/v0.0.2
• as7262-python - Port to new i2cdevice API as7262-python#4 - release https://github.com/pimoroni/as7262-python/releases/tag/v0.1.0
• bh1745-python - Port to new i2cdevice API bh1745-python#3 - release https://github.com/pimoroni/bh1745-python/releases/tag/v0.0.4
• msa301-python - Port to new i2cdevice API msa301-python#1 - release https://github.com/pimoroni/msa301-python/releases/tag/v0.0.2
• ltr559-python - Port to i2cdevice next ltr559-python#8 - release https://github.com/pimoroni/ltr559-python/releases/tag/v0.1.0
• ads1015-python - Port to new i2cdevice API ads1015-python#2 - release https://github.com/pimoroni/ads1015-python/releases/tag/v0.0.4
• rv3028-python - Ported to new i2cdevice API, bugfixes rv3028-python#7 - release https://github.com/pimoroni/rv3028-python/releases/tag/v0.0.4
• mcp9600-python - Port to new i2cdevice API, various linting fixes and expanded test coverage mcp9600-python#2 - release https://github.com/pimoroni/mcp9600-python/releases/tag/v0.0.3
• max30105-python - Port to new i2cdevice API, tests and fixes max30105-python#3 - release https://github.com/pimoroni/max30105-python/releases/tag/v0.0.2
• drv2605-python - Port to new i2cdevice API drv2605-python#1 - release https://github.com/pimoroni/drv2605-python/releases/tag/v0.0.2