alt functions on pins

[ag88]

it seemed most of the boards do not show the alt functions on pins, i'd think showing the alt functions would be really helpful

[ThomasGravekamp]

As far as I am aware, non of the board pages show the alternative functions of any of the pins, except for maybe the debug headers.

I am currently working on is building the board pages from a JSON file instead of the markdown files. Take a look at the refactor-boards-pages branch for a proof of concept.

Information like this could be added to the device JSON files on that branch. Do you feel like helping out with adding this information when the new JSON format is more definitive? If you do, I can provide you with more information on how I think that kind of information could be added.

[ag88]

doing JSON seem like a cool idea ;)
i tend to agree that since PAxx gpios are after all tied to device rather than boards, using json to generate the the board files would be really good. displaying the alt functions can then be done by processing the json and device files into markdown files. so that it could look like

Pin	Main	Alt
1	PA0	ADC1_1 / WKUP

one thing though is there a way that the collation / substitutions is done by github itself?
otherwise it would likely take a utility / tool to convert the json into markdowns

[ThomasGravekamp]

Github pages is based on Jekyll. Jekyll is capable of using JSON and some other formats as data sources. Combine this with templates, and the board pages can be generated.

Lookups shouldn't be too big of a problem. When generating the page, the pin name is known, for example PA0. The device is also already known, based on the device name stored in the board's JSON. Given that the pins are modelled like this:

"pins": {
    "PA0": [
        "ADC1_1",
        "WKUP"
    ]
}

When a commit is pushed to a Github pages repository, Github runs something like jekyll build and then hosts the resulting static files. No need for other tooling or something.

[ag88]

thanks, i'd check out Jekyll ! :)

[ThomasGravekamp]

I have converted some board pages to the new format. They are now based on JSON files. If you still feel up to it, you can use this to experiment with adding the alternative functions for microcontroller pins.

[ag88]

thanks ! i'd take a look, at the moment got caught out with the daily grind so i may defer this.
I'd like to suggest closing this issue at least for now as i may not work on it in a while. it is more of an 'enhancement' than a 'bug'

[ag88]

i got Jekyll running, and i noted a thing, in the json file the function is made on a per board per pin basis. while this should be ok, it would lead to quite a lot of duplications across boards e.g. all the stm32f103 PA1 will actually have the same alternate functions. would you prefer to continue with this or would you prefer 'macros'? (which i do not know how to do as i barely got ruby and jekyll running).

another way though is that we can start with this brute force approach, i.e. specify the alt function per board per pin and make do with the dups and may be refactor the programming later.

of course one of the considerations is that normally a PAxx gpio would have a set of alt functions assignments. But not all pins are gpios and hence won't have alt functions.

[ag88]

i made a PR for Blue Pill STM32F103C8 added the alt functions
#27
i've verified the page with the alt functions added looks good offline in my copy of Jekyll, but the rendered page won't appear in my repository as it isn't a github 'home' page.

[ThomasGravekamp]

As an answer to your comment before the PR:

I already thought of an approach for this. I am sure that we do not want to go the brute force way. That will indeed lead to too much duplication and cleaning that up will take a lot of work.

I want to expand on the existing JSON files in the _data/devices directory. The information in these files is already used to deduplicate information across board pages. Stuff like memory sizes and package information are stored in those files. The same goes for information on voltage regulators and other devices like external EEPROMS etc...

I want to expand those files to include a mapping from the pin number (PA6) to its alternate functions (SPI1_MISO/ADC12_IN6/TIM3_CH1) and remap (TIM1_BKIN). To make this work we need to solve another small issue. That is that a bunch of different part numbers use the same mapping.

I imagine something like this:

"STM32F103C8T6": {
    "manufacturer": {
        "name": "ST-Microelectronics",
        "url": "https://www.st.com/content/st_com/en.html"
    },
    "part": {
        "name": "STM32F103C8T6",
        "marking": "STM32F103C8T6",
        "url": "https://www.st.com/en/microcontrollers-microprocessors/stm32f103c8.html"
    },
    // Omitted other properties
    "pins": {
        "PA0": {
            "alternate": ["WKUP", "USART2_CTS", "ADC12_IN0", "TIM2_CH1_ETR"],
            "remap": []
        },
        "PA1": {
            "alternate": ["USART2_RTS", "ADC12_IN1", "TIM2_CH2"],
            "remap": []
        },
        "PA2": {
            "alternate": ["USART2_TX", "ADC12_IN2", "TIM2_CH3"],
            "remap": []
        },
        "PA3": {
            "alternate": ["USART2_RX", "ADC12_IN3", "TIM2_CH4"],
            "remap": []
        },
        "PA4": {
            "alternate": ["SPI1_NSS", "USART2_CK", "ADC12_IN4"],
            "remap": []
        },
        "PA5": {
            "alternate": ["SPI1_SCK", "ADC12_IN5"],
            "remap": []
        },
        "PA6": {
            "alternate": ["SPI1_MISO", "ADC12_IN6", "TIM3_CH1"],
            "remap": ["TIM1_BKIN"]
        },
        "PA7": {
            "alternate": ["SPI1_MOSI", "ADC12_IN7", "TIM3_CH2"],
            "remap": ["TIM1_CH1N"]
        }
    }
},

[ag88]

this is cool ;)
but i'd guess it'd take some work to rework those, but any way no hurries.

[ThomasGravekamp]

Yeah, this will take some time. I will try to look into this the coming week. One thing I want to work out first is how I can prevent duplication between some devices. When that's sorted, making changes to the template isn't even that hard.

Having this information will probably be valuable in the future too. It will, for example, make it possible to create a feature which highlights all pins that are related to SPI or more specific SPI1. It may also help in creating a separate page for each device, regardless of its board. So many ideas, so little time...

[ThomasGravekamp]

Oh, and by the way, can you please split out those changes you made to the STM32F401 black pill page in a separate PR so that we can merge those improvements separately?

[ag88]

hi, i've actually removed the image so that it isn't included. it is included accidentally. i've made a 3rd commit in the same PR which removes the image in the same pr so that what is left in the pr is just the changes for stm32f103c8 Blue Pill alt functions.

[ThomasGravekamp]

I've pushed a branch with a proof of concept implementation of automatically mapping pin names to their alternate functions. Needs some more refinement, but this is how I would like to do it.

[ag88]

i think it is a good start, but i'd guess there would be more works on the boards part and some programming to substitute alternate functions where they are relevant. i'd not be pushing any further changes as i'd think it is better for you to make the design decisions and programming.
i'm guessing alt macros could be something like "function": { "dev":"STM32F103C8", "gpio": "PA1" } and it evaluates to the relevant alt functions and maybe remap. it would still be somewhat verbose, but this becomes a lookup than patched in every board.
there is no hurry take your time ;)