Author Activity Diagrams

Activity diagrams describe the functional flow behavior of an architectural system, used in early phases of system design to elaborate on end system goals. To create an activity diagram, see Create New Activity Diagram.

An activity diagram is the primary diagram to describe an activity. An activity describes system behavior that models the flow of tokens from inputs to outputs through a controlled sequence of actions. An activity diagram contains action nodes with pins connected by flow lines. Activity diagrams represent the flow of tokens through various actions that describe the execution of activities.

Use activity diagrams to conceptualize a system, visualize functional flow through actions or decisions, and understand how system components interact with one another. You can use activity diagrams to describe the behavior of systems as a transformation of inputs to outputs through actions that process token flows.

In this topic, you will inspect different parts of an activity diagram and how to author each of the nodes to describe a mobile robot following a randomly generated path.

You can allocate activity diagram elements to elements of a System Composer™ architecture model using the Allocation Editor to more fully describe your functional architectural design. For more information, see Design Architectures and Activity Diagram for Mobile Robot.

You will learn how to:

Begin token flow in your activity diagram. You will use an initial node and a control flow.
Represent actions in your activity diagram.
- Create an action node with MATLAB^® function behavior.
- Create an action node with a nested activity.
- Use MATLAB action nodes without MATLAB functions to initialize object tokens.
Use control nodes to manipulate token flows.
- Use a fork node to replicate a control token in two control flows.
- Use a decision node to route the input token to one of the output flows.
- Create loops with control nodes.
- Consume tokens and terminate your activity with a flow final node and an activity final node.

For a roadmap of the activity diagram topics, see Describe System Behavior Using Activity Diagrams.

Open the activity diagram used in this example below to follow along.

Open Activity Diagram for Mobile Robot Functional Flow

Open Live Script

This example shows a functional flow diagram for modeling a mobile robot architecture that travels between a randomized starting point and destination.

Open the project.

openProject("scMobileRobotExample");

Open the activity diagram.

systemcomposer.openModel("RobotActivity");

RobotActivity activity diagram with action nodes, pins, and flow lines.

First, the robot software calculates the path distance, and if the distance exceeds robot battery life to traverse the distance, the token flows to Error out and the activity terminates, otherwise, the robot follows the path.

Token Flow in Activity Diagrams

Tokens represent objects that travel along your activity diagram invoking activities while routed by control nodes. To begin your activity, use an Initial Node to place a control token on the single outgoing flow.

Tokens are objects that flow in the activity diagram. A token can represent data such as structures and integers, or simply pass on the control.

Use a token to move data or control across the activity diagram. These are the types of tokens:

Object token — Represents an object such as a piece of data.
Control token — Represents a control or a triggering event that does not carry any data.

The RobotActivity activity diagram with a control flow and initial node.

Click the right side the initial node and drag to generate a control flow. Then, use marquee draw to select the action node that appears to instantiate it. The control flow transports the control token to the action node and begins execution.

A flow in an activity diagram connects two nodes. A dashed line represents a control flow and a solid line represents an object flow.

You can use object flows to route input or output tokens to carry information or physical items between object nodes. You can use control flows to model transfer of control from one Action Node to another. These are the types of flows:

Object flow — Tokens in an object flow contains token data on which actions operate.
Control flow — Tokens in a control flow trigger the execution of actions.

Author Activity Diagram Action Nodes

In an activity diagram, you can generate tokens and read tokens using an Action Node.

An action node is a key building block in an activity diagram. An action node represents an action to be executed. Action nodes consume input tokens and produce output tokens on pins.

Use a MATLAB function or a nested activity diagram to describe the behavior of an action node.

You can add an action node in your activity diagram by clicking and dragging the action node icon from the left side palette to the canvas.

Clicking and dragging an action node from the left side palette to the activity diagram canvas.

Author Action Node with MATLAB Function Behavior

The first Action Node of an activity diagram with a MATLAB function behavior determines how the control token that begins the action produces an object token on the action node output pin.

Change the Behavior Type parameter in the Property Inspector to MATLAB to implement MATLAB function behavior, then populate the MATLAB Function Name text box with the name of your function.

The RobotActivity activity diagram with a control flow and initial node connected to the Select Target Position action node with a MATLAB function GeneratePosition.

Double-click the Select Target Position action node to view the GeneratePosition.m function file in the MATLAB editor.

function [TargetPos] = GeneratePosition()

close all;
figure('Name','RobotPath');
set(gca, 'XLim', [0 100], 'YLim', [0 100]);
hold on;

pos = randi(100, [1 2]);
TargetPos(1) = pos(1); % x
TargetPos(2)= pos(2); % y
TargetPos(3) = floor(rand*360); % orientation

plot(pos(1), pos(2), 'go', 'MarkerSize', 12);

end

The GeneratePosition function calculates a random starting position and ending position on the graph for the mobile robot. The GeneratePosition function contains no input arguments and one output argument. The output argument TargetPos corresponds to the output pin on the action node and represents a 3-dimensional vector with the starting position, ending position, and orientation of the robot.

To create a pin on an action node, hover over the edge of an action node and click the blue pin, then choose whether to create an input pin or an output pin.

Add an object pin to the right side of an action node in the activity diagram canvas.

You can select the TargetPos pin and view its types in the Types Editor to view the corresponding PositionData type with expected dimensions [1,3].

TargetPos associated with scalar PositionData type in the Types Editor.

Note

When you set Dimensions to 3, the Types Editor automatically interprets the dimensions as a column vector [1,3].

A pin directs tokens in or out of an action node. The directionality of the pin represents input or output. You can connect pins by object flows.

Use pins to route an object token to or from an Action Node. Pins are also used to store object tokens before or during execution. You can use pins only for object flows.

Use Nested Activity to Describe Action

You can represent an Action Node in an activity diagram as a nested activity. The flow of tokens in a nested activity execute as an invocation action. An invocation action can only be executed sequentially and cannot have multiple concurrent invocations.

When an action starts, one instance of the action executes, and if new tokens arrive, new tokens will wait in the input pin. The input pin is a queue. The Token Multiplicity parameter in the Property Inspector for an input pin determines the size of the queue.

The RobotActivity activity diagram with the Plan Path action node with Behavior Type Activity to implement a nested activity.

Change the Behavior Type parameter in the Property Inspector to Activity to implement a nested activity, then double-click your action node to author your nested activity.

The Plan Path nested activity in the Plan Path action node in RobotActivity shows two action nodes called Do Plan Path and Apply Path Limits both with MATLAB function behavior.

The nested activity Plan Path executes normally according to the MATLAB function behaviors on each of the serially connected action nodes Do Plan Path and Apply Path Limits. Path planning calculates the path in steps:

Turn the robot to the starting orientation.
Move the robot in the x-direction.
Turn the robot from the x-direction to the y-direction.
Move the robot in the y-direction.
Turn the robot to the ending orientation.

Use MATLAB Action Node without MATLAB Function to Initialize Object Token

When you author your activity diagram and connect flow lines between object pins on action nodes, to describe the sequence of actions, a MATLAB action can be used without any MATLAB function.

Note

For an action node where a MATLAB function is not defined, a default token with all attributes set to 0 is created on the output pin.

The Initialize Path Follower action node with Behavior Type set to MATLAB, has no defined MATLAB Function Name. You can specify the output pin type to initialize an object token type for the next action node.

Initialize Path Follower action node with one output pin with an owned type called Count.

The output pin stores a token that travels down the flow line to the next action node input pin. For the Initialize Path Follower action node, specify the type of the output pin Count as owned type with type double and dimension of 1.

Note

When you initialize a datatype in the Types Editor, the options include fixed point and enumerations. Due to limited support, compile time checks are active. Compile your activity diagram using CTRL+D to validate your datatypes.

Use Control Nodes to Manipulate Token Flows

Control flows constrain the timing and ordering of the execution of actions in an activity diagram using control nodes.

A control node routes a logical flow of tokens through the system.

Use control nodes and flows to route tokens. Control nodes can be used to initialize, split, merge, and terminate token flows.

Use Fork Node to Split Control Flow

A Join or Fork Node node replicates an input control token on each output flow when implemented as a fork node.

Fork node replicating a token from one control flow to two control flows.

The control flows transport the control tokens to two different action nodes and begins execution.

Use Decision Node to Create Conditional Flow

A Decision or Merge Node routes an input token to a particular output flow based on the evaluation of decision conditions when implemented as a decision node. You can use a decision node to manipulate token flow to demonstrate the following scenario: When there is enough battery life for the robot to follow the calculated path distance, the robot can follow its path.

A decision node routes an input token to an output flow based on decision conditions.

When the function isBatteryLifeSufficient evaluates to true after taking the current token value from the built in variable, token, the token continues to the Follow Path action node. Otherwise, the token is routed to the Error out action node.

To access the token flowing through the flow, use the built in keyword token. When the isBatteryLifeSufficient(token) function evaluates to true, the token continues to the Follow Path action node. When the isBatteryLifeSufficient(token) function evaluates to false, the token is routed to the Error out action node.

Create Loops with Decision and Merge Nodes

When you have an iterating function that uses a count variable to keep track of number of loops until completion, you can use a Decision or Merge Node to route tokens to and from the same action node.

Issue Command is a looped MATLAB function behavior action node.

In this example, the nested activity Follow Path contains an Issue Command action node that loops five times before the mobile robot completes following the path.

End Flows and Activity with Final Nodes

You can use a Flow Final Node to terminate one object or control, but not the entire activity. Flow final nodes are used in the Follow Path activity diagram above. You can use an Activity Final Node to terminate the incoming token and the parent activity.

Error out activity ends in an activity final node.

After the mobile robot path planning errors out, the activity ends via an activity final node.

Simulate and Validate Activity Diagrams

Now that you learned how to author an activity diagram for a mobile robot following a path, you can simulate the activity diagram to visualize token flow. For more information, see Simulate, Visualize, and Validate Activity Diagrams.