i2ctarget documentation error filing and improvement request

[XenonFlits]

CircuitPython version

Adafruit CircuitPython 9.0.4 on 2024-04-16; Adafruit QT Py RP2040 with rp2040

Code/REPL

# n/a see Description

Behavior

n/a see Description

Description

Hi,

The sample on page https://docs.circuitpython.org/en/latest/shared-bindings/i2ctarget/index.html is kind of incomplete and insufficient.
Also, there is an error in this page.

First the error in formatting of the line "I2CTargetRequest.read() ack=False." at the bottom of the page.
I believe it should be "I2CTargetRequest.read(ack=False)"

Second the sample code: It is of little practical value, to get one going. It is even incomplete.

For example: I try to connect an i2c master to a slave (i2c target with an address). The master is a microcontroller using a few lines in CircuitPython. The slave is a microcontoller using CircuitPython too. Both are on the same breadboard, same powerrail and i2c pins are interconnected, included is a pull-up resistor on each line.

What I think one expects in the sample, is a scan to check the connection health of the target slave on i2c bus. Next logical step a read of a value over i2c of a slave register.
What I think one expects next is a write of a value over i2c to a register in the slave.
The current sample code does not provide this.

Even worse, in the sample code given, "if not r.is_read" is used with little explanation. Short names and non-related generic names make this sample extra difficult to read. (b, r, device).
Longer and self-explanatory names like "busi2c" instead of device etc.

Also, little is explained when and why ACK or NACK should be used on the bus.

I know the i2c is quite complicated, I also know that to get it to work can be a headache. So two separate pieces of sample code that runs well between two microcontrollers using CircuitPython will be a good starting point for any coder interested in using CircuitPython "i2ctarget".

Now Linux (undefined) is used as a master, which is of little help for a CircuitPython coder interested in in i2c communication between devices.

Kind regards,

Xf

Additional information

No response

[dhalbert]

A Learn Guide with an example would be helpful.

[ajmirsky]

@XenonFlits @dhalbert Happened to be recently working on understanding I2CTargets so I took what I learned and created some additional documentation. If you have a moment, could you review and see if there are additional gaps that I haven't explained clearly?

Also, I believe there is a bug in 9.04 that prevents the full example (as well as the original example) from working: during write-then-read transactions, is_restarted is never set. I'll be filing that bug shortly and will post an update here when I do. In the meantime, you can work around this by commenting out line 174-179 but make sure you replace the assertion with a proper error check of the index.

[ajmirsky]

oh, and you'll need this snippet of code to get the output to work correctly. I'll remove this dependency before submitting a pull request for this documentation

import adafruit_logging as logging


class NamedStreamHandler(logging.StreamHandler):

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

    def format(self, record):

        return f"{record.created:<0.3f}: {record.levelname} - {record.name} : {record.msg}"

[ajmirsky]

FYI: pull request opened with is_restarted fix as well as additional documentation: #9236

[ajmirsky]

@XenonFlits @dhalbert pull request #9236 approved so hopefully the new documentation is sufficient and this issue can be closed as well (?)

[tannewt]

I think it is @ajmirsky. Thanks again!