Annotation

This assigns reference designators (refdes) to components on the schematic. These refdes are important for ensuring that the link between schematic and PCB is maintained.

For new schematics that have not started PCB layout, the refdes assignment is not critical. However, once the PCB layout is started, it is very important to maintain the link between schematic components and PCB footprints.

When new components are added into an existing circuit, it might cause the refdes of exisiting components to be changed. This is not a bug, but how circuitscript works.

In this example below, the 1k resistor is initially annotated with a refdes of R1.

from std import *

v5 = supply("5V")
gnd = dgnd()

# Original circuit
at v5
wire down 100
add res(1k)
wire down 100
to gnd

When a new circuit is added this circuit, due to the way circuitscript runs the code, the 1k resistor is now annotated with a refdes of R2.

from std import *

v5 = supply("5V")
gnd = dgnd()

# Added circuit
at v5
wire down 100
add res(2.1k)
wire down 100
to gnd

# Original circuit
at v5
wire down 100
add res(1k)
wire down 100
to gnd

Maintaining stable refdes

Stable refdes refers to components maintaining their assigned refdes even though there are code changes. This ensures that the correct component links to the PCB are maintained and do not cause a mismatch.

Refdes comments

Circuitscript manages refdes annotation using a special comment symbol: #=. In circuitscript, the # symbol denotes the start of a comment and #= provides a refdes hint to the circuitscript interpreter through comments. When the interpreter encounters this symbol, it will extract the refdes information from the comment and apply it to the active component.

Besides stating clearly the refdes of the component, another benefit of refdes comments are that they will "follow" the code if it is copied/moved to another location. This ensures that the refdes remains stable for a given circuit.

To assign another refdes, the refdes comment can be removed or specifically set to another value.

In the example below, the 1k resistor is assigned a refdes of R99 because of the #= R99 comment annotation.

from std import *

v5 = supply("5V")
gnd = dgnd()

# Added circuit
at v5
wire down 100
add res(2.1k)
wire down 100
to gnd

# Original circuit
at v5
wire down 100
add res(1k) #= R99
wire down 100
to gnd

For circuits that have loops or are within functions, the comment annotation must have a underscore character at the end.

from std import *

v5 = supply("5V")
gnd = dgnd()

for i in range(0, 5):
    at v5
    wire down 100
    branch:
        wire right 200 down 100
        add cap(1n) #= C23_
        wire down 100
        to gnd

    wire down 100
    add res(1k) #= R65_
    wire down 100
    to gnd

Alternative refdes assignment

Besides the refdes comments, the refdes can be manually assigned using the refdes parameter. In this example below, the 1k resistor is defined with a fixed refdes of "R1".

from std import *

v5 = supply("5V")
gnd = dgnd()

# Added circuit
at v5
wire down 100
add res(2.1k)
wire down 100
to gnd

# Original circuit
at v5
wire down 100
add res(1k)
..refdes = "R1"
wire down 100
to gnd

tip

Refdes comments are preferred, since they are more flexible and are not directly "hardcoded" into the circuit itself. When a circuit is reused in a new design, a different refdes might be assigned.

Automatic refdes comments

Using the CLI tool

The refdes comments can be automatically added into the source files by using the -u parameter in the circuitscript CLI tool.

Imported libraries

By default, refdes comments are not added into imported libraries. To add these refdes comments, the #= annotate keyword must be added to the end of the import. This ensures that imported libraries are not modified unless clearly intended.

Example:

from std import *
from my_library import my_component #= annotate

v5 = supply("5V")
gnd = dgnd()

tmp = my_component()

at tmp pin 1
wire left 100 up 100
to v5

at tmp pin 6
wire right 100 down 100
to gnd

Shared libraries

For imported libraries that may be shared with other designs, refdes comments should not be added within the library code itself. In circuitscript, these are also known as external libraries.

Please specify the #= annotate-external keyword at the end of the import statement and an external <projectName>.refdes.json file is created with the refdes annotations for all external libraries that are used in the project.

warning

Only use #= annotation-external for libraries that do not change! If the library code is changed, it may cause refdes assignment issues as the <projectName>.refdes.json file no longer accurately reflects the refdes information of the external library in the given codebase.