:experimental:

[[multichannel]]
== Multichannel layout

KiCad has a multichannel layout feature for replicating the layout of repetitive blocks of circuitry in a PCB design.
This is useful for designs that contain multiple identical subcircuits,
such as an audio mixer with many identical channels,
a multi-output power supply with repeated regulation stages,
or an LED driver board with identical per-channel circuitry.
Instead of manually placing and routing each repeated block, you perform the layout for one block and then automatically replicate that placement and routing to all other matching blocks.

image::images/multichannel_layout.png[]

The multichannel layout workflow has three main stages:

. **Schematic setup**: Designate which portions of the schematic represent the repeated parts of the circuit.
  Each repeated block is called a _channel_.
. **Rule area generation**: Create placement rule areas on the PCB board to define the physical boundary of each channel.
. **Layout replication**: Manually place and route one _reference_ channel, then use the **Repeat Layout** tool to copy its placement and routing to all _target_ channels.

Using the multichannel layout feature first requires you to designate which portions of the schematic represent the repeated parts of the circuit.
You can use xref:../eeschema/eeschema.adoc#hierarchical-schematics[hierarchical sheets] (with a repeated hierarchical sheet for each channel),
xref:../eeschema/eeschema.adoc#component-classes[component classes] (with a unique component class assigned to the symbols in each channel), or named <<groups,groups>>.
Each channel will exactly correspond to the symbols (and their associated connections) in a single sheet, component class, or group.

For the layout, specially configured <<pcb-rule-areas,rule areas>> are drawn on the board and used to describe the physical location of each repeated channel.
The automatic placement of footprints, routing, and other items is restricted to these placement rule areas.
Each "channel" of the design corresponds to a single rule area.
One rule area will be the _reference_ rule area, which will be manually placed and routed.
The other rule areas are the _target_ rule areas, which will reuse the placement and routing from the reference rule area.

After setting up the placement rule areas for each channel and manually routing the reference channel, the Repeat Layout tool is used to copy the placement and layout from the reference rule area to the target rule areas.

NOTE: KiCad includes a demo project, called `multichannel`, that demonstrates the use of the multichannel layout feature.

[[multichannel-schematic]]
=== Multichannel design procedure: schematic

Designing a multichannel layout begins in the schematic.
You need to specify which components (symbols) belong to each channel.
Each channel in the schematic must be equivalent to the other channels.
This means channels must match each other in the following ways:

- each matched channel needs to have the same number of symbols
- corresponding symbols in each channel need to have the same reference designator prefix (e.g. `R` or `U`), although the full reference designators need to be unique as usual
- corresponding symbols in each channel need to have the same footprint
- connections between symbols need to be equivalent in each channel

In the example schematic below, Channels 1, 2, 3, and 4 are equivalent and therefore can be used to share routing in a multichannel design.
Even though the net connections are drawn differently in some channels, the underlying net connections are the same.
The different symbols in Channel 2 and the different values in Channel 3 also do not break the equivalency.
Footprint assignments are not shown in the image, but the symbols that correspond between channels must use the same footprints.
In this example, this means that R1, R3, R5, and R7 each must use the same footprint, as must R2, R4, R6, and R8.

In contrast, Channels A and B are not equivalent to Channels 1-4, nor to each other.
Channel A contains an extra parallel resistor not present in the other channels, and Channel B is missing a connection between the two resistors.

image::images/multichannel_equivalency.png[]

You can assign symbols to channels in three ways:

- **Hierarchical sheets**: using xref:../eeschema/eeschema.adoc#hierarchical-schematics[hierarchical sheets], each channel is represented by a different sheet.
  Normally you will instantiate the same hierarchical sheet file multiple times, with one instantiation per channel.
  Each sheet instantiation needs to include all of the symbols for the corresponding channel, with no extra symbols.
- **Component classes**: using xref:../eeschema/eeschema.adoc#component-classes[component classes], each channel is represented by a different component class.
  Each component class needs to include all of the symbols for the corresponding channel, with no extra symbols.
  Component classes are shown in the previous schematic example.
- **Groups**: using named <<groups,groups>>, each channel is represented by a group of footprints on the board.
  This provides a more explicit way to define channels when hierarchical sheets or component classes are not suitable.

TIP: Hierarchical sheets are the most common and convenient approach for multichannel designs.
     By instantiating the same sheet file multiple times, you guarantee that each channel has identical circuitry.
     The schematic editor automatically assigns unique reference designators to each instantiation.

[[multichannel-board]]
=== Multichannel design procedure: board

In the board, each channel is represented with a <<pcb-rule-areas,rule area>> with its rules configured for placement.
You need to add a rule area for each channel.
One rule area is the _reference_, containing manually placed and routed footprints.
The other rule areas are _targets_ and have the reference placement and routing copied to them.
Placement rule areas, whether for reference or target channels, need the following settings configured in their properties:

- The options in the **Placement** tab should be configured to select the hierarchical sheet, component class, or named <<groups,group>> that contains the channel's components.
- The options in the **Keepouts** tab should typically be unselected, unless there is a specific type of item that needs to be excluded from the rule area.
- The rule area's **layers** should be set based on which layers are considered part of the channel.
  An item will be copied from the reference channel to a target channel only if the item's layer is enabled in both the reference and target rule areas.
- The **area name** is used to label the rule area when it is listed in the Repeat Layout dialog.
  While not strictly required, it will be hard for you to distinguish rule areas in the GUI unless each rule area has a unique name.

image::images/rule_area_placement.png[]

[[multichannel-generate-rule-areas]]
==== Generating placement rule areas

Placement rule areas can be manually created like any <<pcb-rule-areas,rule area>>, or they can be automatically generated by selecting **Tools** -> **Multi-Channel** -> **Generate Placement Rule Areas...**.
This tool scans the design for hierarchical sheets, component classes, and named groups, then creates a placement rule area for each one you select.
This is the fastest way to set up placement rule areas for a multichannel design.

NOTE: The tool allows you to generate a placement rule area for *any*
      sheet, component class, or named group,
      even if it is not intended to represent a channel in a multichannel design.
      It is your responsibility to select only the desired sheets, component classes, or groups.

The Generate Multichannel Rule Areas dialog contains a tabbed notebook with three tabs:

- **Sheets**: lists every hierarchical sheet path found on the board.
  Each row shows the sheet path and the sheet file name.
  Check the **Generate** checkbox for each sheet that represents a channel.
- **Component Classes**: lists every component class assigned to footprints on the board.
  Check the **Generate** checkbox for each component class that represents a channel.
- **Groups**: lists every named group on the board.
  Check the **Generate** checkbox for each group that represents a channel.

image::images/multichannel_generate_rule_area.png[]

Below the tabbed source selection, the dialog has additional options:

[cols="35%,65%",options="header"]
|===
| Option | Description

| **Replace existing placement rule areas**
| If enabled, the newly generated rule area for each channel will replace any rule areas that already exist for that channel.
  If disabled, channels that already have a placement rule area will be skipped.

| **Group footprints with their placement rule areas**
| If enabled, the newly generated rule area for each channel will be added to a <<groups,group>> with all footprints associated with that rule area. This allows the target rule area and its associated items to be manipulated as a single entity.
  This option is disabled for group-based sources, because the footprints already belong to their respective groups.
|===

When you click **OK**, KiCad performs the following steps for each selected channel:

. Queries the board for all footprints belonging to the sheet, component class, or group.
. Computes a convex hull around those footprints with a small margin.
. Rectifies the hull into an axis-aligned polygon using only 90-degree segments.
. Creates a new rule area configured as a placement area, with the appropriate source type (sheet path, component class, or group name) recorded.
. Sets the rule area layers to all copper layers.
. If **Replace existing** is checked and a matching rule area already exists, the old rule area is removed.
. If **Group footprints** is checked, a new group is created containing the rule area and all its associated footprints.
. Names the generated rule area automatically using the pattern `auto-placement-area-<source>`, where `<source>` is the sheet path, component class name, or group name.

After generating a rule area, you may want to change the configured layers to ensure all desired items in the reference channel get copied to the target channels.

NOTE: If generated rule areas are grouped with their footprints, you will need to enter the group (or ungroup the items) in order to edit the rule area.

TIP: After generating rule areas, enlarge the reference rule area to enclose all routing for the reference channel.
     Target rule areas will be resized automatically to match the reference when you run **Repeat Layout**.

[[multichannel-repeat-layout]]
==== Repeating the layout

Once you have created rule areas for each channel and completed placing footprints and routing for the reference channel, you can use the **Repeat Layout** tool to copy the reference channel's layout to the other channels.
The tool is accessed from **Tools** -> **Multi-Channel** -> **Repeat Layout...**.

The complete workflow is:

. **Select the reference rule area.** Either select a placement rule area on the board before running the tool, or run the tool without a selection and you will be prompted to click on the reference rule area.
  The reference rule area is the one whose placement and routing you want to replicate.
. **Topology check.** KiCad automatically finds all other placement rule areas on the board and checks whether their circuit topology matches the reference.
  This process attempts to find a one-to-one mapping of components and connections (an _isomorphism_) between the reference and each target.
  A progress indicator is shown for large designs.
. **Configure the Repeat Layout dialog.** The dialog displays the results of the topology check and lets you select which targets to update and which items to copy.
. **Execute.** Click **OK** to apply the reference layout to all selected target channels.

If a rule area is selected when the tool is run, that rule area will be used as the reference rule area.
If no rule area is selected, you will be prompted to select a rule area.
You can also select a group that contains a rule area, and the rule area within the group will be used.
When the reference rule area is determined, a dialog will appear.

image::images/multichannel_repeat_layout.png[]

[[multichannel-repeat-layout-dialog]]
===== Target rule area table

The table at the top of the dialog controls which target rule areas will receive the layout from the reference channel.
Each row represents one target rule area and shows the following columns:

[cols="20%,80%",options="header"]
|===
| Column | Description

| **Copy**
| A checkbox controlling whether this target will receive the replicated layout.
  Targets whose topology matches the reference are checked by default.
  Targets with mismatches are unchecked and cannot be selected.

| **Rule Area**
| The name of the target rule area, as configured in its zone properties.

| **Status**
| Shows "OK" if the target channel's topology matches the reference, or an error message describing the mismatch.
  Click the details icon (if present) to see a detailed breakdown of the mismatch reasons.
|===

The tool will only copy items to a target rule area if the target's status is listed as "OK".
If the status is not "OK", the target channel's circuit topology cannot be matched to the reference channel;
see the requirements for <<multichannel-schematic,how channels need to match in the schematic>> for more information.

===== Repeat layout options

There are several options to control which items from the reference channel are copied to the selected target areas, and how those copied items are handled:

[cols="35%,65%",options="header"]
|===
| Option | Description

| **Anchor footprint**
| If a footprint is selected in the dropdown, that footprint (and its equivalent in each channel) acts as an anchor for the channel.
  Each channel will be positioned and oriented relative to the channel's anchor footprint.
  If no footprint is selected, each channel will be positioned relative to the center of the reference rule area.

| **Copy footprint placement**
| If enabled, the placement of footprints in the reference rule area will be replicated for footprints associated with the target rule area(s).
  Footprints are copied if they are enclosed by or intersect the reference rule area; they are not copied if they are fully outside.
  Footprints will only be copied if they are on a layer that is enabled in both the reference and target rule areas.

| **Copy routing**
| If enabled, any tracks and vias in the reference rule area will be copied to the target rule area(s).
  Routing is copied if it is fully enclosed by the reference rule area; it is not copied if it is partially or fully outside.
  Routing will only be copied if it is on a layer that is enabled in both the reference and target rule areas.
  Existing routing in the target rule areas is removed before the new routing is placed.

| **Restrict to routing connected within the area**
| A sub-option of **Copy routing**.
  When checked, tracks and vias will not be copied unless they share a net with a pad inside the reference rule area.
  This can be useful to prevent copying unrelated tracks that happen to pass through the rule area.

| **Copy other items**
| If enabled, any other items (zones, graphic objects) fully enclosed by the reference rule area will be copied to the target rule area(s).
  Items are copied if they are fully enclosed by the reference rule area; they are not copied if they are partially or fully outside.
  This means, for example, that a large copper zone that intersects a reference channel will not be copied to the target channels.
  Items will only be replicated if they are on a layer that is enabled in both the reference and target rule areas.

| **Group items with their target rule areas**
| If enabled, the items copied to a target rule area will be added to a <<groups,group>> with that rule area.
  This allows the target rule area and its associated items to be manipulated as a single entity.

| **Include locked items**
| If enabled, items in the reference rule area will be copied even if they are <<locking,locked>>, and items associated with target rule areas will be updated even if they are locked.
  If not enabled, locked items in the reference rule area will not be copied and locked items in the target rule area will not be updated or deleted to match the reference rule area.
|===

After clicking **OK**, the layout from the reference channel will be applied to the target channels.
An info bar message confirms how many rule areas were updated.
When the repeat layout is completed, each channel can be individually edited like any other part of the board design.

TIP: You can run **Repeat Layout** multiple times as you refine your reference channel.
     Each run replaces the target channel contents with the current state of the reference channel.

[[multichannel-topology-matching]]
=== Topology matching

The core of the multichannel layout feature is the topology matching algorithm, which determines how components in the reference channel correspond to components in each target channel.
Understanding how this matching works is important for diagnosing issues when channels fail to match.

==== How components are matched

KiCad analyzes the connectivity of both the reference and target channels.
For each channel it catalogs:

- **Components**: one entry per footprint, identified by its reference designator prefix (the letters before the numeric suffix, e.g. `R` from `R1`, `U` from `U3`).
- **Pins**: one entry per pad on each footprint.
- **Connections**: which pins share the same net.

Two components are considered the "same kind" if they share the same reference designator prefix.
For hierarchical designs where references may include a channel identifier (such as `TRIM_1.1` and `TRIM_2.1`),
the algorithm detects a common prefix and treats the trailing channel-specific suffix as a channel identifier, so the components will still be matched.

The algorithm then searches for a one-to-one mapping (an _isomorphism_) of components in the reference to components in the target such that all pin connections are preserved.
This means:

- For every pair of connected pads in the reference channel, the corresponding pads in the target channel must also be connected.
- The matching is based on actual net connectivity, not on reference designator numbers.
  `R1` in the reference does not necessarily map to `R1` in the target -- it maps to whichever resistor has the same connectivity pattern.

==== Tie-breaking for identical components

When multiple components in a target channel have identical connectivity (for example, a row of identical decoupling capacitors all connected between the same power and ground nets), the algorithm uses tie-breaking strategies to select the best match:

. **Symbol/sheet instance matching**: if the reference and target components originated from the same hierarchical sheet instance, they are preferentially matched.
  This is the most reliable tie-breaker for hierarchical sheet designs.
. **Position-based proximity**: components closer in physical position to their reference counterparts may be preferred.

==== Mismatch error details

When a target channel fails the topology check, the **Status** column in the Repeat Layout dialog shows an error summary.
You can click the details icon in the rightmost column to view a detailed error dialog listing:

- Which specific components could not be matched and why.
- The total component count in the reference vs. the target area, if they differ.
- A list of all components in each area for comparison.

See <<multichannel-troubleshooting>> for common reasons that topology matching fails and how to resolve them.

[[multichannel-routing-duplication]]
=== Routing duplication details

When **Copy routing** is enabled, the Repeat Layout tool duplicates all tracks and vias from the reference rule area to each target rule area.
Understanding how this process works will help you achieve clean results.

==== What is copied

The tool identifies routing in the reference rule area by testing whether each track or via on the board is _enclosed by_ the reference rule area polygon.
Items that are fully enclosed are candidates for copying.
Items that only partially overlap or are fully outside the rule area are not copied.

For each copied item, the tool:

. Duplicates the item (track segment or via).
. Translates the duplicated item from the reference position to the target position, based on the offset between the rule area centers (or anchor footprints, if an anchor is set).
. Rotates the duplicated item to match any orientation difference between the anchor footprints.
. Reassigns the net of the duplicated item to the corresponding net in the target channel, using the component matching to look up which target pad connects to the same net.

==== Net reassignment

When a track or via is duplicated, it must be assigned to the correct net in the target channel.
The tool does this by:

. Finding which pads in the reference channel are connected to the same net as the original routing item.
. Looking up those pads' parent footprints.
. Finding the corresponding pads on the matched target footprints.
. Assigning the target pad's net to the duplicated routing item.

This means routing is automatically reassigned to the correct target-channel nets without any manual intervention.

==== Existing target routing

Before copying routing to a target area, the tool removes any existing routing within the target rule area that is on layers enabled in the target rule area.
This ensures a clean copy without leftover routing from a previous iteration.
If **Restrict to routing connected within the area** is enabled, only routing connected to pads within the area is removed.

==== Layer considerations

A routing item is only copied if its layer is enabled in _both_ the reference and target rule areas.
This means:

- If the reference rule area includes layers `F.Cu` and `B.Cu`, but a target rule area only includes `F.Cu`, then only front-copper routing will be copied to that target.
- Inner copper layers must be explicitly included in both rule areas for inner-layer routing to be copied.

TIP: Make sure all copper layers used by your routing are enabled in both the reference and target rule areas.
     A common issue is forgetting to add inner copper layers to the rule area layer set, which causes inner-layer routing to be silently skipped.

==== When routing duplication fails

Routing duplication can produce unexpected results in several situations:

- **Routing extends outside the rule area**: tracks that exit the reference rule area will not be copied.
  Make sure the reference rule area is large enough to enclose all routing for the channel, including any via fan-outs near the edge.
- **Net reassignment failure**: if a track's net cannot be mapped to a target channel net (for example, because it belongs to a global net that is not part of any channel), the duplicated track may retain the reference channel's net.
  Enabling **Restrict to routing connected within the area** can help avoid copying such unrelated tracks.
- **Layer mismatch**: if the reference routing uses a layer not enabled in the target rule area, those segments will be silently omitted.

[[multichannel-other-items]]
=== Other item duplication

When **Copy other items** is enabled, zones and graphic objects (such as drawings, text, and dimensions) within the reference rule area are also duplicated to each target rule area.
The same displacement and rotation transforms are applied.

Zones are duplicated with their net reassigned using the same component-match-based lookup used for routing.
A zone is only copied if all of its layers are present in both the reference and target rule areas.

Graphic objects that are not connected (such as silkscreen text, board outlines, or fab layer drawings) are copied without net assignment.
They must be on a layer enabled in both rule areas.

NOTE: Footprint text items (reference designators, values, and other footprint fields) are handled as part of footprint placement, not as standalone items.
      Their position, visibility, and attributes are updated to match the reference footprint's fields when placement is copied.

[[multichannel-step-by-step]]
=== Step-by-step multichannel workflow

The following procedure summarizes the complete multichannel layout workflow from start to finish:

. **Design the schematic.** Create the repeated circuit as a hierarchical sheet (or assign component classes / groups).
  Instantiate the sheet once per channel.
  Ensure all channels have identical circuit topology.

. **Import the netlist / Update PCB.** Transfer the schematic to the PCB editor.
  All footprints for all channels will appear on the board.

. **Generate placement rule areas.** Select **Tools** -> **Multi-Channel** -> **Generate Placement Rule Areas...**.
  In the dialog, check the sheets (or component classes, or groups) that correspond to your channels.
  Click **OK**.

. **Arrange the rule areas.** Move each generated rule area to its desired position on the board.
  The footprints associated with each rule area do not need to be inside the rule area yet -- that will happen during the repeat layout step.

. **Design the reference channel.** Choose one rule area as your reference.
  Place all of its footprints inside the rule area and route the channel completely.
  Ensure the rule area boundary encloses all footprints, routing, and other items you want to replicate.

. **Enlarge the reference rule area if needed.** The auto-generated rule area may be too small to enclose routing.
  Edit the rule area outline to include all routing, including via fan-outs and any local copper zones.

. **Run Repeat Layout.** Select the reference rule area, then select **Tools** -> **Multi-Channel** -> **Repeat Layout...**.
  In the dialog:
   - Verify all target channels show **OK** status.
   - Select an anchor footprint if you want channels to be oriented relative to a specific component.
   - Enable **Copy footprint placement**, **Copy routing**, and **Copy other items** as desired.
   - Click **OK**.

. **Review the results.** Inspect each target channel to verify that placement and routing were copied correctly.
  Run DRC to check for errors.

. **Iterate as needed.** If you need to make changes to the reference channel's layout, edit it and run **Repeat Layout** again.
  Target channels will be updated to match.

[[multichannel-troubleshooting]]
=== Troubleshooting multichannel layouts

==== Channels fail topology matching

If a target channel's status shows an error instead of "OK" in the Repeat Layout dialog, the channel's circuit topology does not match the reference.
Click the details icon to see specifics.
Common causes:

- **Missing or extra components**: verify that each channel's schematic sheet (or component class) contains exactly the same set of symbols.
  A common mistake is adding a decoupling capacitor to one channel but not the others.
- **Different reference designator prefixes**: a component in the target channel has a different prefix than any component in the reference (e.g. `R` vs. `C`), so no pairing is possible.
- **Different footprint assignments**: corresponding symbols in different channels must use the same footprint.
  If `R1` uses a 0402 footprint but `R3` uses a 0603, and they should correspond, the pad counts will differ and matching will fail.
- **Different net connections**: if a net is connected differently in one channel (e.g. a wire was accidentally deleted or connected to the wrong pin), the connectivity will differ.
- **Nested hierarchical sheets**: child sheets within the channel sheet are included when querying components.
  Ensure that nested sheets are identical across channels.

==== Routing does not appear in target channels

- **Rule area too small**: the most common cause.
  Routing outside the reference rule area boundary is not copied.
  Enlarge the reference rule area to enclose all routing.
- **Layer mismatch**: ensure that all copper layers used by the routing are enabled in both the reference and target rule areas.
  Check the rule area properties on the **Layers** tab.
- **Unrelated routing filtered out**: if **Restrict to routing connected within the area** is checked, tracks and vias whose net does not appear on any pad inside the rule area will be skipped.
  This is a net-based check, so a via that shares a net with a pad inside the area will be copied even if it is not physically routed to that pad.
  Uncheck this option if you need to copy routing on nets that have no pads inside the rule area.
- **Net reassignment to wrong net**: if a track belongs to a global or shared net that is not unique to the channel (e.g. a power net), the duplicated track may retain the reference channel's net instead of being reassigned.
  Enabling **Restrict to routing connected within the area** can help avoid copying such unrelated tracks.

==== Footprint placement is not copied

- **Footprint outside reference area**: footprints must be enclosed by or intersect the reference rule area.
  Footprints fully outside the area are not copied.
- **Layer not enabled**: a footprint is only copied if its layer is enabled in both the reference and target rule areas.
- **Locked footprints**: if **Include locked items** is not checked, locked footprints in the reference area will not be copied, and locked footprints in the target area will not be moved.

==== Other items do not appear in target channels

- **Item not fully enclosed**: zones and graphic objects must be fully enclosed by the reference rule area to be copied.
  A large copper zone that only intersects the rule area boundary will not be copied.
- **Zone layer mismatch**: a zone is only copied if all of its layers are present in both the reference and target rule areas.
- **Locked items**: if **Include locked items** is not checked, locked items in the reference area will not be copied and locked items in the target area will not be updated.

==== Target rule area shape is wrong

Target rule area outlines are automatically updated to match the shape of the reference rule area (translated and rotated to the target position).
If a target rule area has a shape you did not expect, check the reference rule area's outline -- the target is a direct copy of it.

==== Tips for clean multichannel designs

- **Use hierarchical sheets** with a single sheet file instantiated multiple times.
  This guarantees identical circuitry across channels.
- **Name your rule areas** descriptively (e.g. `Channel 1`, `Channel 2`) so you can easily identify them in the Repeat Layout dialog.
- **Make the reference rule area generous** in size.
  It is better to have extra space around routing than to accidentally clip routing at the boundary.
- **Route the reference channel completely** before running Repeat Layout.
  Partial routing can be replicated, but it is easier to verify a complete channel.
- **Group items with rule areas** for convenient manipulation.
  After replication, each channel's components, routing, and rule area can be moved as a unit.
- **Run DRC after replication** to catch any issues with the duplicated layout, such as clearance violations caused by different board areas or net assignment problems.

