Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 42 additions & 1 deletion docs/elements/assembly-cable.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import CircuitPreview from "@site/src/components/CircuitPreview"
import preview1 from "@site/src/data/assembly-previews/assembly-cable-1.json"
import preview2 from "@site/src/data/assembly-previews/assembly-cable-2.json"
import preview3 from "@site/src/data/assembly-previews/assembly-cable-3.json"
import preview4 from "@site/src/data/assembly-previews/assembly-cable-4.json"

`assembly.cable` connects two endpoints inside an [`assembly.device`](./assembly-device.mdx). Give it a `name`, `from`, and `to`. Core infers a compatible cable and its route from the connectors' positions and orientations, then renders its wires and plugs in 3D.

Expand Down Expand Up @@ -128,6 +129,43 @@ define a bullet connector model. The two cable ends must have the same contact
count. An explicit model also supports other combinations, such as
`adaptercable_a(jst_sh_pins4)_b(jst_ph_pins4)`.

## Route a cable around a part with waypoints

Pass `waypoints` as ordered `{ x, y, z }` offsets in millimetres to guide a cable around nearby hardware such as a gimbal's phone holder. Core draws a smooth curve through the points while keeping both plugs seated in their connectors:

<CircuitPreview
wrapCode
circuitJson={preview4}
threeDImageUrl="/img/elements/assembly-cable-waypoints.png"
defaultView="3d"
hideSchematicTab
code={`import { assembly, jscad } from "tscircuit"

export default () => (
<assembly.device>
<board width={64} height={44} thickness={1.6} routingDisabled>
<connector name="J1" standard="jst_ph" pinCount={3}
footprint="jst3_ph" pcbX={-22} />
<connector name="J2" standard="jst_ph" pinCount={3}
footprint="jst3_ph" pcbX={22} />
</board>
<assembly.printedpart
name="HOLDER"
jscad={<jscad.cuboid size={[20, 16, 18]} center={[0, 0, 9.8]} />}
/>
<assembly.cable name="HARNESS" from=".J1" to=".J2"
waypointAnchor="start"
waypointAxisOrientation="board_at_start"
waypoints={[
{ x: 8, y: 16, z: 10 },
{ x: 36, y: 16, z: 10 },
]} />
</assembly.device>
)`}
/>

`waypointAnchor` picks the origin connector (`"start"` for `from` or `"end"` for `to`), and `waypointAxisOrientation` picks which endpoint's board axes orient the `{ x, y, z }` offsets (`"board_at_start"` or `"board_at_end"`). Both props are required whenever `waypoints` is provided; omitting `waypoints` (or passing `[]`) keeps automatic routing.

## Cable properties

| Property | Type | Description |
Expand All @@ -137,7 +175,10 @@ count. An explicit model also supports other combinations, such as
| `to` | `string` | Required ending endpoint, distinct from `from`. |
| `model` | `string` | Optional explicit cable model, including different-ended adapter cables. Omit to infer the model from the endpoints. |
| `standard` | `"usb_c"` | Optional USB-C preset. Omit to infer USB-C, JST SH (1 mm pitch), or JST PH (2 mm pitch) from the endpoints. |
| `waypoints` | `{ x: number; y: number; z: number }[]` | Optional ordered route offsets in millimetres. Omit (or pass `[]`) for automatic routing. |
| `waypointAnchor` | `"start" \| "end"` | Origin connector (`from` or `to`) for `waypoints` offsets. Required when `waypoints` is provided. |
| `waypointAxisOrientation` | `"board_at_start" \| "board_at_end"` | Endpoint board axes used to orient `waypoints` offsets. Required when `waypoints` is provided. |

When `model` is omitted, both JST connectors must have the same standard and `pinCount`. Select a matching footprint, such as `jst6_ph` for a six-pin PH header. Inferred cables reject incompatible standards or pin counts. Missing or ambiguous endpoints report errors with either mode. Endpoints resolve within the nearest `assembly.device`, including components declared later.

Add one `assembly.cable` for each physical cable; several cables can share a device. Each creates an independent cable path. The initial route includes connector exit directions and a clearance arch. It does not perform obstacle avoidance or calculate gravity sag, so inspect the rendered path when placing enclosures and nearby parts. There are no length or route-hint props.
Add one `assembly.cable` for each physical cable; several cables can share a device. Each creates an independent cable path. The initial route includes connector exit directions and a clearance arch. It does not perform obstacle avoidance or calculate gravity sag, so inspect the rendered path when placing enclosures and nearby parts.
Loading
Loading