Pin numbers not the same as microcontroller pins?

Using Arduino Microcontrollers
1

I making a custom board based on the MKRZERO board. I'm keeping most things the same except no battery charging and no SD card. I'm following the schematic and noticed there's an LED connected to PB08. In the documentation, it says this is set/cleared with the predefined pin name "LED_BUILTIN". It also says that "unlike other boards, it uses dedicated pin 32 instead of 13". But looking on the schematic, it's as I said, Port B digital i/o #8 which is pin 7 on the 48-pin TQFP package. What is the documentation referring to when it says pin 32?

The reason I using the MKRZERO schematic as a reference is because I want to be able to choose the MKRZERO board in the Arduino IDE thus not creating any kind of custom board definition file, and by extension I'll be able to use all the existing APIs that work with that board.

Additionally, I notice there are other numbers labelled on the header pins of the MKRZERO board, but as can be seen on the schematic, these seem to have nothing to do with the actual physical pins or pin names on the microcontroller. For example, DAC0/A0 (as labelled on the header) is connected to PA02 (port A i/o #2), and the net name on the schematic is AIN0 and A1 is connected to PB02, but the net name is AIN10. Digital 0 (or rather just labelled "0" on the MKRZERO header) is PA22, and the net name is TC4-W0. Also confusing, digital i/o 2 thru 5 are labelled ~2, ~3, ~4, and ~5, with net names like TCC0-W2. I can only guess that the tilde is to differentiate i/o pins that mux with Timers and Capture/Compare inputs as opposed to Timer/Counter pins (no tilde) based on the net names TCCx and TCx. However, NONE of this is documented anywhere!

Can someone please clarify and help me understand what I'm seeing and why there are all these discrepancies?

2
3

Arduino pin numbers are not the same as the physical pins of the chip. The file referenced above contains the mapping between I/O pins (port and pin within port) and arduino pin numbers. The relationship between port pins and physical pin number is documented in the datasheet.

The better pin mapping diagrams available online contain the arduino pin number, the port pin, and sometimes even the physical pin (depending on how thorough the creator was and how advanced the target audience is) for every pin available on a microcontroller board.