Circuit Diagram Document

The Circuit Diagram Document format (cddx) is the native file format of Circuit Diagram.

Features

The Circuit Diagram Document format is designed for storing electronic circuit designs.

It stores the following information about a circuit:

  • Layout: where components and wires are placed, to allow rendering a circuit as an image.
  • Connections: how components are connected together to allow simulating a circuit (similar to a netlist).
  • Metadata: details such as the author and when the circuit was created.

The above sections are optional, meaning that CDDX files may not contain all of them. For example, a document might contain only layout information without the connection details required for simulating the circuit.

Structure

The CDDX format is a container file conforming to the Open Packaging Conventions.

This is a file structure consisting of a ZIP archive containing a number of individual files and manifest files. It is the same structure as used by Microsoft Word documents (.docx). You can read more about Open Packaging Conventions on microsoft.com.

Rename a .cddx file to .zip to look at the contents of the individual files inside the OPC archive.

CDDX files typically contain the following inside the OPC archive:

Circuit.cddx/
├── circuitdiagram/
│   └── Document.xml
├── docProps/
│   └── core.xml
├── _rels/
│   └── .rels
└── [Content_Types].xml

Document

This file stores the main content of the circuit, including layout and connection information. It is normally called Document.xml has the following properties:

  • Content type: application/vnd.circuitdiagram.document.main+xml
  • Relationship: http://schemas.circuit-diagram.org/circuitDiagramDocument/2012/relationships/circuitDiagramDocument

Due to the nature of the OPC format, this file is not guaranteed to be called Document.xml and should be found by following the relationship in the .rels file.

It is an XML file with the following structure:

<?xml version="1.0" encoding="utf-8"?>
<circuit version="1.4" xmlns="http://schemas.circuit-diagram.org/circuitDiagramDocument/2012/document">
	<properties>
		<width>640</width>
		<height>480</height>
	</properties>
	<definitions>
		<src col="http://schemas.circuit-diagram.org/circuitDiagramDocument/2012/components/common">
			<add id="0" item="resistor" />
			<add id="1" item="capacitor" />
		</src>
	</definitions>
	<elements>
		<c id="0" tp="{0}" x="320" y="120" o="h" sz="50" flp="false">
			<prs>
				<p k="style" v="IEC" />
				<p k="text" v="" />
				<p k="resistance" v="4700" />
				<p k="showResistance" v="True" />
				<p k="t" v="Standard" />
			</prs>
			<cns>
				<cn id="0" pt="b" />
				<cn id="1" pt="a" />
			</cns>
		</c>
		<w x="370" y="180" o="v" sz="130" />
        ...
	</elements>
</circuit>

Properties

This section defines the width and height of the circuit.

Definitions

The types of components used in the circuit are defined here. The src element references a collection and contains a number of add entries which define an id which will be used to refer to each component type in the elements section.

Elements

The following elements are permitted within this section: c, w.

The component element defines a component with the circuit. It has an id attribute which is unique within the document, and a tp attribute referring to one of the component types defined in the definitions section, enclosed in curly braces.

If the file contains layout information, the following attributes specify the positional information of the component:

  • x: the x coordinate where the component is placed
  • y: the y coordinate where the component is placed
  • o: orientation h (horizontal) or v (vertical)
  • sz: size of the component
  • flp: whether the component is flipped

Property values are defined in the prs tag. Each property has a key and a value. The permitted properties depend on the type of component.

If the document contains connection information, the cns tag defines how the component is connected.

  • id: the ID of this connection. Other cn tags in this file with the same ID are connected to this.
  • pt: the name of the connection point on this component. The permitted values for this depend on the type of the component.

The wire element is similar to the component element, but it only contains layout information. It should not be present in documents that have only been written with connection information.

Libraries reading this format should descend into unknown element types within the elements section. For example, if the library is not aware of the semantics of the some-element tag, the following should be treated as equivalent:

<elements>
    <some-element>
        <w x="370" y="180" o="v" sz="130" />
    </some-element>
</elements>

<elements>
    <w x="370" y="180" o="v" sz="130" />
</elements>

When writing this file, custom elements must not be added to the Circuit Diagram namespace defined in the xmlns attribute in the above example. If custom elements are required, they must be added with a custom XML namespace.

Metadata

The core properties file stores information such as the title and date the circuit was created. It is normally located at docProps/core.xml.

  • Content type: application/vnd.circuitdiagram.document.core-properties+xml
  • Relationship: http://schemas.circuit-diagram.org/circuitDiagramDocument/2012/relationships/metadata/core-properties
<?xml version="1.0" encoding="utf-8"?>
<coreProperties xmlns="http://schemas.circuit-diagram.org/circuitDiagramDocument/2012/metadata/core-properties">
	<title xmlns="http://purl.org/dc/terms/">My Circuit</title>
	<date xmlns="http://purl.org/dc/terms/">2020-01-01 00:00:01Z</date>
</coreProperties>

Usage

Applications

You can create and edit CDDX files using the following applications:

Circuit Diagram Web Editor

Design circuits and import to/from CDDX format in your web browser. The Web Editor also has basic support for simulating circuits (BETA).

→ Open Circuit Diagram Web Editor

Circuit Diagram CLI

This is a cross-platform (Windows, Mac, Linux) command-line application that can render CDDX files as PNG or SVG images.

→ Download Circuit Diagram CLI

Circuit Diagram Desktop

Design circuits in this desktop application for Windows.

→ Download Circuit Diagram Desktop

Libraries

.NET

The GPLv2-licensed CircuitDiagram.Document library is available on NuGet.