Protected pins dict and instead exposed a get_pin function on device.

This allows introspection on pin internals to making usage easier.

Author: CreatingNull

CHANGES.rst

@@ -32,6 +32,8 @@ Version 0.5.0
   This allows us more freedom to build higher level decoding functions.
 * Adding functionality to include ADC and GPIO responses as objects stored
   in the device pins.
+* Protected pins dict and instead exposed a get_pin function on device.
+  This allows introspection on pin internals to making usage easier.
 
 Version 0.4.0
 -------------

uoshardware/abstractions.py

@@ -309,6 +309,8 @@ class Pin:
     # pylint: disable=too-many-instance-attributes
     # Due to the nature of embedded pin complexity.
 
+    index: int = -1
+
     gpio_out: bool = False
     gpio_in: bool = False
     dac_out: bool = False
@@ -330,9 +332,25 @@ class Device:
     name: str
     interfaces: list
     functions_enabled: dict
-    pins: dict[int, Pin] = field(default_factory=dict)
+    _pins: dict[int, Pin] = field(default_factory=dict)
     aux_params: dict = field(default_factory=dict)
 
+    def get_pin(self, pin_index) -> Pin:
+        """Return a pin object corresponding to index.
+
+        :param pin_index: The index of the pin to return.
+        :return: Pin object for provided index.
+        """
+        if pin_index not in self._pins:
+            raise UOSRuntimeError(
+                f"Pin index {pin_index} doesn't exist for device {self.name}"
+            )
+        return self._pins[pin_index]
+
+    def get_pins(self) -> set:
+        """Return a set of pin indices known by this device."""
+        return set(self._pins.keys())
+
     def get_compatible_pins(self, function: UOSFunction) -> dict:
         """Return a dict of pin objects that are suitable for a function.
 
@@ -348,7 +366,7 @@ def get_compatible_pins(self, function: UOSFunction) -> dict:
             return {}
         return {
             pin_index: pin
-            for pin_index, pin in self.pins.items()
+            for pin_index, pin in self._pins.items()
             if all(
                 getattr(pin, requirement) for requirement in function.pin_requirements
             )
@@ -368,11 +386,11 @@ def update_adc_samples(self, result: ComResult):
         sample_values = result.get_rx_payload(0)
         logger.debug("Device returned sampled adc values %s", sample_values)
         for sample_index, pin in enumerate(result.tx_packet.payload):
-            if pin not in self.pins:
+            if pin not in self._pins:
                 raise UOSRuntimeError(
                     f"Can't update ADC samples on pin {pin} as it's invalid for {self.name}."
                 )
-            self.pins[pin].adc_reading = ADCSample(
+            self._pins[pin].adc_reading = ADCSample(
                 sample_values[sample_index * 2 : sample_index * 2 + 2],
                 steps=pow(2, self.aux_params["adc_resolution"]),
                 reference=self.aux_params["adc_reference"],
@@ -381,7 +399,7 @@ def update_adc_samples(self, result: ComResult):
                 "Setting pin %s adc reading to %s",
                 pin,
                 # This is a false call as it can't be None here.
-                self.pins[pin].adc_reading.value,  # type: ignore
+                self._pins[pin].adc_reading.value,  # type: ignore
             )
 
     def update_gpio_samples(self, result: ComResult):
@@ -394,14 +412,14 @@ def update_gpio_samples(self, result: ComResult):
         logger.debug("Device returned sampled gpio values %s", sample_values)
         for sample_index, pin in enumerate(sample_values):
             pin = result.tx_packet.payload[2 * sample_index]
-            if pin not in self.pins:
+            if pin not in self._pins:
                 raise UOSRuntimeError(
                     f"Can't update GPIO samples on pin {pin} as it's invalid for {self.name}."
                 )
-            self.pins[pin].gpio_reading = DigitalSample(sample_values[sample_index])
+            self._pins[pin].gpio_reading = DigitalSample(sample_values[sample_index])
             logger.debug(
                 "Setting pin %s gpio reading to %s",
                 pin,
                 # This is a false call as it can't be None here.
-                self.pins[pin].gpio_reading.value,  # type: ignore
+                self._pins[pin].gpio_reading.value,  # type: ignore
             )

uoshardware/devices/_arduino.py

@@ -14,7 +14,7 @@
         UOSFunctions.hard_reset.name: [Persistence.NONE],
         UOSFunctions.get_system_info.name: [Persistence.NONE],
     },
-    pins={
+    _pins={
         2: Pin(gpio_out=True, gpio_in=True, pull_up=True),
         3: Pin(
             gpio_out=True,
@@ -94,9 +94,9 @@
     name="Arduino Uno 3",
     interfaces=_ARDUINO_NANO_3.interfaces,
     functions_enabled=_ARDUINO_NANO_3.functions_enabled,
-    pins={  # Doesn't expose the addition mux'd ADCs.
-        pin_index: value
-        for pin_index, value in _ARDUINO_NANO_3.pins.items()
+    _pins={  # Doesn't expose the additional mux'd ADCs.
+        pin_index: _ARDUINO_NANO_3.get_pin(pin_index)
+        for pin_index in _ARDUINO_NANO_3.get_pins()
         if pin_index not in {20, 21}
     },
     aux_params={"default_baudrate": 115200, "adc_reference": 5, "adc_resolution": 10},