pixalynx/edge-connector

README.md

# USB PCB edge connectors

Reusable tscircuit components whose contacts are part of your PCB. Each provides a schematic symbol, named pins, exposed copper pads, and no solder-paste apertures.

| Export | Contacts | PCB thickness | Copper faces | Preview |
| --- | --- | --- | --- | --- |
| `UsbAEdgeConnector` | USB-A male, 4 | 2 mm | Top | `index.circuit.tsx` |
| `UsbCEdgeConnector` | USB-C receptacle tongue, 24 | 0.6 mm | A: top; B: bottom | `examples/usb-c.circuit.tsx` |
| `MicroUsbEdgeConnector` | Micro-B receptacle tongue, 5 | 0.6 mm | Top | `examples/micro-usb.circuit.tsx` |

USB-C and Micro-B follow the shell-less receptacle tongues in [vasya-zh's PCB Edge USB library](https://github.com/vasya-zh/PCB-Edge-USB-connector-KiCad-library). USB-A retains the previously created geometry. This package was renamed from `@tsci/pixalynx.goldfingers`; update existing imports and local dependency paths to the new name.

## Install from the tscircuit registry

From your new tscircuit project:

```sh
bunx tsci add pixalynx/edge-connector
```

Import from `@tsci/pixalynx.edge-connector` as shown below.

## Reuse locally

From another project beside `edge-connector`:

```sh
bun add ../edge-connector
```

### Automatic board outline and connector placement

Use `UsbEdgeConnectorBoard` in place of `<board>`. Choose the connector and overall board size; it generates the tongue, mating reliefs, board thickness, and connector position together.

```tsx
import { UsbEdgeConnectorBoard } from "@tsci/pixalynx.edge-connector"

export default () => (
  <UsbEdgeConnectorBoard
    connector="usb-a"
    width={20}
    height={30}
    edge="top"
    connectorProps={{ name: "J1" }}
  >
    {/* Place your other components and traces here, just like inside <board>. */}
    <resistor name="R1" resistance="10k" footprint="0402" pcbX={0} pcbY={-5} />
  </UsbEdgeConnectorBoard>
)
```

- `connector`: `"usb-a"`, `"usb-c"`, or `"micro-usb"`.
- `width` / `height`: total outside dimensions **including the tongue**, in numeric millimetres. Coordinates remain centred on those overall bounds. The usable rectangular body is smaller on the connector side.
- `edge`: `"top"` (default), `"right"`, `"bottom"`, or `"left"`. Both the connector and profile rotate together.
- `offset`: shift along the selected edge in millimetres (default 0). Positive moves toward +X on top/bottom, or +Y on left/right.
- `connectorProps`: the connector's `name`, typed `connections`, schematic position, and other non-placement props. PCB position and rotation are computed automatically.
- Children, nets, and traces share the board with the connector. Other board props, such as `title`, `autorouter`, and `solderMaskColor`, pass through.

The wrapper selects 2 mm thickness for USB-A and 0.6 mm for USB-C/Micro-B. It selects the USB-C reference's 0.15 mm edge clearance (0.2 mm for the others). Dimensions and offset are checked; profiles that cannot fit on the selected edge throw a descriptive error. It does not place other components automatically outside the mating region.

All three circuit examples now use this wrapper. It supports **one connector on an otherwise rectangular board**. For an arbitrary outline, multiple connectors, or different fabrication geometry, use the individual components and exported profiles below; a child footprint does not change its parent board's outline.

### Individual components for custom board outlines

```tsx
import {
  UsbAEdgeConnector,
  UsbCEdgeConnector,
  MicroUsbEdgeConnector,
} from "@tsci/pixalynx.edge-connector"

// Inside your own <board>, with its tongue outline aligned as described below:
<UsbAEdgeConnector
  name="J1"
  pcbX={0}
  pcbY={0}
  connections={{
    VBUS: "net.VBUS",
    DM: "U1.USB_DM",
    DP: "U1.USB_DP",
    GND: "net.GND",
  }}
/>
```

You can also use traces such as `<trace from="J1.DM" to="U1.USB_DM" />`. Normal layout props such as `pcbRotation`, `schX`, and `schY` are supported. Each instance needs a unique `name`. Copper faces are fixed to preserve the source pinout; rotate with `pcbRotation` rather than changing `layer`.

Registry publication is not required for local reuse. For a source copy, all three components need `EdgeContactFootprint.tsx`; USB-C and Micro-B also need their corresponding geometry file. The board wrapper imports all three components. Retain `LICENSE` and `NOTICE.md` with the adaptations.

## USB-A placement and board shape

At `pcbRotation={0}`, insertion is toward **+Y**. Viewed from above with the tip pointing up, the contacts run left to right:

| Pin | Signal | X (mm) | Y (mm) | Pad width × length (mm) |
| --- | --- | ---: | ---: | --- |
| 1 | VBUS | -3.5 | 0 | 1.5 × 7.5 |
| 2 | D− (`DM`) | -1 | -0.5 | 1 × 6.5 |
| 3 | D+ (`DP`) | 1 | -0.5 | 1 × 6.5 |
| 4 | GND | 3.5 | 0 | 1.5 × 7.5 |

The component origin is the centre of the outer contacts. All contacts end at local Y = -3.75 mm on the circuit side. Power and ground extend 1 mm farther toward the tip than the data contacts.

When using the individual component, your board supplies a **12 mm wide tongue**, with the tip at local **Y = +4.8 mm** and shoulders at **Y = -3.9 mm**. `usbAEdgeConnectorGeometry` exports these dimensions, an `edgeProfile`, and the **2 mm PCB thickness**. Translate and rotate the tongue outline along with the component when placing it elsewhere. `UsbEdgeConnectorBoard` handles these steps automatically.

See `index.circuit.tsx` for the short wrapper-based example; the profile includes clipped tip corners.

## USB-C and Micro-B placement

Both new connectors mate toward local **+Y** at `pcbRotation={0}`. The wrapper incorporates their profiles and side reliefs automatically. When using the individual components instead, your parent board must incorporate the supplied profile; placing copper pads alone does not create a usable connector. The separate examples select the corresponding connector and 0.6 mm board thickness through the wrapper.

`usbCEdgeConnectorGeometry` and `microUsbEdgeConnectorGeometry` export `boardThickness`, `tipY`, and `edgeProfile`. Each profile is an **open path from left to right** in component-local coordinates. For custom outlines, join its endpoints into the rest of your board perimeter, translating and rotating the profile together with the component. `UsbEdgeConnectorBoard.tsx` implements this for rectangular carriers.

USB-C keeps the source's 0.5 mm pitch, 0.25 mm pad widths, and 3.45/3.65/3.8 mm pad lengths. Its origin is at the centre of the four outer ground contacts; the tip is Y=2.55 mm. A1 is at X=+2.75 mm on top, while B1 is at X=-2.75 mm on the bottom, in a common top-view coordinate frame. Do not mirror the B-row positions a second time.

Micro-B uses five 0.35 × 2.7 mm pads at 0.65 mm pitch, all centred at Y=0. Pin 1 is at X=-1.3 mm, pin 5 at X=+1.3 mm, and the tip is Y=1.58 mm. Its 2 mm side cutouts are part of the exported profile.

The source arcs are approximated with short straight segments (chord error below 0.004 mm). The USB-C wrapper uses `minBoardEdgeClearance={0.15}` because that source has approximately 0.17 mm clearance beside its outer contacts. Confirm that clearance with your fabricator; the geometry is preserved rather than widened to fit the default 0.2 mm rule.

## Wiring the new connectors

Micro-B pins are `VBUS`, `DM`, `DP`, `ID`, `GND` (pins 1–5). It also accepts `D_MINUS`, `D_PLUS`, and numeric selectors such as `J1.pin2`. Decide how to handle `ID` in your circuit; it is not tied to ground internally.

USB-C exposes every physical contact as `A1`–`A12` and `B1`–`B12`, plus these unique functional aliases:

| Function | Contacts / aliases |
| --- | --- |
| Ground | A1 / GND_A1, A12 / GND_A12, B1 / GND_B1, B12 / GND_B12 |
| VBUS | A4 / VBUS_A4, A9 / VBUS_A9, B4 / VBUS_B4, B9 / VBUS_B9 |
| Configuration | A5 / CC1, B5 / CC2 |
| USB 2 data | A6 / DP_A6, A7 / DM_A7, B6 / DP_B6, B7 / DM_B7 |
| Sideband | A8 / SBU1, B8 / SBU2 |
| Transmit | A2 / TX1_P, A3 / TX1_N, B2 / TX2_P, B3 / TX2_N |
| Receive | A10 / RX2_N, A11 / RX2_P, B10 / RX1_N, B11 / RX1_P |

For example, `connections={{ CC1: "net.USB_CC1", CC2: "net.USB_CC2", A6: "net.USB_DP", B6: "net.USB_DP" }}` connects the named pins to your circuit. No contacts are joined internally, including repeated VBUS, ground, or data contacts. Wire all required pins and provide the CC circuitry appropriate to your USB role. The component supplies no termination, USB controller, ESD protection, or routing policy. Numeric tscircuit pins 1–12 map to A1–A12; 13–24 map to B1–B12. No nonexistent shield pin is exported.

## Fabrication

Specify a suitable gold contact finish with the board fabricator (hard gold for repeated insertion; ENIG is commonly used for prototypes). Do not apply solder or HASL to the contact area. Mask openings extend 0.05 mm beyond each USB-A pad and 0.025 mm beyond each USB-C/Micro-B pad; paste apertures are suppressed. `doNotPlace` marks these as PCB geometry rather than assembled parts.

Keep components, vias, unrelated copper, and silkscreen out of the mating region on both faces. Route from the rear of the contacts. These components do not enforce routing keepouts or differential-pair impedance. Confirm finished thickness, fit, and any edge bevel with the fabricator and a physical mating sample. Clipped outline corners are not a through-thickness bevel. The connectors have no metal shield; none has been physically fit-tested or compliance-tested here. Exposing USB-C's SuperSpeed contacts does not establish high-speed signal integrity.

Geometry reference: [USB-A-PCB footprint in the SparkFun KiCad conversion](https://github.com/benwis/SparkFun-Kicad-Libraries/blob/master/SparkFun-Connectors.pretty/USB-A-PCB.kicad_mod), rotated to point up and rounded to nominal millimetres. Board-thickness reference: [PCB Edge USB library](https://github.com/vasya-zh/PCB-Edge-USB-connector-KiCad-library).

## Preview and validate

```sh
bun run dev
bun run typecheck
bun test
bun run build -- --pcb-png --schematic-png
bunx tsci build examples/usb-c.circuit.tsx --pcb-png --schematic-png
bunx tsci build examples/micro-usb.circuit.tsx --pcb-png --schematic-png
```

`index.tsx` exports the board wrapper and all three individual components; the default export remains the individual USB-A connector. Circuit files are preview boards. Tests compare every new rendered pad against the retained upstream footprint, including rotation, copper face, pin mapping, no-paste output, cutout containment, and independent USB-C connections. Board-wrapper tests cover all three connectors on every edge, offsets, invalid dimensions, child components, and wiring.

## Attribution

The USB-C/Micro-B adaptations retain the upstream GPL-3.0 license. See `LICENSE`, `NOTICE.md`, and the original files in `vendor/pcb-edge-usb`. The package declares `GPL-3.0-only`.