Extend AnalogIn API: read_voltage

[AGlass0fMilk]

Summary of changes

For calculating real-world parameters (eg: ohms, amps) from ADC readings, it is often useful to know the actual voltage represented by the ADC's numerical output. This functionality can indeed be abstracted elsewhere, but I think it makes sense to put this in the ADC API itself.

As it stands, the AnalogIn API only provides a normalized output and leaves the application up to calculate the actual voltage based on the system's ADC reference.

This PR adds the ability for the user to configure a default ADC Vref by overriding target.default-adc-vref. Additionally, an AnalogIn instance's reference voltage can be set at runtime in case multiple ADC references are possible in the target (in the case of multiple ADC peripherals or internally configurable ADC references such as in the case of Nordic chips).

Impact of changes

Since this PR only extends the AnalogIn API, there should be no impacts on existing users.

Migration actions required

None

Documentation

I will update AnalogIn API documentation once this PR has been discussed with the Mbed OS team and agreed upon.

---

Pull request type

[] Patch update (Bug fix / Target update / Docs update / Test update / Refactor)
[X] Feature update (New feature / Functionality change / New API)
[] Major update (Breaking change E.g. Return code change / API behaviour change)

---

Test results

[] No Tests required for this change (E.g docs only update)
[X] Covered by existing mbed-os tests (Greentea or Unittest)
[] Tests / results supplied as part of this PR

---

Reviewers

---

[ciarmcom]

@AGlass0fMilk, thank you for your changes.
@ARMmbed/mbed-os-tools @ARMmbed/mbed-os-core @ARMmbed/mbed-os-maintainers please review.

[0xc0170]

Why was the default value chosen to be in drivers, not part of HAL as each target (=board in this case) can overwrite this value - it's board dependent (external vs internal ref used).

[AGlass0fMilk]

Why was the default value chosen to be in drivers, not part of HAL as each target (=board in this case) can overwrite this value - it's board dependent (external vs internal ref used).

Good point. I immediately thought "AnalogIn configuration ==> mbed_lib.json in drivers folder"

I can change it to a target-level configuration and add it to the base target that everything inherits from to provide a default. Would that be acceptable?

[0xc0170]

I can change it to a target-level configuration and add it to the base target that everything inherits from to provide a default. Would that be acceptable?

I would think that would be better in this case. Any objections?

[AGlass0fMilk]

I will rebase this soon. Had a thought though:

In the future the AnalogIn (and all Analog-related API's, really) should be redesigned. The function set_reference_voltage should not just set an internal scalar, but also be able to interact with a new HAL function that actually attempts to set the internal reference voltage. This would allow developers greater control over their analog peripherals while still using Mbed's APIs.

[AGlass0fMilk]

@0xc0170 I addressed the outstanding issues with this PR and rebased.

Let me know if any other changes are needed.

[AGlass0fMilk]

Any update on the CI? LGTM

[0xc0170]

CI restarted

Any update on the CI? LGTM

It should be stable ,so lets try

Pull request has been modified.

[AGlass0fMilk]

@0xc0170 @kjbracey-arm
Let me know if there are any other changes that should be made or if this needs a rebase.

[AGlass0fMilk]

@0xc0170 @kjbracey-arm Any update on this PR? I have addressed all change requests.

[AGlass0fMilk]

@0xc0170 Any update on this? It's blocking development at my company.

[adbridge]

@AGlass0fMilk I'll see if I can get someone to review and move this on.

[0xc0170]

Ci triggered

@ithinuel Can you review if this is now OK to go in?

[mbed-ci]

Test run: SUCCESS

Summary: 6 of 6 test jobs passed
Build number : 2
Build artifacts

[0xc0170]

Waiting on @ithinuel review

[ithinuel]

LGTM

[AGlass0fMilk]

@0xc0170 merge merge merge!