#safety-logic

Following figures are from the website of YAKINDU Statechart Tool.

Editing

SCT features an intuitive combination of graphical and textual notation. While states, transitions and state hierarchies are graphical elements, all declarations and actions are specified using a textual notation. The usability of the statechart editor is simply fascinating.

Validation

The validation of state machines includes syntax and semantic checks of the full model. Examples of built in validation rules are the detection of unreachable states, dead ends and references to unknown events. These validation constraints are checked live during editing.

Simulation

The simulation of state machine models allows the dynamic semantics to be checked. Active states are directly highlighted in the statechart editor and a dedicated simulation perspective features access to execution controls, inspection and setting variables, as well as raising events.

Code generation

SCT includes code generators for Java, C and C++ out of the box. The code generators follow a code-only approach and do not rely on any additional runtime library. The generated code provides a well-defined interface and can be integrated easily with any client code.

After the marketing part, let’s get some hands-on experience with Yakindu. It has a really intuitive and exhaustive documentation with lots of tutorials and video instructions. One can get familiar with Yakindu in an hour or so.

Transforming BridgePoint models to Yakindu statecharts

 As I mentioned in the previous parts of this post series (#1, #2), I designed a lot of state machines in xtUML BridgePoint Editor. However, we had some serious issues with BridgePoint, so we switched for Yakindu Statechart Tool. We hoped it would be a statechart designer suite that enables simulation and code generation too.

Since BridgePoint follows the xtUML methodology is based on Shlaer-Mellor Method of Model-Driven Architecture that is an object-oriented software development methodology (more on Wikipedia). This means we can design the structure of the state machine hierarchy in a class diagram manner depicted in the next figure.

As you can see classes can inherit from each other, however multiple inheritance is not allowed. This inheritance is similar to the virtual function concept of C++, and the abstract method concept of Java and C#. This means if the superclass does not handle an event, then its subclass must handle it. However it is not possible to redefine an event in subclass, that has already been handled by the superclass.

In Yakindu Statecharts this object-oriented concept is not followed, because it would be quite weird. Instead, we had to translate this in some respect hierarchical structure to a more convenient one.

That’s why we created a separate SCT model for the Section and the Turnout. Within each model we designed a hierachical statechart that consists of parallel regions, let’s see.

Section

We introduced a general statechart for the Sections. It means in the figure above you can see that the Section was connected to the Turnout through three associations, which describes from which direction the Section connects to the Turnout (of course only one association was valid for each Section instance).

Now, this information is stored in a variable, called direction, which may have three values: STRAIGHT, DIVERGENT, TOP. In the statechart all the messages are compared to this direction value, and in this way the concept of direction has been preserved for the ‘safety logic’ protocol.

The statechart of the OccupiedSection, depicted below, can be compared to the former version here that was designed in BridgePoint.

Turnout

The highest-level statechart of the Turnout is responsible for differentiating the recent direction of the Turnout. It means, whether the Turnout connects the straight - top or the divergent - top sections. In this way the former large columns of inheritance hierarhcy (depicted above) have been replaced with two composite states which contain parallel regions.

As an example the StraightTurnout state now handles the possible events in five parallel regions. This way multiple events can be handled from the safety logic protocol’s perspective, at one time. In the former version, if a lock request has been received by the Turnout, then it rejects and further requests. In the recent version it now handles the parallel requests independently. The statechart is too complicated to be depicted in this post, but you can see it on an external link here.

Validation

Yakindu Statechart Tool has a built-in validation framework for syntax and semantic checks of the created models.

It includes the detection of unreachable states, dead ends and references to unknown events. These validation constraints are checked live during editing.

E.g. for the Turnout model it found that several choice nodes, do not have a default outgoing transition. So it can be a problem, if at runtime there is no valid outgoing transition from a choice node.

Simulation

We have not tried the Simulator for our models, because we were so eager to see the generated code working with the model railway track, that we skipped this stage.

Code generation

We used the built-in Java code generator to generate code from the statecharts. We connected the Section and Turnout models through the interfaces of the generated codes.

If they raise an event, that should be dispatched to each other, then it goes through the interfaces of the separate statecharts. In this way all statecharts are separated, can be configured and run individually.

Besides, we integrated our codebase, that is necessary to communicate with the model railway track’s embedded controllers, with the statecharts, so we managed to get the statecharts control and stop the trains if any dangerous situation emerges.

Although BrdigePoint has a great statechart designer module (depicted in figure above), which improves productivity a lot, the other parts of the software has some defects.

The suite comes with a module called Verifier, though it should be called Simulator instead, that helps to simulate and validate your state machines in design time.

Since the Verifier can be connected to platform-specific implementation code (such as Java, C, C++) through an interface, at simulation time events can be sent from the state machines to this code and vice versa. Thus it gives you a real simulation environment that can be even made cyber-physical, if the platform-specific glue code is necassarry for controling trains on a model railway!

However, there are some problems with the Verifier.

Although it is single threaded, the interface that shall be used for raising events from the platform-specific code to the simulation environment often threw NullPointerException if we used it from multiple threads concurrently in Java. This bug was not justified by any means of the structure of the state machines or the platform-independent code written inside them. We reported this non-deterministic bug to the developers, but has not found any resolution yet.

Second, we caught some weird exceptions from the Verifier, that originated from the real depth of this module. Because xtUML BridgePoint Editor is open source, we received the advice to debug and fix the errors ourselves, and then push it its GitHub repository. The only problem was, the code base is huge and its quite difficult for a developer to get involved and fix the bug in a not too long time, because we shall develop our system as well.

After the Verifier, we had some problems with the code generator module too, called Model Compiler.

First, the generated C++ code could not fit in our Arduino Uno embedded controller’s program memory (read What this project was all about). It was mostly because of the complex structure of our state machines, so we decided to write an own model compiler using BridgePoint’s own query language, RSL.

Here comes the second and the greatest problem regarding the extensibility of BridgePoint. The RSL (Rule Specification Language) is a query language (just like SQL) that should be used if you would like to transform your platform independent state machines to platform-specific code.

Because the state machines are platform independent and they are model-based, they have a metamodel that describes what elements can be found in a state machine model. This metamodel is so complex and there are so many associations and non-trivial paths in it, e.g. fetching the exact order of the OAL expressions that are written within the states requires 10+ classes and associations to go through. Inspecting the meta model requires days, because it is separated for 30+ packages and 3-40+ classes are in each package. In the figure above the metamodel package for State Machine is depicted.

So if you have much time, maybe years, you can write your own code generator in BridgePoint.

That was when we started to look for a new statechart editor, and found Yakindu Statecharts. It is open source and much easier to be extended by a code generator.

Safety logic

The class diagram is depicted here:

It is quite complicated, so I describe it in short. Section and Turnout (or switch in better terminology) were differentiated.

Section

Section can be FreeSection if no train is on it, otherwise it's OccupiedSection.

The behaviour of the FreeSection is quite simple, it simply allows any train to come to the section. Because its so simple, it is not depicted now. :-)

But, the OccupiedSection is more interesting, because it contains a more complex logic in itself:

As you may see, there is some text in the squares, that are called states. The edges connecting the states are called transitions, which have events or triggers written on them. If an event is occured in a state, then the respective transition is fired, which means the state machine moves from one state to another.

As an illustration: in BridgePoint one can write platform independent actions, in the BridgePoint's own language, called OAL (Object Action Language). With the help of actions, we can create and fire events, instantiate new state machines, create references between objects, and so on. Actions can be written within edges and states as well.

E.g. in the BecomesLocked state the next OAL code is written:

select one section related by self->Section[R1];

send Port1::setSection(sectionId: section.id, isEnabled: false);

It gathers a reference for a section, and sends a setSection event with several parameters through Port1.

Turnout

A Turnout can either be Straight, or Divergent. It is illustrated on the following picture (the recent direction is marked with black):

The logic for the Turnout was designed in a three-level hiearchy (see the high-level class diagram on the top of this post!). Only one column of the hierarchy exists at a time, depending on the recent direction of the turnout (or switch).

The first level is responsible for rejecting new events that are received while a former event is being handled by the hierarchy.

The second level is responsible for handling events which are received from perpendicular direction than the turnout's recent one.

The third level is actually responsible for what we call safety logic itself.

It is quite complex, but on high-level it can be described easily; we have to stop trains if they are close to each other. On this level we are prepared for the worst-case scenario, which means the trains are approaching to each other!

Trains are either in the territory of the local turnout, or a remote one. Thus turnouts have to communicate with each other, whcih adds an extra complexity to the system.

Wrapping up this long post

Ugh, it was quite a long post, but we hope you liked it, and found the state machines fascinating.