"""Scaffolding shared by the JLCPCB substrates.
A buildup in this package should be a declaration of its layers and its
impedance numbers and nothing else. What lives here is everything that is not
those numbers.
"""
from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from jitx.si import (
DifferentialRoutingStructure,
RoutingStructure,
symmetric_routing_layers,
)
from jitx.stackup import Material
from jitx.substrate import Substrate
from jitx.units import ohm
SOLDERMASK = 0.01524
"""Soldermask thickness in mm, JLCPCB's 0.6 mil above-trace figure."""
[docs]
class JLCPCBSubstrate(Substrate):
"""Base for the substrates in this package.
A subclass declares three things: its `stackup`, its `constraints`, and
the via set for its layer count and material, mixed in from `vias`. None
of the three is fixed here on purpose. JLCPCB's fabrication minimums
differ between a 2-layer process and a multilayer one, the extra-cost via
tiers apply only to 6+ layer boards, and JLCPCB fills no via on a Rogers
board (mix in `UnfilledVias` there, not `StandardVias`), so a base that
supplied any of them would hand substrates capabilities they cannot order.
>>> class JLC02161_Example(JLCPCBSubstrate, StandardVias):
... @inline
... class stackup(Stackup):
... layers = symmetric(...)
... constraints = JLCPCBRules()
"""
# A surface finish would be selected here, per order: the same buildup is
# bought with HASL or ENIG at different prices, so it belongs neither on
# the stackup class nor in its layer list. JITX cannot describe a surface
# treatment in a stackup, so there is nothing to select it with; see
# `materials.py` and `plans/stackup-revision-plan.md` §4. If a per-order
# options object is ever built, this class is where it goes.
[docs]
def symmetric(*outer: Material, centre: Material) -> list[Material]:
"""Full layer list for a buildup that mirrors about a single centre layer.
A convenience over writing the list out, not the interface: a stackup
takes the full list, since several of JLCPCB's buildups have a centre of
prepreg/core/prepreg or two prepregs, and at least one published row is
not symmetric at all.
Args:
outer: The layers from the outside in, up to but excluding the centre.
centre: The unmirrored middle layer.
"""
return [*outer, centre, *reversed(outer)]
[docs]
@dataclass(frozen=True)
class Trace:
"""Single-ended trace geometry for one routing layer, in mm."""
trace_width: float
clearance: float
velocity: float
[docs]
@dataclass(frozen=True)
class Pair:
"""Differential pair geometry for one routing layer, in mm.
`uncoupled_clearance` applies where the pair separates and is routed as
two single-ended traces; it is often tighter than the coupled clearance.
"""
trace_width: float
pair_spacing: float
clearance: float
uncoupled_clearance: float
velocity: float
[docs]
def single_ended(
impedance: float,
layers: Mapping[int, Trace],
*,
insertion_loss: float,
) -> RoutingStructure:
"""A single-ended routing structure, mirrored onto the bottom half.
Args:
impedance: Target impedance in ohms, also used to name the structure.
layers: Geometry per routing layer, top half only, outermost is 0.
insertion_loss: Loss tangent of the surrounding dielectric.
"""
return RoutingStructure(
impedance=impedance * ohm,
name=f"{impedance:g} Ohm Routing Structure",
layers=symmetric_routing_layers(
{
index: RoutingStructure.Layer(
trace_width=trace.trace_width,
clearance=trace.clearance,
velocity=trace.velocity,
insertion_loss=insertion_loss,
)
for index, trace in layers.items()
}
),
)
[docs]
def differential(
impedance: float,
layers: Mapping[int, Pair],
*,
insertion_loss: float,
) -> DifferentialRoutingStructure:
"""A differential routing structure with its uncoupled region, mirrored
onto the bottom half.
Args:
impedance: Target differential impedance in ohms, also used to name
the structure.
layers: Geometry per routing layer, top half only, outermost is 0.
insertion_loss: Loss tangent of the surrounding dielectric.
"""
return DifferentialRoutingStructure(
impedance=impedance * ohm,
name=f"{impedance:g} Ohm Differential Routing Structure",
layers=symmetric_routing_layers(
{
index: DifferentialRoutingStructure.Layer(
trace_width=pair.trace_width,
pair_spacing=pair.pair_spacing,
clearance=pair.clearance,
velocity=pair.velocity,
insertion_loss=insertion_loss,
)
for index, pair in layers.items()
}
),
uncoupled_region=RoutingStructure(
impedance=impedance * ohm,
name=f"{impedance:g} Ohm Differential Routing Structure, Uncoupled",
layers=symmetric_routing_layers(
{
index: RoutingStructure.Layer(
trace_width=pair.trace_width,
clearance=pair.uncoupled_clearance,
velocity=pair.velocity,
insertion_loss=insertion_loss,
)
for index, pair in layers.items()
}
),
),
)
__all__: Sequence[str] = [
"JLCPCBSubstrate",
"Pair",
"SOLDERMASK",
"Trace",
"differential",
"single_ended",
"symmetric",
]