Reading ADC values is pretty common and it would be great if all ports had the same behaviour in this respect. The current situation is:

• For stm32 and esp32:

adc = machine.ADC(pin) # pin is any pin object
adc.read() # returns value between 0 and 4095

• For esp8266:

adc = machine.ADC(id) # id=0 or 1
adc.read() # returns value between 0 and 1024

• For cc3200:

periph = machine.ADC()
channel = periph.channel(pin=id) # id is a pin id, a string
channel.value() # returns value between 0 and 4095

To at least make reading values standard across ports, the return values should be in the same range across ports. I also think it's a good idea to make explicit the units/range in the name of the read method, because then it's completely unambiguous as to what it returns.

My proposal would be to specify the behaviour of machine.ADC to at least support the following usage:

adc = machine.ADC(id) # id can be an integer, pin, or any other identifier
adc.read_u16() # returns a raw integer reading between 0 and 65535 inclusive
adc.read_mv() # returns a calibrated voltage reading in millivolts (int, could be negative)
adc.read_v() # returns a calibrated voltage reading (int, or float if port supports floats)

The read_u16() method is there to get full access to the raw underlying value. read_mv() is more than just convenience: on systems that are able to calibrate the value it is very useful to be able to read a calibrated value (functionality not directly available with read_u16()), and it's an integer to avoid the need for floats. read_v() is convenience and would be read_mv()/1000.

The advantage of using a suffix for the units is that the existing read() method on the various ports can stay for backwards compatibility (at least for now).

Then there are a few items that would be useful to configure, but I don't have a concrete proposal on how to configure these just yet:

• setting bit-width precision of the ADC peripheral
• setting sample time for the reading