val = ADC.read_v() # read voltage, float
val = ADC.read_mv() # read mV, integer

Why there's need for duplicate functions? Just read_mv() should be enough and will work on any port. (Btw, cc3200 is very good port to have in the mainline, should not be dropped.) And that's if "ADC" really should be able to read volts, instead of just doing generic analog to digital conversion.

And was mentioned in previous discussions, "read" is a stream interface verb, if there's another easy alternative, it should be used, and here get_u16, etc. is an obvious choice.

split up this way into two classes (ADC and ADCBlock)

Well, there's no pattern of this "Block" suffix in the machine API, while the issue of "basic" vs "advanced" control of peripherals definitely exists. And makes sense to consider whether this "Block" naming would scale. For example, why not use "ADCExt"?

Why there's need for duplicate functions? Just read_mv() should be enough and will work on any port.

Because adc.read_v() will be the main, convenience one that is used at the REPL and in quick scripts (the reason why i2c.readfrom exists, as well as i2c.readfrom_into), and because a float will give more precision than an integer in millivolts. Ports without floating point can just return an integer for adc.read_v().

And that's if "ADC" really should be able to read volts, instead of just doing generic analog to digital conversion.

As talked about in #3943 (comment), a lot of actual ADCs provide a calibrated reading, and this seems the natural way to get such a calibrated value (and if it's not calibrated automatically then it would need to be done manually in the code to make sense of the measured value).

And was mentioned in previous discussions, "read" is a stream interface verb, if there's another easy alternative, it should be used, and here get_u16, etc. is an obvious choice.

Read was chosen because it is an obvious choice: it's making a reading of the voltage, doing an action. "Get" implies that it's just a constant value that can be retrieved, and that getting twice in a row would yield the same value (which it won't).

Using read keeps things more consistent because there's no need to remember if this particular class uses read, or get, or something else. Everything uses read, no need to think, muscle memory typing it is the same.

If there was an extension added to read multiple values at once (eg over time, like stm32 has read_timed()) then read as a verb makes more sense because it's doing a reading of many values.

And read_u16() has the same signature and return value as it would if it were a stream method, so why not use it here?

Well, there's no pattern of this "Block" suffix in the machine API, while the issue of "basic" vs "advanced" control of peripherals definitely exists. And makes sense to consider whether this "Block" naming would scale. For example, why not use "ADCExt"?

Because it's not an extension to ADC. ADCBlock is supposed to represent an actual entity, the ADC converter block itself. Really ADC and ADCBlock should be ADCChannel and ADC respectively (like it is currently in cc3200), but I wanted to make it simpler for the vast majority of cases where only the "channel" is needed, and for ports that don't want to/can't expose the concept of ADCBlock. So ADC is an endpoint that reads values, and ADCBlock is the super-entity that "contains" ADC's. On some MCUs there can be multiple ADCBlock's, each representing one of the converters.

... ADCBlock is supposed to represent an actual entity, the ADC converter block itself. ...

Ok, sounds good. But another question isn't answered - is it a new pattern reusable across machine API, or just random adhoc case for ADC?

Because adc.read_v() will be the main, convenience one that is used at the

Well, "main" and "convenience" contradict each other. "Main" should be something which is consistent and reusable across ports, and "convenience" can go into "from easy_hw import *".

Ports without floating point can just return an integer for adc.read_v().

Yes, that's the point - everyone will use it, and it won't be usable on non-FP ports. And (AFAIK) it's the first case of adding float func to machine API, and opens black hole with this stuff. And I'm not aware of any C low-level lib/HALs with return floats, and the promise was that MicroPython tries to not be much worse than C (and yes, using floats is worse - more overhead, slower operation).

"Get" implies that it's just a constant value that can be retrieved, and that getting twice in a row would yield the same value (which it won't).

Why suddenly? "Get" is a standard accessor name, there's an "ADC" block, it maintains a current value, you use "get" to get it.

Using read keeps things more consistent because there's no need to remember if this particular class uses read, or get, or something else.

Easy to remember - "read" is reserved for streams and stream-likes, everything else tries to use "get".

Everything uses read, no need to think, muscle memory typing it is the same.

That's exactly a danger of too much generalization, where it may lead to confusion or at least less clarity.

(I obviously don't try oppose it in any way, just trying to provide a all-rounded review, including "devil's advocate" one. Because fairly speaking, nobody else cares how it's designed. The biggest issue IMHO is tainting machine API with floats. I'd bring an argument that if there's desire for cuteness, there's already CircuitPython API as an alternative, so it only makes to stick with "efficiency" requirement of the original machine API.)

... ADCBlock is supposed to represent an actual entity, the ADC converter block itself. ...

Ok, sounds good. But another question isn't answered - is it a new pattern reusable across machine API, or just random adhoc case for ADC?

It could be reused for PWM and DAC, with PWMBlock and DACBlock. PWMBlock is very similar to Timer though. I guess anything that has the concept of "channel" could have a block that represents a combination of "channels".

An alternative to ADCBlock would be to both:

1. allow to specify bits in the ADC constructor
2. allow to specify block in the ADC constructor, to have finer control over the ADC channel that is used for the ADC object.

See #4237 for a proposal about machine.PWM which is similar to ADC (although the true counterpart to ADC is DAC) and shows the idea of a using block argument instead of PWMBlock.

Renaming of old machine.ADC to machine.ADCWiPy was done in 8a23723, and initial specification of new machine.ADC class was done in e509da2

This PR is now rebased against those changes.

I've updated this based on discussion in #7788. The updated API looks like this:

ADC(id, *, sample_ns, atten) # create ADC object
ADC.init(*, sample_ns, atten) # initialise
block = ADC.block() # get the associated ADCBlock
val = ADC.read_u16() # read value between 0-65535
val = ADC.read_uv() # read uV, integer

ADCBlock(id, *, bits) # create ADC peripheral object
ADCBlock.init(*, bits) # initialise
adc = ADCBlock.connect(channel) # connect to a channel
adc = ADCBlock.connect(source) # connect up a pin or other object
adc = ADCBlock.connect(channel, source) # connect a channel to a pin