Specifying Logical System Interfaces

System interfaces identify the sets of services, data, and flows into and out of a system. By logical interfaces, we mean abstract interfaces that specify the content and precision of the flows but not their physical realization. For example, a system interface to a radar might include a message herezaRadarTrack(r: RadarTrack) as a SysML event carrying a radar track as a parameter without specifying what communication means will be used, let alone the bit-mapped structure of the realizing 1553 Bus message. Nevertheless, the specification of the interface allows us to consider the set of services requested of the system by actors, the set of services needed by the system from actors, and the physical and information flow across the system boundary.

The initial set of interfaces is a natural outcome of use case analysis. Each use case characterizes a set of interactions of the system with a group of actors for a similar purpose. These interactions necessitate system interfaces. This recipe will focus on the identification of these interfaces and the identification of the data and flows that they carry; the actual definition of these data elements is described in the last recipe in this chapter, Creating the Logical Data Schema.

The logical interfaces from a single use case analysis are only a part of the entire set of system interfaces. The set interfaces from multiple use cases are merged together during system architecture definition. This topic is discussed in the recipes of the next chapter, Developing Systems Architectures. Those are still logical interfaces, however, and abstract away implementation detail. The specification of physical interfaces from their logical specification is described in Chapter 4, Handoff to Downstream Engineering.

A Note about SysML Ports and Interfaces

SysML supports a few different ways to model interfaces, and this is intricately bound up with the topic of ports. SysML has the standard port (from UML), which is typed by an interface. An interface is similar to an abstract class; it contains specifications of services but no implementation. A block that realizes an interface must provide an implementation for each operation specified within that interface. UML ports are typed by the interfaces they support. A port may either provide or require one or more interfaces. If an interface is provided by the system, that means that the system must provide an implementation that realizes the requested services. If an interface is required, then the system can request an actor to provide those services. These services can be synchronous calls or asynchronous event receptions and can carry data in or out, as necessary. Note that the difference between provided and required determines where the services are implemented and not the direction of the data flow.

These interfaces are fundamentally about services that can, incidentally, carry data. SysML also defines flow ports that allow data or flow to be exchanged without services being explicitly involved. Flow ports are bound to a single data or flow element and have an explicit flow direction: either into or out of the element. Block instances could bind flow ports to internal value properties and connect them to flow ports on other blocks that were identically typed.

SysML 1.3 and later deprecate these standard and flow ports and added the proxy port. To be clear, “deprecated” means that the use of these ports is “discouraged” but they are still part of the standard, so feel free to use them. Proxy ports essentially combine both the standard ports and flow ports. The flows specified sent or received by a proxy part are defined to be flow properties rather than value properties, a small distinction in practice. More importantly, proxy ports are not typed by interfaces but rather by interface blocks. Interface blocks are more expressive than interfaces in that they can contain flow properties, nested parts, and proxy ports themselves. This allows the modeling of some complex situations that are difficult with simple interfaces. With proxy ports, gone are the “lollipop” and the “socket” notations; they are replaced by the port and port conjugate (”~”) notation. In short, standard ports use interfaces but proxy ports use interface blocks. The examples in this book exclusively use proxy ports and interface blocks and not standard ports.

This recipe specifically refers to the identification and specification of logical interfaces during use case specification, as experience has shown this is a highly effective means for identifying the system interfaces.

Continuous flows

Systems engineering must contend with something that software development does not: continuous flows. These flows may be information but are often physical in nature, such as material, fluids, or energy. SysML extends the discrete nature of UML activities with the «continuous» stereotype for continuous flows. The «stream» stereotype (from UML) refers to object flows (“tokens”) that arrive as a series of flow elements at a given rate. «continuous» is a special case where the time interval between streaming flow elements approaches zero. In practice, «stream» is used for a flowing stream of discrete elements, often at a rate specified with the SysML «rate» stereotype, while «continuous» is used for truly continuous flows. An example of «stream» might be a set of discrete images sent from a video camera at a rate of 40 frames per second. An example of a «continuous» flow might be water flowing through a pipe or the delivery of electrical power.

In my work, I use these stereotypes on flows in sequence diagrams as well. I do this by applying the stereotypes to messages and through the use of a continuous interaction operator. To create the flows, I use a standard Message on the sequence diagram and add item flows to it with Cameo’s Item Flow Manager. To enable that, the relations between the elements typing the lifelines must have such flows defined. Figure 2.80 shows such a context for a system that heats water for bathing:

Figure 2.80: Structural context for continuous flows example

Since the flows are defined, they can be added to the messages sent between the lifelines defined by those blocks. While the Rhapsody tool allows me to create new interaction operators, Cameo does not. Thus, in Cameo, I use a Critical Region interaction operator and apply the continuous stereotype to it.

The resulting sequence diagram is shown in Figure 2.81:

Figure 2.81: Continuous flows on sequence diagrams

The figure shows flows (messages with item flows) marked with the «continuous» stereotype. This indicates that the flow is continuous throughout its execution context. That context can be the entire diagram or limited to an interaction operator, as it is in this case. Within a context, there is no ordering among «continuous» flows; this is in contrast to the normal partial ordering semantics of SysML sequence diagrams in which “lower in the diagram” corresponds (roughly) to “later in time.” However, «continuous» flows are active throughout their execution context and so the ordering of continuous flows is inherently meaningless.

The use of the interaction operator with the continuous stereotype defines the context during which the flows are continuous and unordered. Any normal (non-continuous) messages within the interaction operator still operate via the normal partial ordering semantics.

Purpose

The purpose of this recipe is to identify the exchange of services and flows that occur between a system and a set of actors, especially during use case analysis.

Inputs and preconditions

The precondition is that a use case and set of associated actors have been identified.

Outputs and postconditions

Interfaces or interface blocks are identified, as well as which actors must support which interfaces or interface blocks.

How to do it

Figure 2.82 shows the workflow for this recipe. This overlaps with some of the other recipes in this chapter but focuses specifically on the identification of the system interfaces:

Figure 2.82: Specify logical interfaces workflow

Identify use case

This first step is to identify the generic usage of the system that will use the to-be-identified system interfaces.

Identify related actors

The related actors are those people or systems outside our scope that interact with the system while it executes the current use case. These actors can send messages to the system, receive messages from the system, or both using the system interfaces.

Create the execution context

The use case execution context is a kind of modeling “sandbox” that contains an executable component consisting of executable elements representing the use case and related actors. The recommended way to achieve this is to create separate blocks representing the use case and the actors, connected via ports. Having an isolated simulation sandbox allows different system engineers to progress independently on different use case analyses.

Create activity flow

This step is optional but is a popular way to begin to understand the set of flows in the use case. This step identifies the actions – event reception actions, event send actions, and internal system functions – that define the set of flows of the use case.

Capture the use case scenarios

Scenarios are singular interactions between the system and the actors during the execution of the use case. When working with non-technical stakeholders, they are an effective way to understand the desired interactions of the use case. We recommend starting with normal, “sunny day” scenarios before progressing to edge case and exceptional “rainy day” scenarios. It is important to understand that every message identifies or represents one or more requirements and results in messages that must be supported in the derived interfaces. If the Create Activity Flow task is performed, then the sequence diagrams can be derived from those flows.

Use asynchronous events for all actor > system and system > actor service invocations. This is specifying the logical interfaces and so the underlying communication mechanism should be abstracted away. Later, in the definition of the physical interfaces and data schema, these can be specified in a technology-specific fashion.

Add message parameters

These signals often carry data. This data should be explicitly modeled as signal attributes that become message arguments.

Add flows

Use UML “flows” to indicate discrete flows of information, material, fluids, or energy exchanges between the system and an actor that are not intimately bound to a service request. Stereotype these flows as «continuous» when appropriate, such as the flows of energy or fluids.

Create parameter and flow types

The event arguments must be typed by elements in the logical data schema (see the recipe Creating the Logical Data Schema). The same is true for flow types. Because these types are specifications, they will include not only some (logical) base types, but also units, ranges, and other kinds of metadata.

Create ports and interfaces

Based on the defined interaction of the system with the actors while executing the use case, add ports between the actor and use case blocks and type these ports with interfaces. These interfaces will enumerate the services and flow going between the actors and the system. Technically speaking, this can be done using UML standard ports and SysML flow ports, or the more modern SysML 1.3 proxy ports.

Example

This example will use the Control Resistance use case but we will a different approach than was used for this use case in the Functional Analysis with Activities recipe, just to demonstrate that there are alternative means to achieve similar goals in MBSE.

Identify use case

The Control Resistance use case focuses on how resistance is applied to the pedals in response to simulated gearing, conditions, and user-applied force. The description was shown previously in Figure 2.19.

Identify related actors

There are two actors here for this use case: Rider and Training App. The Rider provides power to and receives resistance from the pedals. The Training App is sent the rider power information.

Create the execution context

Creating the execution context creates blocks that represent the actors and use cases for the purpose of analysis and simulation. They contain proxy ports that will be defined by the interfaces identified in this workflow:

Figure 2.83: Control resistance execution context for interface definition

Create activity flow

The activity flow shows the object and control flows for the use case. In this example, we will show continuous flows in addition to discrete flows. The activity is decomposed into three diagrams. The top level is shown in Figure 2.84. This diagram shows the system sending bike data to the Training App on the left. The center part, containing the Determine Base Pedal Resistance call behavior, does the bulk of the functional work of the use case.

Note that it takes the computed base resistance on the pedal and adjusts it for its current angular position. On the right, pedal cadence is computed from pedal speed.

Discrete events, such as turning the system on and off or changing the gears, are simple to model in the activity diagrams; they can easily be modeled as either signal receptions for incoming events or send signal actions for outgoing events. Of course, these events can carry information as arguments as needed.

It is somewhat less straightforward to model continuous inputs and outputs. These are modeled on the flow properties pedalSpeed and pedalResistance. The activity uses a change event for monitoring when the pedal speed changes and uses this, along with other information, to compute and apply resistance at the point of the pedal:

Figure 2.84: Control resistance activity flow for creating interfaces

Figure 2.85 shows the details for the Determine Pedal Resistance call behavior from the previous figure. In it, we see the base pedal resistance is computed using another call behavior, Compute Bike Physics. The Determine Pedal Resistance behavior never terminates (at least until the entire behavior terminates) so it uses a «rate» stereotype to indicate the data output on these activity parameter streams, although Cameo doesn’t show it graphically. I added a constraint to show the rate.

Remember that normal activity parameters require the activity to terminate before they can output a value:

Figure 2.85: Determine base pedal resistance activity

Lastly, we have the call behavior Compute Physics, shown in Figure 2.86. This simulates the physics of the bike using the rider mass, current incline, current speed, and the power applied by the rider to the pedal to compute the resistance to movement, and couples that with the combined bike and rider inertia to compute the simulated bike speed and acceleration:

Figure 2.86: Compute bike physics activity

Capture the use case scenarios

The interfaces can be produced directly from the activity model but it is often easier to produce them from a set of sequence diagrams derived from the activity model. Accept event actions and flows on activities don’t indicate the source but this is clearly shown in the sequences. If you do create a set of sequence diagrams, it is adequate to produce the set of scenarios such that all inputs and outputs and internal flows are represented in at least one sequence diagram.

The next three diagrams show the functional behavior modeled to follow the same structure as the activity model. Figure 2.87 shows the high-level behavior. Note the use of «continuous» flows for the resistance to movement supplied by the system (pedal resistance) and the speed of the pedal (pedal speed). The critical region interaction operator is stereotyped as «continuous» and defines a scope for continuous flows. Note the use of a parallel interaction operator to show things that are going on concurrently, and loops and critical regions nested within it. The referenced interaction occurrence Determine Pedal Resistance Scenario references the sequence diagram shown in Figure 2.7:

Figure 2.87: Control resistance scenario

Throughout the entire scenario shown in Figure 2.88, the continuous flows are active, so no scoping continuous interaction occurrence is required. This scenario also includes a nested scenario, the referenced Compute Physics, shown in Figure 2.89. This scenario includes a continuous flow but doesn’t need a critical region stereotyped as continuous because the scope of the continuous flow is the entire sequence diagram:

Figure 2.88: Determine pedal resistance scenario

Figure 2.89: Compute bike physics

Add message parameters

Rather than show all the stages of development of the scenarios, the previous step is shown already including the message parameters.

Add flows

Rather than show all the stages of development of the scenarios, the previous step is shown already including the continuous flows.

Create parameter and flow types

The detail of how to create all the types is the subject of the next recipe, Creating the Logical Data Schema. The reader is referred to that recipe for more information.

Create ports and interfaces

Now that we have the set of flows between the actors and the system and have characterized them, we can create the interfaces. In this example, we are using the SysML 1.3 standard approach of using proxy ports and interface blocks, rather than standard ports, flow ports, and standard interfaces. This is a bit more work than using the older approach but is more modern and descriptive.

Figure 2.83 shows the execution context of the use case analysis for the Control Resistance use case. Although the diagram is itself a block definition diagram, Cameo allows you to show diagrams within diagrams; thus the corresponding internal block diagram is shown at the bottom of the figure. The IBD parts of the use case block Uc_ControlResistance and the actor blocks aCR_Rider and aCR_TrainingApp with SysML connectors between the appropriate ports. Note that, by convention, the unconjugated form interface is referenced at the use case block end of the connector and the conjugated form is used at the actor end, as indicated by the tilde (“~”) in front of the interface block name.

At the top of the diagram are the (current empty) interface blocks that will be elaborated on in this step. Later, during architecture development, these interface blocks will be added to the interfaces provided by the system and decomposed and allocated to the subsystems.

A note about naming conventions

The package Functional Analysis Pkg::Control Resistance Pkg holding the model used in this recipe provides a sandbox for the purpose of analyzing the Control Resistance use case. To that end, a block representing the use case is created and given the name uc_ControlResistance.

For the actors, local blocks are created for the purpose of analysis and are given the names of a (for actor), followed by the initials of the use case (CR) followed by the name of the actor (with white space removed). So, these sandbox actor blocks are named aCR_Rider and aCR_TrainingApp. The interfaces are all named i <use case block name> “_” <actor block name>, as in iControlResistance_ Rider. This makes it easy to enforce naming consistency at the expense of sometimes creating lengthy names.

Since the flows are shown on the sequence diagrams, it is a simple matter to add these elements to the interface blocks:

• For each message from the use case to an actor, add that signal reception as required to the interface block defining that port.
• For each message from an actor to the use case, add that signal reception as provided to the interface block defining that port.
• For each flow from the use case to an actor, add that flow as an output flow property to the interface block defining that port.
• For each flow from an actor to the use case, add that flow as an input flow property to the interface block defining that port.

The result is shown in Figure 2.90. Note that the event receptions are either provided (prov) or required (reqd) while the flow properties are either in or out (from the use case block perspective):

Figure 2.90: Created interface blocks

You should note that these are, of course, logical interfaces. As such, they reflect the intent and content of the messages but not their physical realization. For example, bike data sent to the training app is modeled in the logical interface as an event, but the implementation will actually be as a Bluetooth message. The creation of physical interfaces from logical ones is discussed in the last chapter.