Schematic Editor


1 Introduction
2 Placing Elements
    2.1 Placing Symbols
    2.2 Placing New Wires
    2.3 Placing Comment Text
    2.4 Placing Frames
3 Selecting Elements
4 Moving Elements
5 Configuring Elements
    5.1 Editing Symbol Properties
        5.1.1 Good Practice
        5.1.2 Default Values of EPICS Record Properties
        5.1.3 EPICS Record Aliases and Information Items
        5.1.4 Assignable Symbol Ports
        5.1.5 Link Field Properties
    5.2 Editing Wires - Moving Wire Points
    5.3 Editing Comment Text
    5.4 Editing Frames
6 Finding Symbols in a Schematic
7 Changing an EPICS Record Type
8 Instance Ports (dbd mode only)
9 Instance Properties
    9.1 Adding/Removing Instance Properties
    9.2 Adding/Removing Record Aliases
    9.3 Adding/Removing Record Information Items
10 PP and MS Properties on Input and Output Links

1. Introduction to Schematic Editing

The Schematic Editor is an integral part of the tdct application. It allows placing and configuring of the following elements:

New schematics are created by selecting from the main menu:  File >> New schematic.
Existing schematics are opened from the main menu: File >> Open Schematic.
Recently modified schematics are opened from the main menu: File >> Open Recent.

The Schematics Editor and the Symbol Editor can work on different tabs in the same session.





2. Placing Elements

2.1 Placing Symbols

Symbols are placed on a schematic from the Symbol menu. There are several options:

Menu command keyboard shortcut tdct action
Symbol >> Add by name N or n will prompt for  a symbol name
Symbol >> User Symbol P or p will start a file open dialog for interactively selecting a symbol
Symbol >> Hierarchical connectors none will open a secondary menu for selection of hierarchy connectors
Symbol >> Epics Primitives none will open a secondary menu (*)

Notes:
(*) By default, the secondary menu collects all EPICS record symbols from the directories specified with the [epicslib] directive in the tdct configuration file. Alternatively the content of the secondary menu(s) can be configured in the tdct configuration file.


2.2 Placing New Wires

For placing a normal wire, select from the main menu  Symbol >> New wire or use the short-cut key  w.
For placing a bus, select from the main menu  Symbol >> New bus or use the short-cut key  b.
For placing a bus wire, select from the main menu  Symbol >> New bus wire  or use the short-cut key u.

Note:
- tdct allows only horizontal and vertical wire-segments, i.e. each wire corner forms a 90o angle.
- tdct enforces that wires connect to symbol ports with a horizontal connection.

 There are two ways of drawing a wire:

a) Click-and-Move

Left-click where you want the first wire segment to start and move the mouse to the point where you want the first wire segment to end. Left-click to start the next wire segment, etc.
Finish the last wire segment by right-clicking at the point where you want the last wire segment to end.

b) Press-and-Drag
Left-press where you want the first wire segement to start and drag the mouse to the point where you want the first wire segment to end. Release the left button and left-press to start the next wire segment, etc.
Finish the last wire segment byright-clicking at the point where you want the last wire segment to end.

Connecting Wires to Symbol Ports

When you drag a new wire segment and the mouse position is close to a symbol port, the mouse cursor changes shape to a pointing hand. If you place a point at this position, the wire is connected to the symbol port.

Connecting Wires to Wires

When you drag a new wire segment and the mouse position is close to a segment of a different wire, the mouse cursor changes shape to a pointing hand. If you place a point at this position, the wire will be connected with a junction to the other wire..

Auto-Routing

When you place the first wire point on a symbol port and the second wire point on another symbol port, tdct auto-routes a wire between the two ports. Tdct attempts to avoid all areas occupied by symbols. It also attempts not to create overlapping wire segments. The auto-routing feature can be disabled from the Options >> Modify Configuration menu.

Buses and Bus Wires

Buses and bus wires are supported for compatibility with Capfast™. I believe anyone who wants to use buses would be familiar with their functionality in Capfast.
As a quick recap:
A bus contains a "range" of wires. Individual wires (bus-wires) can be "tapped" in or out of the bus at an arbitrary location of the bus.
The developer gives the bus an id of the form <bus name>[<range>], i.e BUS1[0-9].
Bus-wires have the form <bus name>[<wire number>], i.e. BUS2[7].
Each wire has an index which must fall into the bus rage. All bus-wires with the same wire-index are considered as one logical wire-network by tdct.

Buses are a convenient way of passing a group of PVs from one hierarchy level to another or between symbols at the same level of hierarchy.
Buses can only connect to hierarchy connectors and symbol ports with a range greater 1.
Bus-wires can only connect to hierarchy connectors and symbol ports with a range of 1.
(Note that hierarchy connectors and bus ports have  the range 1 if there is no range specification -.
If there is a range mis-match, i.e. if  the range changes between a bus and a hierarchy connector or between a bus and a symbol port, tdct will issue a warning and ask for confirmation. When building an EPICS database, these mis-matches are ignored.

Bus-tap symbols, which are required for compatiblility with Capfast are handled automatically by tdct:


The bus implementation in tdct is in some aspects more restricted than in Capfast (e.g. bus range definition)

Some final remarks:

The bus support in tdct was new and not well tested before release 2.15, because we don't use buses here at TRIUMF.
Thanks to Al Honey form Keck for helping with the testing and debugging of the bus features.

2.3 Placing Comment Text

Compatible with Capfasttdct supports three types of comments, which are ignored during database building:

2.3.1 String Comments

String Comments consist of one line of text. Rotation information in a schematic is ignored by tdct.

To place a String Comment, select from the main menu  Symbol >> Comment text or use the short-cut key T.

A text dialog will prompt you for the comment text and the text size. Text size is specified as a percentage of the default font size.
When you accept, the text will be placed as a selected item in the top left corner of the canvas. Drag it to the desired location.

2.3.2 Note-Boxes

Note-Boxes consist of text displayed in a rectangular box.

To place a Note-Box, select from the main menu  Symbol >>Note-box or use the short-cut key X.

Draw a rectangle to define the width and top of the Note-box. After releasing the mouse a text dialog will prompt you for the comment text and the text size.
Text size is specified as a percentage of the default font size. You can select to fit the text to the box or to maintain original line-breaks.

When you accept, the text will be placed in a box at the desired location. If you selected to fit the text to the box, the text may overflow the drawn rectangle to the bottom.

You may select the Note-Box and drag it to a different location.

Note-Boxes can be resized. Select, right-click and press the "Resize" button on the dialog. Then drag a new rectangle.

2.3.2 Comment Frames

Comment Frames consist of a rectangular box with an optional label. 

To place a Comment Frame, select from the main menu  Symbol >>Comment Frame or use the short-cut key F
Draw a rectangle to define the Comment Frame. After releasing the mouse a text dialog will prompt you for the label text, label  text size and label alignment.
Text size is specified as a percentage of the default font size.
 
Note that Comment Frames are selected (like any other frame) via the main menu Frame >> Select. If there is more than one Frame or Comment Frame in the schematics select by left-clicking inside the frame.
You may drag a selected Comment frame to a different location.

Comment Frames can be resized. Select, right-click and press the "Resize" button on the dialog. Then drag a new rectangle.


2.4 Placing Frames

Select from the main menu Frame >> Add.

Note that Frames are selected  via the main menu Frame >> Select. If there is more than one Frame or Comment Frame in the schematics select by left-clicking inside the frame.
You may drag a selected  Frame to a different location.






3 Selecting Elements

Any element is selected by left-clicking within its bounding box. Once selected, the element's colour changes to the "select colour" (default red). If you are not sure where the bounding box is, use the menu Help >> Show bounding box.

You can add to the selection by CTRL-left-clicking on additional elements.

Alternatively, you can select one or more elements by drawing a "Selection Rectangle". There are two ways of doing this:
  1. Hold down the CTRL key, left-press to define one corner of the rectangle, then left-drag the mouse and left-release to define the opposite corner of the rectangle.
  2. left-middle-press and drag.

Exception:  Frames and Comment Frames are selected from the main menu  Frame >> Select. If there is more than one frame on a schematic select the desired one after choosing the menu option.







4 Moving Elements

Select an element. Then left-drag to the new position.

Note: When you are moving a wire, connections at the end points are not maintained.







5 Configuring Elements


5.1 Editing Symbol Instance Properties

After selecting a symbol instance on a schematic, right-click to display the property dialog.
For each property you can modify the property value, how the property is displayed and where the property is located on the schematic.

To modify a property value, use the "Edit" column. Depending on the property type, you can edit the property value with a text entry field or a combo-box. If you are editing via a text entry field and hit the ESC key, the original property value will be restored in the text field.

To modify how a property is displayed, use the combo box in the "Display" column. It lets you select "Nothing", "Value Only", or "All".

To modify where the property is located on the schematic, use the "Move" column. After clicking the "Move" button for a property, left-press on the schematic (which "catches" the property text) and drag to the desired location on the schematic canvas.

If the selected symbol instance represents an EPICS record, the property dialog will show buttons for adding / removing record aliases or record information nodes.
 

5.1.1 Good Practice


On a schematic, it is good practice to display all EPICS record properties which have been changed from their default values. In order to make this more convenient, tdct has the option to display an "Arrange Properties" dialog after the "Ok" or "Apply" button on the property dialog is pressed. (This dialog is only displayed if any property values were changed). This dialog allows moving the changed properties and controlling if they are displayed or not. For moving a property, left-click the "Move" button, then left-press on the schematic (which "catches" the property text) and drag to the desired location.

This tdct option is by default enabled, but can be disabled in the configuration file (option: display_changed_properties). It can also be enabled/disabled interactively for the current tdct session with Options >> Modify Configuration.

5.1.2 Default Values of EPICS Record Properties



In Capfast Compatibility mode:
In Dbd mode:

5.1.3 EPICS Record Aliases and Information Items

In addition to properties which define record fields, EPICS records may also contain properties which define aliases for the record name and information items (see EPICS Application Developers Guide about record information items and record name aloases). Both features are supported by tdct and are controlled by the configuration options record_aliases and record_info.

If an option is enabled, corresponding buttons will appear on the record property dialog.

If an option is disabled, but a schematic contains properties for this option, tdct allows the modification of these properties and saves them with the schematic. The record properties are, however, not written to the EPICS database.

5.1.4 Assignable Symbol Ports

Some EPICS record symbols have assignable ports, especially the large symbols. These ports have names such as FLD0, FLD1, ...
In the property dialog, they show up as   "username(U0)", "username(U1)", ....  and the names FLDx can be set to any record field which "makes sense".
In order to "make sense"
  1. the record field must be able to accept the data provided to the port via a wire
  2. the record field must be listed in edb.def for the record type (in Capfast compatibility mode).
For details about editing link field properties see the section about Link Fields in the Capfast Compatiblity section.

5.2 Editing Wires - Moving Wire Points

After selecting a wire, right-click to enter "wire-edit" mode. The corners of each wire segment will display a grab-square (default colour: green). If you move the mouse over a grab-square, the cursor will change to a pointing hand. Now you can drag the wire point to a new location. The cursor will change back to an arrow and the grap-square will show the select colour (default: red).

If you are dragging a wire end-point over a location where the wire could make a connection, i.e. a symbol port or another wire, the mouse cursor will change to a pointing hand.

Note: tdct does not allow multiple wires to connect to the same symbol port nor does it allow a wire end point to connect to a different wire's end point.


5.3 Editing Comment Text

After selecting a String Comment, a Note-Box or a Comment Frame,  right-click to display the property dialog.


5.4 Editing Frames

After selecting a comment text, right-click to display the property dialog.



6 Finding Symbols in a Schematic

Type CTRL-F and a select box will pop up, which lets you select the name of one of the symbols used in the schematic (Note: this is the symbol name, not the symbol instance name). Tdct will select the first symbol with this name. Use CTRL-F again to advance to the next symbol with this name. Use ESC to forget the symbol name.

7 Changing an EPICS Record Type

This function allows the modification the record type of an EPICS record instance in the schematic. It assumes you have a single EPICS record selected.

Select  Edit >> Change record type from the main menu and choose the desired record type from the pop-up.

tdct retains the record name and all record instance properties of the original record which  are available on the new record type. Wire connections are retained if the new record symbol contains a port at the same location at which the wire was connected to the original record symbol. A warning is issued if the record  type change results in unconnected wires.


8 Instance Ports (dbd mode only)

In dbd mode, "instance ports" can be added to an EPICS record. This allows wire connections to be attached to record properties, which are not part of the EPICS library symbol.
The following functions are available from the main menu:
Edit >> Reuse port
Edit >> Add instance port
Edit >> Reuse instance port
Edit >> Move instance port

When an instance port is added radiobuttons are used to select if the new port is input or output and if the port is added atop or abottom of the existing ports.

Once a port is placed it can be moved with the left/right arrow keys. Vertical port distances are fixed.

9 Instance Properties

9.1 Adding / Removing Instance Properties

After a symbol which is instantiated on a schematic, selecting and right-clicking the symbol pops up the the property sheet. It shows all properties which may be edited by the user.
For user symbols and for EPICS records in Capfastcompatibility mode, the list of  properties is defined by the symbol designer.
Tdct allows the addition of instance properties to a symbol, which allows fixing of symbol design shortcomings when modifying a symbol is not desired.

Example: the standard EPICS record symbol distribution obtained with Capfasthas no pproc(OUT) and no palrm(OUT) properties defined in the eaos.sym file. In order to make a wire-link form an ao record's OUT field to another record with the PP property, an instance property pproc(OUT) with value PP can be added to the record.

For EPICS records in dbd mode the editable properties are determined by the dbd files. The addition of instance properties does not make sense.

9.2 Adding/Removing Record Aliases

Alias names for EPICS records can be added / removed with buttons on the record property dialog.

9.3 Adding/Removing Record Information Items

Names and values for EPICS record information items can be added / removed with buttons on the record property dialog.

10 PP and MS Properties on Input and Output Links

EPICS record input and output links may specify "process passive" and "maximize severity" behaviour for the link (in the following called "ppms properties").

This behaviour is specified in the link field in the following format:
 <link field value> =  <pv name> [<pp property>] [<ms property>]
where the square brackets denote optional items as usual.

If only a PV <pv> is specified, the default behaviour is equivalent to <pv> NPP NMS. If the configuration option addnppnms is set to true, the PV name in the link field in the EPICS database will have " NPP NMS" appended. If the option is set to false, only the PV name will appear in the link field.

The <pv name> must be followed by at least one space before the other properties are entered.

Valid values for <pv property> are: NPP, PP, CA, CP, and  CPP.

Valid values for <ms property are: NMS and MS.

In tdct it is possible to define links for an EPICS record by assigning an explicit link field vallue or by connecting a wire to the link port.

Since release 2.12.5, non-default ppms properties are displayed on the wire-segment next to the link port.


Capfast™ compatibility mode

In Capfastcompatibility mode there exist the properties pproc(<link field>) and palrm(<link field>) for specifying <pp property> and<ms property> for the <link field>. The pproc and palrm properties work together with the configuration option pproc_wireonly:

If pproc_wireonly is true, tdct uses the pproc and palrm properties only for links which are specified with a wire, not for links which are specified by a link field value..

If pproc_wires_only is false, tdct uses pproc and palrm properties also for links which are specified by a link field value. If the link field values specifies a <pp property> , the pproc property is ignored. If the link field values specifies an <ms property> , the palrm property is ignored.

Since release 2.12.5, the ppms properties can also be specified by double-clicking on a wire segment next to a link port. The values selected will modify the EPICS record's pproc and palrm properties.


Dbd mode

Since release 2.12.5, the ppms properties must be specified by double-clicking on a wire segment next to a link port.


Hardware I/O

If a link field value is specified on a hwin or hwout symbol (which is connected by wire to the link field), ppms properties on the hardware I/O symbol override the ppms properties defined on the wire or the record's link field