Nondirectioned Ground refactor (#364)

This introduces a dedicated non-directioned Ground type, with an
optional GroundReference which can specify the voltage level. Ground can
optionally specify a voltage tolerance.

Prior, Ground was actually just a VoltageSink in disguise, which had a
few problems stemming from the VoltageSink/VoltageSource directionality
that this fixes:
- Avoids needing explicit VoltageSource merges when connecting the
ground of multiple power supplies, eg USB + battery
- Avoids a confusing gnd and gnd_src for devices that can source or sink
power
- Eliminates unused current_draw parameter

This refactors a lot of internal libraries. Notable structural changes:
- BLDC driver current-sense resistors moved into the block, generating
if the sense pins are used.
- Ditto with the soldering iron connector
- Gate driver switch node is now a Ground
- Unify gnd and gnd_src for blocks that have both
- DecouplingCapacitor defined in terms of gnd/voltage instead of pos/neg

This change is breaking and requires some changes to top-level designs:
- Voltage-source merges for grounds for multiple power sources must be
removed
- GroundSource should be replaced with Ground (remapped with a
deprecation)
- VoltageTestPoint must be replaced with GroundTestPoint, now that the
types are different
- In general, ground-side current sense resistors are more difficult
now, the move so far is to move them into the associated block

Library cleanup to support offset grounds is needed in the future, to
make sure all devices use VoltageSink.from_gnd to use a ground-relative
voltage instead of assuming ground is 0v.

Also some internal cleanup.

Notes for the future:
- Some things that might need further thought
- Is there a clean unified way to get the voltage of a port accounting
for connected-ness and directionality? Currently, we have
`GroundLink._voltage_range` and `VoltageLink,_voltage_range`, though
code that doesn't need to be as robust uses port.link().voltage

Author: ducky64

edg/abstract_parts/AbstractCapacitor.py

@@ -328,17 +328,18 @@ def __init__(self, capacitance: RangeLike, *, exact_capacitance: BoolLike = Fals
     super().__init__()
 
     self.cap = self.Block(Capacitor(capacitance, voltage=RangeExpr(), exact_capacitance=exact_capacitance))
-    self.gnd = self.Export(self.cap.neg.adapt_to(VoltageSink()), [Common])
-    self.pwr = self.Export(self.cap.pos.adapt_to(VoltageSink(
-      voltage_limits=(self.cap.actual_voltage_rating + self.gnd.link().voltage).hull(self.gnd.link().voltage),
+    self.gnd = self.Export(self.cap.neg.adapt_to(Ground()), [Common])
+    self.pwr = self.Export(self.cap.pos.adapt_to(VoltageSink.from_gnd(
+      self.gnd,
+      voltage_limits=self.cap.actual_voltage_rating,
       current_draw=0*Amp(tol=0)
     )), [Power, InOut])
 
     self.assign(self.cap.voltage, self.pwr.link().voltage - self.gnd.link().voltage)
 
     # TODO there should be a way to forward the description string of the inner element
 
-  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) -> \
       'DecouplingCapacitor':
     """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/AbstractDevices.py

@@ -11,7 +11,7 @@ def __init__(self, voltage: RangeLike,
     super().__init__()
 
     self.pwr = self.Port(VoltageSource.empty())  # set by subclasses
-    self.gnd = self.Port(GroundSource.empty())
+    self.gnd = self.Port(Ground.empty())
 
     self.voltage = self.ArgParameter(voltage)
     self.capacity = self.ArgParameter(capacity)

edg/abstract_parts/AbstractLed.py

@@ -111,7 +111,7 @@ def __init__(self, count: IntLike, color: LedColorLike = Led.Any, *,
                current_draw: RangeLike = (1, 10) * mAmp):
     super().__init__()
     self.signals = self.Port(Vector(DigitalSink.empty()), [InOut])
-    self.gnd = self.Port(VoltageSink.empty(), [Common])
+    self.gnd = self.Port(Ground.empty(), [Common])
 
     self.color = self.ArgParameter(color)
     self.current_draw = self.ArgParameter(current_draw)

edg/abstract_parts/AbstractOpamp.py

@@ -50,7 +50,7 @@ def __init__(self):
 class MultipackOpampGenerator(MultipackOpamp, GeneratorBlock):
   """Skeleton base class that provides scaffolding for common packed opamp definitions"""
   class OpampPorts(NamedTuple):
-    gnd: VoltageSink
+    gnd: Ground
     pwr: VoltageSink
     amps: List[Tuple[AnalogSink, AnalogSink, AnalogSource]]  # amp-, amp+, out
 
@@ -68,17 +68,17 @@ def generate(self):
     super().generate()
     amp_ports = self._make_multipack_opamp()
 
-    self.gnd_merge = self.Block(PackedVoltageSource())
+    self.gnd_merge = self.Block(PackedGround())
     self.pwr_merge = self.Block(PackedVoltageSource())
-    self.connect(self.gnd_merge.pwr_out, amp_ports.gnd)
+    self.connect(self.gnd_merge.gnd_out, amp_ports.gnd)
     self.connect(self.pwr_merge.pwr_out, amp_ports.pwr)
 
     requested = self.get(self.pwr.requested())
     assert self.get(self.gnd.requested()) == self.get(self.inp.requested()) == \
            self.get(self.inn.requested()) == self.get(self.out.requested()) == requested
     for i, (amp_neg, amp_pos, amp_out) in zip(requested, amp_ports.amps):
       self.connect(self.pwr.append_elt(VoltageSink.empty(), i), self.pwr_merge.pwr_ins.request(i))
-      self.connect(self.gnd.append_elt(VoltageSink.empty(), i), self.gnd_merge.pwr_ins.request(i))
+      self.connect(self.gnd.append_elt(Ground.empty(), i), self.gnd_merge.gnd_ins.request(i))
       self.connect(self.inn.append_elt(AnalogSink.empty(), i), amp_neg)
       self.connect(self.inp.append_elt(AnalogSink.empty(), i), amp_pos)
       self.connect(self.out.append_elt(AnalogSource.empty(), i), amp_out)

edg/abstract_parts/AbstractResistor.py

@@ -204,7 +204,7 @@ class PulldownResistorArray(TypedTestPoint, GeneratorBlock):
   @init_in_parent
   def __init__(self, resistance: RangeLike):
     super().__init__()
-    self.gnd = self.Port(VoltageSink.empty(), [Common])
+    self.gnd = self.Port(Ground.empty(), [Common])
     self.io = self.Port(Vector(DigitalSingleSource.empty()), [InOut])
     self.generator_param(self.io.requested())
     self.resistance = self.ArgParameter(resistance)

edg/abstract_parts/AbstractTestPoint.py

@@ -51,6 +51,18 @@ def contents(self):
     self.assign(conn_tp.tp_name, (self.tp_name == "").then_else(self.io.link().name(), self.tp_name))
 
 
+class GroundTestPoint(BaseTypedTestPoint, Block):
+  """Test point with a VoltageSink port."""
+  def __init__(self, *args):
+    super().__init__(*args)
+    self.io = self.Port(Ground.empty(), [InOut])
+    self.connect(self.io, self.tp.io.adapt_to(Ground()))
+
+  def connected(self, io: Port[GroundLink]) -> 'GroundTestPoint':
+    cast(Block, builder.get_enclosing_block()).connect(io, self.io)
+    return self
+
+
 class VoltageTestPoint(BaseTypedTestPoint, Block):
   """Test point with a VoltageSink port."""
   def __init__(self, *args):

edg/abstract_parts/DummyDevices.py

@@ -10,6 +10,12 @@ def __init__(self) -> None:
     self.io = self.Port(Passive(), [InOut])
 
 
+class DummyGround(DummyDevice):
+  def __init__(self) -> None:
+    super().__init__()
+    self.gnd = self.Port(Ground(), [Common, InOut])
+
+
 class DummyVoltageSource(DummyDevice):
   @init_in_parent
   def __init__(self, voltage_out: RangeLike = RangeExpr.ZERO,

edg/abstract_parts/GateDrivers.py

@@ -29,7 +29,7 @@ def __init__(self, has_boot_diode: BoolLike):
     self.low_out = self.Port(DigitalSource.empty())  # referenced to main gnd
 
     self.high_pwr = self.Port(VoltageSink.empty(), optional=True)  # not used with internal boot diode
-    self.high_gnd = self.Port(VoltageSink.empty())  # this encodes the voltage limit from gnd
+    self.high_gnd = self.Port(Ground.empty())  # a separate constraint needs to encode voltage limits
     self.high_out = self.Port(DigitalSource.empty())  # referenced to high_pwr and high_gnd
 
 

edg/abstract_parts/IoControllerInterfaceMixins.py

@@ -86,26 +86,15 @@ class IoControllerBle(BlockInterfaceMixin[BaseIoController]):
     """Mixin indicating this IoController has programmable Bluetooth LE. Does not expose any ports."""
 
 
-@non_library
-class IoControllerGroundOut(BlockInterfaceMixin[IoController]):
-    """Base mixin for an IoController that can act as a power output (e.g. dev boards),
-    this only provides the ground source pin. Subclasses can define output power pins.
-    Multiple power pin mixins can be used on the same class, but only one gnd_out can be connected."""
-    def __init__(self, *args, **kwargs) -> None:
-        super().__init__(*args, **kwargs)
-        self.gnd_out = self.Port(GroundSource.empty(), optional=True,
-                                 doc="Ground for power output ports, when the device is acting as a power source")
-
-
-class IoControllerPowerOut(IoControllerGroundOut, BlockInterfaceMixin[IoController]):
+class IoControllerPowerOut(BlockInterfaceMixin[IoController]):
     """IO controller mixin that provides an output of the IO controller's VddIO rail, commonly 3.3v."""
     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")
 
 
-class IoControllerUsbOut(IoControllerGroundOut, BlockInterfaceMixin[IoController]):
+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)

edg/abstract_parts/PowerCircuits.py

@@ -88,11 +88,11 @@ def contents(self):
         self.connect(self.high_gate_res.b, self.high_fet.gate)
 
         # to avoid tolerance stackup, model the switch node as a static voltage
+        self.connect(self.low_fet.drain, self.high_fet.source)
         self.connect(self.low_fet.drain.adapt_to(VoltageSource(
-                voltage_out=self.pwr.link().voltage)),
-            self.high_fet.source.adapt_to(VoltageSink()),
-            self.driver.high_gnd,
+            voltage_out=self.pwr.link().voltage)),
             self.out)
+        self.connect(self.out.as_ground((0, 0)*Amp), self.driver.high_gnd)  # TODO model driver current
 
 
 class FetHalfBridgeIndependent(FetHalfBridge, HalfBridgeIndependent):