Compositional passive for Ground (#468)

Re-structures Ground() as containing a Passive-typed net. Towards #114 

... and associated refactors to eliminate most of the
.adapt_to(Ground()):
- Add DigitalCapacitor block, for a capacitor attached to a Digital link
- Add AnalogSetpointResistor block, for a resistor from an Analog to
Ground typically used as a programming / bias resistor
- Refactors ports using this to be AnalogSource, typically assumed
between vss and vdd
- Refactors (abstract) Crystal to be fully Passive typed, to be
consistent, and as an indication it should not be directly used in an
application circuit
- Refactors HasPassivePort to only define (and not instantiate) the net
subport, to avoid generic type issues
- Removes E2154fs091 and has it delegate the the waveshare EPD circuit
- Adds better port / component typing to the EPD driver
- Improves port typing for MAX17048
- Improve reset subcircuit structure for BH1750 and expose reset pin
- Refactor Lm4871 subcircuit to use typed ports

Author: ducky64

edg/abstract_parts/AbstractCapacitor.py

@@ -366,7 +366,7 @@ 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(Ground()), [Common])
+        self.gnd = self.Port(Ground(), [Common])
         self.pwr = self.Export(
             self.cap.pos.adapt_to(
                 VoltageSink.from_gnd(
@@ -375,7 +375,7 @@ def __init__(self, capacitance: RangeLike, *, exact_capacitance: BoolLike = Fals
             ),
             [Power, InOut],
         )
-
+        self.connect(self.gnd.net, self.cap.neg)
         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
@@ -403,11 +403,11 @@ 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.Port(Ground.empty(), [Common])
+        self.gnd = self.Port(Ground(), [Common])
         self.io = self.Port(AnalogSink(), [InOut])  # ideal open port
 
         self.assign(self.cap.voltage, self.io.link().voltage - self.gnd.link().voltage)
-        self.connect(self.cap.neg.adapt_to(Ground()), self.gnd)  # TODO refactor #114
+        self.connect(self.gnd.net, self.cap.neg)
         self.connect(self.io.net, self.cap.pos)
 
     def connected(
@@ -478,6 +478,36 @@ def connected(
         return self
 
 
+class DigitalCapacitor(DiscreteApplication, KiCadImportableBlock):
+    """Capacitor attached to a digital line, that presents as an open model-wise."""
+
+    @override
+    def symbol_pinning(self, symbol_name: str) -> Dict[str, BasePort]:
+        assert symbol_name in ("Device:C", "Device:C_Small", "Device:C_Polarized", "Device:C_Polarized_Small")
+        return {"1": self.io, "2": self.gnd}
+
+    def __init__(self, capacitance: RangeLike, *, exact_capacitance: BoolLike = False) -> None:
+        super().__init__()
+
+        self.cap = self.Block(Capacitor(capacitance, voltage=RangeExpr(), exact_capacitance=exact_capacitance))
+        self.gnd = self.Port(Ground(), [Common])
+        self.io = self.Port(DigitalSink.empty(), [InOut])  # ideal open port
+
+        self.assign(self.cap.voltage, self.io.link().voltage - self.gnd.link().voltage)
+        self.connect(self.gnd.net, self.cap.neg)
+        self.connect(self.io, self.cap.pos.adapt_to(DigitalSink()))
+
+    def connected(
+        self, gnd: Optional[Port[GroundLink]] = None, io: Optional[Port[DigitalLink]] = None
+    ) -> "DigitalCapacitor":
+        """Convenience function to connect both ports, returning this object so it can still be given a name."""
+        if gnd is not None:
+            cast(Block, builder.get_enclosing_block()).connect(gnd, self.gnd)
+        if io is not None:
+            cast(Block, builder.get_enclosing_block()).connect(io, self.io)
+        return self
+
+
 class CombinedCapacitorElement(Capacitor):  # to avoid an abstract part error
     @override
     def contents(self) -> None:

edg/abstract_parts/AbstractCrystal.py

@@ -20,8 +20,9 @@ def __init__(self, frequency: RangeLike) -> None:
         self.actual_frequency = self.Parameter(RangeExpr())
         self.actual_capacitance = self.Parameter(FloatExpr())
 
-        self.crystal = self.Port(CrystalPort(self.actual_frequency), [InOut])  # set by subclass
-        self.gnd = self.Port(Ground(), [Common])
+        self.xtal_in = self.Port(Passive())
+        self.xtal_out = self.Port(Passive())
+        self.gnd = self.Port(Passive())
 
     @override
     def contents(self) -> None:
@@ -43,21 +44,21 @@ class CrystalStandardFootprint(StandardFootprint["Crystal"]):
 
     FOOTPRINT_PINNING_MAP = {
         "Oscillator:Oscillator_SMD_Abracon_ASE-4Pin_3.2x2.5mm": lambda block: {
-            "1": block.crystal.xtal_in,
+            "1": block.xtal_in,
             "2": block.gnd,
-            "3": block.crystal.xtal_out,
+            "3": block.xtal_out,
             "4": block.gnd,
         },
         "Crystal:Crystal_SMD_3225-4Pin_3.2x2.5mm": lambda block: {
-            "1": block.crystal.xtal_in,
+            "1": block.xtal_in,
             "2": block.gnd,
-            "3": block.crystal.xtal_out,
+            "3": block.xtal_out,
             "4": block.gnd,
         },
         "Crystal:Crystal_SMD_2520-4Pin_2.5x2.0mm": lambda block: {
-            "1": block.crystal.xtal_in,
+            "1": block.xtal_in,
             "2": block.gnd,
-            "3": block.crystal.xtal_out,
+            "3": block.xtal_out,
             "4": block.gnd,
         },
     }
@@ -91,8 +92,8 @@ def __init__(self, frequency: RangeLike) -> None:
         Should include load capacitors."""
         super().__init__()
 
-        self.crystal = self.Port(CrystalPort.empty(), [InOut])
         self.gnd = self.Port(Ground.empty(), [Common])
+        self.crystal = self.Port(CrystalPort.empty(), [InOut])
 
         self.frequency = self.ArgParameter(frequency)
 
@@ -118,6 +119,9 @@ def contents(self) -> None:
 
         self.package = self.Block(Crystal(self.frequency))
 
+        self.gnd.init_from(Ground())
+        self.crystal.init_from(CrystalPort(self.package.actual_frequency))
+
         cap_model = Capacitor(
             capacitance=(
                 (self.package.actual_capacitance - self.PARASITIC_CAPACITANCE) * 2 * (1 - self.CAPACITOR_TOLERANCE),
@@ -127,10 +131,9 @@ def contents(self) -> None:
         )
         self.cap_a = self.Block(cap_model)
         self.cap_b = self.Block(cap_model)
-        self.connect(self.crystal, self.package.crystal)
-        self.connect(self.crystal.xtal_in, self.cap_a.pos)
-        self.connect(self.crystal.xtal_out, self.cap_b.pos)
-        self.connect(self.gnd, self.cap_a.neg.adapt_to(Ground()), self.cap_b.neg.adapt_to(Ground()), self.package.gnd)
+        self.connect(self.crystal.xtal_in, self.package.xtal_in, self.cap_a.pos)
+        self.connect(self.crystal.xtal_out, self.package.xtal_out, self.cap_b.pos)
+        self.connect(self.gnd.net, self.cap_a.neg, self.cap_b.neg, self.package.gnd)
 
 
 class CeramicResonator(OscillatorReference):

edg/abstract_parts/AbstractDiodes.py

@@ -194,7 +194,7 @@ def __init__(self, voltage: RangeLike):
         super().__init__()
 
         self.pwr = self.Port(VoltageSink.empty(), [Power, InOut])
-        self.gnd = self.Port(Ground.empty(), [Common])
+        self.gnd = self.Port(Ground(), [Common])
 
         self.voltage = self.ArgParameter(voltage)
 
@@ -210,7 +210,7 @@ def contents(self) -> None:
             ),
             self.pwr,
         )
-        self.connect(self.diode.anode.adapt_to(Ground()), self.gnd)
+        self.connect(self.gnd.net, self.diode.anode)
 
 
 @deprecated("Use AnalogClampResistor, which should be cheaper and cause less signal distortion")
@@ -222,7 +222,7 @@ def __init__(self, voltage: RangeLike):
 
         self.diode = self.Block(ZenerDiode(zener_voltage=voltage))
 
-        self.gnd = self.Port(Ground.empty(), [Common])
+        self.gnd = self.Port(Ground(), [Common])
         self.signal_in = self.Port(AnalogSink(), [Input])
         self.signal_out = self.Port(
             AnalogSource(
@@ -236,7 +236,7 @@ def __init__(self, voltage: RangeLike):
         self.assign(self.signal_in.current_draw, self.signal_out.link().current_drawn)
 
         self.connect(self.signal_in.net, self.signal_out.net, self.diode.cathode)
-        self.connect(self.diode.anode.adapt_to(Ground()), self.gnd)
+        self.connect(self.gnd.net, self.diode.anode)
 
     @override
     def symbol_pinning(self, symbol_name: str) -> Dict[str, Port]:

edg/abstract_parts/AbstractLed.py

@@ -98,7 +98,7 @@ def __init__(self, color: LedColorLike = Led.Any, *, current_draw: RangeLike = (
         self.target_current_draw = self.Parameter(RangeExpr(current_draw))
 
         self.signal = self.Port(DigitalSink.empty(), [InOut])
-        self.gnd = self.Port(Ground.empty(), [Common])
+        self.gnd = self.Port(Ground(), [Common])
 
         self.require(self.signal.current_draw.within((0, self.target_current_draw.upper())))
 
@@ -118,7 +118,7 @@ def __init__(self, color: LedColorLike = Led.Any, *, current_draw: RangeLike = (
         )
 
         self.connect(self.res.a, self.package.k)
-        self.connect(self.res.b.adapt_to(Ground()), self.gnd)
+        self.connect(self.gnd.net, self.res.b)
 
 
 class IndicatorLedArray(Light, GeneratorBlock):
@@ -227,7 +227,7 @@ def __init__(self, color: LedColorLike = Led.Any, *, current_draw: RangeLike = (
         self.target_current_draw = self.Parameter(RangeExpr(current_draw))
 
         self.signal = self.Port(VoltageSink.empty(), [Power, InOut])
-        self.gnd = self.Port(Ground.empty(), [Common])
+        self.gnd = self.Port(Ground(), [Common])
 
         self.require(self.signal.current_draw.within(current_draw))
 
@@ -246,7 +246,7 @@ def __init__(self, color: LedColorLike = Led.Any, *, current_draw: RangeLike = (
             self.package.a.adapt_to(VoltageSink(current_draw=self.signal.link().voltage / self.res.actual_resistance)),
         )
         self.connect(self.res.a, self.package.k)
-        self.connect(self.res.b.adapt_to(Ground()), self.gnd)
+        self.connect(self.gnd.net, self.res.b)
 
 
 # TODO should there be some kind of abstract LED class, that works for both CA and CC type LEDs?

edg/abstract_parts/AbstractResistor.py

@@ -228,9 +228,11 @@ def __init__(self, resistance: RangeLike) -> None:
 
         self.res = self.Block(Resistor(resistance, 0 * Watt(tol=0)))  # TODO automatically calculate power
 
-        self.gnd = self.Export(self.res.a.adapt_to(Ground()), [Common])
+        self.gnd = self.Port(Ground(), [Common])
         self.io = self.Export(self.res.b.adapt_to(DigitalSource.pulldown_from_supply(self.gnd)), [InOut])
 
+        self.connect(self.gnd.net, self.res.a)
+
     def connected(
         self, gnd: Optional[Port[GroundLink]] = None, io: Optional[Port[DigitalLink]] = None
     ) -> "PulldownResistor":
@@ -327,7 +329,7 @@ def connected(
 
 
 class CurrentSenseResistor(DiscreteApplication, KiCadImportableBlock, GeneratorBlock):
-    """Current sense resistor with a power passthrough resistor and positive and negative sense temrinals."""
+    """Current sense resistor with a power passthrough resistor and positive and negative sense terminals."""
 
     def __init__(self, resistance: RangeLike, sense_in_reqd: BoolLike = True) -> None:
         super().__init__()
@@ -372,6 +374,39 @@ def symbol_pinning(self, symbol_name: str) -> Dict[str, Port]:
         return {"1": self.pwr_in, "2": self.pwr_out, "sense_in": self.sense_in, "sense_out": self.sense_out}
 
 
+class AnalogSetpointResistor(DiscreteApplication, KiCadImportableBlock):
+    """AnalogSink-typed resistor that acts as a setpoint, aka bias or programming resistor"""
+
+    @override
+    def symbol_pinning(self, symbol_name: str) -> Mapping[str, BasePort]:
+        assert symbol_name in ("Device:R", "Device:R_Small")
+        return {"1": self.io, "2": self.gnd}
+
+    def __init__(self, resistance: RangeLike) -> None:
+        super().__init__()
+
+        self.gnd = self.Port(Ground())
+        self.io = self.Port(AnalogSink(impedance=RangeExpr()), [InOut])
+
+        voltage = self.io.link().voltage - self.gnd.link().voltage
+        self.res = self.Block(Resistor(resistance=resistance, power=voltage * voltage / resistance))
+        self.actual_resistance = self.Parameter(RangeExpr(self.res.actual_resistance))
+
+        self.assign(self.io.impedance, self.res.actual_resistance)
+        self.connect(self.gnd.net, self.res.a)
+        self.connect(self.io.net, self.res.b)
+
+    def connected(
+        self, gnd: Optional[Port[GroundLink]] = None, io: Optional[Port[AnalogLink]] = None
+    ) -> "AnalogSetpointResistor":
+        """Convenience function to connect both ports, returning this object so it can still be given a name."""
+        if gnd is not None:
+            cast(Block, builder.get_enclosing_block()).connect(gnd, self.gnd)
+        if io is not None:
+            cast(Block, builder.get_enclosing_block()).connect(io, self.io)
+        return self
+
+
 class AnalogSeriesResistor(DiscreteApplication, KiCadImportableBlock):
     """Analog passthrough series resistor"""
 

edg/abstract_parts/AbstractSolidStateRelay.py

@@ -51,7 +51,7 @@ def __init__(self) -> None:
         super().__init__()
 
         self.signal = self.Port(DigitalSink.empty())
-        self.gnd = self.Port(Ground.empty(), [Common])
+        self.gnd = self.Port(Ground(), [Common])
 
         self.pwr_in = self.Port(VoltageSink.empty())
         self.pwr_out = self.Port(VoltageSource.empty())
@@ -70,7 +70,7 @@ def __init__(self) -> None:
             self.ic.leda.adapt_to(DigitalSink(current_draw=self.signal.link().voltage / self.res.actual_resistance)),
         )
         self.connect(self.res.a, self.ic.ledk)
-        self.connect(self.res.b.adapt_to(Ground()), self.gnd)
+        self.connect(self.gnd.net, self.res.b)
 
         self.connect(
             self.pwr_in,
@@ -114,7 +114,7 @@ def __init__(self) -> None:
         self.ic = self.Block(SolidStateRelay())
 
         self.signal = self.Port(DigitalSink.empty())
-        self.gnd = self.Port(Ground.empty(), [Common])
+        self.gnd = self.Port(Ground(), [Common])
 
         self.ain = self.Port(
             AnalogSink(
@@ -152,7 +152,7 @@ def __init__(self) -> None:
             self.ic.leda.adapt_to(DigitalSink(current_draw=self.signal.link().voltage / self.res.actual_resistance)),
         )
         self.connect(self.res.a, self.ic.ledk)
-        self.connect(self.res.b.adapt_to(Ground()), self.gnd)
+        self.connect(self.gnd.net, self.res.b)
 
         self.connect(self.ain.net, self.ic.feta)
         self.connect(self.aout.net, self.ic.fetb)

edg/abstract_parts/AbstractSwitch.py

@@ -94,7 +94,7 @@ class DigitalSwitch(HumanInterface):
     def __init__(self) -> None:
         super().__init__()
 
-        self.gnd = self.Port(Ground.empty(), [Common])
+        self.gnd = self.Port(Ground(), [Common])
         self.out = self.Port(DigitalSource.empty(), [Output])
 
     @override
@@ -103,7 +103,7 @@ def contents(self) -> None:
         self.package = self.Block(Switch(current=self.out.link().current_drawn, voltage=self.out.link().voltage))
 
         self.connect(self.out, self.package.sw.adapt_to(DigitalSource.low_from_supply(self.gnd)))
-        self.connect(self.gnd, self.package.com.adapt_to(Ground()))
+        self.connect(self.gnd.net, self.package.com)
 
 
 @abstract_block_default(lambda: DigitalWrapperRotaryEncoder)
@@ -134,7 +134,8 @@ def contents(self) -> None:
         dio_model = DigitalSource.low_from_supply(self.gnd)
         self.connect(self.a, self.package.a.adapt_to(dio_model))
         self.connect(self.b, self.package.b.adapt_to(dio_model))
-        self.connect(self.gnd, self.package.com.adapt_to(Ground()))
+        self.gnd.init_from(Ground())
+        self.connect(self.gnd.net, self.package.com)
 
 
 @abstract_block_default(lambda: DigitalWrapperRotaryEncoderWithSwitch)
@@ -194,7 +195,8 @@ def contents(self) -> None:
         self.connect(self.b, self.package.b.adapt_to(dio_model))
         self.connect(self.c, self.package.c.adapt_to(dio_model))
         self.connect(self.d, self.package.d.adapt_to(dio_model))
-        self.connect(self.gnd, self.package.com.adapt_to(Ground()))
+        self.gnd.init_from(Ground())
+        self.connect(self.gnd.net, self.package.com)
 
 
 @abstract_block_default(lambda: DigitalWrapperDirectionSwitchWithCenter)

edg/abstract_parts/AbstractTestPoint.py

@@ -59,8 +59,8 @@ class GroundTestPoint(BaseTypedTestPoint, Block):
 
     def __init__(self, *args: Any) -> None:
         super().__init__(*args)
-        self.io = self.Port(Ground.empty(), [InOut])
-        self.connect(self.io, self.tp.io.adapt_to(Ground()))
+        self.io: Ground = self.Port(Ground(), [InOut])
+        self.connect(self.io.net, self.tp.io)
 
     def connected(self, io: Port[GroundLink]) -> "GroundTestPoint":
         cast(Block, builder.get_enclosing_block()).connect(io, self.io)

edg/abstract_parts/AbstractTvsDiode.py

@@ -38,7 +38,7 @@ def __init__(self, working_voltage: RangeLike):
         super().__init__()
 
         self.pwr = self.Port(VoltageSink.empty(), [Power, InOut])
-        self.gnd = self.Port(Ground.empty(), [Common])
+        self.gnd = self.Port(Ground(), [Common])
 
         self.working_voltage = self.ArgParameter(working_voltage)
 
@@ -54,7 +54,7 @@ def contents(self) -> None:
             ),
             self.pwr,
         )
-        self.connect(self.diode.anode.adapt_to(Ground()), self.gnd)
+        self.connect(self.gnd.net, self.diode.anode)
 
 
 class DigitalTvsDiode(Protection):
@@ -64,7 +64,7 @@ def __init__(self, working_voltage: RangeLike, *, capacitance: RangeLike = Range
         super().__init__()
 
         self.io = self.Port(DigitalSink.empty(), [InOut])
-        self.gnd = self.Port(Ground.empty(), [Common])
+        self.gnd = self.Port(Ground(), [Common])
 
         self.working_voltage = self.ArgParameter(working_voltage)
         self.capacitance = self.ArgParameter(capacitance)
@@ -81,4 +81,4 @@ def contents(self) -> None:
             ),
             self.io,
         )
-        self.connect(self.diode.anode.adapt_to(Ground()), self.gnd)
+        self.connect(self.gnd.net, self.diode.anode)