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 1553 Bus message. Nevertheless, the specification of the interface allows us to consider the set of services requested from the system by actors, the set of services needed by the system from the actors, and the physical flows across the system boundary.
The initial set of interfaces are a natural outcome of our 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, Chapter 3, Developing System 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 an interface. 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, which 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 from 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 versions deprecate the standard and flow ports and add the proxy port. Proxy ports essentially combine both the standard ports and flow ports. The flows specified as 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 powerful than interfaces in that they can contain 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 with proxy ports use interface blocks. The examples in this book exclusively use proxy ports and interface blocks and not standard ports.
Note
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.
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 materiel, 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 «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. An example is shown in Figure 2.74:
Figure 2.74 – Continuous flows on sequence diagrams
The figure shows flows (messages with dash lines) 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 (although the ordering of non-continuous messages is still in force).
The use of the «continuous» interaction operator emphasizes the unordered nature of the flows. Any events with 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, and well as which actors must support which interfaces or interface blocks.
How to do it…
Figure 2.75 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.75 – Specify logical interfaces workflow
Identify the 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 systems engineers to progress independently on different use case analyses.
Create the 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 cases 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 the activity flow task is performed, then the sequence diagrams can be derived from those flows.
Recommendation:
Use asynchronous events for all actor > system and system > actor service invocations. This specifies 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 events often carry data. This data should be explicitly modeled as event arguments.
Add flows
Use UML flows to indicate discrete flows of information, materiel, 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 Creating the logical data schema recipe). The same is true for flow types. Because these types are specifications, they will include not only some (logical) base type, 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 interface blocks. These interface blocks will enumerate the services and flows 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
We will now look at an example.
This example will use the Control Resistance use case, but we will follow a different approach than we 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 the 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 is shown in Figure 2.18.
Identify related actors
There are three actors for this use case: Rider, Training App, and Power Source. The Rider provides power to and receives resistance from the pedals. The Training App is sent the rider power information. The Power Source provides electric power to run the system motors and digital electronics.
Create the execution context
Creating the execution context creates blocks that represent the actors and the use case for the purpose of analysis and simulation. They contain proxy ports that will be defined by the interfaces identified in this workflow:
Figure 2.76 – Control Resistance execution context for interface definition
Create the 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.77. This diagram shows the distribution of electric power on the left. This section contains an interruptible region that terminates the entire behavior when an evPowerOff event is received. 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, the Training App is updated periodically with bike data.
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 event receptions for incoming events or send 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. What I have done here is use an object node, stereotyped as both «external» and «continuous» for such flows. An example of a continuous flow coming from an external actor is electrical power from the wall supply (see wallPower in Figure 2.77). Conversely, the resistance the system continuously applies to the pedal is an example of an output (see RiderPedalResistance in the same figure). These will be modeled as flow properties in the resulting interfaces:
Figure 2.77 – Control Resistance activity flow for creating interfaces
Figure 2.78 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 this activity's parameter streams. Remember that normal activity parameters require the activity to terminate before they can output a value:
Figure 2.78 – Determine Base Pedal Resistance activity
Lastly, we have the Compute Bike Physics call behavior, shown in Figure 2.79. 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.79 – 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 it from a set of sequence diagrams derived from the activity model. Event receptions 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.
Figure 2.80 shows the first such scenario, which solely focuses on the delivery of power. It is also the only scenario shown that actually powers up and powers down the system. The power delivery is modeled as «continuous» flows to and inside the system:
Figure 2.80 – Electrical Power scenario
The next three diagrams show the functional behavior modeled to follow the same structure as the activity model. Figure 2.81 shows the high-level behavior. Note the use of «continuous» flows for the power the rider applies to the pedal (appliedPower), the resistance to movement supplied by the system (pedalResistance), and the position of the pedal (pedalPosition). The continuous interaction occurrence provides a scope for the continuous flows. The referenced interaction occurrence, Determine Base Pedal Resistance, references the sequence diagram shown in Figure 2.82:
Figure 2.81 – Control Resistance scenario
Throughout the entire scenario shown in Figure 2.82, the continuous flows are active, so no scoping continuous interaction occurrence is required:
Figure 2.82 – Determine Base Pedal Resistance scenario
The presence of these flows isn't strictly required since they are active at the high-level scenario, but they are included here as a reminder. This scenario also includes a nested scenario. This one is the referenced Compute Bike Physics, scenario shown in Figure 2.83:
Figure 2.83 – Compute bike physics
Lastly, we must add the scenario for updating the Training App (Figure 2.84):
Figure 2.84 – Update Training App with ride data
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 details 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.
The IBD in Figure 2.85 shows the execution context of the use case analysis for the Control Resistance use case. The instances of the Uc_ControlResistance use case block and the aCR_PowerSource, aCR_Rider, and aCR_TrainingApp actor blocks expose their proxy ports and are connected via SysML connectors. Note that, by convention, the unconjugated 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 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 IBD shown here 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_PowerSource, aCR_Ride, and aCR_TrainingApp. The interfaces are all named i <use case block name>_<actor block name>, as in iUc_ControlResistance_aCR_PowerSource. This makes it easy to enforce naming consistency at the expense of sometimes creating lengthy names.
The creation of the elements is automated via the Harmony SE Toolkit, provided with the Rhapsody modeling tool:
Figure 2.85 – Control Resistance execution context
Since we have the flows all shown in 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 event reception as required to the interface block defining that port.
- For each message from an actor to the use case, add that event 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.
Rhapsody does provide some assistance here in the Harmony SE Toolkit, although it is not difficult to do manually:
- First, realize all the messages for the sequence diagrams; this creates event receptions on the target blocks.
- Then apply the Harmony SE Toolkit helper called Create Ports and Interfaces to populate the interfaces.
You will still need to add the flows manually as flow properties.
The result is shown in Figure 2.86. 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.86 – 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 physical interface will actually be as a Bluetooth message. Wall power is modeled as a flow (its content will be described in the next recipe), but the actual interface involves the flow of electrons over a wire. The creation of physical interfaces from logical ones is discussed in Chapter 4, Handoff to Downstream Engineering.