ATtiny804 Pin Mapping Discrepancy with megaTinyCore Library

[krishank652]

Dear megaTinyCore Community,

I'm using the megaTinyCore library to program an ATtiny804 microcontroller. I've noticed a discrepancy between the physical pin numbers and the program pin configuration for setting pin modes.

As shown in the provided image (https://github.com/SpenceKonde/megaTinyCore/assets/157563241/3554bd8e-6baa-4fd4-9706-bceb3f7f1574), the ATtiny804 has 14 pins. However, when setting pin modes in the code, we need to use different numbers ("program pin configuration") than the physical pin numbers.

For example, to set physical pin 2 as an output high, we need to use pinMode(0, OUTPUT, HIGH). This mismatch can be confusing, especially when referencing pins in libraries.

Here are my specific questions:

1. Why is there a difference between the physical pin numbers and the program pin configuration?
2. When using libraries that reference RX and TX pins, which pin numbers should I use: 6 and 7 (physical pins) or 4 and 5 (program pin configuration)?
3. Similarly, for libraries requiring a pin named SS, should I use physical pin 2 or program pin 0?

Clarifying this pin mapping discrepancy would be greatly appreciated by users of the megaTinyCore library. Thank you for your time and assistance.

[SpenceKonde]

1. The physical pin numbers have never been what you use to refer to pins from within the code. Physical pin 0 is Vcc. You can't digitalRead() the Vcc pin, and you certainly can't write it either. Power and ground pins have never been given logical pin numbers.
2. Physical pin numbers are never used by the code, Only logical pin numbers can be used, however use of unadorned numbers to reference pins (which I think is one of the biggest mistakes of Arduino proper) is not advised in general
3. As above.

This is all described under the "How to refer to pins" section of the readme (which it sounds as though you have not read), where I describe the preferred method to refer to pins: PIN_Pxn (where x is a capital letter for the port, and n is is the number of the pin.) Ex: PIN_PA1 This has a number of benefits - it removes any shred of ambiguity about what is being referred to. Imagine you have written code and then realize that you need to swap two pins. Where in the code did you reference them, let's see those are logical pins 4 and 5. Let's search the code for... every place I used the number 4 or 5? [, ][45][ ,\)]? That's gonna get a lot of bogus results. You search for PIN_PB3 and PIN_PB2 - if you always use PIN_Pxn notation to refer to pins, that would get every place you referred to either pin. An even bigger advantage of the PIN_Pxn notation is that, as you may notice looking at that list of pinout images you linked, while perpherals are on different physical pin numbers, and different Arduino pin numbers on say, the 14 pin vs the 24 pin ones - they aren't on different PIN_Pxn numbers! So you can easily write code that is portable across the whole tiny range. You can also open up the manufacturer datasheet and, if you've been using PIN_Pxn notation, you'll recognize all the pins, because the manufacturer refers to pins by port and bit as Pxn.

In the variant file, where the Arduino pin numbers are defined and the tables that map the arduino pin numbers to port/bit are located, I always have PIN_Pxn defines for every pin on the part to point to the arduino pin number assigned to that port/bit.

This also means that if we ever end up forced to support an inferior pin mapping, if you've been using PIN_Pxn, you can use that pin mapping or the old one and the code will behave identically [except for binary size and execution speed, see below]. If some aliexpress vendor whose defective piece of junk I give a scathing review, or a customer who is unhappy with my customer service also happens to be a madman, and I was killed by a mailbomb a month after writing the review, and someone else took over the core and said "Well the first thing I'm doing is fixing this pinmapping" and renumbers the pins in the most optimal way - assuming he didn't bungle it, your code would work without modification as long as you used PIN_Pxn notation!

Aside about mapping optimality: See, depending on the order in which you number the pins (and no other changes, and PIN_Pxn notation used so the behavior of the sketch is the same) - just through use of a different numbering scheme, the execution speed of code and the binary size will be different! (Arduino's atmega328p numbering jumps all over the chip! They shuffled them around to make it "make more sense" Trying to copy that has spawned many horrible pin mappings (over on ATTC we have to support multiple pinouts for I think 6 families, in two cases, there are three pin mapping options - and I personally have had problems that were simply from using the wrong pin mapping there. A vaccine against those bugs was certainly an objective of PIN_Pxn numbering)
When the core defines the pin mapping, it doesn't just need to include that couple of tables saying what timers, what port etc each pin is on (it's 4 tables on mTC/DxC, 3 on classic), it also has to provide macros that translate pin numbers into analog channels (we don't talk about them on mTC, but there is a separate set of numbers that channels are known by. We decided after the disaster of ATTC's analog channel mess to sweep them under the run and staple the rug down, and analogRead() takes arduino pin numbers (which I hope will be in PIN_Pxn notation, though they by no means need to be), passes them through a macro supplied inthe variant file to find the analog channel that it needs to write to ADC0.MUXPOS to read from that pin; (ex ((p) >= 5 ? ((p) <11)? (p)-5:NOT_A_PIN):NOT_A_PIN) - purely for sake of example, not for an actual part). You can see how this macro could be very simple or very complicated depending on how well the numberings aligned, and when executing code where there are pins that are not compile time known foldable constants, it needs to bring along that calculation. So while the numberings are chosen arbitrarily by core authors, the choice has consequences in performance and binary size, not large ones, but I've been berated over 50 bytes - people really do care about flash usage.