shield: m5stack m5dial

[MrMarteng]

Add support for M5Stack-Dial shield

[tejlmand]

Thanks for this proposal.

Before getting into the details of the PR itself I would like to raise a discussion
regarding the use of a shield for this devkit.

It's true that the M5Dial is built around the M5 Stamp3 board, but the compleete
solution looks more like a devkit than a shield.
https://docs.m5stack.com/en/core/M5Dial
https://docs.m5stack.com/en/core/stamps3

As a versatile embedded development board, M5Dial integrates the necessary features and sensors for various smart home control applications. It features a 1.28-inch round TFT touchscreen, a rotary encoder, an RFID detection module, an RTC circuit, a buzzer, and under-screen buttons, enabling users to easily implement a wide range of creative projects.

Some of the reasons why this looks more like a devkit, and therefore should be implemented as a board, and not a shield to be used with existing board:

• the shield cannot be purchased alone, nor used together with another board
• the M5dial itself seems to be intended as a complete stand-alone kit (like a Thingy)
  Afaict the shield and board are tightly integrated in their functionality.
• I believe users buying and developing for the M5Dial will see this as an integrated product and therefore look for a corresponding board in Zephyr, and not see this as a M5 Stamp3 board with a shield.

[MrMarteng]

@tejlmand I initially had a PR for a separate devkit (#67065). There we came to the conclusion it's better to implement the m5dial as a shield. When implementing m5dial as a separate devkit you basically need to make a copy of the stamps3 board and adjust all perihperals.
Imo using a shield for m5dial is the better solution as this has the benefit of less or nearly no redundance.

[tejlmand]

@tejlmand I initially had a PR for a separate devkit (#67065). There we came to the conclusion it's better to implement the m5dial as a shield.

Hm, I see that. I wonder why you only had @kartben added as reviewer on that PR, was it perhaps opened as draft ?

When implementing m5dial as a separate devkit you basically need to make a copy of the stamps3 board and adjust all perihperals.

which actually is true for many devkits that are based on same SoC.

I try to see this from developer's view point.
If I buy the M5Dial and want to use this kit with Zephyr, then where would I go look for documentation to see if it is supported.

Would I consider this a devkit and thus look in the boards section ?
Or would I be have the insight to actually know that this is a M5 Stamp3 board, so that I have to build for the M5 Stamp3 board and treat the dial as a shield ?

I see that @kartben comment here relates to a potential use of the dial on another board: #67065 (comment)
which is also what I mention in my comment.

But from what I can tell, using the dial on another board is not officially supported, nor pin compatible with the other stamp core modules I just browsed here https://docs.m5stack.com/en/products.

So for now I see little reason or value in creating this as a shield, but would like to hear if there are other / better arguments to why it should be a shield. Comments @kartben ?

[tejlmand]

When implementing m5dial as a separate devkit you basically need to make a copy of the stamps3 board and adjust all perihperals.

which actually is true for many devkits that are based on same SoC.

oh, and by the way a very common and proposed way to create a new board, ref:
https://docs.zephyrproject.org/latest/hardware/porting/board_porting.html#create-your-board-directory

Once you’ve found an existing board that uses your SoC, you can usually start by copy/pasting its board directory and changing its contents for your hardware.

[MrMarteng]

@tejlmand I initially had a PR for a separate devkit (#67065). There we came to the conclusion it's better to implement the m5dial as a shield.

Hm, I see that. I wonder why you only had @kartben added as reviewer on that PR, was it perhaps opened as draft ?

Yes, it was a draft at that time.

But from what I can tell, using the dial on another board is not officially supported, nor pin compatible with the other stamp core modules I just browsed here https://docs.m5stack.com/en/products.

So for now I see little reason or value in creating this as a shield, but would like to hear if there are other / better arguments to why it should be a shield. Comments @kartben ?

I am getting confused now. Maybe let's clarify the buildup of M5stack-Dial. The M5Stack-dial is physically including a M5Stack-StampS3 module (see https://shop.m5stack.com/cdn/shop/files/4_ae790f23-43de-4348-9df0-fa37c1c47dd2_1200x1200.webp?v=1696659474 for reference).
We have created a connector definition for the StampS3 module (https://github.com/zephyrproject-rtos/zephyr/blob/4bb945300bf92e4708404102d2a3b54e540bfd6c/boards/m5stack/m5stack_stamps3/m5stack_stamps3_connectors.dtsi). The M5Dial interfaces to these pin connectors. There is actually more equipment available that uses the StampS3 module (https://shop.m5stack.com/collections/m5-controllers/STAMP)

For me the definition of a board meanwhile is quite simple: If it directly features a microcontroller it is a board. If it utilizes an existing module or board and only consists of peripherals it's a shield.

If e.g. M5Stack decides to release a new Stamp-Module that is pin-compatible but maybe features a different controller, the M5dial shield may work without modification. If we maintain the M5Dial as a board we may need to create a separate board for this new combination.

[tejlmand]

The M5Stack-dial is physically including a M5Stack-StampS3 module

Correct, and I also mentioned that here: #80778 (review)

For me the definition of a board meanwhile is quite simple: If it directly features a microcontroller it is a board. If it utilizes an existing module or board and only consists of peripherals it's a shield.

If just the world was this simple.
There are other boards / devkits where one could say they should be modeled independently because they are technically a board / SoM attached to another board which provides peripherals, for example:

• https://docs.zephyrproject.org/latest/boards/actinius/icarus_som_dk/doc/index.html, where the Icarus SoM (nRF9160) is attached to another board which provides the sensors, leds, buttons, etc. but still it's modeled as a complete board in Zephyr.
  The Icarus SoM can be bought and used independently, for example in your own product.
• https://docs.zephyrproject.org/latest/boards/st/nucleo_wb05kz/doc/index.html, which provides a MCU board with Bluetooth radio, attached to a board providing leds, buttons.

and in Zephyr there are more boards like this.

[MrMarteng]

I could argue, that the examples you referred to above are quite more complex than the m5dial. And to my quick research they are also no not reused in zephyr. You may find examples and arguments for both solutions. Don't get me wrong. I initially created a board for the m5dial and switched to a shield. So I see both sides.

I believe users buying and developing for the M5Dial will see this as an integrated product and therefore look for a corresponding board in Zephyr, and not see this as a M5 Stamp3 board with a shield.

You definitely have a point here

On the other hand, I don't like the redundance. There are two additional hardware solutions in my backlog that also used the StampS3:

• https://shop.m5stack.com/products/m5stack-cardputer-kit-w-m5stamps3
• https://shop.m5stack.com/products/m5stack-capsule-kit-w-m5stamps3
  Although M5Stack is selling the M5Dial only in the bundle with StampS3, the StampS3 is designed to be used in extension hardware like the m5dial.

[kartben]

https://shop.m5stack.com/products/m5stack-cardputer-kit-w-m5stamps3

Just for the record main...kartben:zephyr:cardputer :)

[MrMarteng]

https://shop.m5stack.com/products/m5stack-cardputer-kit-w-m5stamps3

Just for the record main...kartben:zephyr:cardputer :)

I see you followed the approach implementing the cardputer as shield as well.
What's your opinion on this general discussion?

[tejlmand]

I could argue, that the examples you referred to above are quite more complex than the m5dial. And to my quick research they are also no not reused in zephyr.

The Icarus SoM exists both as the independent SoM and the devkit, so I would say that use-case is more or less the same as the M5Dial:

• The SoM standalone: https://docs.zephyrproject.org/latest/boards/actinius/icarus_som/doc/index.html
• The dk with the SoM module attached: https://docs.zephyrproject.org/latest/boards/actinius/icarus_som_dk/doc/index.html

On the other hand, I don't like the redundance.

I think we agree a lot on this. The more re-use we can have, the better.
With hwmv2 in place we now have a design in place which allows much better for future expansion.
Which is also why we have this RFC: #55637

A board can be extended by creating new variants out-of-tree with: #72857
so a logical next step would be for a board to inherit another board, and from there extend functionality, as described in #55637

In case we had the board inherit feature in place already, would you then had preferred such inherit solution over the shield approach ?
Reason i'm asking is because in that case, then perhaps start out with a board having duplicated files for now, and then when we have #55637 fully in place then we can rework the board to inherit the M5Stamp.
That way the change is seamless to the users, because the board targets stays the same.
A change from board + shield --> inherited board would instead change the user's workflow.

So I see both sides.

I think we both do, so thanks for the discussion 👍
I think having this discussion is very important as it hopefully will make a better outcome for Zephyr developers and users.

[tejlmand]

as a side-note, with introduction of HWMv2 we actually aimed for more reuse and reduction of files needed when introducing HWMv2, but had to walk-back on part of the solution for unforeseen reasons, #71149

Plan is still to allow the intended re-use but in slightly adjusted way.

[kartben]

oh, and by the way a very common and proposed way to create a new board, ref: docs.zephyrproject.org/latest/hardware/porting/board_porting.html#create-your-board-directory

@tejlmand To me this is a recommendation that applies well to out-of-tree (or at least downstream) users, but that shouldn't be the norm for in-tree boards. Do we really want all the "dev kits" sharing a same "motherboard" to duplicate everything? It simply becomes unmanageable to make sure a bug fix or improvement on said motherboard is properly applied everywhere, does it not?

I try to see this from developer's view point.
If I buy the M5Dial and want to use this kit with Zephyr, then where would I go look for documentation to see if it is supported.

Would I consider this a devkit and thus look in the boards section ?
Or would I be have the insight to actually know that this is a M5 Stamp3 board, so that I have to build for the M5 Stamp3 board and treat the dial as a shield ?

Yes, that's a fair point, hence why we need a shield model sooner than later. To me, the "board catalog" should shortly evolve into a "board + shield catalog" (in fact I already have tried it in a model-less fashion and it works really well, it's just that I don't want to deploy it as-is since the "guesses" being made on the shields' metadata due to not having a real model can sometimes lead to errors).
That catalog will effectively allow the developer to do exactly what you describe, and more:

• "Is "M5Dial" supported?" by searching by name
• "I want to quickly test something and need a devkit, I don't really care if it's a shield or a board, that has a DISPLAY, and SDCARD" which would potentially list boards and shields matching the criteria
• etc.

I think it is important that physical components that can be interfaced with a board using an abstracted out connector (Uno, Feather, ... but also more bespoke connectors like the many we have for e.g. parallel displays or, here, the "bespoke" stamp-s3-with-1.27-header-pins) are described as shields, as the composability this brings is important. Yes, the M5Dial may not be bought on its own today but I wouldn't be surprised if that's the case in the future or if M5 releases ex. an RP2040 STAMP that's pin compatible. Or, in any case, one may always want to create their own board that has a compatible connector, and they should be able to do so.

BTW another, maybe better, example of something from the M5 portfolio that def. should be a shield although it feels like it could be a board is: https://docs.m5stack.com/en/app/Atom%20JoyStick
It ships with a regular Atom-S3, but it can already be used, today, with other Atoms (ex. this one or this one), so not modelling it as a shield would be making things unecessarily difficult for people wanting to replace the default brain of their JoyStick for they really see it as a very practical shield they can use for any Atom based project where they need analog sticks.

[kartben]

#67253 (comment) this still applies

[tejlmand]

Do we really want all the "dev kits" sharing a same "motherboard" to duplicate everything?

I believe I already made my opinion clear here: #80778 (comment)
I'm too in favor of re-using as much as possible, but I prefer to first look at How should this look from logical viewpoint, and from there try to re-use, and not from, How can I reuse / avoid duplicating files and then being forced into a specific solution.

I referred to the first try of merging / inherit files which we had to roll-back, see: #80778 (comment)

I asked a question, for which no answer has been given:

so a logical next step would be for a board to inherit another board, and from there extend functionality, as described in #55637

In case we had the board inherit feature in place already, would you then had preferred such inherit solution over the shield approach ?
Reason i'm asking is because in that case, then perhaps start out with a board having duplicated files for now, and then when we have #55637 fully in place then we can rework the board to inherit the M5Stamp.
That way the change is seamless to the users, because the board targets stays the same.
A change from board + shield --> inherited board would instead change the user's workflow.

as for the other example:

BTW another, maybe better, example of something from the M5 portfolio that def. should be a shield although it feels like it could be a board is: https://docs.m5stack.com/en/app/Atom%20JoyStick

Yes, I agree, this is a better example.
In fact I believe this discussion more shows that boards vs shields are not black or white, but sometimes can be in-between.

I wonder if we should have a dedicated task (or part of #69548 / #55637) to support a board to always include a shield.
This way a given board can simply state in its board.yml that it's locked with the shield, but allows the shield to still be used independently.

But based on the comment in #80778 (comment)
I would still prefer to see such implementation to start with the m5dial to be the board, and from there work it into also having the top part as a reusable shield, because that way we won't impact the user's workflow.

[github-actions]

This pull request has been marked as stale because it has been open (more than) 60 days with no activity. Remove the stale label or add a comment saying that you would like to have the label removed otherwise this pull request will automatically be closed in 14 days. Note, that you can always re-open a closed pull request at any time.