Add AA battery stack to library and Vin to Xiao RP2040 (#394)

Add an example with a Xiao RP2040 powered from a 4x stack of AA
batteries.

Library changes:
- Add IoControllerVin, for microcontroller dev boards with a >=5v Vusb
in / Vin pin
- Add link type to Ground port and fix up some places that were still
using VoltageLink
- Make the link type covariant, so Port[GroundLink] and
Port[VoltageLink] are both Port[Any]
- Add AaBatteryStack for a series stack of AA batteries that boost the
voltage
- Change battery model to support offset ground for series stacks. A
one-of change for now, in the future most robust / consistent support
for offset ground is needed.
- Change AA battery limits to 1.0-1.6v to accommodate NiMH rechargeable
cells. 1.0v lower limit is a compromise to get the Xiao to build,
devices may want to support down to 0.9v to maximize runtime off
rechargables.

Author: ducky64

edg/abstract_parts/AbstractDevices.py

@@ -17,6 +17,6 @@ def __init__(self, voltage: RangeLike,
     self.capacity = self.ArgParameter(capacity)
     self.actual_capacity = self.Parameter(RangeExpr())
 
-    self.require(self.pwr.voltage_out.within(voltage))
+    self.require(self.pwr.voltage_out.within(voltage + self.gnd.link().voltage))
     self.require(self.pwr.current_limits.contains(current))
     self.require(self.actual_capacity.upper() >= capacity)

edg/abstract_parts/AbstractResistor.py

@@ -157,7 +157,7 @@ def __init__(self, resistance: RangeLike) -> None:
       DigitalSource.pulldown_from_supply(self.gnd)
     ), [InOut])
 
-  def connected(self, gnd: Optional[Port[VoltageLink]] = None, io: Optional[Port[DigitalLink]] = None) -> \
+  def connected(self, gnd: Optional[Port[GroundLink]] = None, io: Optional[Port[DigitalLink]] = None) -> \
       'PulldownResistor':
     """Convenience function to connect both ports, returning this object so it can still be given a name."""
     if gnd is not None:

edg/abstract_parts/IoControllerInterfaceMixins.py

@@ -91,12 +91,20 @@ class IoControllerPowerOut(BlockInterfaceMixin[IoController]):
     def __init__(self, *args, **kwargs) -> None:
         super().__init__(*args, **kwargs)
         self.pwr_out = self.Port(VoltageSource.empty(), optional=True,
-                                 doc="Power output port, typically of the device's Vdd or VddIO rail; must be used with gnd_out")
+                                 doc="Power output port, typically of the device's Vdd or VddIO rail at 3.3v")
 
 
 class IoControllerUsbOut(BlockInterfaceMixin[IoController]):
     """IO controller mixin that provides an output of the IO controller's USB Vbus."""
     def __init__(self, *args, **kwargs) -> None:
         super().__init__(*args, **kwargs)
         self.vusb_out = self.Port(VoltageSource.empty(), optional=True,
-                                  doc="Power output port of the device's Vbus, typically 5v; must be used with gnd_out")
+                                  doc="Power output port of the device's Vbus, typically 5v")
+
+
+class IoControllerVin(BlockInterfaceMixin[IoController]):
+    """IO controller mixin that provides a >=5v input to the device, typically upstream of the Vbus-to-3.3 regulator."""
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self.pwr_vin = self.Port(VoltageSink.empty(), optional=True,
+                                 doc="Power input pin, typically rated for 5v or a bit beyond.")

edg/abstract_parts/PassiveFilters.py

@@ -51,7 +51,7 @@ def __init__(self, impedance: RangeLike, time_constant: RangeLike):
     self.io = self.Export(self.rc.output.adapt_to(DigitalSource.pullup_from_supply(self.pwr)), [Output])
     self.gnd = self.Export(self.rc.gnd.adapt_to(Ground()), [Common])
 
-  def connected(self, *, gnd: Optional[Port[VoltageLink]] = None, pwr: Optional[Port[VoltageLink]] = None,
+  def connected(self, *, gnd: Optional[Port[GroundLink]] = None, pwr: Optional[Port[VoltageLink]] = None,
                 io: Optional[Port[DigitalLink]] = None) -> 'PullupDelayRc':
     """Convenience function to connect both ports, returning this object so it can still be given a name."""
     if gnd is not None:

edg/abstract_parts/__init__.py

@@ -97,7 +97,7 @@
 from .IoControllerExportable import BaseIoControllerExportable
 from .IoControllerInterfaceMixins import IoControllerSpiPeripheral, IoControllerI2cTarget, IoControllerTouchDriver,\
     IoControllerDac, IoControllerCan, IoControllerUsb, IoControllerI2s, IoControllerDvp8
-from .IoControllerInterfaceMixins import IoControllerPowerOut, IoControllerUsbOut
+from .IoControllerInterfaceMixins import IoControllerPowerOut, IoControllerUsbOut, IoControllerVin
 from .IoControllerInterfaceMixins import IoControllerWifi, IoControllerBluetooth, IoControllerBle
 from .IoControllerProgramming import IoControllerWithSwdTargetConnector
 from .IoControllerMixins import WithCrystalGenerator

edg/electronics_model/CircuitBlock.py

@@ -9,7 +9,7 @@
 from .KiCadImportableBlock import KiCadImportableBlock
 
 
-CircuitLinkType = TypeVar('CircuitLinkType', bound=Link)
+CircuitLinkType = TypeVar('CircuitLinkType', bound=Link, covariant=True)
 class CircuitPort(Port[CircuitLinkType], Generic[CircuitLinkType]):
   """Electrical connection that represents a single port into a single copper net"""
   pass

edg/electronics_model/DigitalPorts.py

@@ -309,7 +309,7 @@ def __init__(self, voltage_out: RangeLike = RangeExpr.ZERO,
     self._bridged_internal: BoolExpr = self.Parameter(BoolExpr(_bridged_internal))
 
   @staticmethod
-  def low_from_supply(neg: Port[VoltageLink], *, current_limits: RangeLike = RangeExpr.ALL) -> DigitalSource:
+  def low_from_supply(neg: Port[GroundLink], *, current_limits: RangeLike = RangeExpr.ALL) -> DigitalSource:
     return DigitalSource(
       voltage_out=neg.link().voltage,
       current_limits=current_limits,
@@ -329,7 +329,7 @@ def high_from_supply(pos: Port[VoltageLink], *, current_limits: RangeLike = Rang
     )
 
   @staticmethod
-  def pulldown_from_supply(neg: Port[VoltageLink]) -> DigitalSource:
+  def pulldown_from_supply(neg: Port[GroundLink]) -> DigitalSource:
     return DigitalSource(
       voltage_out=neg.link().voltage,
       output_thresholds=(neg.link().voltage.upper(), float('inf')),
@@ -471,7 +471,7 @@ def __init__(self, *, voltage_limits: RangeLike = RangeExpr.ALL,
 class DigitalSingleSourceFake:
   @staticmethod
   @deprecated("use DigitalSource.sink_from_supply")
-  def low_from_supply(neg: Port[VoltageLink], is_pulldown: bool = False) -> DigitalSource:
+  def low_from_supply(neg: Port[GroundLink], is_pulldown: bool = False) -> DigitalSource:
     if not is_pulldown:
       return DigitalSource.low_from_supply(neg)
     else:

edg/electronics_model/GroundPort.py

@@ -95,7 +95,7 @@ def __init__(self):
         ))
 
 
-class Ground(CircuitPort):
+class Ground(CircuitPort[GroundLink]):
     link_type = GroundLink
     bridge_type = GroundBridge
 
@@ -118,7 +118,7 @@ def __init__(self, voltage_limits: RangeLike = Range.all()) -> None:
         self.voltage_limits = self.Parameter(RangeExpr(voltage_limits))
 
 
-class GroundReference(CircuitPort):
+class GroundReference(CircuitPort[GroundLink]):
     link_type = GroundLink
 
     def __init__(self, voltage_out: RangeLike = RangeExpr.ZERO) -> None:

edg/parts/Batteries.py

@@ -1,3 +1,5 @@
+from typing import Optional, Union
+
 from ..abstract_parts import *
 
 
@@ -6,7 +8,7 @@ def __init__(self, voltage: RangeLike = (2.0, 3.0)*Volt, *args,
                actual_voltage: RangeLike = (2.0, 3.0)*Volt, **kwargs):
     super().__init__(voltage, *args, **kwargs)
     self.pwr.init_from(VoltageSource(
-      voltage_out=actual_voltage,  # arbitrary from https://www.mouser.com/catalog/additional/Adafruit_3262.pdf
+      voltage_out=self.gnd.link().voltage + actual_voltage,  # arbitrary from https://www.mouser.com/catalog/additional/Adafruit_3262.pdf
       current_limits=(0, 10)*mAmp,
     ))
     self.gnd.init_from(Ground())
@@ -32,7 +34,7 @@ def __init__(self, voltage: RangeLike = (2.5, 4.2)*Volt, *args,
                actual_voltage: RangeLike = (2.5, 4.2)*Volt, **kwargs):
     super().__init__(voltage, *args, **kwargs)
     self.pwr.init_from(VoltageSource(
-      voltage_out=actual_voltage,  # arbitrary from https://www.mouser.com/catalog/additional/Adafruit_3262.pdf
+      voltage_out=self.gnd.link().voltage + actual_voltage,
       current_limits=(0, 2)*Amp,  # arbitrary assuming low capacity, 1 C discharge
     ))
     self.gnd.init_from(Ground())
@@ -51,17 +53,18 @@ def contents(self):
       mfr='Keystone', part='1042'
     )
 
-class AABattery(Battery, FootprintBlock):
-  """AA Alkaline battery"""
+
+class AaBattery(Battery, FootprintBlock):
+  """AA battery holder supporting alkaline and rechargeable chemistries."""
   @init_in_parent
-  def __init__(self, voltage: RangeLike = (1.3, 1.7)*Volt, *args,
-               actual_voltage: RangeLike = (1.3, 1.7)*Volt, **kwargs):
+  def __init__(self, voltage: RangeLike = (1.0, 1.6)*Volt, *args,
+               actual_voltage: RangeLike = (1.0, 1.6)*Volt, **kwargs):
     super().__init__(voltage, *args, **kwargs)
+    self.gnd.init_from(Ground())
     self.pwr.init_from(VoltageSource(
-      voltage_out=actual_voltage,  # arbitrary from https://www.mouser.com/catalog/additional/Adafruit_3262.pdf
+      voltage_out=self.gnd.link().voltage + actual_voltage,
       current_limits=(0, 1)*Amp,
     ))
-    self.gnd.init_from(Ground())
 
   def contents(self):
     super().contents()
@@ -76,3 +79,33 @@ def contents(self):
       },
       mfr='Keystone', part='2460'
     )
+
+
+class AaBatteryStack(Battery, GeneratorBlock):
+    """AA Alkaline battery stack that generates batteries in series"""
+    @init_in_parent
+    def __init__(self, count: IntLike = 1, *, cell_actual_voltage: RangeLike = (1.0, 1.6)*Volt):
+        super().__init__(voltage=Range.all())  # no voltage spec passed in
+        self.count = self.ArgParameter(count)
+        self.cell_actual_voltage = self.ArgParameter(cell_actual_voltage)
+        self.generator_param(self.count)
+
+    def generate(self):
+        super().generate()
+        prev_cell: Optional[AaBattery] = None
+        prev_capacity_min: Union[FloatExpr, float] = float('inf')
+        prev_capacity_max: Union[FloatExpr, float] = float('inf')
+        self.cell = ElementDict[AaBattery]()
+        for i in range(self.get(self.count)):
+          self.cell[i] = cell = self.Block(AaBattery(actual_voltage=self.cell_actual_voltage))
+          if prev_cell is None:  # first cell, direct connect to gnd
+            self.connect(self.gnd, cell.gnd)
+          else:
+            self.connect(prev_cell.pwr.as_ground(self.pwr.link().current_drawn), cell.gnd)
+            prev_capacity_min = cell.actual_capacity.lower().min(prev_capacity_min)
+            prev_capacity_max=  cell.actual_capacity.upper().min(prev_capacity_max)
+          prev_cell = cell
+
+        assert prev_cell is not None, "must generate >=1 cell"
+        self.connect(self.pwr, prev_cell.pwr)
+        self.assign(self.actual_capacity, (prev_capacity_min, prev_capacity_max))

edg/parts/Microcontroller_Rp2040.py

@@ -372,7 +372,8 @@ def _crystal_required(self) -> bool:  # crystal needed for USB b/c tighter freq
     return len(self.get(self.usb.requested())) > 0 or super()._crystal_required()
 
 
-class Xiao_Rp2040(IoControllerUsbOut, IoControllerPowerOut, Rp2040_Ios, IoController, GeneratorBlock, FootprintBlock):
+class Xiao_Rp2040(IoControllerUsbOut, IoControllerPowerOut, IoControllerVin, Rp2040_Ios, IoController, GeneratorBlock,
+                  FootprintBlock):
   """RP2040 development board, a tiny development (21x17.5mm) daughterboard.
   Has an onboard USB connector, so this can also source power.
 
@@ -382,6 +383,7 @@ class Xiao_Rp2040(IoControllerUsbOut, IoControllerPowerOut, Rp2040_Ios, IoContro
   The 'Seeed Studio XIAO Series Library' must have been added as a footprint library of the same name.
 
   Pinning data: https://www.seeedstudio.com/blog/wp-content/uploads/2022/08/Seeed-Studio-XIAO-Series-Package-and-PCB-Design.pdf
+  Internal data: https://files.seeedstudio.com/wiki/XIAO-RP2040/res/Seeed-Studio-XIAO-RP2040-v1.3.pdf
   """
   SYSTEM_PIN_REMAP: Dict[str, Union[str, List[str]]] = {
     'VDD': '12',
@@ -411,8 +413,6 @@ def _vddio(self) -> Port[VoltageLink]:
 
   def _system_pinmap(self) -> Dict[str, CircuitPort]:
     if self.get(self.pwr.is_connected()):  # board sinks power
-      self.require(~self.vusb_out.is_connected(), "can't source USB power if power input connected")
-      self.require(~self.pwr_out.is_connected(), "can't source 3v3 power if power input connected")
       return VariantPinRemapper({
         'VDD': self.pwr,
         'GND': self.gnd,
@@ -430,14 +430,26 @@ def contents(self) -> None:
     self.gnd.init_from(Ground())
     self.pwr.init_from(self._iovdd_model())
 
+    self.pwr_vin.init_from(VoltageSink(  # based on RS3236-3.3
+      voltage_limits=(3.3*1.025 + 0.55, 7.5)*Volt,  # output * tolerance + dropout @ 300mA
+      current_draw=RangeExpr()
+    ))
     self.vusb_out.init_from(VoltageSource(
       voltage_out=UsbConnector.USB2_VOLTAGE_RANGE,
       current_limits=UsbConnector.USB2_CURRENT_LIMITS
     ))
+    self.require(~self.pwr_vin.is_connected() | ~self.vusb_out.is_connected(), "cannot use both VUsb out and VUsb in")
+    self.require((self.pwr_vin.is_connected() | self.vusb_out.is_connected()).implies(~self.pwr.is_connected()),
+                 "cannot use 3.3v input if VUsb used")
+
     self.pwr_out.init_from(VoltageSource(
       voltage_out=3.3*Volt(tol=0.05),  # tolerance is a guess
       current_limits=UsbConnector.USB2_CURRENT_LIMITS
     ))
+    self.require(~self.pwr_out.is_connected() | ~self.pwr.is_connected(), "cannot use both 3.3v out and 3.3v in")
+    self.assign(self.pwr_vin.current_draw, self.pwr_out.is_connected().then_else(  # prop output current draw
+      self.pwr_out.link().current_drawn, (0, 0)*Amp
+    ))
 
     self.generator_param(self.pwr.is_connected())