1 // Copyright 2021 The Pigweed Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 4 // use this file except in compliance with the License. You may obtain a copy of 5 // the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12 // License for the specific language governing permissions and limitations under 13 // the License. 14 #pragma once 15 16 #include "pw_chrono/system_clock.h" 17 #include "pw_result/result.h" 18 19 namespace pw::analog { 20 21 /// Base interface for getting analog-to-digital (ADC) samples from one ADC 22 /// channel in a thread-safe manner. 23 /// 24 /// The ADC backend interface is up to the user to define and implement for now. 25 /// This gives flexibility for the ADC driver implementation. 26 /// 27 /// `AnalogInput` controls a specific input / channel where the ADC peripheral 28 /// may be shared across multiple channels that may be controlled by multiple 29 /// threads. The implementer of this pure virtual interface is responsible for 30 /// ensuring thread safety and access at the driver level. 31 class AnalogInput { 32 public: 33 /// Specifies the sample range. 34 /// These values do not change at runtime. 35 struct Limits { 36 /// The minimum of the sample range. 37 int32_t min; 38 /// The maximum of the sample range. 39 int32_t max; 40 }; 41 42 virtual ~AnalogInput() = default; 43 44 /// Blocks until the specified timeout duration has elapsed or the ADC sample 45 /// has been returned, whichever comes first. 46 /// 47 /// This method is thread safe. 48 /// 49 /// @returns @rst 50 /// 51 /// .. pw-status-codes:: 52 /// 53 /// OK: Returns a sample. 54 /// 55 /// RESOURCE_EXHAUSTED: ADC peripheral in use. 56 /// 57 /// DEADLINE_EXCEEDED: Timed out waiting for a sample. 58 /// 59 /// Other statuses left up to the implementer. 60 /// 61 /// @endrst TryReadFor(chrono::SystemClock::duration timeout)62 Result<int32_t> TryReadFor(chrono::SystemClock::duration timeout) { 63 return TryReadUntil(chrono::SystemClock::TimePointAfterAtLeast(timeout)); 64 } 65 66 /// Blocks until the deadline time has been reached or the ADC sample 67 /// has been returned, whichever comes first. 68 /// 69 /// This method is thread safe. 70 /// 71 /// @returns @rst 72 /// 73 /// .. pw-status-codes:: 74 /// 75 /// OK: Returns a sample on success. 76 /// 77 /// RESOURCE_EXHAUSTED: ADC peripheral in use. 78 /// 79 /// DEADLINE_EXCEEDED: Timed out waiting for a sample. 80 /// 81 /// Other statuses left up to the implementer. 82 /// 83 /// @endrst 84 virtual Result<int32_t> TryReadUntil( 85 chrono::SystemClock::time_point deadline) = 0; 86 87 /// @returns The range of the ADC sample. These values do not change at 88 /// runtime. 89 virtual Limits GetLimits() const = 0; 90 }; 91 92 } // namespace pw::analog 93