CircuitBlock.py

from __future__ import annotations

from typing import Generic, Any, Optional, Mapping, Dict, Union, TYPE_CHECKING, Tuple, Iterable, overload

from deprecated import deprecated
from typing_extensions import TypeVar, override

from .KiCadImportableBlock import KiCadImportableBlock
from ..core import *
from ..core.HdlUserExceptions import EdgTypeError

if TYPE_CHECKING:
    from .PassivePort import HasPassivePort, Passive


@non_library
class FootprintBlock(Block):
    """Block that represents a component that has part(s) and trace(s) on the PCB.
    Provides interfaces that define footprints and copper connections and generates to appropriate metadata.
    """

    # TODO perhaps don't allow part / package initializers since those shouldn't be used
    def __init__(self, *args: Any, **kwargs: Any) -> None:
        super().__init__(*args, **kwargs)
        self.fp_footprint = self.Parameter(StringExpr())
        self.fp_pinning = self.Parameter(ArrayStringExpr())
        self.fp_datasheet = self.Parameter(StringExpr())

        self.fp_mfr = self.Parameter(StringExpr())
        self.fp_part = self.Parameter(StringExpr())
        self.fp_value = self.Parameter(StringExpr())
        self.fp_refdes = self.Parameter(StringExpr())
        self.fp_refdes_prefix = self.Parameter(StringExpr())

        self.fp_pnp_rot = self.Parameter(FloatExpr())
        self.fp_pnp_offset_x = self.Parameter(FloatExpr())
        self.fp_pnp_offset_y = self.Parameter(FloatExpr())

    @overload
    def footprint(
        self,
        refdes: StringLike,
        footprint: StringLike,
        pinning: Mapping[str, Union[Passive, HasPassivePort]],
        mfr: Optional[StringLike] = None,
        part: Optional[StringLike] = None,
        value: Optional[StringLike] = None,
        datasheet: Optional[StringLike] = None,
        pnp_rot: Optional[float] = None,
        pnp_offset: Optional[tuple[float, float]] = None,
    ) -> None: ...

    @overload
    def footprint(
        self,
        refdes: StringLike,
        footprint: StringLike,
        pinning: Mapping[Union[Iterable[str], str], Union[Passive, HasPassivePort]],
        mfr: Optional[StringLike] = None,
        part: Optional[StringLike] = None,
        value: Optional[StringLike] = None,
        datasheet: Optional[StringLike] = None,
        pnp_rot: Optional[float] = None,
        pnp_offset: Optional[tuple[float, float]] = None,
    ) -> None: ...

    def footprint(
        self,
        refdes: StringLike,
        footprint: StringLike,
        pinning: Union[
            Mapping[str, Union[Passive, HasPassivePort]],
            Mapping[Union[Iterable[str], str], Union[Passive, HasPassivePort]],
        ],
        mfr: Optional[StringLike] = None,
        part: Optional[StringLike] = None,
        value: Optional[StringLike] = None,
        datasheet: Optional[StringLike] = None,
        pnp_rot: Optional[float] = None,
        pnp_offset: Optional[tuple[float, float]] = None,
    ) -> None:
        """Creates a footprint in this circuit block.
        Value is a one-line description of the part, eg 680R, 0.01uF, LPC1549, to be used as an aid during layout or
        assembly.
        pnp_rot defines the rotation offset, in degrees, of the footprint for pick-and-place. This amount is added
        (additional CCW rotation) to the rotation of the footprint. This is defined as the rotation from the footprint
        to get to the rotation on the reel, as consistent with JLC's assembly conventions.
        pnp_offset defines the position offset, in mm, of the footprint for pick-and-place. Offsets are applied before
        rotation and are in Kicad space (-y is up).
        """
        from .PassivePort import HasPassivePort, Passive
        from ..core.Blocks import BlockElaborationState, BlockDefinitionError

        if self._elaboration_state not in (
            BlockElaborationState.init,
            BlockElaborationState.contents,
            BlockElaborationState.generate,
        ):
            raise BlockDefinitionError(
                type(self),
                "can't call Footprint(...) outside __init__, contents or generate",
                "call Footprint(...) inside those functions, and remember to make the super() call",
            )

        self.fp_is_footprint = self.Metadata("")

        pinning_array = []
        for pin_name, pin_port in pinning.items():
            if isinstance(pin_port, HasPassivePort):
                pin_port = pin_port.net
            if not isinstance(pin_port, (CircuitPort, Passive)):
                raise EdgTypeError(f"Footprint(...) pin", pin_port, Passive)

            if isinstance(pin_name, str):
                pin_tuples: Tuple[str, ...] = (pin_name,)
            else:
                pin_tuples = tuple(iter(pin_name))
            for pin in pin_tuples:
                pinning_array.append(f"{pin}={pin_port._name_from(self)}")
        self.assign(self.fp_pinning, pinning_array)

        self.assign(self.fp_footprint, footprint)
        self.assign(self.fp_refdes_prefix, refdes)
        if mfr is not None:
            self.assign(self.fp_mfr, mfr)
        else:
            self.assign(self.fp_mfr, "")
        if part is not None:
            self.assign(self.fp_part, part)
        else:
            self.assign(self.fp_part, "")
        if value is not None:
            self.assign(self.fp_value, value)
        else:
            self.assign(self.fp_value, "")
        if datasheet is not None:
            self.assign(self.fp_datasheet, datasheet)
        else:
            self.assign(self.fp_datasheet, "")

        # PNP rotation is left explicitly unassigned if not defined
        if pnp_rot is not None:
            self.assign(self.fp_pnp_rot, pnp_rot)
        if pnp_offset is not None:
            self.assign(self.fp_pnp_offset_x, pnp_offset[0])
            self.assign(self.fp_pnp_offset_y, pnp_offset[1])


@non_library
class WrapperFootprintBlock(FootprintBlock):
    """Block that has a footprint and optional internal contents, but the netlister ignores internal components.
    Useful for, for example, a breakout board where the modelling details are provided by internal chip blocks,
    but needs to show up as only a carrier board footprint.
    EXPERIMENTAL - API SUBJECT TO CHANGE."""

    def __init__(self, *args: Any, **kwargs: Any) -> None:
        super().__init__(*args, **kwargs)
        self.fp_is_wrapper = self.Metadata("A")  # TODO replace with not metadata, eg superclass inspection


AdapterDstType = TypeVar("AdapterDstType", covariant=True, bound=Port, default=Port)


@non_library
class KicadImportablePortAdapter(KiCadImportableBlock, PortAdapter[AdapterDstType], Generic[AdapterDstType]):
    @override
    def symbol_pinning(self, symbol_name: str) -> Dict[str, BasePort]:
        assert symbol_name == "edg_importable:Adapter"
        return {"1": self.src, "2": self.dst}


CircuitLinkType = TypeVar("CircuitLinkType", bound=Link, covariant=True, default=Link)


@deprecated("Use compositional Passive sub-port instead")
class CircuitPort(Port[CircuitLinkType], Generic[CircuitLinkType]):
    """Electrical connection that represents a single port into a single copper net"""

    pass


@non_library
@deprecated("Use compositional passive and connect nets instead of inheriting")
class NetBaseBlock(BaseBlock):
    def net(self) -> None:
        """Defines all ports on this block as copper-connected"""
        self.nets = self.Metadata({"_": "_"})  # TODO should be empty


@abstract_block
@deprecated("Use compositional passive and connect nets instead of inheriting")
class NetBlock(InternalBlock, NetBaseBlock, Block):
    @override
    def contents(self) -> None:
        super().contents()
        self.net()


@abstract_block
@deprecated("Use compositional passive and connect nets instead of inheriting")
class CircuitPortBridge(NetBaseBlock, PortBridge):
    @override
    def contents(self) -> None:
        super().contents()
        self.net()


@abstract_block
@deprecated("Use compositional passive and connect nets instead of inheriting")
class CircuitPortAdapter(KicadImportablePortAdapter[AdapterDstType], NetBaseBlock, Generic[AdapterDstType]):
    @override
    def contents(self) -> None:
        super().contents()
        self.net()


@non_library
@deprecated("Use compositional passive and connect nets instead of inheriting")
class CircuitLink(NetBaseBlock, Link):
    @override
    def contents(self) -> None:
        super().contents()
        self.net()