Many functions documented to return booleans are returning None.

[Human]

On a Raspberry Pi running RaspiOS Bookworm (Debian 12) with sparkfun-qwiic-serlcd installed, many functions documented to return bool are returning None.

setCursor() returns None, as do writeChar(), setFastBacklight(), disableSystemMessages(), setContrast(), and clearScreen(). The issue ultimately lies with the calls to self._i2c.writeByte() within qwiic_serlcd.py. It doesn't seem as if the available Python I2C drivers will return bool from writeByte() yet qwiic_serlcd.py appears to have been written as if they do this.

Incidentally, print() always returns True because its call to self._i2c.writeCommand() in qwiic_serlcd.py compares the None from writeCommand() to False and returns True by default. So it has the same root cause bug, but the surface manifestation is different.

The demo code appears to have been written with the understanding that these functions won't return bool as well - they just make the calls and hope they were successful.

At the very least, code function and documentation should match. It'd be ideal if we actually could get a bool back from these functions to know if the operation completed successfully. Maybe we could all avoid all these sleep() commands to reduce the number of OSError exceptions thrown by the library because we can't tell if the device is ready for the next command.

[sfe-SparkFro]

Hi there, thanks for the report!

I think we just need to update the docs. I believe all the I2C functions will actually throw exceptions if they fail for some reason, so there's no need to return a bool to indicate success anyways. @malcolm-sparkfun How's that sound?

[malcolm-sparkfun]

Sounds good, yes thank you for bringing this to our attention, we should update the comments and docs. We should also alter the functions such that they do not have return calls if they aren't returning anything useful since it's misleading.

Alternatively we could add try/excepts into these calls and return false on exception but it seems the pattern for our similar libraries is to just let the underlying i2c drivers throw exceptions when they're unhappy and allow users to have control over the catching and handling of exceptions.

[sfe-SparkFro]

Agreed, let the user do the exception handling. Exceptions also provide a lot more info than a simple Boolean, so the user can make some smarter decisions for their application.

[Human]

Thanks for your attention to this issue!

Fixing the documentation to reflect current behavior would be a fine change, I think. It wouldn't fix the reliability issues with the hardware, but it would at least let developers know that there's no way to predict whether or not a given API call succeeded or completed, and that it's up to them to assume that any API call will often throw exceptions that corrupt the display, forcing the entire thing to be re-drawn.

[Human]

@sfe-SparkFro Just to clarify, for this particular application, I'm unaware of what smarter decisions can be made based on the nature of the exception thrown. A thrown exception can come with screen corruption, and the remedy appears to be to redraw the entire character matrix on the LCD because we can't know where the corruption appeared.

[sfe-SparkFro]

many functions documented to return bool are returning None

It wouldn't fix the reliability issues with the hardware

Is this an XY problem?

Is your display not working correctly? If so, we should try to address that. I2C commands should "just work" without much need to resend commands over and over again.

Can you explain more about the reliability issues you're seeing? Is the screen displaying weird characters or something? Or are you getting exceptions thrown? Could you post some replication code and the exact output of your code? A wiring diagram of your setup would also be helpful, and the I2C configuration of your Pi.

[Human]

I can go into that, sure. Would you like me to open a new issue detailing the reliability issues?

[sfe-SparkFro]

Yes please!

[Human]

@sfe-SparkFro Please see #9 for that discussion. Thanks for offering to go over the details.

For this discussion, it'd still be a nice step to bring the API and the API documentation in line with what it's actually returning from the API calls.

[sfe-SparkFro]

This should be resolved when #10 gets merged! Going to preemptively close this issue.

Thank you!