Author Activity Diagrams

Activity diagrams describe the functional flow behavior of an architectural system. You can use activity diagrams 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 describes an activity in an architectural system. 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.

Use activity diagrams to conceptualize a system, visualize functional flow through actions or decisions, and understand how system components interact with one another.

This topic shows you how to 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 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.

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.

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

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. 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 are objects that flow in the activity diagram. A token can represent data such as structures and integers, or a token can simply pass on the control.

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

To begin your activity, use an Initial Node to place a control token on the single outgoing flow.

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

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

These are the types of flows:

Object flow — Tokens in an object flow contains token data on which actions operate. You can use object flows to route input or output tokens to carry information or physical items between object nodes.
Control flow — Tokens in a control flow trigger the execution of actions. You can use control flows to model transfer of control from one Action Node to another.

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.

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.

A cursor shows an action node that was dragged 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.

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.

To implement MATLAB function behavior, in the Property Inspector, set Behavior Type to MATLAB. Then, in the MATLAB Function Name text box, enter 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.

To view the GeneratePosition.m function file in the MATLAB editor, double-click the Select Target Position action node.

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 three-dimensional vector with the starting position, ending position, and orientation of the robot.

To create a pin on an action node, pause on the edge of an action node and click the blue pin. Select whether to create an input pin or an output pin.

An object pin is on the right side of an action node in the activity diagram canvas.

A type defines the contents of a token that flows through a pin. A type has dimension, unit, complexity, minimum, maximum and description.

These are three token types in activity diagrams:

Value type: A value type is a type assigned to a single value.
Composite type: A composite type is equivalent to a bus structure that contains field of different values and data types.
MATLAB class type: A MATLAB class type references a MATLAB class on the path that defines a complex object with properties and methods. You can use a built-in MATLAB class or define your own MATLAB class. For more information on using MATLAB class type, see Model Complex Objects in Activity Diagrams Using MATLAB Class Tokens.

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].

Match Action Node Pins to MATLAB Function Arguments

When the input and output arguments in the MATLAB function file match the input and output pins on your action node, you can control the expected behavior of the action node using the linked MATLAB function.

On the action node, in the Property Inspector, select Behavior Type as MATLAB, then link to a MATLAB function file on the path.
Right-click the action node, and from the context menu, select the menu option Match action pins to MATLAB function arguments.

The names and numbers of input and output pins on the action node match the names and numbers of input and output arguments in the linked MATLAB function.

Use Nested Activity to Describe Action

You can represent an action node in an activity diagram as a nested activity. The action that you describe using nested activity 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, they 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.

To implement a nested activity, in the Property Inspector, set Behavior Type to Activity. Then, to author your nested activity, double-click your action node.

A parameter node route tokens into or out of a nested activity diagram. When a pin is created, a corresponding parameter node will be created inside the nested activity.

Use parameter node to define how tokens enter or leave a nested activity. There are two types of parameter nodes input and output.

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 action notes have 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, you can use a MATLAB action 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 an owned type with type double and a dimension of 1.

Note

When you initialize a data type 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 data types.

Use Action Node to Generate Control Flow

To generate control flow from an action node, click on side of the node and drag it to the other nodes.

The RobotActivity activity diagram with a control flow from an action node.

Use Control Nodes to Manipulate Token Flows

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.

A fork node replicates 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. Use a decision node to manipulate token flow to demonstrate this scenario: When enough battery life remains 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 the 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. The Follow Path activity diagram uses flow final nodes. 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 know 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.