ADC example scaling wrong

[jordens]

The ADC examples scale the ADC codes with VREF/max_sample.

stm32h7xx-hal/examples/adc.rs

Lines 76 to 80 in a46841c

	info!(
	"ADC reading: {}, voltage for nucleo: {}",
	data,
	data as f32 * (3.3 / adc1.max_sample() as f32)
	);

max_sample = ((1 << bits) - 1) << lshift by itself is correct according to its docstring.

stm32h7xx-hal/src/adc.rs

Lines 790 to 793 in a46841c

	/// Returns the largest possible sample value for the current settings
	pub fn max_sample(&self) -> u32 {
	((1 << self.get_resolution().number_of_bits() as u32) - 1) << self.get_lshift().value() as u32
	}

But the conversion is not. VREF corresponds to 1 << bits + lshift here as in all ADCs that I know of.
c.f. stm32-rs/stm32f4xx-hal#362 (comment) and other places.

The best approach is probably to change max_sample() and its docstring.

[richardeoin]

I enjoyed the explaination on the f4 thread, thanks! Indeed this is clearly an error in the example, and a footgun in the API.

My preferred way of fixing this would be to add a new method, perhaps pub fn slope(&self) -> u32 that returns 1 << bits + lshift. After that, max_sample can be marked as depreciated.

[jordens]

Yes. Much better solution!