[RSDK-7154] update analog reader interface to include range/accuracy (#619)

Surprisingly, the compiled protobufs in this repo already have the new data, and all I needed to do was start using it!

When reading an analog pin on a board, you now get the raw value, the minimum/maximum possible value the reader can output, and the minimum change the reader can notice.

Author: penguinland

src/viam/components/board/__init__.py

@@ -18,7 +18,7 @@ async def create_status(component: Board) -> Status:
     for x in analog_names:
         analog = await component.analog_by_name(x)
         read = await analog.read()
-        analogs[x] = read
+        analogs[x] = read.value
 
     for y in digital_interrupt_names:
         digital_interrupt = await component.digital_interrupt_by_name(y)

src/viam/components/board/board.py

@@ -1,13 +1,19 @@
 import abc
 from datetime import timedelta
+import sys
 from typing import Any, Dict, Final, List, Optional
 
-from viam.proto.component.board import PowerMode, StreamTicksResponse
+from viam.proto.component.board import PowerMode, StreamTicksResponse, ReadAnalogReaderResponse
 from viam.resource.types import RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, Subtype
 from viam.streams import Stream
 
 from ..component_base import ComponentBase
 
+if sys.version_info >= (3, 10):
+    from typing import TypeAlias
+else:
+    from typing_extensions import TypeAlias
+
 Tick = StreamTicksResponse
 TickStream = Stream[Tick]
 
@@ -38,11 +44,18 @@ class Analog:
         name: str
         """The name of the analog pin"""
 
+        Value: "TypeAlias" = ReadAnalogReaderResponse
+        """
+        Value contains the result of reading an analog reader. It contains the raw data read,
+        the reader's minimum and maximum possible values, and its step size (the minimum possible
+        change between values it can read).
+        """
+
         def __init__(self, name: str):
             self.name = name
 
         @abc.abstractmethod
-        async def read(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> int:
+        async def read(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> Value:
             """
             Read the current value from the reader.
 
@@ -59,7 +72,7 @@ async def read(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optiona
                 reading = await reader.read()
 
             Returns:
-                int: The current value.
+                Value: The current value, including the min, max, and step_size of the reader.
             """
             ...
 

src/viam/components/board/client.py

@@ -19,7 +19,6 @@
     PWMRequest,
     PWMResponse,
     ReadAnalogReaderRequest,
-    ReadAnalogReaderResponse,
     SetGPIORequest,
     SetPowerModeRequest,
     SetPWMFrequencyRequest,
@@ -48,12 +47,11 @@ async def read(
         extra: Optional[Dict[str, Any]] = None,
         timeout: Optional[float] = None,
         **__,
-    ) -> int:
+    ) -> Board.Analog.Value:
         if extra is None:
             extra = {}
         request = ReadAnalogReaderRequest(board_name=self.board.name, analog_reader_name=self.name, extra=dict_to_struct(extra))
-        response: ReadAnalogReaderResponse = await self.board.client.ReadAnalogReader(request, timeout=timeout)
-        return response.value
+        return await self.board.client.ReadAnalogReader(request, timeout=timeout)
 
     async def write(
         self,

src/viam/components/board/service.py

@@ -138,8 +138,7 @@ async def ReadAnalogReader(self, stream: Stream[ReadAnalogReaderRequest, ReadAna
         except ResourceNotFoundError as e:
             raise e.grpc_error
         timeout = stream.deadline.time_remaining() if stream.deadline else None
-        value = await analog_reader.read(extra=struct_to_dict(request.extra), timeout=timeout, metadata=stream.metadata)
-        response = ReadAnalogReaderResponse(value=value)
+        response = await analog_reader.read(extra=struct_to_dict(request.extra), timeout=timeout, metadata=stream.metadata)
         await stream.send_message(response)
 
     async def GetDigitalInterruptValue(self, stream: Stream[GetDigitalInterruptValueRequest, GetDigitalInterruptValueResponse]) -> None:

tests/mocks/components.py

@@ -230,12 +230,12 @@ async def do_command(self, command: Mapping[str, ValueTypes], *, timeout: Option
 
 
 class MockAnalog(Board.Analog):
-    def __init__(self, name: str, value: int):
-        self.value = value
+    def __init__(self, name: str, value: int, min_range: float, max_range: float, step_size: float):
+        self.value = self.Value(value=value, min_range=min_range, max_range=max_range, step_size=step_size)
         self.timeout: Optional[float] = None
         super().__init__(name)
 
-    async def read(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> int:
+    async def read(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> Board.Analog.Value:
         self.extra = extra
         self.timeout = timeout
         return self.value

tests/test_board.py

@@ -45,8 +45,8 @@ def board() -> MockBoard:
     return MockBoard(
         name="board",
         analogs={
-            "reader1": MockAnalog("reader1", 3),
-            "writer1": MockAnalog("writer1", 5),
+            "reader1": MockAnalog("reader1", 3, 0.0, 1.0, 0.1),
+            "writer1": MockAnalog("writer1", 5, 0.0, 1.0, 0.1),
         },
         digital_interrupts={
             "interrupt1": MockDigitalInterrupt("interrupt1"),
@@ -119,7 +119,7 @@ async def test_status(self, board: MockBoard):
         assert status.name == MockBoard.get_resource_name(board.name)
         assert status.status == message_to_struct(
             BoardStatus(
-                analogs={"reader1": int(read1), "writer1": int(read2)},
+                analogs={"reader1": int(read1.value), "writer1": int(read2.value)},
                 digital_interrupts={"interrupt1": val},
             )
         )
@@ -171,6 +171,9 @@ async def test_read_analog(self, board: MockBoard, service: BoardRPCService):
             request = ReadAnalogReaderRequest(board_name=board.name, analog_reader_name="reader1", extra=dict_to_struct(extra))
             response: ReadAnalogReaderResponse = await client.ReadAnalogReader(request, timeout=4.4)
             assert response.value == 3
+            assert response.min_range == 0.0
+            assert response.max_range == 1.0
+            assert response.step_size == pytest.approx(0.1)
 
             reader = cast(MockAnalog, board.analogs["reader1"])
             assert reader.extra == extra