# Schematics

> Control hardware using schematics.

![](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/console/schematics/example-light.png)

A schematic diagrams your physical or simulated system. It displays live sensor data and lets you exercise manual control by writing to channels tied to actuators.

[Download the example schematic](https://github.com/synnaxlabs/synnax/blob/main/client/py/examples/control/tpc/schematic.json) to try it out yourself.

## Creating a schematic

Create a schematic with the `Create a schematic` command in the [command palette](https://docs.synnaxlabs.com/reference/console/ui-overview#search-and-command-palette), or by adding a new tab and selecting the schematic visualization.

> Make sure that you are working in an [**active project**](https://docs.synnaxlabs.com/reference/console/projects). A schematic created outside one is **not saved**.

[](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/console/schematics/create-dark.mp4#t=0.001)

## Modes

Schematics have three modes: **view**, **edit**, and **control**. To change modes, use the controls in the top-right corner of the schematic.

| Mode        | Description                                                                                                                  |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **View**    | Live data from the Core is displayed on the schematic. Symbols are not editable and the user cannot change the system state. |
| **Edit**    | Symbols can be added and moved, and their properties can be edited.                                                          |
| **Control** | The user can click on symbols such as valves and buttons to control them.                                                    |

### Control mode

In control mode, click an actionable symbol, such as a valve, switch, or button, to write to its command channel. The indicator next to the symbol displays the control status.

A blue circle indicates the current user has control.

A green circle indicates the current user has absolute control.

A red square indicates another user or process holds control.

The color of the bar and legend indicate what has control over the channel.

[](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/console/schematics/valve-dark.mp4#t=0.001)

## Configuring the schematic

Click the schematic button in the bottom-left corner to open the component toolbar and configure the schematic. Select a symbol to show its properties in the toolbar; the tabs fine-tune its look and behavior.

### Symbols library

Schematics are assembled by dragging symbols from the library onto the canvas. Symbols represent sensors, actuators, and other components of your hardware system. Synnax has a collection of built-in symbols including valves, live sensor values, buttons, and tanks.

### Style tab

The style tab edits the symbol’s label, size, orientation, color, and other visual properties.

| Property          | Description                                                                       |
| ----------------- | --------------------------------------------------------------------------------- |
| **Label**         | The text that appears by the symbol.                                              |
| **Label size**    | The size of the label.                                                            |
| **Color**         | The color of the symbol.                                                          |
| **Normally open** | Inverts the visual state of the valve.                                            |
| **Units**         | The units a value symbol displays.                                                |
| **Orientation**   | Determines the orientation of the symbol and the relative placement of the label. |

### Telemetry tab

The telemetry tab is available on symbols that receive data, such as the value, gauge, string display, light, switch, valve, and state indicator symbols. Select a channel to stream and display its live data.

| Property             | Description                                                                                                            |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Channel**          | The channel to stream data from.                                                                                       |
| **Precision**        | The number of decimal places to display.                                                                               |
| **Averaging window** | Display a rolling average for the channel. This does not change the underlying value written to the Synnax Core.       |
| **Stale timeout**    | The time in seconds without data from the channel before the symbol registers as stale.                                |
| **Stale color**      | The color the symbol changes to when its channel is stale. An unset color uses the warning color of the current theme. |

> A channel that writes on change can pass its stale timeout while it is healthy. Give such a channel a timeout longer than the longest gap you expect between changes. A symbol registers as stale only after data arrives and then stops.

[](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/console/schematics/value-dark.mp4#t=0.001)

### Control tab

The control tab is available on symbols that can be actuated.

| Property            | Description                                                                                                            |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **State channel**   | The display state of the symbol. The symbol displays as activated when the channel has a value of `1`.                 |
| **Command channel** | The channel commands are written to. Clicking a deactivated symbol writes`1`; clicking an activated symbol writes `0`. |

### Redline tab

The redline tab is available on value symbols. Use it to change the background color of the value when the value passes a threshold. Click `Add band`, then set the threshold and the color of the band.

Each band has a threshold and a color. A band paints the values at or above its threshold and below the next higher threshold. Values below every threshold show the background from the `Style` tab. By default, the background paints nothing.

* **Transition** -> `Steps` changes the color at each threshold. `Smooth` blends the colors between thresholds.
* **Flash** (lightning icon) -> Makes the band blink between its color and the background while the value is in the band.

## Styling the schematic

### Connection lines

Attachment points appear when you hover over a symbol. To draw a connection line, click an attachment point and drag to another symbol:

[](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/console/schematics/connections-dark.mp4#t=0.001)

### Selecting multiple elements

Hold (Windows) / (macOS) or and click a symbol or connection line to add it to the selection or remove it again. Dragging a box on the canvas selects everything inside it.

### Aligning elements

Select the elements to align, then use the vertical or horizontal alignment buttons:

[](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/console/schematics/align-items-dark.mp4#t=0.001)

### Editing several elements

Select several elements to edit their shared properties at once. The properties tab shows a group when any selected element has it, and a change applies only to the elements that have it. For example, select all and set a staleness color to change every element that shows staleness.

The colors group has Stroke, Fill, and Text controls. A control shows “Mixed” when the selected elements use different colors. The Selection control lists each color the selection uses. Change a swatch to recolor every element that uses that color.

[](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/console/schematics/edit-several-elements-dark.mp4#t=0.001)

## Snapshotting a schematic

Snapshot a schematic to a range to preserve exactly how it looked at that point in time. Right-click the schematic in the projects toolbar and snapshot it to a range.

[](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/console/schematics/snapshot-dark.mp4#t=0.001)

## Creating custom symbols

Create your own symbols with the built-in symbol editor. They can display data and actuate channels like the built-in symbols.

### Creating a symbol group

Create a new symbol group in the schematic symbols browser.

[](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/console/schematics/symbol-create-group-dark.mp4#t=0.001)

### Opening the editing dialog

Once you’ve created a group, open the create symbol dialog and import an SVG file.

[](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/console/schematics/symbol-import-svg-dark.mp4#t=0.001)

### Static symbols vs. actuators

Static symbols are used for background images and other non-interactive elements. They have a single color palette and are not connected to any telemetry sources.

Actuators are interactive elements that command outputs to `1` or `0`, like the built-in valves and switches. They have two states: `base`, shown when the connected channel is `0`, and `active`, shown when it is `1`.

### Choosing color palettes

Each actuator state has its own color palette.

![](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/console/schematics/symbol-color-regions-light.png)

Synnax identifies regions of the imported SVG by color. Click a region’s color swatch to change it.

To edit how an actuator looks when clicked, select the `active` tab under the states section and edit the region’s colors.

### Scaling the symbol

The imported SVG’s dimensions set the symbol’s default size on a schematic. Drag the slider or enter a value in the properties field to change the scale.

## Sharing and exporting

Select `Copy link` from the Projects or Component Toolbar. Anyone on the Core can open it from a browser.

Select `Export` to save the schematic as a JSON file. Drag the file back into the Console to import it.