m0: error messages refer to confusing pin names

[deshipu]

I just tried the latest release of the CircuitPython for the Feather M0 Basic, and I noticed a problem with some of the error messages. I tried to replicate the LED fading in and out, so I did this:

>>> p = nativeio.AnalogOut(board.D13)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: AnalogOut only supported on pin PA02.

However, I can't seem to be able to find the pin PA02 anywhere. The board module only contains this:

>>> board.
A0              A1              A2              A3
A4              A5              SCK             MOSI
MISO            D0              RX              D1
TX              SDA             SCL             D5
D6              D9              D10             D11

I tried to pass the pin name as a string, but that results in this:

>>> p = nativeio.AnalogOut('PA02')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: Expected a Pin

Finally, I went to the reference documentation at http://circuitpython.readthedocs.io/en/latest/shared-bindings/nativeio/AnalogOut.html and discovered, that I'm not supposed to be using the pins from the board module, but instead import pin from microcontroller and use those. Fine, I wonder what the board module is for then...

Anyways, I searched the documentation further to try and find out which physical pin on the board the microcontroller.pin.PA02 refers to, but I wasn't able to find it. I know that I can just go to the Feather M0 product page and look at the datasheet for the microcontroller and compare it with the schematic to learn that, but I think this is a bit more of an effort than an everage user can do.

Would it make more sense to either put that reference somewhere in the documentation, or use the pin constants defined in the board module?

[tannewt]

Yup, I agree its confusing. Maybe it'd be better to omit the PA02 from the error message and simply say its not supported. I used PA02 for that example because no matter what board, PA02 is the only one that support analog out.

The board module is meant to provide easy names for the pins broken out by a particular board. The underlying objects are the same. Its a good idea to auto-generated board specific docs on the mapping.

I'll leave this open because it has a number of good ideas.

[deshipu]

Is there any way to display what microcontroller pins refer to which board pins? Maybe the repr of the pin objects should include that information?

[tannewt]

Yup, I totally agree. I hope to capture that in #76 .

For now, its defined here: https://github.com/adafruit/circuitpython/blob/master/atmel-samd/boards/feather_m0_basic/pins.c

[deshipu]

Thinking about this a bit more, it would be nice if the __repr__ also displayed the pin's capabilities/alternate functions (timers, dac, adc, etc.) -- since you can't create a pin object, we don't have to follow the convention that the repr should tell you how the constructor was called -- we can make up our own parameters, since the user will never be able to call it.

It also would be nice to have a way of telling the board pin from the microcontroller.pin pin -- preferably in a way that could be used in the programs to display messages about pins.