Debian Codegraph @

texmf-dist/doc/latex/tikz-sfc/tikz-sfc-doc.tex

raw
1 %% This is file `tikz-sfc-doc.tex'
2 %% Version: 1.0.1
3 %% Version date: 2018-15-12
4 %%
5 %% Copyright (C) 2018 by Luis Paulo Laus, [email protected]
6 %%
7 %% This package can be redistributed and/or modified under the terms
8 %% of the LaTeX Project Public License distributed from CTAN
9 %% archives in directory macros/latex/base/lppl.txt; either
10 %% version 1 of the License, or (at your option) any later version,
11 %% with `The Package' referring to the software `tikzlibrarycircuits.plc.sfc.code.tex'
12 %% and its accompanying documentation and `The Copyright Holder' referring to
13 %% the person Luis Paulo Laus.
14 %%
15 %%
16 %% IMPORTANT NOTICE:
17 %%
18 %% For error reports, comments or suggestions in case of UNCHANGED
19 %% versions send mail to:
20 %% [email protected]
21 %%
22 %%
23 \documentclass[a4paper]{ltxdoc}
24 \usepackage[hyphens]{url}
25 \usepackage[pdfborder={0 0 0}]{hyperref}
26 \usepackage[version=latest]{pgf}
27 \usepackage{calc,listings,tikz}
28 \usepackage{pdfpages}
29
30 \usepackage{hyperref}
31 \hypersetup{%
32 colorlinks=false, % use true to enable colors below:
33 linkcolor=blue,%red,
34 filecolor=blue,%magenta,
35 urlcolor=blue,%cyan,
36 citecolor=blue,
37 pdfborder=0 0 0,
38 }
39
40 % We need lots of libraries\ldots
41 \usetikzlibrary{backgrounds,circuits.logic.IEC}
42
43 \newif\ifgdccodebasic
44 \newif\ifgdccodeogdf
45
46 \usepackage[a4paper,left=2.25cm,right=2.25cm,top=2.5cm,bottom=2.5cm,nohead]{geometry}
47 \usepackage{amsmath,amssymb}
48 \usepackage{xxcolor}
49 \usepackage{pifont}
50 %% \usepackage{tgpagella} % no ligatures (test)
51 \usepackage{makeidx}
52 \usepackage{enumitem}
53 \usepackage[T1]{fontenc}
54 \usepackage[latin9]{inputenc}
55
56
57 \input{pgfmanual-en-macros} % Borrowed from TikZ/PGF
58
59 \makeindex
60
61 \makeatletter
62 \renewcommand*\l@section[2]{%
63 \ifnum \c@tocdepth >\z@
64 \addpenalty\@secpenalty
65 \addvspace{1.0em \@plus\p@}%
66 \setlength\@tempdima{2.5em}%
67 \begingroup
68 \parindent \z@ \rightskip \@pnumwidth
69 \parfillskip -\@pnumwidth
70 \leavevmode \bfseries
71 \advance\leftskip\@tempdima
72 \hskip -\leftskip
73 #1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par
74 \endgroup
75 \fi}
76 \renewcommand*\l@subsection{\@dottedtocline{2}{2.5em}{3.3em}}
77 \renewcommand*\l@subsubsection{\@dottedtocline{3}{5.8em}{4.2em}}
78 \def\@pnumwidth{2.2em}
79 \makeatother
80
81
82 % Global styles:
83 \tikzset{
84 every plot/.style={prefix=plots/pgf-},
85 shape example/.style={
86 color=black!30,
87 draw,
88 fill=yellow!30,
89 line width=.5cm,
90 inner xsep=2.5cm,
91 inner ysep=0.5cm}
92 }
93
94 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
95 %
96 % This file really starts here, all the above is for pgfmanual
97 % compatibility
98 % \usetikzlibrary{circuits.plc.sfc}
99 \input ../tex/tikzlibrarycircuits.plc.sfc.code
100 % \usetikzlibrary{circuits.plc.ladder} % used in examples
101 \input ../../tikz-ladder/tex/tikzlibrarycircuits.plc.ladder.code
102 \sloppy
103
104 \begin{document}
105
106 \title{Typesetting Sequential Function Chart (SFC) with \LaTeX{} and \tikzname{}}
107 \author{Luis Paulo Laus\\e-mail: \texttt{[email protected]}}
108 \date{Version: 1.0, Version date: 2018-01-16}
109
110 \maketitle
111
112 \section{Abstract}
113 Sequential Function Chart (SFC) describes the behaviour of a control program. It is derived from Petri Nets and GRAFCET. This package contains a set of symbols that simplifies the drawing of SFC diagrams with emphasis in readability and in agreement with the international standard IEC~61\,131-3. It extends the \tikzname-library |circuits| which defines general keys for creating circuits. All graphic elements of SFC are supported by |tikz-sfc|: steps (normal and initial), transitions, actions and actions qualifiers (with and without time duration) are supported. The placement of all actions associated with a step is done automatically. Comments can also be placed automatically in a suitable location near the element they refer to. The final appearance of each element can be fine-tuned individually or in group.
114
115 \section{Introduction\label{sec:introduction}}
116 IEC~61\,131-3 Sequential Function Chart (SFC) describes the behaviour of a control program. It is derived from Petri Nets and IEC~60\,848 GRAFCET, with the changes necessary to convert the representation from a documentation standard to a set of execution control elements.
117
118 The GRAFCET language, described by IEC~60\,848, has served as foundation of SFC
119 language of IEC standard 61\,131-3, but the syntax and the semantics defined by each of the two standards are nevertheless distinct because their scopes are different. GRAFCET is regarded as a \emph{specification language} and SFC as an \emph{implementation of the language for programming}. Many features of GRAFCET are not supported in SFC, but all GRAFCET functionalities can be implemented in SFC, although not directly. Particularly, assignation condition, time dependent assignation condition, delayed action, time limited action, stored actions, action on activation, action on deactivation, action at the clearing and action on event are all done, one way or another, in SFC using action qualifiers\footnote{This package typesets qualifiers in the agreement with the international standard IEC 61 131-3/2013. The lack of qualifier support in GRAFCET and in particular in the |grafcet| package is the main reason to have a different package for SFC.} (mainly). Consequently, the graphical representation of those features is fairly different. If you are interested in GRAFCET, refer to Robert Papanicola's |grafcet| package\footnote{The |grafcet| package uses a very different approach in the user interface. It is based in writing down a sequence of macro calls. The |tikz-sfc| uses the \tikzname-library |circuits| interface in which you place symbols along a path.}.
120
121 SFC structures the internal organization of a program, and helps to decompose a control problem into manageable parts, while maintaining the overview.
122
123 SFC consists of steps and transitions interconnected by directed links. Associated with each step is a set of actions, and with each transition is associated a transition condition. Each step represents a particular state of the systems being controlled. A transition is associated with a condition, which, when true, causes the step before the transition to be deactivated, and the next step to be activated. Steps are linked to actions, performing a certain control action. An action qualifier can be used in the association of a step with an action. Each element can be programmed in any of the standard languages defined in IEC~61\,131-3, including SFC itself.
124
125 Steps (normal and initial), transitions, actions and actions qualifiers (with and without time) are shown in the example below for a star-delta motor starter with dead time.
126
127 \begin{codeexample}[width=4.5cm]
128 \begin{tikzpicture}[circuit plc sfc,thick,x=2.6\tikzcircuitssizeunit,
129 y=1.3\tikzcircuitssizeunit,sfcaqw=8\tikzcircuitssizeunit]
130 \draw (0,0)
131 to [flow direction={pos=0.95}] ++(0,-1)
132 to [sfcstepi={info=O}] ++(0,-4)
133 node [sfctransition={info=b1 AND NOT b0}] {}
134 to [sfcstep={info=I,
135 sfcaction={info=K1,qualifier=N},
136 sfcaction={info=K2,qualifier=L,time=T\#3s},
137 sfcaction={info=K3,qualifier=D,time=T\#3s400ms}}] ++(0,-4)
138 node [sfctransition={info=b0}]{}
139 |- ++(-1,-1) |- (0,0);
140 \end{tikzpicture}
141 \end{codeexample}
142
143 \section{SFC Library}
144 \begin{pgflibrary}{circuits.plc.sfc}
145 This library provides graphics for Sequential Function Chart (SFC) related to programable controllers (PLC) and according to the international standard IEC-61\,131-3. The library was written to extend the standard \tikzname\-library |circuit|. The reader is urged to read the Section~``Circuit Libraries'' of \tikzname\ manual.
146 This library defines the following keys:
147
148 \begin{key}{/tikz/circuit plc sfc}
149 This key should be passed as an option to a picture or a scope that contains a SFC. It will do some internal setups.
150 \end{key}
151
152 \begin{key}{/tikz/sfcaqw=\meta{width} (initially 0\char`\\|tikzcircuitssizeunit|)}
153 This key sets the qualifier width. See Section~\ref{sec:actions} for details.
154 \end{key}
155
156 \begin{key}{/tikz/sfcanw=\meta{width} (initially 2.6\char`\\|tikzcircuitssizeunit|)}
157 This key sets the action name width. See Section~\ref{sec:actions} for details.
158 \end{key}
159
160 \begin{key}{/tikz/sfcah=\meta{height} (initially 2.6\char`\\|tikzcircuitssizeunit|)}
161 This key sets the action height. See Section~\ref{sec:actions} for details.
162 \end{key}
163
164 \begin{key}{/tikz/time=\meta{time}}
165 This key sets the action duration time to be used with qualifier D, L, DS, SD, LS. See Section~\ref{sec:actions} for details.
166 \end{key}
167
168 \begin{key}{/tikz/qualifier=\meta{qualifier}}
169 This key sets the action qualifier. See Section~\ref{sec:actions} for details.
170 \end{key}
171
172 \begin{stylekey}{/tikz/flow direction arrow}
173 The value of this key will be used for the arrow tip for |flow direction| as depicted in |direction ee| shape in \tikzname\ manual.
174 \end{stylekey}
175 \end{pgflibrary}
176
177
178 \section{Convention}
179 In this package, the main information about the language element is written with |info|=\meta{text} and comments with |info'|=\meta{comment}. The |tikz-sfc| package takes care of placing those texts in the appropriated position. For steps and actions, |info| places the \meta{text} inside the block that represents the element. For transitions, |info| places the \meta{text} at the right side of the transition symbol. Comments are placed at left side of steps and transitions and right side of actions. This behaviour can be override using the \meta{angle} option. For instance, if you want to place a comment at the right side of a step, you need to type something like \verb|info'={right:(* first step *)}|. See Section~``The Label Option'' in \tikzname\ manual for details.
180
181
182 \section{Steps}
183 A step represents a situation in which the behaviour of a program organization unit (POU) with respect to its inputs and outputs follows a set of rules defined by the associated actions of the step. A step is either active or inactive. At any given moment, the state of the program organization unit is defined by the set of active steps and the values of its internal and output variables.
184
185 A step shall be represented graphically by a block containing a step name in the form of an identifier. The directed link(s) into the step can be represented graphically by a vertical line attached to the top of the step. The directed link(s) out of the step can be represented by a vertical line attached to the bottom of the step.
186
187 The initial state of the program organization unit is represented by the initial values of its internal and output variables, and by its set of initial steps, i.e., the steps which are initially active. Each SFC network shall have exactly one initial step.
188
189 The graphical form with directed links of an initial step and a step (normal\footnote{A step which is not initial is just called ``step'', the ``normal'' is unappropriated, that is why is was written between parenthesis. This document is full of pedantic comments like this.}) are shown below:
190
191 \begin{center}
192 \begin{tikzpicture}[circuit plc sfc,thick,y=1.3\tikzcircuitssizeunit]
193 \draw (0,0)
194 to [sfcstepi={info=S0}] (0,-4);
195 \draw (2,0)
196 to [sfcstep={info=S1}] (2,-4);
197 \end{tikzpicture}
198 \end{center}
199
200 One or more actions (actually, action blocks) can be associated with a step. See Section~\ref{sec:actions} for details.
201
202 The initial size of all steps is $2.6\times2.6$|\tikzcircuitssizeunit|. This size and other features can be changed globally using the style |every sfcstepi/.style| for initial steps and |every sfcstep/.style| for steps. For example, to change the size of all steps to $1\times 1$|cm|, the line colour to red, fill them in light blue and change the distance\footnote{The default value is six times the inner separation which, by its time, is half the line width. Thus, just divide the desire among by six.} between the lines of the initial step to 1.8\,mm, you can place |every sfcstep/.style={red, fill=blue!20, minimum width=1cm, minimum height=1cm, inner sep=0.3mm},every sfcstepi/.style=every sfcstep| as an option to your \tikzname\ command. You can also use the command |\tikzset| to set it document wide.
203 \begin{codeexample}[]
204 \begin{tikzpicture}[circuit plc sfc,thick,y=1.3\tikzcircuitssizeunit,
205 every sfcstep/.style={red, fill=blue!20, minimum width=1cm,
206 minimum height=1cm, inner sep=0.3mm},
207 every sfcstepi/.style=every sfcstep]
208 \draw (0,0)
209 to [sfcstepi={info=S0}] (0,-4);
210 \draw (2,0)
211 to [sfcstep={info=S1}] (2,-4);
212 \end{tikzpicture}
213 \end{codeexample}
214
215 Every step need a step name and it is placed inside the block by the |info| key.
216 \begin{key}{/tikz/info=\opt{|[|\meta{options}|]|\meta{angle}|:|}\meta{text}}
217 This key has nearly the same effect as the |label| key, only the placement position is change to the block centre and following style is used additionally and automatically:
218 \begin{stylekey}{/tikz/every info}
219 Set this style to configure the styling of info labels. Since this
220 key is \emph{not} used with normal labels, it provides an easy way
221 of changing the way info labels look without changing other
222 labels.
223 \end{stylekey}
224 The \meta{options} and \meta{angle} are passed directly to the
225 |label| command.
226 \begin{codeexample}[width=3cm]
227 \begin{tikzpicture}[circuit plc sfc,thick,y=1.3\tikzcircuitssizeunit,
228 every info/.style=red]
229 \draw (0,0)
230 to [sfcstepi={info=S0}] (0,-4);
231 \draw (2,0)
232 to [sfcstep={info=S1}] ++(0,-4);
233 \end{tikzpicture}
234 \end{codeexample}
235
236 For a detailed discussion of the |label| option refer to the \tikzname\ manual.
237 \end{key}
238
239 \begin{key}{/tikz/info'=\opt{|[|\meta{options}|]|\meta{angle}|:|}\meta{text}}
240 This key is meant to place a comment at the \emph{left} side of the step\footnote{Note that, IEC~61\,131 does allow comments, but it is not clear where they are allowed.}. It has nearly the same effect as the |label| key, only the placement position is change and following style is used additionally and automatically:
241 \begin{stylekey}{/tikz/every info'}
242 Set this style to configure the styling of info' labels. Since this
243 key is \emph{not} used with normal labels, it provides an easy way
244 of changing the way info labels look without changing other
245 labels.
246 \end{stylekey}
247 The \meta{options} and \meta{angle} are passed directly to the |label| command.
248 \begin{codeexample}[width=3.2cm]
249 \begin{tikzpicture}[circuit plc sfc,thick,y=1.3\tikzcircuitssizeunit,
250 every info'/.style={red,font=\ttfamily,text width=2cm}]
251 \draw (0,0)
252 to [sfcstepi={info=S0,info'={(* initial step *)}}] (0,-4);
253 \draw (0,-5)
254 to [sfcstep={info=S1,info'={(* step or ``normal'' step *)}}] ++(0,-4);
255 \end{tikzpicture}
256 \end{codeexample}
257 For a detailed discussion of the |label| option refer to the \tikzname\ manual. % \ttfamily, \bfseries, \large, \scshape, \itshape, \fontfamily{ptm}
258 \end{key}
259
260
261 \section{Transitions}
262 A transition represents the condition whereby control passes from one or more steps preceding the transition to one or more successor steps along the corresponding directed link. The transition shall be represented by a horizontal line across the vertical directed link.
263
264 The direction of evolution following the directed links shall be from the bottom of the predecessor step(s) to the top of the successor step(s).
265
266 Each transition shall have an associated transition condition which is the result of the evaluation of a single Boolean expression. A transition condition which is always true shall be represented by the symbol 1 or the keyword TRUE.
267
268 A transition condition can be associated with a transition by one of the following means, as
269 shown in example bellow\footnote{Textual representation of transition is not covered herein. Connector, though possible, is not covered herein.}:
270 \begin{enumerate}
271 \item By placing the appropriate Boolean expression in the Structured Text (ST) language physically or logically adjacent to the vertical directed link.
272 \item By a ladder diagram network in the Ladder Diagram (LD) language physically or logically adjacent to the vertical directed link.
273 \item By a network in the Function Block Diagram (FBD) language, physically or logically adjacent to the vertical directed link.
274 \end{enumerate}
275
276 \begin{codeexample}[width=6cm]
277 \begin{tikzpicture}[circuit plc ladder, circuit logic IEC, circuit plc sfc, thick,
278 y=1.3\tikzcircuitssizeunit, x=2.6\tikzcircuitssizeunit,
279 sfcaqw=2.6\tikzcircuitssizeunit]
280 \draw (0,0) node[above,blue]{ST}
281 to [sfcstep={info=S1}] ++(0,-4)
282 to [sfctransition={name=t1,info=b1 AND b2}] ++(0,-2)
283 to [sfcstep={info=S2}] ++(0,-4);
284 \pgftransformyshift{-16\tikzcircuitssizeunit}
285 \draw (0,0) node[above,blue]{LD}
286 to [sfcstep={info=S1}] ++(0,-4)
287 to [sfctransition={name=t1}] ++(0,-2)
288 to [sfcstep={info=S2}] ++(0,-4);
289 \draw (t1)
290 to [contact NO={info'=b2}] ++(-2,0)
291 to [contact NO={info'=b1}] ++(-2,0) ++(0,2) -- +(0,-4);
292 \pgftransformyshift{-16\tikzcircuitssizeunit}
293 \draw (0,0) node[above,blue]{FBD}
294 to [sfcstep={info=S1}] ++(0,-4)
295 to [sfctransition={name=t1}] ++(0,-2)
296 to [sfcstep={info=S2}] ++(0,-4);
297 \node[and gate={name=a1}] at ($(t1)-(2,0)$) {};
298 \draw (a1.input 1) -- ++(-1,0) node[left]{b1}
299 (a1.input 2) -- ++(-1,0) node[left]{b2}
300 (a1.output) -- (t1);
301 \end{tikzpicture}
302 \end{codeexample}
303
304 For Ladder Diagram (LD) language typesetting refer to, for instance, package |tikz-ladder| and its documentation. For Function Block Diagram (FBD) language typesetting refer to \tikzname-library |circuits.logic.IEC| in the \tikzname\ manual. In this case, in order to conform \tikzname-library |circuits.logic.IEC| with IEC~61\,131-3 you need to place the following command in the document preamble:
305
306 \begin{codeexample}[code only]
307 \tikzset{every circuit symbol/.style={
308 logic gate inverted radius=0.8ex,
309 and gate IEC symbol = {$\char`\&$},
310 nand gate IEC symbol = {$\char`\&$},
311 or gate IEC symbol = {$>=1$},
312 nor gate IEC symbol = {$>=1$},
313 xor gate IEC symbol = {$=2k+1$},
314 xnor gate IEC symbol = {$=2k+1$},
315 not gate IEC symbol = {},
316 buffer gate IEC symbol = {}
317 }}
318 \end{codeexample}
319 \noindent{}or, if the textual Boolean function names are preferred:
320
321 \begin{codeexample}[code only]
322 \tikzset{every circuit symbol/.style={
323 logic gate inverted radius=0.8ex,
324 and gate IEC symbol = {AND},
325 nand gate IEC symbol = {AND},
326 or gate IEC symbol = {OR},
327 nor gate IEC symbol = {OR},
328 xor gate IEC symbol = {XOR},
329 xnor gate IEC symbol = {XOR},
330 not gate IEC symbol = {},
331 buffer gate IEC symbol = {NOT}
332 }}
333 \end{codeexample}
334 \noindent{}Note that, in this case, |buffer gate| is meant for |NOT| function (a block with the word ``NOT'' inside of it). The |not gate| produces an empty rectangle with a circle in the output to represent the negation.
335
336 Transitions are affected by the following keys:
337
338 \begin{stylekey}{/tikz/every sfctransition}
339 Set this style to configure the styling of transitions.
340 \begin{codeexample}[width=1.5cm]
341 \begin{tikzpicture}[circuit plc sfc,thick,y=1.3\tikzcircuitssizeunit,
342 every sfctransition/.style={red}]
343 \draw (0,0)
344 to [sfctransition={info=b1}] ++(0,-1);
345 \end{tikzpicture}
346 \end{codeexample}
347 \end{stylekey}
348
349 \begin{key}{/tikz/info=\opt{|[|\meta{options}|]|\meta{angle}|:|}\meta{text}}
350 This key is meant to place a Boolean expression in the Structured Text (ST) language at the \emph{right} side of the transition to depict the transition condition. It has nearly the same effect as the |label| key, only the placement position is change and following style is used additionally and automatically:
351 \begin{stylekey}{/tikz/every info}
352 Set this style to configure the styling of info labels. Since this
353 key is \emph{not} used with normal labels, it provides an easy way
354 of changing the way info labels look without changing other
355 labels.
356 \end{stylekey}
357 The \meta{options} and \meta{angle} are passed directly to the |label| command.
358 \begin{codeexample}[width=3.4cm]
359 \begin{tikzpicture}[circuit plc sfc,thick,y=1.3\tikzcircuitssizeunit,
360 every info/.style={red}]
361 \draw (0,0)
362 to [sfcstep={info=S1}] ++(0,-4)
363 to [sfctransition={info=b1 AND b2}] ++(0,-1)
364 to [sfcstep={info=S2}] ++(0,-4);
365 \end{tikzpicture}
366 \end{codeexample}
367 Note that this key affects all |info| keys, including those used in steps. For a detailed discussion of the |label| option refer to the \tikzname\ manual.
368 \end{key}
369
370 \begin{key}{/tikz/info'=\opt{|[|\meta{options}|]|\meta{angle}|:|}\meta{text}}
371 This key is meant to place a comment at the \emph{left} side of the transition\footnote{Note that, IEC~61\,131 does allow comments, but it is not clear where they are allowed.}. It has nearly the same effect as the |label| key, only the placement position is change and following style is used additionally and automatically:
372 \begin{stylekey}{/tikz/every info'}
373 Set this style to configure the styling of info' labels. Since this
374 key is \emph{not} used with normal labels, it provides an easy way
375 of changing the way info labels look without changing other
376 labels.
377 \end{stylekey}
378 The \meta{options} and \meta{angle} are passed directly to the |label| command.
379 \begin{codeexample}[width=5cm]
380 \begin{tikzpicture}[circuit plc sfc,thick,y=1.3\tikzcircuitssizeunit,
381 every info'/.style={red,font=\ttfamily}]
382 \draw (0,0)
383 to [sfcstep={info=S1, info'={(* S1 *)}}] ++(0,-4)
384 to [sfctransition={info=b1 AND b2, info'={(* t1 *)}}] ++(0,-1)
385 to [sfcstep={info=S2, info'={(* S2 *)}}] ++(0,-4);
386 \end{tikzpicture}
387 \end{codeexample}
388 Note that this key affects all |info'| keys, including those used in steps. For a detailed discussion of the |label| option refer to the \tikzname\ manual.
389 \end{key}
390
391
392
393 \section{Flow direction}
394
395 When necessary for clarity, an arrow can be used to indicate control flow. When this feature is used, the arrow shall be located in the middle of the line, or at least not at the line ends\footnote{IEC~61\,131-3/2013 demands that ``When this feature is used, the corresponding character shall be located between two ``-'' characters, that is, in the character sequence ``|-<-|'' or ``|->-|''\ldots'' indicating that the arrow shall not be in the end of a line.}.
396
397 \begin{codeexample}[]
398 \begin{tikzpicture}[circuit plc sfc,thick,circuit symbol unit=9pt,
399 x=1.2cm, y=1.3\tikzcircuitssizeunit]
400 \node[sfcstepi={info=S11},name=n0]{};
401 \draw (n0)
402 to [sfctransition={info=t21}] ++(0,-3) coordinate(n1)
403 to [sfcstep={info=S12}] ++(0,-4)
404 node [sfctransition={info=t22}]{}
405 to [sfcstep={info=S13}] ++(0,-4) coordinate(n2) -- ++(0,-1)
406 node [sfctransition={info=t23}]{}
407 to [sfcstep={info=S14}] ++(0,-4)
408 (n2) -| ++(1,-1)
409 node [sfctransition={info=t24}]{}
410 -- ++(0,-1) to [flow direction] +(1,0) |- ($(n1)+(2,0)$) to [flow direction] (n1);
411 \end{tikzpicture}
412 \end{codeexample}
413
414 There are two symbols for indicating flow directions:
415
416 |/tikz/flow direction|: \tikz[circuit plc sfc,baseline] \draw (0,0.6ex) to [flow direction] (1,0.6ex); and
417
418 |/tikz/flow direction'|: \tikz[circuit plc sfc,baseline] \draw (0,0.6ex) to [flow direction'] (1,0.6ex);
419
420 In other words, the apostrophe (|'|) reverts the arrow direction.
421
422 The |to| command is used to place the arrow between two coordinates and the position of the arrow can be fine-tuned with |pos| key. Do not use \verb|pos=1|, it makes impossible for the internal algorithm to establish the correct orientation.
423
424 If there is nothing beyond the next coordinates, |pos| behaves quit predictably:
425
426 \begin{codeexample}[width=1cm,pre={\begin{tikzpicture}[circuit plc sfc,thick,y=1.3\tikzcircuitssizeunit,>=stealth]},post={\draw[thin,|<->|] (0.3,0) -- (0.3,-1);\end{tikzpicture}}]
427 \draw (0,0) to [flow direction={pos=0}] (0,-1);
428 \end{codeexample}
429 \begin{codeexample}[width=1cm,pre={\begin{tikzpicture}[circuit plc sfc,thick,y=1.3\tikzcircuitssizeunit,>=stealth]},post={\draw[thin,|<->|] (0.3,0) -- (0.3,-1);\end{tikzpicture}}]
430 \draw (0,0) to [flow direction={pos=0.05}] (0,-1);
431 \end{codeexample}
432 \begin{codeexample}[width=1cm,pre={\begin{tikzpicture}[circuit plc sfc,thick,y=1.3\tikzcircuitssizeunit,>=stealth]},post={\draw[thin,|<->|] (0.3,0) -- (0.3,-1);\end{tikzpicture}}]
433 \draw (0,0) to [flow direction={pos=0.5}] (0,-1);
434 \end{codeexample}
435 \begin{codeexample}[width=1cm,pre={\begin{tikzpicture}[circuit plc sfc,thick,y=1.3\tikzcircuitssizeunit,>=stealth]},post={\draw[thin,|<->|] (0.3,0) -- (0.3,-1);\end{tikzpicture}}]
436 \draw (0,0) to [flow direction={pos=0.95}] (0,-1);
437 \end{codeexample}
438 \begin{codeexample}[width=1cm,pre={\begin{tikzpicture}[circuit plc sfc,thick,y=1.3\tikzcircuitssizeunit,red,>=stealth]},post={\draw[thin,|<->|] (0.3,0) -- (0.3,-1);\end{tikzpicture}}]
439 \draw (0,0) to [flow direction={pos=1}] (0,-1);
440 \end{codeexample}
441 \noindent{}where~ \tikz[y=1.3\tikzcircuitssizeunit,>=stealth]\draw[thin,black,|<->|] (0,0) -- (0,-1); ~is one unit of length long and serves to indicate where the \verb|\draw| command starts and ends. It points out that the \verb|pos| stablishes the arrow centre (not its tip as intuition might suggest).
442
443 Care should be taken when the next command is also a |to| because the next length will not be taken into account for the placement of the arrow. This can be misleading:
444
445 \begin{codeexample}[width=1cm,pre={\begin{tikzpicture}[circuit plc sfc,thick,y=1.3\tikzcircuitssizeunit,>=stealth]},post={\draw[thin,|<->|] (0.3,0) -- (0.3,-1);\end{tikzpicture}}]
446 \draw (0,0) to [flow direction={pos=0}] ++(0,-1) to [sfcstepi={info=S1}] ++(0,-4);
447 \end{codeexample}
448 \begin{codeexample}[width=1cm,pre={\begin{tikzpicture}[circuit plc sfc,thick,y=1.3\tikzcircuitssizeunit,>=stealth]},post={\draw[thin,|<->|] (0.3,0) -- (0.3,-1);\end{tikzpicture}}]
449 \draw (0,0) to [flow direction={pos=0.05}] ++(0,-1) to [sfcstepi={info=S1}] ++(0,-4);
450 \end{codeexample}
451 \begin{codeexample}[width=1cm,pre={\begin{tikzpicture}[circuit plc sfc,thick,y=1.3\tikzcircuitssizeunit,>=stealth]},post={\draw[thin,|<->|] (0.3,0) -- (0.3,-1);\end{tikzpicture}}]
452 \draw (0,0) to [flow direction={pos=0.5}] ++(0,-1) to [sfcstepi={info=S1}] ++(0,-4);
453 \end{codeexample}
454 \begin{codeexample}[width=1cm,pre={\begin{tikzpicture}[circuit plc sfc,thick,y=1.3\tikzcircuitssizeunit,>=stealth]},post={\draw[thin,|<->|] (0.3,0) -- (0.3,-1);\end{tikzpicture}}]
455 \draw (0,0) to [flow direction={pos=0.95}] ++(0,-1) to [sfcstepi={info=S1}] ++(0,-4);
456 \end{codeexample}
457 \begin{codeexample}[width=1cm,pre={\begin{tikzpicture}[circuit plc sfc,thick,y=1.3\tikzcircuitssizeunit,red,>=stealth]},post={\draw[thin,black,|<->|] (0.3,0) -- (0.3,-1);\end{tikzpicture}}]
458 \draw (0,0) to [flow direction={pos=1}] ++(0,-1) to [sfcstepi={info=S1}] ++(0,-4);
459 \end{codeexample}
460
461 Note that the distance considered by |pos| is not from |(0,0)| to top of the initial step block, but from |(0,0)| to |(0,-1)| which, in this case, is a point half the way from |(0,0)| to top of the step block. The arrow need to be placed near |(0,-1)|, but since \verb|pos=1| turns the arrow around, the solution is to use \verb|pos=0.95|.
462
463 \section{Divergence of sequence with left to right priority}
464 A selection between several sequences is represented by as many transition symbols, under the horizontal line, as there are different possible evolutions. The asterisk denotes left-to-right priority of transition evaluations. To place an asterisk, we use the symbol |sfcstar|:
465
466 \begin{codeexample}[]
467 \begin{tikzpicture}[circuit plc sfc,thick,x=2.6\tikzcircuitssizeunit,
468 y=1.3\tikzcircuitssizeunit]
469 \draw (0,0)
470 to [sfcstep={info=S1,pos=0.4},sfcstar={name=divORC,pos=0.8}] ++(0,-5)
471 node [sfctransition={info=t2}]{}
472 to [sfcstep={info=S3}] ++(0,-4)
473 (divORC) -- ++(-2.2,0) ++(0.2,0) -- ++(0,-1)
474 node [sfctransition={info=t1}]{}
475 to [sfcstep={info=S2}] ++(0,-4)
476 (divORC) -- ++(2.2,0) ++(-0.2,0) -- ++(0,-1)
477 node [sfctransition={info=t3}]{}
478 to [sfcstep={info=S4}] ++(0,-4);
479 \end{tikzpicture}
480 \end{codeexample}
481
482 The asterisk has to be placed with the special syntax |to| in order to interrupt the lines near it. Thus, the first |to| command places both the step~S1 and the asterisk. To leave enough room, the usual distance of four units of length were increased to five units of length. The step is placed two units of length bellow the line start ($5\cdot 0.4=2$) and de asterisk is place one unit of length above the transition ($5-5\cdot 0.8=1$). See Section~\ref{sec:guidance} for hints on how to set the unit of length to a sensible value.
483
484
485 \section{Actions\label{sec:actions}}
486 One or more actions (actually, action blocks) can be associated with a step. Each association is done by the annotation\footnote{The |sfcaction| style is not an annotation any longer, but it was initially written as an annotation and behaves like one. The main difference from a real annotation is that there is not |sfcaction'| to place a mirrored action.} |sfcaction|. The first action associated with the step will be placed at the right side of the step and a line will be drawn connecting the action and the step. The distance between the step and the action is controlled by |label distance|. The default distance is |2\tikzcircuitssizeunit|. Any further actions will be placed bellow the last action associated with the step. The action template is:
487 \begin{center}
488 \begin{tikzpicture}[circuit plc sfc,thick]
489 \node[sfcstep={gray,info={[gray]$s$},sfcaction={info={[name=ac]$a$},qualifier=$q$,time=$t$,sfcaqw=4\tikzcircuitssizeunit}}] {};
490 \draw[|<->|,thin] ($(ac.south west) - (6\tikzcircuitssizeunit-\pgflinewidth,5mm)$) -- node[above]{$d$} ($(ac.south west) - (4\tikzcircuitssizeunit-2\pgflinewidth,5mm)$);
491 \draw[|<->|,thin] ($(ac.south west) - (4\tikzcircuitssizeunit-\pgflinewidth,5mm)$) -- node[above]{$x$} ($(ac.south west) - (-2\pgflinewidth,5mm)$);
492 \draw[|<->|,thin] ($(ac.south west) - (-\pgflinewidth,5mm)$) -- node[above]{$w$} ($(ac.south east) - (\pgflinewidth,5mm)$);
493 \draw[|<->|,thin] ($(ac.south east) + (5mm,\pgflinewidth)$) -- node[above,rotate=90]{$2h$} ($(ac.north east) + (5mm,-\pgflinewidth)$);
494 \end{tikzpicture}
495 \end{center}
496 \noindent{}where:
497 \begin{description}[align=right,leftmargin=8mm,labelwidth=6mm,labelsep=2mm]
498 \item[$s$] is the associated step;
499 \item[$q$] is the action qualifier set by key |qualifier|. The style for all qualifiers can be set by \verb|every sfcqualifier/.style|. Accordingly to the standard IEC~61\,131-3, the valid qualifier are: (none), N, R, S, L, D, P, SD, DS, SL, P1 and P0. No test is performed, however, to reinforce this rule and it is the user responsibility to cope with the standard in this respect;
500 \item[$t$] is the duration time (to be used with qualifiers: L, D, SD, DS, and SL) and set by key |time|. Again, no test is performed and any qualifier can be associated with a time, even if it is not in accordance to the standard implying in a syntax error. The style for all duration times can be set by \verb|every sfctime/.style|. Remember that the symbol \# shall be preceded by a |\|, e.g., to obtain T\#3s type |T\#3s|;
501 \item[$a$] the action name set by key |info|. The style for all action names can be set by \verb|every sfcactionname/.style|;
502 \item[$d$] the horizontal distance between the step and the action(s) associated with the step. This can be set globally using something like \verb|every sfcaction/.style={label distance=1cm}| or individually placing a label distance specification on the desired |sfcaction| -- this potentially breaks multiple actions alignment on the same step;
503 \item[$x$] the qualifier width set, usually globally, by key |sfcaqw|;
504 \item[$w$] the action name width set, usually globally, by key |sfcanw|; and
505 \item[$h$] the single line action height set, usually globally, by key |sfcah|. Actions with time association have a height of $2h$ and this is done automatically.
506 \end{description}
507 Initially, the qualifier width, $x$ in the figure, |sfcaqw| is set to zero because either qualifiers are not used (defaulted to ``null qualifier'') or it needs to be set manually to match the biggest qualifier or qualifier duration. It is possible to set |sfcaqw| individually, but usually it is not desirable.
508
509 In the first example, for instance, the qualifier width |sfcaqw| is set to |8\tikzcircuitssizeunit| to leave room for the duration time of T\#3s400ms, then three actions were associated with step~|I|.
510
511 \begin{stylekey}{/tikz/every sfcaction}
512 Set this style to configure the styling of action blocks. The horizontal distance between the step and the actions is controlled by |label distance|, here is place to adjust it globally.
513 \end{stylekey}
514
515 \begin{stylekey}{/tikz/every sfcqualifier}
516 Set this style to configure the styling of action qualifiers.
517 \end{stylekey}
518
519 \begin{stylekey}{/tikz/every sfctime}
520 Set this style to configure the styling of action qualifier time durations.
521 \end{stylekey}
522
523 \begin{stylekey}{/tikz/every sfcactionname}
524 Set this style to configure the styling of action names.
525 \end{stylekey}
526
527 \begin{key}{/tikz/info=\opt{|[|\meta{options}|]|}\meta{text}}
528 This key is meant to place the action name inside the action block. The following style is used additionally and automatically:
529 \begin{stylekey}{/tikz/every info}
530 Set this style to configure the styling of info labels. Since this
531 key is \emph{not} used with normal labels, it provides an easy way
532 of changing the way info labels look without changing other
533 labels.
534 \end{stylekey}
535 Note that this key affects all |info| keys, including those used in steps and transitions.
536 \end{key}
537
538 \begin{key}{/tikz/info'=\opt{|[|\meta{options}|]|}\meta{text}}
539 This key is meant to place a comment at the \emph{right} side of the action\footnote{Note that, IEC~61\,131 does allow comments, but it is not clear where they are allowed.}. The following style is used additionally and automatically:
540 \begin{stylekey}{/tikz/every info'}
541 Set this style to configure the styling of info' labels. Since this
542 key is \emph{not} used with normal labels, it provides an easy way
543 of changing the way info labels look without changing other
544 labels.
545 \begin{codeexample}[width=7.3cm]
546 \begin{tikzpicture}[circuit plc sfc,thick,
547 x=2.6\tikzcircuitssizeunit,
548 y=1.3\tikzcircuitssizeunit,
549 sfcaqw=8\tikzcircuitssizeunit,
550 every info'/.style={blue,font=\ttfamily,
551 text width=2.2cm}]
552 \draw (0,0)
553 to [flow direction={pos=0.95}] ++(0,-1)
554 to [sfcstepi={info=O,info'=
555 {[text width=]right:(* K1{,} K2 and K3 are all OFF *)}}]
556 ++(0,-4)
557 node [sfctransition={info=b1 AND NOT b0}] {}
558 to [sfcstep={info=I,
559 sfcaction={info=K1,qualifier=N,
560 info'=(* main relay ON *)},
561 sfcaction={info=K2,qualifier=L,time=T\#3s,
562 info'={[red](* star for 3s *)}},
563 sfcaction={info=K3,qualifier=D,time=T\#3s400ms,
564 info'=(* delta{,} after 0.4s dead time *)}}
565 ] ++(0,-4)
566 node [sfctransition={info=b0}]{}
567 |- ++(-1,-1) |- (0,0);
568 \end{tikzpicture}
569 \end{codeexample}
570 \end{stylekey}
571 Note that this key affects all |info'| keys, including those used in steps and transitions. Also, observe that the commas in ``K1, K2 and\ldots'' and ``delta, after\ldots'' are surrounded by curly brackets. This is also necessary for colon (:) and equal sign (=). However, the colon in |[text width=]right:(* K1{,}|\ldots it is not meant to be printed, it is a \meta{angle} specification marker and such as it is not surrounded by curly brackets.
572 \end{key}
573
574
575 \section{Design Guidance\label{sec:guidance}}
576
577 This section brings some recommendations that reflect the way I produce SFC diagrams. It may or may not work for you. Feel free to e-mail me if you have better ideas.
578
579 The first thing to consider is that, as the manual says, ``\tikzname\ \emph{ist kein Zeichenprogramm}'' which translates to ``\tikzname\ \emph{is not a drawing program}''. You shall start with a draft of you chart and then codify it using \tikzname. Generally, a handmade pencil sketch will do. In this draft, you shall use node names for future reference.
580
581 The second thing to consider is that |tikz-sfc| uses the |\tikzcircuitssizeunit| to keep all figures proportional. Therefore, when you consider any dimension related to symbol size it is good idea to set that dimension in respect to |\tikzcircuitssizeunit|, i.e., using |\tikzcircuitssizeunit| as the unit of length. The default value of |\tikzcircuitssizeunit| is 7\,pt or approximately 2.46\,mm and it can be set by the |circuit symbol unit| key among several other keys.
582
583 Steps and transitions are placed along a vertical line. An even space between them are desired. The |to| command is used to interrupt the line and place the symbol between two coordinates. Since a transition is only and horizontal line crossing the vertical line, it does not matter if the vertical line is interrupted or not. Thus, it is possible to employ the command |node| to place a transition. In this way, the transition centre coordinates will be precisely known, but the centre coordinates of the step will be in the middle point of two known points. For a single sequence, it makes sense to place all transitions and then connect them with evenly spaced steps. This is rarely the case, however. Commonly, it is necessary to place an initial step in the begin of a line and dummy nodes (coordinate point) for loops.
584
585 Since steps are basically squares measuring $2.6\times 2.6$|\tikzcircuitssizeunit|, one possible solution is to set the vertical unit of length to half of this distance. Thus, if two transitions are place four units of length apart, it leaves one unit of length between each transition and the step between them. This is why you've been seen |y=1.3\tikzcircuitssizeunit| in the examples.
586
587 For instance:
588 \begin{codeexample}[width=2cm]
589 \begin{tikzpicture}[circuit plc sfc,thick,x=1cm,
590 y=1.3\tikzcircuitssizeunit]
591 \node[sfcstepi={info=S7},name=n0]{};
592 \draw (n0)
593 to [sfctransition={info=t5}] ++(0,-3) coordinate(n1)
594 to [sfcstep={info=S8}] ++(0,-4)
595 node [sfctransition={info=t6}]{}
596 to [sfcstep={info=S9}] ++(0,-4)
597 node [sfctransition={info=t7}]{}
598 -- +(0,-1) coordinate(n2) (n1) to [flow direction'] ++(-1,0) |- (n2);
599 \end{tikzpicture}
600 \end{codeexample}
601 \noindent{}the initial step S7 is drawn with command |\node| and named n0 for future reference. Note that |\node| requires an argument, in this case an empty text |{}|. Then, starting from n0 (the initial step name for drawing purposes) a descending vertical line is drawn. Three units of length below the centre of n0, n1 is placed. Between n0 and n1 the transition with receptivity t5 is placed. Here is the beauty of the placement algorithm: the distance between n0 centre and n1 is 3 units, but the distance between n0 border and n1 is only 2 unit (the height of n0 is 2 units, so 1 unit from the centre to the border); t5 is placed between the border (not the centre) of n0 and n1. This will certainly cause you troubles soon or later. Now, S8 is placed between n1 and an unnamed point 4 units below n1. At this point, t6 is place. All the same for S9 and t7. After placing t7, we move down one vertical unit and place n2 (for future reference). Then restarting at n1 we move left one horizontal unit of length and place an arrow pointing right (with |flow direction'|) between this location and n1. Finally, we move to n2, but not in a straight line, with the commando \verb!|- (n2)!.
602
603 There are, of course, other ways of drawing this chart. For instance, the last line could be replaced by \verb!|- +(-1,-1) -- ($(n1)+(-1,0)$) to [flow direction] (n1);!. Thus, after placing t7, we move down one vertical unit and left one horizontal unit (\verb!|- +(-1,-1)!); then move up to a point aligned with n1, one horizontal unit at its left computed by |($(n1)+(-1,0)$)|; then finally go to n1 placing an arrow on the path (|flow direction|). In both cases, we do not have to know the distance between t7 and n1, so additional steps and transitions can be inserted in the middle of the chart without the need to change the loop.
604
605 The distance between every feature, disregarding the line width, is one unit of length.
606
607 Suppose now that we need to associate actions with S8. The first one will be placed at S8 right side, but the second will be aligned with t6. Since t6 is a simple and, more important, small expression, it causes no harm.
608 \begin{codeexample}[width=3cm]
609 \begin{tikzpicture}[circuit plc sfc,thick,x=1cm,
610 y=1.3\tikzcircuitssizeunit]
611 \node[sfcstepi={info=S7},name=n0]{};
612 \draw (n0)
613 to [sfctransition={info=t5}] ++(0,-3) coordinate(n1)
614 to [sfcstep={info=S8,sfcaction={info=A},sfcaction={info=B}}] ++(0,-4)
615 node [sfctransition={info=t6}]{}
616 to [sfcstep={info=S9}] ++(0,-4)
617 node [sfctransition={info=t7}]{}
618 |- +(-1,-1) -- ($(n1)+(-1,0)$) to [flow direction] (n1);
619 \end{tikzpicture}
620 \end{codeexample}
621 \noindent{}but what if t6 were a long expression like, e.g., |b1 AND b2|? In this case, a filler is needed to create a dead space between S8 and the following transition.
622
623 \begin{codeexample}[width=3.5cm]
624 \begin{tikzpicture}[circuit plc sfc,thick,x=1cm,
625 y=1.3\tikzcircuitssizeunit]
626 \node[sfcstepi={info=S7},name=n0]{};
627 \draw (n0)
628 to [sfctransition={info=t5}] ++(0,-3) coordinate(n1)
629 to [sfcstep={info=S8,sfcaction={info=A},sfcaction={info=B}}] ++(0,-4) -- ++(0,-2)
630 node [sfctransition={info=b1 AND b2}]{}
631 to [sfcstep={info=S9}] ++(0,-4)
632 node [sfctransition={info=t7}]{}
633 |- +(-1,-1) -- ($(n1)+(-1,0)$) to [flow direction] (n1);
634 \end{tikzpicture}
635 \end{codeexample}
636
637 The filler |-- ++(0,-2)| is placed just after the second coordinate used to draw S8. The rule of thumb for fillers is to allow \emph{two} vertical units for every action exciding the first one, \emph{four} if the action involves duration (key |time| is used). If the first action also involves duration, add \emph{two} vertical units.
638
639
640 \subsection{Divergence and convergence}
641
642 Divergence and convergence can be exclusive (single line) or simultaneous (double line). They both can be done using the |\coordinate| command to place points during the construction of the path, then using those points to draw the divergence and convergence lines. In the following example, the second |\draw| command extends every horizontal line by half unit of length in both directions.
643
644 \begin{codeexample}[width=5.5cm]
645 \begin{tikzpicture}[circuit plc sfc,thick,
646 x=1.3\tikzcircuitssizeunit,
647 y=1.3\tikzcircuitssizeunit]
648 \draw (0,0)
649 to [flow direction={pos=0.95}] ++(0,-1)
650 to [sfcstepi={info=S1}] ++(0,-4)
651 node[sfctransition={info=t1}]{} -- ++(0,-1)
652 ++(4,0) coordinate(N2) ++(-8,0) coordinate(N1)
653 to [sfcstep={info=S2}] ++(0,-4)
654 node[sfctransition={info=t2}]{} -- ++(0,-1)
655 ++(2,0) coordinate(N4) ++(-4,0) coordinate(N3)
656 to [sfcstep={info=S4}] ++(0,-4) -- ++(0,-2) coordinate(N7)
657 (N4) to [sfcstep={info=S5}] ++(0,-4) -- ++(4,-1)
658 -- ++(0,-1) coordinate(N9)
659 ++(-6,0) -- ++(0,-1) node[sfctransition={info=t4}]{}
660 to [sfcstep={info=S8}] ++(0,-4) coordinate(N11)
661 (N2) to [sfcstep={info=S3}] ++(0,-4)
662 node[sfctransition={info=t3}]{} -- ++(0,-1)
663 ++(2,0) coordinate(N6) ++(-4,0) coordinate(N5)
664 to [sfcstep={info=S6}] ++(0,-4)
665 --++(-4,-1) --++(0,-1) coordinate(N8)
666 (N6) to [sfcstep={info=S7}] ++(0,-4) -- ++(0,-2) coordinate(N10)
667 ++(-2,0) -- ++(0,-1) node[sfctransition={info=t5}]{}
668 to [sfcstep={info=S9}] ++(0,-4) coordinate(N12)
669 ++(-4,0) to[sfctransition={info=t6}] ++(0,-2)
670 -- ++(-8,0) |- (0,0);
671 \draw[double=graphicbackground]
672 (N1) ++(-0.5,0) -- (N2) -- ++(0.5,0)
673 (N3) ++(-0.5,0) -- (N4) -- ++(0.5,0)
674 (N5) ++(-0.5,0) -- (N6) -- ++(0.5,0)
675 (N7) ++(-0.5,0) -- (N8) -- ++(0.5,0)
676 (N9) ++(-0.5,0) -- (N10) -- ++(0.5,0)
677 (N11) ++(-0.5,0) -- (N12) -- ++(0.5,0);
678 \foreach \x in {1,...,12}
679 \node[label={[label distance=-4pt,above right, red,font=\tiny]N\x},
680 circle,inner sep=1pt,draw=red,thin] at (N\x) {};
681 \end{tikzpicture}
682 \end{codeexample}
683 \noindent{}The |\foreach| command is used to print small circles marking the nodes with node names in tiny red letters and those are not part of the chart, yet they do nicely for debug purposes. By the way, |graphicbackground| is the background colour of the examples in the document.
684
685 \subsection{Beamer presentation with overlay}
686
687 Perhaps the most important feature of \beamer\ is its capacity of creating a series of slides based in one slide for, e.g., showing one concept step by step. It is called overlay. Unfortunately, \beamer\ overlay and \tikzname\ present some compatibilities issues when overlay macros are typed in the options list of a \tikzname\ command. This can be solved setting two \tikzname\ keys that takes advantage of the fact that |\pgfkeysalso| doesn't change the path.
688
689 \begin{codeexample}[code only]
690 \tikzset{ % alt and visible (overlay)
691 alt/.code args={<#1>#2#3}{%
692 \alt<#1>{\pgfkeysalso{#2}}{\pgfkeysalso{#3}}
693 },
694 visible/.code args={<#1>#2}{%
695 \alt<#1>{\pgfkeysalso{#2}}{}
696 }
697 }
698 \end{codeexample}
699
700 Once these keys are in place, they can be used instead of |\visible| and |\alt| with a syntax slightly different. The following example creates two slides, one with S1 active and the other with S2 active (activations are shown by filling the steps in light blue). Bellow, the result is shown side by side:
701
702 \begin{codeexample}[width=5.6cm,render instead={\begin{tikzpicture}[circuit plc sfc,thick,x=2.6\tikzcircuitssizeunit,
703 y=1.3\tikzcircuitssizeunit]
704 \draw
705 (0,0) to [flow direction={pos=0.95}] ++(0,-1)
706 to [sfcstepi={info=S1,fill=blue!20}] ++(0,-4)
707 node [sfctransition={info=b1}]{}
708 to [sfcstep={info=S2,sfcaction={info=A}}]
709 ++(0,-4)
710 node [sfctransition={info=b0}]{}
711 -- ++(0,-1) node[red,font=\small\itshape,below=4mm]{slide 1} -- ++(-1,0) |- (0,0);
712 \draw
713 (5,0) to [flow direction={pos=0.95}] ++(0,-1)
714 to [sfcstepi={info=S1}] ++(0,-4)
715 node [sfctransition={info=b1}]{}
716 to [sfcstep={info=S2,sfcaction={info=A},fill=blue!20}]
717 ++(0,-4)
718 node [sfctransition={info=b0}]{}
719 -- ++(0,-1) node[red,font=\small\itshape,below=4mm]{slide 2} -- ++(-1,0) |- (5,0);
720 \end{tikzpicture}}]
721 \begin{tikzpicture}[circuit plc sfc,thick,
722 x=2.6\tikzcircuitssizeunit,
723 y=1.3\tikzcircuitssizeunit]
724 \draw
725 (0,0) to [flow direction={pos=0.95}] ++(0,-1)
726 to [sfcstepi={info=S1,
727 visible={<1>{fill=blue!20}}}] ++(0,-4)
728 node [sfctransition={info=b1}]{}
729 to [sfcstep={info=S2,sfcaction={info=A},
730 visible={<2>{fill=blue!20}}}] ++(0,-4)
731 node [sfctransition={info=b0}]{}
732 |- ++(-1,-1) |- (0,0);
733 \end{tikzpicture}
734 \end{codeexample}
735 Thus, you can explain that, initially, S1 is active, pressing the push button b1 the transition fires deactivating S1 and activating S2 that turns on motor A. The S1 light blue background is visible in slide~1, but it is not in slide~2; conversely, S2 background is visible only on slide~2. One cool trick is that you can press push button b0 returning to slide~1.
736
737
738 \subsection{Adjusting the diagram size}
739 The diagram size can be adjusted in two ways: fully or just the distance between the elements.
740
741 Typing the key \verb|circuit symbol unit=|\meta{dimension} in \tikzname\ options before setting anything using |\tikzcircuitssizeunit| will adjust everything but the font size and line width.
742
743 To adjust the horizontal distance between the symbols, set the $x$ unit of length with \verb|x=|\meta{dimension}. For vertical distances use \verb|y=|\meta{dimension}. The default procedure adopted in this document is to set \verb|y=1.3\tikzcircuitssizeunit| in order to get a nice vertical distance between the elements. Usually, only the fillers will need to be rethought after a change in |y| and it can be done multiply the old filler distance by the ratio between the old and new values of |y|.
744
745
746 \section{Known Issues}
747 The user interface is a bit inconsistent: texts are treated differently depending on where they should appear. Normally, |info| and |info'| keys are used to place text on the chart, but sometimes actions need one or two extra text (qualifier and time duration) and it is done by other keys, namely, |qualifier| and |time|. The problem is that these keys do not accept optional arguments like |info| and |info'|. It is possible to modify those keys to deal with optional arguments, but there is price to pay.
748
749 The keys |info| and |info'|, largely employ to place text, actually uses the |label| interface. This is great because you can pass an optional list of configurations. The trade-off is that you have to be careful when writing the text, particularly you need to surround the commas, colons\footnote{If you literally mean ``:'' and not a \meta{angle} specification.} and equal signs in curly brackets. This is due to |\pgfkeys|.
750
751 If you want the report a bug or have any suggestion, please feel free to send me an e-mail. Contact details are in the first page. Every feedback is important.
752
753
754 \section{Final Remarks}
755
756 This package has been tested and used for more than three years, so I do believe it is mature by now and I decided to share it. On the other hand, I was the only person who used it, therefore idiosyncrasies were not detected.
757
758 Any comments, suggestions, and feedbacks are welcomed. I will do my best to answer as soon as possible. My contact e-mail is in the first page.
759
760 It should be great if someone with experience in writing \tikzname\ libraries could have a look in the code and point out error or improvements to be made.
761
762
763 \appendix
764 \newgeometry{left=1cm,right=1cm,top=1.5cm,bottom=1.5cm,nohead}
765 \section*{Appendix A -- Beamer example of delta-star motor starter with dead time in SFC}
766
767 In this example, the animation is done in two layers: the chart is drawn on foreground with step, transitions, actions and animation (filling and colouring); on the background, circles (actually, ellipses since |x| and |y| scales are different) are drawn in light red to highlight the activated transition. In order to place the ellipses in the precise position, every transition is named.
768
769 At first, only the SFC is drawn and the example of Section~\ref{sec:introduction} is used as starting point. Since the fonts used in the beamer presentation are different in size, it is necessary the adjust the chart size. In this particular, |sfcaqw| was increased to |9\tikzcircuitssizeunit|. When the chart is done, the animation part is made adding the |visible| key in the foreground and the |\visible| macro in the background.
770
771 Macro |\overlaynumber|, placed in the |frame| title, is used in the development phase to show the slide number in a sequence (animation). It helps the development of animated slides because you can see the slide number to be used with |visible| and |alt| keys or |\visible| and |\alt| macros.
772
773 After the \LaTeX\ code, the slides were included for reference. They shall be found as a separated PDF file in the same folder you have found this document.
774
775 \lstinputlisting[language={[LaTeX]TeX},basicstyle={\small},breakautoindent=true]{BeamerAnimation.tex}
776 \clearpage
777 \eject \pdfpagewidth=128mm \pdfpageheight=96mm
778 \includepdf[pages=-,offset=-116 285,noautoscale]{BeamerAnimation.pdf}
779
780 \end{document}