Tested this with the I2C QT Rotary Encoder.

I like microdev's method because it could apply to other boards with more than one I2C whether stemma or not.

I think we might consider doing both. The board.STEMMA_I2C() has affordance.

# for primary bus:
board.I2C() = board.I2C(0)
# for secondary bus:
board.I2C(1) 
# and so on...

Let me be describe further our naming scheme for the board.SOMEBUS() singletons, and on pin or pin-group names in general. board pin names try to correspond to the silkscreen names on the board. They may also refer to specific-function pins that are not broken out to pads, but are attached to some on-board functionality, like board.LED, board.ACCELEROMETER_INTERRUPT, board.SD_CS, etc.

A few boards have defined "standard" pins to use for certain groups of pins. These usually correspond to clearly labelled pins, such as board.I2C() for SCL and SDA. Very occasionally there are pins that are not labelled, such as the SPI 2x3 header on Arduino-shaped boards, but there is a strong convention there, and the pins should be labelled. And the STEMMA/QT connectors define an I2C bus connection standard, though they are not literally labelled.

So for instance if a board had SCL, SDA, SCL1, and SDA1 pins, then it would might make sense to have board.I2C() and board.I2C1(). However, we have not tried to do board.SOMEBUS() singletons for weaker groups that are only convenience conventions. We discussed this in #5041 and 4121, specifically about the Pi Pico default buses, which actually vary between languages.

My general thought about this is that if you have to refer to documentation to figure out which pins correspond to SOMEBUSx, then you may as well just list the pins. If I were reading the code, I would have to refer to that documentation, so if instead the code uses the actual silkscreen pin names, I am better off without the pin group abstractions.

Here is an earlier discussion about this on Scott's Deep Dive with Lady Ada - https://youtu.be/5UKr0fT51ro?t=5957

Is it possible to point board.STEMMA_I2C() to board.I2C(1)? This way we can have board.BUS(instance) at the board module level and board specific names matching silk screen or documentation can be set in the board's config file.

Is it possible to point board.STEMMA_I2C() to board.I2C(1)? This way we can have board.BUS(instance) at the board module level and board specific names matching silk screen or documentation can be set in the board's config file.

That is certainly be possible. I assume you have some specific use case in mind, probably for your own boards. Could you describe how you want to use and designate multiple buses?

I did a crude implementation of my proposal and it can be found here.

I assume you have some specific use case...

I am proposing this method for a couple of reasons:

• Reduced code duplication.
• Provides more flexibility in terms of compatibility with boards.

I am looking at an implementation like that. My original intent was that the new code did not take any more space that the old one when not used, which led me to do an ugly duplication, but that's not good... Also I was not sure how to implement some of that. I'll commit an update soon.

I am not in favor of adding a parameter to the python API of board.I2C(). The idea is to add named dedicated I2C ports, in particular the STEMMA port in the case of the QT PY 2040, for discoverability. It's better for that if singletons are named in pins.c.

I am not in favor of adding a parameter to the python API of board.I2C() ...

I agree about discoverability of the bus and thus in the implementation above I have set up following redirect at board level:

// in pins.c
STATIC mp_obj_t board_stemma(void) {
    return board_uart(mp_obj_new_int(0));
}
MP_DEFINE_CONST_FUN_OBJ_0(board_stemma_obj, board_stemma);

STATIC const mp_rom_map_elem_t board_module_globals_table[] = {
    { MP_ROM_QSTR(MP_QSTR_STEMMA), MP_ROM_PTR(&board_stemma_obj) },
};

# in this case
board.STEMMA() = board.UART(0) = board.UART()

@microdev1 board.STEMMA_UART, right, to distinguish STEMMA_UART and STEMMA_I2C?

@microdev1 board.STEMMA_UART, right, to distinguish STEMMA_UART and STEMMA_I2C?

Yup, my implementation is just a poc... any name or even multiple names can be pointed to same instance at board level.

@Neradoc Are you still looking into this? If not, I can work on maturing the poc.

I pushed a new version, you declare the list of I2C pins and their number like this:

#define DEFAULT_I2C_BUS (2)
// SCL, SDA, SCL1, SDA1
#define DEFAULT_I2C_PINS { &pin_GPIO25, &pin_GPIO24, &pin_GPIO23, &pin_GPIO22 }

And declare a new I2C object with a name and then number like this:

ADD_SINGLETON_I2C_OBJ(board_stemma_i2c_obj, 1)
...
    { MP_ROM_QSTR(MP_QSTR_STEMMA_I2C), MP_ROM_PTR(&board_stemma_i2c_obj) },

It is compatible with the old style, thus not requiring any changes in boards that only have board.I2C.

I made some tweaks in the implementation and also converted SPI and UART to allow multiple instances.
I'll try and merge my branch with yours.

This might also be interesting for use on boards like the Maker Pi RP2040 that provide multiple I2Cs on grove connectors.

Actually on further thought, that board might be more trouble than its worth to do that, as it provides I2C0 and I2C1 on 3 different ports each.

I'm still not sold on the idea of a user-facing parameter to board.I2C (and others). For me it is a name for the pins marked SDA and SCL on the silkscreen for convenience, like other entries in board are names for pins, not a function for making I2C buses. board.I2C(1) looks more like it's giving a parameter to the default I2C bus, not a whole different instance on a different set of pins which have a different name.
Also I have seen confusion between board.I2C and busio.I2C, and I feel like that could increase that issue.

And I don't see a use case for it. It doesn't bring any portability since the number doesn't carry meaning. While board.STEMMA_I2C could be used to make portable code for a stemma QT breakout (pending a PR to alias it to board.I2C on relevant boards), board.I2C(1) doesn't do that. I don't see it used to loop through ports either (for scanning for example) since it's not a list, and does not provide a len().

Perhaps we can use the underlying mechanism, but not expose the parameter. Another example of multiple buses is Grand Central M4.

I agree with @Neradoc.

board.I2C() and friends shouldn't take in a parameter because instance ID is meaningless. (It could also be confused with the peripheral instance number that MP uses too.) The purpose of board isn't to replace busio.I2C(). board is about reflecting the physical API of the board and shared board design pattern benefits. I like board.STEMMA_I2C() instead because it clearly designates a feature of a board that may be uniform across multiple boards and therefore makes the code more portable.

I'm ok using numbers internally but would prefer a text identifier. Perhaps use the QSTR instead of an instance ID.

I'd suggest adding a _COUNT suffix to the defines like CIRCUITPY_BOARD_SPI so it's clearer.

Thanks for iterating on this! It'll be nice to have multiple standard names for buses.

A lot of boards have buses with pin names TX0/RX0, TX1/RX1 and so on, the instance id parameter could work nicely here.

I'm ok using numbers internally but would prefer a text identifier. Perhaps use the QSTR instead of an instance ID.

Yes, we are already doing this, for example on adafruit_qtpy_rp2040:

board.STEMMA_I2C() = board.I2C(1)

The numerical parameter is a secondary and hidden way of interacting with the buses.

Which of the following is a better way for handling of multiple bus instances?

board.BUS() = board.BUS(0), board.BUS(1)...

board.BUS() = board.BUS0(), board.BUS1()...

My preference is BUS0 and BUS1 because it emphasizes that these are names.

I would choose names related to the board nomenclature or silkscreen: I2C, I2C1, etc.

Thanks for the suggestions everyone, I haven't been able to get back to this and may not able to complete this for a while.
@Neradoc would you like to pitch in?

@microdev1 Hello! We're looking at finishing this up, but I'm unclear on exactly what is left to be done. We need to add the QT Py ESP32-S2, but I believe from the conversation above, there's at least one other thing that needs to be done? I'm hoping you can clarify so we can get this finished up. Thanks!

The instance parameter is now removed so this should be good to go.