Skip to content

Interacting with Channel Maps

A list of channels on devices within groups of connected harnesses. Each completed pairing is a mapped channel; remaining rows are unmapped.

Columns

Columns are automatically generated when channel_map.new() is called. Additional columns are ok but discouraged due to consistency. If you need more columns, use data structures in build instructions.

Column Description
group_of_connected_harnesses harnesses linked through passthroughs (or a single standalone harness)
from_device_refdes device instance refdes of this channel endpoint (seeded by new())
from_device_channel_id channel id on that device (from its signals list)
from_repeat_channel_id required when that channel has two endpoints; blank otherwise
from_channel_type channel type of the from endpoint (from the signals list)
to_device_refdes device instance refdes of the mapped partner; blank until mapped
to_device_channel_id channel id of the mapped partner; blank until mapped
to_repeat_channel_id required when that channel has two endpoints; blank otherwise
to_channel_type channel type of the mapped partner; blank until mapped
multi_ch_junction_id set by map(..., multi_ch_junction_key=...); shared id for a multi-channel junction net
chain_of_connectors filled by passthrough_map.resolve(); semicolon-separated refdes.connector path (e.g. MIC3.J1;X1.A;X1.B;PREAMP1.J1)
chain_of_harnesses filled by passthrough_map.resolve(); semicolon-separated harness refdes hops (e.g. H1;H2)
manual_map_channel_python_equiv channel_map.map(...) call that produced this pairing; copy back into build instructions

Commands

These functions are already available in build instructions as channel_map. Use them as written.

channel_map.read()

Use this when a system build needs every row of the channel map in the revision that is open.

Return the channel map (cached).

channel_map.new()

Use this when a system build is starting a blank channel map. system.build() calls this before the script and replaces the file. A system script does not call it again.

Makes a new blank channel map. Overwrites existing channel map.

Seeds one row per channel endpoint, including both faces of a passthrough. Auto-map skips those multi-endpoint rows; map() uses a 3-tuple to name a face.

Args: none

Returns: none

channel_map.map(from_key, to_key=None, multi_ch_junction_key='')

Use this when a system build needs one channel endpoint patched to another, or landed on a multi-channel junction, and the channel types are compatible.

Map one channel endpoint to another (a patch), or consume it onto a multi-channel junction.

Each key is (device_refdes, channel_id) when that channel has one endpoint, or (device_refdes, channel_id, repeat_channel_id) when it has two. A 3-tuple on a single-instance channel is an error; omitting the repeat on a two-instance channel is an error.

Dual-map is two calls to the two repeats of the same passthrough. That consumes both faces as patch ends and does not write a passthrough-map row.

Both endpoints must belong to the same group_of_connected_harnesses. Unmated terminating connectors are in no group. An unmated passthrough face still belongs to the group of its other, mated face.

A patch may end by crossing a device only if the destination face has no harness. If that face has a harness, the last hop must be that harness.

Pass multi_ch_junction_key="jcn1" instead of to_key to consume from_key and write jcn1 as multi_ch_junction_id. Several rows can share that id (connecting those channels to each other) without pairing to a single partner. A channel may join only if its type is, or is compatible with, every other member already on that junction.

Args: - from_key: Endpoint to map. (device_refdes, channel_id) when the channel has one endpoint, or (device_refdes, channel_id, repeat_channel_id) when it has two. A 3-tuple on a single-endpoint channel is an error, and omitting the repeat on a two-endpoint channel is an error. - to_key: Other endpoint of the patch, in the same tuple shape as from_key. Both ends must belong to the same group of connected harnesses. Optional. Omit it, or pass None, when you pass multi_ch_junction_key instead. - multi_ch_junction_key: Junction id, such as "jcn1", that consumes from_key. Every channel that shares that id is connected, without pairing to one partner. The channel type must be compatible with members already on the junction. Do not pass this together with to_key. Optional.

channel_map.force(from_key, to_key)

Use this when a system build needs one channel endpoint patched to another even though the channel types do not match. Pair the signals with circuits_list.force before circuits_list.new.

Map one channel endpoint to another regardless of channel-type compatibility.

Same key, group, and face rules as map(). A 1:1 patch only: there is no multi_ch_junction_key. map() is unchanged and does not record a pending patch.

Signal names still pair by name when both channel types list the same set, and circuits_list.new() compiles those circuits as usual. When the sets differ, the patch is recorded as pending. Call circuits_list.force() with a from-signal → to-signal dict, and drop every to-side signal you are leaving unwired, before circuits_list.new(). A pending patch still waiting at circuit compile raises ValueError.

The circuit's from_signal is the from-side name. A from-side signal cannot be left unwired. If the from channel has a name the to channel does not, swap the endpoints so that extra name is on the to side, then drop it.

channel_map.flatten()

Use this when a system build needs the flattened channel map of this system and the subsystems it contains.

Write maps/channel_map_flattened.tsv for this system and every child subsystem.

Reads this system's channel map, then the channel map imported with each child subsystem, recursively. An imported subsystem channel map is the source of truth for which endpoints were mapped. This does not re-run channel mapping inside the subsystem.

A passthrough channel whose two faces are both mapped patch ends is folded into one row between the outer endpoints before subsystem prefixes are applied. The lexicographically smaller outer endpoint (refdes, channel id, repeat) is the from side. chain_of_connectors records the disconnect between them (SNK-0.J1;X-6.B;X-6.A;SNK-3.J1). chain_of_harnesses on that row is left blank. A chain of dual-mapped disconnects folds to the two outer devices, with every disconnect in the connector chain. A channel with only one face mapped stays as that one patch. A row that already joins the two faces is left unchanged. Rows with no partner and no multi-channel junction are omitted. A junction row is kept. The flat channel map is not rewritten.

Rows from a subsystem prefix that subsystem's instance name onto group_of_connected_harnesses, from_device_refdes, to_device_refdes, multi_ch_junction_id, chain_of_connectors, and chain_of_harnesses. A list is prefixed per entry (AMP.H1+AMP.H2, AMP.H1;AMP.H2, AMP.MIC3.J1;AMP.X1.A). Nested subsystems accumulate prefixes (AMP.PRE.MIC1). from_repeat_channel_id, to_repeat_channel_id, and manual_map_channel_python_equiv are omitted. from_channel_type_description and to_channel_type_description sit beside the channel type columns and are the description from that type's channel_types.tsv. Channel ids and channel types are copied unchanged. This system's own rows are not prefixed.

Call after channel mapping, including map_unmapped_compatibles_alphabetically(). The sheet snapshots the channel map as it stands at the call.

Args: none

Returns: the written rows

channel_map.already_mapped(key)

Use this when a system build needs to know whether one channel endpoint is already consumed by a map or a route.

Return whether an endpoint is already in the mapped-channels set.

Args: - key: Endpoint key in the same shape map uses: (device_refdes, channel_id) or (device_refdes, channel_id, repeat_channel_id).

channel_map.already_mapped_set()

Use this when a system build needs every channel endpoint already consumed by map or route.

Return the set of endpoint keys already consumed by map or route.

channel_map.already_mapped_set_append(key)

Use this when a system build needs to mark one channel endpoint as already consumed.

Mark one endpoint as already mapped.

Args: - key: Endpoint key in the same shape map uses: (device_refdes, channel_id) or (device_refdes, channel_id, repeat_channel_id). Raises if that key is already in the mapped set.