2. schematics data

{des2:0} This chapter is an overview of the data model cschem uses. Some details, e.g. attributes, drawing primitives or hierarchic design will be discussed in later chapters.

2.1. Projects

{des2:1} A project is a collection of schematics sheets, data files, configuration, pcb-files, local libraries, logs, etc. What content belongs to a project shall be decided by the user.

{des2:2} The tool-agnostic project file describes the project by having tool-specific sections.

{des2:3} The cschem-specific section of the project file consists of a list of files that are relevant to cschem:

{des2:4} A schematics sheet consists of concrete elements (e.g. drawing primitives, attributes, data) that indirectly describe abstract schematics objects. The user is able to manipulate the concrete elements only, but can also see the abstract objects. Much of cschem deals with the abstract objects.

{des2:5} Each schematics sheet has a cschem generated unique ID and user specified attributes. Both the unique ID and attributes of the graphical sheet are stored in the direct subtree of the sheet.

{des2:68} The following diagram shows how concrete graphical schematics sheet elements can affect objects in the abstract model:

{des2:69} Note 1: concrete object attributes can affect the abstract model by making connections and creating new networks.

{des2:73} Note 2: a connection drawing primitive contributes to the "list of terminals" of wire-nets and bus-nets.

{des2:74} Note 3: groups also donate the attributes on their outgoing arrow; these then become the attribute of concrete objects and as a side effect (blue lines) may affect networks.

2.2. Abstract: schematics objects

{des2:6} On an abstract logical level, a schematic consist of components that have ports, and named networks that connect those ports. Networks can be bundled into buses and buses can be connected to bus-ports. Networks can be split and connected by hubs.

{des2:7} In an electronic example a component is a NAND gate, a port is a pin or pad or terminal of the gate and network is the electrical connection between the port of the gate and other ports in the circuit.

{des2:56} Each view has its own abstract object model, generated by different set of plugins with different configuration from the same concrete model. Since views are independent, the per view abstract models are independent too. The abstract models are generated on the fly and are not saved.

{des2:75} An abstract schematics object always contains a list of concrete-object (or concrete-object:key) pairs referring to any concrete object (or an attribute of a concrete object in the latter case) that contributed to the abstract object. This cross-reference lets the user track back the sources of an abstract object, which is important because the final output (e.g. netlist) is generated from the abstract objects while the user can make changes to the concrete objects only.

2.3. Concrete: graphical schematics sheets

{des2:8} A graphical schematics sheet is a two dimensional drawing, consisting of:

{des2:9} Symbols and networks connections are objects that contribute to the abstract, logical meaning of the sheet (components and networks). A decoration is a graphical element that is displayed and edited and exported on graphical output formats, but does not contribute to the logical meaning on a computer-readable level.

{des2:12} On graphical schematic sheets, many non-decoration objects are realized using graphical drawing primitives:

2.3.1. graphical representation of wires

{des2:13} A wire-net is a group of drawing primitives (e.g lines). In this chapter these drawing primitives are called wire-segments. The group is tagged to be a wire-net by its role attribute. The graphical representation of a wire-net does not need to be a straight line, but can be a graph that even includes cycles. In other words, a wire-net can be drawn as many lines with junctions and loops.

{des2:81} A junction is graphics within a wire-net that represents connected crossings of wires between wire objects of the same wire-nt. The simplest junction is a zero-length line drawn with a pen thicker than wires. Any other junction graphic is drawn packing atoms in a group or group_ref with role=junction within the wirenet.

{des2:14} A wire-net can be connected to zero or more ports or bus-ports. A wire-net can not leave the current sheet - there are no inter-sheet wire-segments.

{des2:15} A wire-net always represents (a part of) a network. In the simplest case a wire-net is a network. In more complex cases multiple wire-nets (potentially on multiple schematics sheets) and/or non-graphical data (e.g. connection dictated by attributes or non-graphical schematics data) build a single network.

{des2:16} A wire-segment has no attributes of its own, only a wire-net has. The attributes of a wire-net contributes to the attributes of the network it is part of. (The details of this will be discussed in a later chapter; TODO: link). Therefore there are always two things to consider, present or edit:

{des2:17} The set of possible attributes of a wire-net is the same as the attributes of a network (see below).

2.3.2. graphical representation of hubs

{des2:57} A hub-point is a concrete object (sometimes graphically represented as a largish dot or polygon). One or more different wire-nets can be connected to a hub-point; these wire-nets will be kept as separate networks, the hub-point won't merge them.

{des2:58} A hub-point also has attributes.

{des2:59} The concrete hub-point is translated into an abstract hub for the abstract model.

{des2:60} Hub-points can connect bus-nets too.

{des2:61} A hub-point differs from a normal wire-net branching in that:

2.3.3. graphical representation of components and ports

{des2:18} The graphical representation of (a part of) a component is called symbol.

{des2:19} A symbol is a group or group_ref with symbol-related attributes. It typically contains furhter groups for terminals, bus-terminals, other symbols and decoration. When a symbol is placed on a schematic sheet (either by copy or by reference), it is instantiated. A symbol has a creation-time cschem generated unique ID (which is the uuid field of the symbol group).

{des2:82} Groups also have an src_uuid field, which is used to track original sources. A newly created group has NIL (empty) src_uuid. Any copy of the group (e.g. an instance of the a library symbol on a sheet) will have src_uuid filled in with the src_uuid value of the source group, or if that was NIL, with the "instance uuid" (the group's uuid field) of the source group.

{des2:53} When an existing instance is moved within the sheet, renamed, its attributes changed, it retrains instance UID (uuid field). When the instance is copied, the new copy is a new instantiaton and gets a new instance UID. In both cases it retains its src_uuid field.

{des2:20} A symbol is usually part of a component, donating ports and attributes to the abstract (logical) component. The simplest component is created by a single symbol. More complex components are created by a combination of multiple symbols placed on graphical schematics sheets (and potentially be generated by non-graphical schematics sheets). Attribute collisions are resolved the standard way.

{des2:21} Among the attributes of symbols instance is one called name, which is the project-unique identifier of the component the symbol instance contributes to. The refdes can be calculated from this name, see also: hierarchy.

{des2:22} A symbol can be marked being decoration, in which case it does not contribute to any component.

{des2:23} A symbol can be used to describe a connection between different schematics sheets, to represent (and reference to) a whole schematics sheet in a hierarchy, to represent a data file or other resource meaningful to specific plugins (TODO: THIS CHAPTER).

{des2:24} The graphical representation of an abstract port is called terminal. A (concrete) terminal is modelled as a line. A terminal hosts a list of attributes.

{des2:25} Similar to port, the bus-port's representation is called bus-terminal, it is also modeled as a line and hosts a list of attributes.

{des2:76} Terminals and bus-terminals are most often part of symbols, but for hierarchical designs they are also placed directly on sheets to serve as an interface to the parent.

2.4. Concrete: data/programmed schematics sheets

{des2:26} A data/programmed schematics sheet is a non-graphical sheet. The purpose of the data/programmed schematics sheet is the same as the purpose of a graphical schematics sheet: to donate concrete source objects for the abstract objects.

{des2:71} The data/programmed schematics sheet contains data in a format understood by one of the plugins in the current view. That plugin is a "compiler" that interprets sheet data and emits abstract objects for cschem to use. The compilation process can be as simple as parsing the data or as complex as interpreting a high level programming language to generate the abstract objects. Cschem doesn't impose any restriction on the data format.

{des2:72} For the GUI a data/programmed schematics sheet is usually opaque data which can not be displayed or edited. Most often the data is edited by external applications. Alternatively the plugin handling the format may provide custom GUI.

2.5. Abstract: details of schematics objects

{des2:27} The abstract schematics consists only of a few object types. Their parent-children relations are illustrated by the tree below:

{des2:28} The attributes of a symbol, terminal and bus-terminal are the same as the attributes of a component, port or bus-port, respectively (see below).

2.5.1. components and ports

{des2:29} A component is a project-global object that has:

{des2:30} A port is a point of connect owned by a component. A port can connect a component to a network.

{des2:31} A port is a component-local object that is created by a graphical symbol (from a graphical sheet) or from data/program (from a data sheet).

{des2:32} A port has:

{des2:33} If there are multiple terminals with the same name within the same component (within one or multiple symbols; specified graphically or via data), they are combined into a single port with their attributes also combined, with the usual attribute collision rules.

{des2:77} The terminal->port name translation can be done by plugins; when available, core will call plugins for this job. This allows slotting implemented in plugins: the same terminal name in different slots may mean different ports within the same component.

{des2:34} A bus-port is a port with multiple "parallel" channels, each channel modelled as a separate port, called channel-port. A channel-port has a chan attribute that specifies which network the given chan will try to connect to when a bus-net or wire-net is connected to the bus-port.

{des2:35} Note: details on addressing networks by name is in a later chapter

{des2:55} Abstract network name attributes are donated directly by the concrete wire-nets contributing name attributes. (In case of hierarchy the name might be translated/calculated by a plugin).

{des2:36} core attributes of a component
attribute value description
uuid unique ID cschem-generated UID (not persistent)
connect PORT:NET list non-graphical connection; PORT is an existing port's name within the component; NET is the name of a network
source list of refs reference list to the concrete objects that contributed to this component; when saved: each item is an UID or an UID:key pair

{des2:37} core attributes of a port
attribute value description
uuid unique ID cschem-generated UID
name name of the port user assigned port name
connect name of a network the given port is also connected to a network (non-graphical connection)
chan channel name connection affinity, in case port is part of a bus-port
chan_rewrite rewrite list see at chan rewrite

{des2:38} core attributes of a bus-port
attribute value description
uuid unique ID cschem-generated UID
name name of the port user assigned port name
connect name of a bus-net the given bus-port is also connected to a named bus (non-graphical connection)
chan_rewrite rewrite list see at chan rewrite

2.5.2. networks

{des2:40} A network is:

{des2:41} A network has a project-wise unique name netname, which is derived from the user specified name attribute and other factors (e.g. hierarchy). A network also has a cschem generated unique ID.

{des2:42} A network is combined from:

{des2:43} core attributes of a network
attribute value description
uuid unique ID cschem-generated UID
netname unique name cschem-specified project-unique network name
name unique name user-specified sheet-unique network name
chan bus-unique name when a connection is made, this name is used to look up and bind channel(s)
source list of refs reference list to the concrete objects that contributed to this component; when saved: each item is an UID or an UID:key pair

2.5.3. bundled networks: buses and bus-ports

{des2:44} A bus-net is a logical bundling of multiple networks.

{des2:45} A bus-net consists of 1 or more bus-channels. Each bus-channel behaves as a network in all regards. Each bus-channel has a chan attribute that specifies what network or channel the given bus-channel will try to connect to when the bus-net as a whole is connected.

{des2:46} If a network is connected to the bus-net, either graphically or by attributes or data schematics, the network is connected to the bus-channel that has the chan attribute that matches the network's chan or name attribute.

{des2:47} If a port is connected to a bus-net directly, the port must specify a chan attribute. The port is connected to the bus-channel that has matching name (chan attribute), considering the chan rewrite attribute of the port. If there is no match, no connection is made.

{des2:48} If a bus-port is connected to a bus-net directly, a matching is performed between the bus-port's chan attributes and the bus-channels' chan attributes, considering the chan rewrite attribute of the bus-port. Whenever a match is found, a connection is made. (Hint: the number of connection made should be indicated by the UI so 0 connection is easy to detect)

{des2:49} If a network is connected to a bus-port, the same rules apply as if the network was connected to a bus-net, plus the bus-port's chan rewrite attribute is considered.

{des2:50} A bus-port accepts multiple bus-net connections and multiple network connections. In case of multiple network connections, networks with different net attributes are not connected together just because they are all connected to the same bus-port. In other words, the channels of the bus-port act as an independent port and each network will interact only with the channel of the same net attribute, but channels are independent. The connections are made on per-channel basis, considering the chan rewrite attribute of the bus-port.

{des2:51} core attributes of a bus-net
attribute value description
uuid unique ID cschem-generated UID
name unique name user-specified unique bus-net name
source list of refs reference list to the concrete objects that contributed to this component; when saved: each item is an UID or an UID:key pair

2.5.4. hubs

{des2:62} A hub is an explicit object that forms a connection between multiple different networks or buses (or in an extreme case is connected to a single network or bus).

{des2:63} On an output (e.g. netlist) that supports this feature, a hub is presented as an explicit object. On output where this feature is not available, the connected networks have to be merged.

{des2:64} A hub can be regarded as a component with as many ports as many networks are connected to it. It represents a physical galvanic connection among all networks connected.

{des2:65} A hub can be regarded as a component with as many bus-ports as many bus-nets are connected to it. It represents a physical galvanic connection among all bus channels with matching name, considering the chan rewrite attribute of the hub.

{des2:66} If a hub has at least one bus connection, it will do all bindings based on chan matching, considering the chan rewrite attribute of the hub. This applies to all channels of all buses connected and to the chan attribute of all networks connected. If a network connected to such a bus does not have a chan attribute even after the chan rewrite, it is left unconnected.

{des2:67} core attributes of a hub
attribute value description
uuid unique ID cschem-generated UID
name unique name user-specified unique hub name (similar to a component's name)
source list of refs reference list to the concrete objects that contributed to this component; when saved: each item is an UID or an UID:key pair
chan_rewrite rewrite list see at chan rewrite

2.5.5. connecting networks and ports

{des2:52} connectivity matrix
  wire-net port hub bus-net bus-port
wire-net direct direct direct 1chan 1chan
port direct direct invalid 1chan 1chan
hub direct invalid invalid match invalid
bus-net 1chan 1chan match match match
bus-port 1chan 1chan invalid match match
connection types
direct 1:1 connection ("knob", "node")
1chan single port or network connected to one of the channels by the chan attribute, if the chan is found in the bus-net or bus-port
match channel list matching; matching channels are connected, considering the chan rewrite attribute of the hub or port or bus-port.
invalid connection can not be made

2.5.6. chan rewrite

{des2:78} The purpose of chan[nel] rewrite is to provide a mechanism that hubs and ports can control how they connect bus channels. The normal mechanism is full name match: e.g. if two buses are connected, the channels with matching names are connected. This happens if the chan rewrite list of the connection point is empty - in the simple, default case.

{des2:79} To allow pseudo-bus-hierarchy, the chan_rewrite attribute can rename chan attributes for the connection lookup. The rewrite affects only the code that performs the chan name matching, it has no effect outside of that domain.

{des2:80} The chan_rewrite attribute is an unordered list of rules. A rule is a name::pattern::subs triplet. Any incoming connection (networks or buses) are searched. If their name attribute matches the name field in the rule, the rule is executed: the regex [TODO: link to appendix for the syntax] pattern is matched against the chan attribute of the network or bus, and the matching portion is substituted with the subs string of the rule.

2.6. glossary

{des2:70} glossary
term context meaning
abstract model project-view an in-memory model of the circuit as rendered by the plugins from the concrete objects; has no graphical representation; not edited by the user
attribute any a textual key=value pair attached to any object in cschem
bus abstract a construct that allows multiple channels (local nets) bundled
bus-channel abstract == channel (in the context of buses: shorthand for "a channel of a bus")
bus-net concrete graphical representation of multiple bus-segments connected (may have junctions)
bus-segment (drawing primitives) graphical representation of a segment of a bus (drawn using drawing primitives)
bus-port abstract a component port where a bus can be connected; behaves like a group of ports
bus-terminal concrete a terminal ("pin") of a symbol that accepts bus connection; allows multiple channels as if it was a bunch of bundled terminals
channel abstract a named "wire" of a bus or bus-port
channel-port abstract each channel of a bus-port behaves similar to a port; these are called channel-ports
component abstract an atomic device
concrete model project the data model edited by the user; used as a source for the abstract model
hub abstract an object that connects multiple networks without making them one network; can be used to split a (former) network into two (new) separate networks
hub-point concrete the graphical representation of a hub (drawing primitive)
junction concrete anonymous junction on a wire-net or bus-net, connecting two or more wire-segments or bus-segments
network abstract a named circuit network: a list of ports connected
port abstract a component's point-of-connect to a network (e.g. a pin or pad)
project-view top-level a specific view of a specific project
symbol concrete schematics symbol that represents (a part of) an element
terminal concrete a "pin" of a symbol that accepts a network connection
(universally/globally) unique ID
any globally unique identifier - a series of random-looking bytes
wire-net concrete graphical representation of multiple wire-segments connected (may have junctions)
wire-segment (drawing primitives) graphical representation of a segment of a wire (drawn using drawing primitives)