Equipment connections (`bt.connections`)¶

Which supply feeds which load, which valve feeds which actuator, which controller input reads which sensor: ports declared on existing equipment, the connections between them, and a report that checks the pairing. The plan rides the .botrail project. See Equipment connections.

import botrail as bt

cx = bt.connections
cx.port(scene, "24V", "psu", "power", "supply")
cx.port(scene, "eye.power", "eye", "power", "load")
cx.connect(scene, "24V", "eye.power", name="W1", cable="CBL-001")

report = cx.report(scene)
assert report.ready, report.to_markdown()

connections ¶

Physical interface requirements over existing equipment and I/O assignments.

bt.connections is the explicit wiring plan behind scene.requirements(). The per-supply current budget most cells need comes from the requirements (each power supply against the current_a of the parts at its voltage); declare ports and connect them when a cell has to say which supply feeds which load, which valve feeds which actuator, which controller input reads which sensor. The plan rides the .botrail project and comes back through generate_python. See docs/guides/connections.md.

Ports describe declared interfaces; they do not execute the cell. Ratings are for one endpoint in total. Unknown consumption is never counted as zero.

ConnectionReport ¶

Connection checks, resolved endpoint specs and source capacity tables.

ready applies only to declared requirements and the missing utility declarations identifiable from Part attributes; it is not installation approval. No declared requirements is not_run.

to_csv ¶

to_csv(table: str = 'connections') -> str

Requirements (one row per port) or power supply capacity CSV.

connect ¶

connect(
    scene,
    source: str,
    target: str,
    *,
    name: str | None = None,
    cable: str | None = None,
    reference: str | None = None,
) -> str

Connect declared ports. Reusing a connection name replaces that link.

Invalid medium/direction pairs are kept for review, like incompatible I/O assignments. Cable identifiers are references, not added BOM lines.

disconnect ¶

disconnect(scene, name: str) -> None

Remove a named connection; required endpoints become unconnected.

port ¶

port(
    scene,
    name: str,
    target: str,
    medium: str | None = None,
    role: str | None = None,
    *,
    target_kind=None,
    required: bool | None = None,
    io=None,
    terminal=None,
    reference=None,
    at=None,
    exit=None,
    straight_m: float = 0.0,
    from_catalog: str | None = None,
    **specs,
) -> str

Define or replace a named interface on an existing resident.

medium is power/pneumatic/signal/network. Roles are supply/load for utilities, output/input for signals, peer for networks. Supply ports are optional by default; other ports require a connection. io references an existing controller assignment: {point, direction, node, aspect?}. terminal and reference are external drawing/specification labels.

Power specs: voltage_v (or voltage_min_v/max_v), current_a (load), capacity_a (supply). Pneumatic specs: pressure_bar (or min/max), flow_l_min / capacity_l_min and flow_reference. Signal specs: signal_type (digital/safe_digital/analog/word), voltage range and logic (pnp/npn). Networks declare protocol. Values apply to this endpoint's total load or capacity; no diversity factor or W/A conversion is inferred.

at places the port for routing (bt.routing): (obstacle_or_frame, (x, y, z)) or (robot, link, (x, y, z)), the offset in that resident's frame — the port then follows the resident. exit is the direction the line leaves the connector, in the same frame, and straight_m how much of it must stay straight (the boot, the gland). A port without at takes part in the connection checks only. from_catalog names a port the resident's catalog product declares (:func:ports_of): its place, exit, straight length, medium and role are the defaults — what you pass wins.

ports_of ¶

ports_of(scene, target: str) -> list[dict]

The ports a resident's catalog product declares (ports: in its pack): each with name, medium, role, at (as :func:port takes it — (robot, link, xyz) on an articulated product, (resident, xyz) on a body of a generated one), exit, straight_m and the pack's note / source. Empty when the product declares none or the resident is not a catalog product. The product is the BOM line the resident is on (scene.bom()), so a robot loaded from the catalog and a part pinned with catalog= both answer.

remove_port ¶

remove_port(scene, name: str) -> None

Remove a port, retaining links so broken references remain visible.

report ¶

report(scene) -> ConnectionReport

Check physical requirements for the entire cell, independent of bake scope.

A single port on a qty=1 equipment target can inherit corresponding Part attributes. Multiple ports of the same medium/role, and grouped qty>1 targets, require explicit port totals. I/O terminals read their existing channel kind/electrical data. Every resolved value records its origin.

restore ¶

restore(scene, plan: dict) -> None

Restore a serialized connection plan, including unresolved references.

The typed project schema validates its structure. :func:report checks its design meaning and names references broken by equipment/port removal.

Equipment connections (bt.connections)¶