Diagram notation

You never draw an SCChart by hand: you write the text, and KIELER lays out and draws the diagram for you. Each construct has its own look, and once you know the symbols you can read a chart’s behaviour off its diagram. Every diagram on this page is a real chart, drawn the way KIELER and SCCharts Lab draw it, except that dataflow regions are simplified; switch to Code to see the text behind it.

At a glance

You see	It means
thin outline	an ordinary state: state A
heavy outline	an initial state: initial state A
double outline	a final state: final state Done
heavy double outline	both: initial final state A
solid arrow	a delayed transition: if A go to B
dashed arrow	an immediate transition: immediate if A go to B
2: before a label	the priority: the second transition written
label on an arrow	trigger, then effects: if A do x = 1
a number first	a count delay: if 3 A
red dot at the start	a strong abort: abort to
green triangle	a termination: join to
H at the head	shallow history: go to S shallow history
H* at the head	deep history: go to S history
red dot at the head	deferred entry: go to S deferred
red dot with a star	deep deferred entry: go to S deep deferred
small filled dot	a connector state: connector state C
box with an inner area	a superstate: state S { … }
areas side by side	concurrent regions: region R { … }
a line in a state	an action of the state: entry do x = 0
violet box, S @ Chart	a reference to another chart: state S is Chart(…)
wires and operator boxes	a dataflow region: dataflow { … }
yellow note	a doc comment: /** … */

While a chart runs, the simulation adds a few marks (in a simulation):

You see	It means
red outline	an active state: where its region is after the tick
blue arrow	a delayed transition that fired in the tick
blue dashed arrow	an immediate transition that fired in the tick
blue outline	a state left in the tick, or entered and left again within it
outline with !	in a chart KIELER rejects: an element a message is about

The chart itself

The chart is the outermost box, with its name at the top. Below the name come its declarations, one line per declaration with the keywords in colour (input bool A, B), then its own actions, and then the region that holds its states. Every region has a small grey corner at its top left; in KIELER it collapses the region to save space (in this guide’s diagrams it is only drawn).

States

StatesChart

Open in the playground

Diagram

Code

scchart States {
  input bool next

  region Steps:
    initial state First
      if next go to Middle

    state Middle
      if next go to Last

    final state Last

  region Idle:
    initial final state Ready
}

In the region Steps, First is initial (heavy outline), Middle ordinary and Last final (double outline); Ready, in the region Idle, is initial and final at once.

• An ordinary state is a rounded box with its name, drawn with a thin outline.
• The initial state of a region, where the region starts, has a heavy outline. Each region has exactly one.
• A final state has a double outline. When every region of a superstate is in a final state, the superstate has finished; at the top level, the chart terminates.
• A state that is both (initial final state) has both: a double outline whose outer ring is heavy. Its region has finished as soon as it starts, so here the chart terminates as soon as Last is reached.

A state with a label (state Off "Light off") shows the label instead of its name; see labels.

Transitions

TransitionsChart

Open in the playground

Diagram

Code

scchart Transitions {
  input bool A, B
  output int x

  initial state Wait
    if A && B do x = 3 go to Both
    if A do x = 1 go to Fast
    if 2 B go to Wait

  state Fast
    immediate do x++ go to Both

  state Both
    go to Wait
}

Warning: KIELER warns about a potential instantaneous loop here, but compiles and runs the chart correctly

• Warning, line 5, column 17KIELER says: Instantaneous loop detected!KIELER's loop check works on the compiled chart, in which count delays are extra regions and transitions, and warns whenever control could go round a circle there within one tick, without checking whether the triggers prevent it: here the circle runs through Wait. The chart works as written.About this message

Three transitions leave Wait, numbered by priority; the one out of Fast is dashed because it is immediate.

A transition is an arrow from its source state to its target state. What it says is written on the arrow:

• Solid or dashed. A solid line is a delayed transition, the default: it cannot fire in the tick its source state is entered. A dashed line is an immediate transition, which can.
• Priority. When a state has more than one outgoing transition, each label starts with its priority, 1:, 2: and so on, in the order the transitions are written. In any tick the enabled transition with the lowest number wins. A state with a single outgoing transition shows no number.
• Trigger and effects. The trigger comes first (A && B); the effects follow a /, one per line (/ x = 3). A transition without a trigger shows only its effects (/ x++); one with neither has no label at all, like the arrow from Both back to Wait.
• Count delay. 2 B means “the second tick in which B holds”, written if 2 B.
• Self-loop. An arrow from a state back to itself, like 3: 2 B. Taking it leaves the state and enters it again.

The warning under the chart is one of KIELER’s false alarms: it suspects an instantaneous loop, but compiles and runs the chart as drawn.

Superstates and regions

SuperstateChart

Open in the playground

Diagram

Code

scchart Superstate {
  input bool A, R
  output int count

  initial state Counter {
    int step = 1
    entry do count = 0
    initial state Counting
      if A do count += step go to Counting
  }
  if R go to Counter
}

Warning: KIELER warns about a potential instantaneous loop here, but compiles and runs the chart correctly

• Warning, line 5, column 17KIELER says: Instantaneous loop detected!KIELER's loop check works on the compiled chart, in which entry actions are extra regions and transitions, and warns whenever control could go round a circle there within one tick, without checking whether the triggers prevent it: here the circle runs through Counter and Counting. The chart works as written.About this message

The superstate Counter shows its declaration and entry action under its name, and its states in the inner area.

A superstate is a state with an inside. It is drawn as a large box: its name at the top, then its declarations and actions, then an inner area (a region) with its own states and transitions. The arrow from the edge of Counter back to itself belongs to the superstate, not to the state inside. Such a reset is a typical cause of the same harmless loop warning, shown under the chart.

RegionsChart

Open in the playground

Diagram

Code

scchart Regions {
  input bool A, B
  output bool O

  initial state WaitAB {
    region HandleA "Wait for A" {
      initial state WaitA
        if A go to DoneA
      final state DoneA
    }
    region HandleB {
      initial state WaitB
        if B go to DoneB
      final state DoneB
    }
  }
  do O = true join to Done

  final state Done
}

WaitAB has two concurrent regions; the first shows its label, Wait for A, the second its name, HandleB.

A superstate with several concurrent regions shows them side by side, each in its own area with its name or label in the top corner. All of them are active at once. A region written without a name and label shows nothing there. A for region is drawn once, with its range after its name: region Seat for i : 0 to 2 shows Seat | i [ 0, 2 ].

Leaving a superstate

The marker at the start of an arrow tells you how it leaves a superstate:

PreemptionChart

Open in the playground

Diagram

Code

scchart Preemption {
  input bool stop, pause, A

  initial state Run {
    initial state Work
      if A go to Finished
    final state Finished
  }
  if stop abort to Stopped
  if pause go to Paused
  join to Complete

  state Stopped
  state Paused
  state Complete
}

From top: a strong abort (red dot), a weak abort (no marker) and a termination (green triangle, dashed because it is immediate).

• No marker: weak abort (go to). When the trigger holds, the inside of the superstate still completes its tick, and then the superstate is left.
• Red dot: strong abort (abort to). When the trigger holds, the superstate is left before the inside does anything in that tick.
• Green triangle: termination (join to). Taken when every region inside has reached a final state. A termination without a trigger is immediate, so it is drawn dashed.

Aborts explains exactly what the inside may still do in each case, and Entry, during and exit actions which actions run.

Returning to a superstate

Markers at the head of an arrow say how the target superstate is entered:

ReturningChart

Open in the playground

Diagram

Code

scchart Returning {
  input bool leave, back, again, quiet, hush

  initial state Mode {
    initial state One
      go to Two
    state Two
  }
  if leave go to Away

  state Away
    if back go to Mode history
    if again go to Mode shallow history
    if quiet go to Mode deferred
    if hush go to Mode deep deferred
}

The four arrows back into Mode, from top: deep history (H*), shallow history (H), deferred (red dot) and deep deferred (red dot with a star).

• H*: deep history (go to S history). The superstate resumes in the states it was in when it was left, at every level.
• H: shallow history (go to S shallow history). Only the superstate’s own regions resume; states nested deeper start again from their initial states.
• Red dot: deferred (go to S deferred). The target is entered quietly: its entry actions do not run, and its immediate transitions wait until the next tick. A star in the dot marks deep deferred, which treats the inner initial states the same way.
• No marker (or reset): the superstate starts from its initial states.

KIELER honours history only for superstates at the top level of a chart (and inside superstates that are themselves entered with history); elsewhere it silently restarts the superstate, although the marker is drawn. The history chapter shows this.

A marker at the start of an arrow is about leaving its source; a marker at the head is about entering its target. One arrow can carry both.

Connector states

JunctionChart

Open in the playground

Diagram

Code

scchart Junction {
  input bool sample
  input int level
  output int band

  initial state Idle
    if sample go to Classify

  connector state Classify
    immediate if level > 10 do band = 2 go to Idle
    immediate if level > 5 do band = 1 go to Idle
    immediate do band = 0 go to Idle
}

The small filled dot is the connector state, called Classify in the code: control passes through it and takes the first branch whose trigger holds.

A connector state is drawn as a small filled dot, without a name. It is a junction, not a place to wait: its outgoing transitions are always immediate, and drawn dashed, even without the keyword immediate, and control passes through it in the same tick. KIELER still asks you to write the keyword, with the warning Outgoing transitions of connector states should be marked as immediate. Give the last branch no trigger, so that one branch always fires.

Actions

ActionsChart

Open in the playground

Diagram

Code

scchart Actions {
  input bool A
  output int entered, ticks, left

  initial state Busy {
    entry do entered++
    immediate during do ticks++
    exit do left++
  }
  if A go to Idle

  state Idle
    if A go to Busy
}

Busy lists its actions under its name, one per line, each starting with its keyword.

A state’s actions are listed inside its box, under the name: the keyword (entry, during, immediate during, exit), then the trigger if there is one, then / and the effects. The other actions are listed the same way: suspend if hold appears as suspend hold (the trigger without its if), weak suspend hold and immediate suspend hold likewise; period 100 is listed as written. A state with actions is drawn as a box rather than a capsule, even when it has no inner states.

References

ReferenceChart

Open in the playground

Diagram

Code

scchart Reference {
  input bool tick
  output bool lamp

  initial state Blinking is Blinker(tick to tick, lamp to light)
}

scchart Blinker {
  input bool tick
  output bool light

  initial state Dark
    if tick do light = true go to Lit

  state Lit
    if tick do light = false go to Dark
}

Blinking is an instance of the chart Blinker, with tick and lamp connected to its interface.

A state that is an instance of another chart (state Blinking is Blinker(tick to tick, lamp to light)) is drawn with a violet fill and the title Blinking @ Blinker (tick, lamp): the state’s name, the referenced chart, and the variables passed to it. Its inside is collapsed (the + corner); KIELER can expand it to show the referenced chart in place.

Dataflow regions

GateChart

Open in the playground

Diagram

Code

scchart Gate {
  input bool A, B
  input int I
  output bool O
  output int N

  dataflow {
    O = A && !B
    N = I * 2 + 1
  }
}

Inputs on the left, operators in the middle, outputs on the right: O = A && !B and N = I * 2 + 1.

A dataflow region is drawn as a circuit: the variables an equation reads come in on the left, each operator is a small box, constants are square boxes, and the variables it writes leave on the right.

Note

This guide draws dataflow regions as a simplified circuit. KIELER’s own drawing of the same region is built from the same parts but differs in detail; the rest of the notation on this page matches KIELER’s.

Labels and comments

LabelsChart

Open in the playground

Diagram

Code

scchart Labels {
  input bool button
  output int presses

  region Main "The lamp":
    initial state Off "Light off"
      if button do presses++ go to On label "press"

    state On "Light on"
      if button go to Off label "press again"
}

The states show their labels instead of their names, the region its label, and the transitions press and press again instead of their triggers and effects.

Labels replace names and expressions in the diagram, never the behaviour:

• state Off "Light off" shows Light off instead of Off; region Main "The lamp": shows its label in the region’s corner.
• go to On label "press" shows press instead of the trigger and effects. KIELER adds a hint to the transition, The trigger of this action is hidden by the label., because the label can hide what really happens.

CommentedChart

Open in the playground

Diagram

Code

/** Switches a lamp on and off. */
scchart Commented {
  input bool button
  output bool light

  /** Waiting for the first press. */
  initial state Off
    if button do light = true go to On

  state On
    if button do light = false go to Off
}

Doc comments become yellow notes attached to the chart and to the state Off.

A doc comment, /** … */ directly before the chart, a state or a region, is shown as a yellow note attached to it; one before a transition becomes an extra label on its arrow. KIELER shows these notes by default (its diagram option Comment Nodes), and so do this guide’s diagrams. The annotation @diagram[commentNodes] false before scchart turns them off for one chart. Ordinary comments (//, /* … */) never appear in the diagram.

In a simulation

When a chart runs, the diagram shows where it is. KIELER, SCCharts Lab and this guide use the same two colours: red for the states that are active after the tick, blue for the transitions taken in it and the states that were left. In this guide’s simulations no mark relies on colour alone:

• An active state has a heavy red outline with a glow and its name in bold; a simple state is also tinted pale red.
• A transition that fired is drawn heavier, in blue, with a glow, and a short pulse runs along it once as it fires (not when your system asks for reduced motion). It keeps its own line: solid when delayed, dashed when immediate, so you can still tell which it is.
• A state that was left during the tick, or entered and left again within it, gets a blue outline and a pale blue tint that fades. A state entered in the tick glows briefly.

The guide’s diagrams also mark compiler messages: in a chart that KIELER rejects, the states and transitions a message is about get a solid red-orange outline with a glow and a small red-orange disc with an exclamation mark.

None of these marks adds dashes: on a transition, a dashed line always means that it is immediate.

SimulationSimulation

Open in the playground

Diagram

Code

scchart Simulation {
  input bool go1
  output int x

  initial state Wait
    if go1 do x = 1 go to Fast

  state Fast
    immediate do x++ go to Done

  state Done
    go to Wait
}

Step

Tick 0 of 4

Inputs for tick 1

go1 Boolean input: true while on. It keeps its value until you change it.

Timing diagram of Simulation

Tick	input bool go1	output int x	Active state of the chart

Click a tick to show it, or use the Left and Right arrow keys to go back and step.

Guided tour, 4 ticks Press Next to run tick 1, or Take over to set the inputs yourself.

Previous Next Take over

Guided tour, 4 ticks:

1. go1 = falseTick 1 enters Wait, the active state: a heavy red outline with a glow.
2. go1 = truego1 is true: the delayed transition to Fast fires (x = 1), and then the immediate transition out of Fast fires in the same tick (x = 2). Both are drawn heavier, in blue, and each keeps its own line: solid for the delayed one, dashed for the immediate one. Wait and Fast, both left in this tick, get a blue outline and tint, and Done is now the active state.
3. go1 = falseThe transition out of Done has no trigger, so it fires in the tick after Done was entered: back to Wait.
4. Nothing is enabled: go1 is false. No transition fires, and Wait stays the active state.

Step through the tour: in tick 2 two transitions fire at once, and the active state changes from Wait to Done.

In tick 2, go1 is true: the delayed transition out of Wait fires, Fast is entered, and its immediate transition fires straight away, so both arrows are marked, one solid and one dashed, and the chart ends the tick in Done. Fast was active only for a moment within the tick, so it is never outlined in red; it gets the blue outline of a state that was left, and so does Wait.