CONTROL ALGORITHM MODELING
GUIDELINES USING MATLAB
®
,
Simulink
®
, and Stateflow
®
Version 3.0
MathWorks Automotive Advisory Board
(MAAB)
CONTROL ALGORITHM MODELING GUIDELINES USING MATLAB
®
, SIMULINK
®
, AND
STATEFLOW
®
............................................................................................................................................. 1
1. HISTORY.................................................................................................................................................. 6
2. INTRODUCTION .................................................................................................................................... 7
2.1. MOTIVATION ........................................................................................................................................ 7
2.2. NOTES ON VERSION 3.0 ......................................................................................................................... 7
2.3. GUIDELINE TEMPLATE .......................................................................................................................... 7
2.3.1. Guideline ID: ................................................................................................................................ 8
2.3.2. Guideline Title: ............................................................................................................................. 8
2.3.3. Priority: ........................................................................................................................................ 8
2.3.4. Scope: ........................................................................................................................................... 9
2.3.5. MATLAB
®
Versions ...................................................................................................................... 9
2.3.6. Prerequisites: ............................................................................................................................... 9
2.3.7. Description: .................................................................................................................................10
2.3.8. Rationale: ....................................................................................................................................10
2.3.9. Last change: ................................................................................................................................10
2.4. DOCUMENT USAGE ..............................................................................................................................10
2.4.1. Guideline Interaction Semantics ..................................................................................................10
2.4.2. Masked Subsystems and Readability Rules .................................................................................11
3. SOFTWARE ENVIRONMENT ............................................................................................................12
3.1. GENERAL GUIDELINES ........................................................................................................................12
3.1.1. na_0026: Consistent software environment ................................................................................12
3.1.2. na_0027: Use of only standard library blocks ............................................................................12
4. NAMING CONVENTIONS ...................................................................................................................14
4.1. GENERAL GUIDELINES ........................................................................................................................14
4.1.1. ar_0001: Filenames .....................................................................................................................14
4.1.2. ar_0002: Directory names ...........................................................................................................14
4.1.3. na_0035: Adoption of naming conventions .................................................................................15
4.2. MODEL CONTENT GUIDELINES ............................................................................................................16
4.2.1. jc_0201: Usable characters for Subsystem name ........................................................................16
4.2.2. jc_0211: Usable characters for Inport block and Outport block ................................................16
4.2.3. jc_0221: Usable characters for signal line name ........................................................................17
4.2.4. na_0030: Usable characters for Simulink Bus names .................................................................17
4.2.5. jc_0231: Usable characters for block names ..............................................................................18
4.2.6. na_0014: Use of local language in Simulink and Stateflow ........................................................19
5. MODEL ARCHITECTURE ..................................................................................................................21
5.1. SIMULINK
®
AND STATEFLOW
®
PARTITIONING .....................................................................................21
5.1.1. na_0006: Guidelines for mixed use of Simulink and Stateflow....................................................21
5.1.2. na_0007: Guidelines for use of Flow Charts, Truth Tables and State Machines ........................27
5.2. SUBSYSTEM HIERARCHIES ...................................................................................................................27
5.2.1. db_0143: Similar block types on the model levels .......................................................................27
5.2.2. db_0144: Use of Subsystems .......................................................................................................29
5.2.3. db_0040: Model hierarchy ..........................................................................................................30
5.2.4. na_0037: Use of single variable variant conditionals .................................................................30
5.2.5. na_0020: Number of inputs to variant subsystems ......................................................................31
5.2.6. na_0036: Default Variant ............................................................................................................31
5.3. J-MAAB MODEL ARCHITECTURE DECOMPOSITION ............................................................................32
5.3.1. jc_0301: Controller model ..........................................................................................................32
5.3.2. jc_0311: Top layer / root level ....................................................................................................33
5.3.3. jc_0321: Trigger layer .................................................................................................................34
5.3.4. jc_0331: Structure layer ..............................................................................................................34
5.3.5. jc_0341: Data flow layer .............................................................................................................35
6. MODEL CONFIGURATION OPTIONS .............................................................................................37
6.1.1. jc_0011: Optimization parameters for Boolean data types .........................................................37
6.1.2. jc_0021: Model diagnostic settings .............................................................................................37
7. SIMULINK ..............................................................................................................................................39
7.1. DIAGRAM APPEARANCE ......................................................................................................................39
7.1.1. na_0004: Simulink model appearance ........................................................................................39
7.1.2. db_0043: Simulink font and font size ...........................................................................................40
7.1.3. db_0042: Port block in Simulink models .....................................................................................40
7.1.4. na_0005: Port block name visibility in Simulink models .............................................................41
7.1.5. jc_0081: Icon display for Port block ...........................................................................................42
7.1.6. jm_0002: Block resizing ..............................................................................................................43
7.1.7. db_0142: Position of block names ...............................................................................................43
7.1.8. jc_0061: Display of block names .................................................................................................44
7.1.9. db_0146: Triggered, enabled, conditional Subsystems ...............................................................45
7.1.10. db_0140: Display of basic block parameters ............................................................................46
7.1.11. db_0032: Simulink signal appearance ......................................................................................47
7.1.12. db_0141: Signal flow in Simulink models ..................................................................................47
7.1.13. jc_0171: Maintaining signal flow when using Goto and From blocks ......................................48
7.1.14. na_0032: Use of Merge Blocks ..................................................................................................49
7.1.15. jm_0010: Port block names in Simulink models ........................................................................50
7.1.16. jc_0281: Naming of Trigger Port block and Enable Port block ................................................50
7.2. SIGNALS ..............................................................................................................................................51
7.2.1. na_0008: Display of labels on signals .........................................................................................51
7.2.2. na_0009: Entry versus propagation of signal labels ...................................................................52
7.2.3. db_0097: Position of labels for signals and busses .....................................................................53
7.2.4. db_0081: Unconnected signals, block inputs and block outputs .................................................54
7.3. BLOCK USAGE .....................................................................................................................................54
7.3.1. na_0003: Simple logical expressions in If Condition block ........................................................54
7.3.2. na_0002: Appropriate implementation of fundamental logical and numerical operations .........56
7.3.3. jm_0001: Prohibited Simulink standard blocks inside controllers ..............................................57
7.3.4. hd_0001: Prohibited Simulink sinks ............................................................................................59
7.3.5. na_0011: Scope of Goto and From blocks ..................................................................................59
7.3.6. jc_0141: Use of the Switch block .................................................................................................60
7.3.7. jc_0121: Use of the Sum block ....................................................................................................61
7.3.8. jc_0131: Use of Relational Operator block .................................................................................63
7.3.9. jc_0161: Use of Data Store Read/Write/Memory blocks .............................................................63
7.4. BLOCK PARAMETERS ...........................................................................................................................64
7.4.1. db_0112: Indexing .......................................................................................................................64
7.4.2. na_0010: Grouping data flows into signals ...............................................................................64
7.4.3. db_0110: Tunable parameters in basic blocks ............................................................................65
7.5. SIMULINK PATTERNS ...........................................................................................................................66
7.5.1. na_0012: Use of Switch vs. If-Then-Else Action Subsystem ........................................................66
7.5.2. db_0114: Simulink patterns for If-then-else-if constructs ...........................................................67
7.5.3. db_0115: Simulink patterns for case constructs ..........................................................................68
7.5.4. na_0028: Use of If-Then-Else Action Subsystem to Replace Multiple Switches ..........................69
7.5.5. db_0116: Simulink patterns for logical constructs with logical blocks .......................................70
7.5.6. db_0117: Simulink patterns for vector signals ............................................................................71
7.5.7. jc_0351: Methods of initialization ...............................................................................................73
7.5.8. jc_0111: Direction of Subsystem .................................................................................................75
8. STATEFLOW ..........................................................................................................................................77
8.1. CHART APPEARANCE ...........................................................................................................................77
8.1.1. db_0123: Stateflow port names ...................................................................................................77
8.1.2. db_0129: Stateflow transition appearance ..................................................................................77
8.1.3. db_0137: States in state machines ...............................................................................................78
8.1.4. db_0133: Use of patterns for Flowcharts ....................................................................................79
8.1.5. db_0132: Transitions in Flowcharts ...........................................................................................79
8.1.6. jc_0501: Format of entries in a State block ................................................................................81
8.1.7. jc_0511: Setting the return value from a graphical function .......................................................82
8.1.8. jc_0531: Placement of the default transition ...............................................................................83
8.1.9. jc_0521: Use of the return value from graphical functions .........................................................84
8.2. STATEFLOW DATA AND OPERATIONS ...................................................................................................85
8.2.1. na_0001: Bitwise Stateflow operators .........................................................................................85
8.2.2. jc_0451: Use of unary minus on unsigned integers in Stateflow .................................................87
8.2.3. na_0013: Comparison operation in Stateflow .............................................................................87
8.2.4. db_0122: Stateflow and Simulink interface signals and parameters ...........................................88
8.2.5. db_0125: Scope of internal signals and local auxiliary variables ..............................................89
8.2.6. jc_0481: Use of hard equality comparisons for floating point numbers in Stateflow .................90
8.2.7. jc_0491: Reuse of variables within a single Stateflow scope ......................................................91
8.2.8. jc_0541: Use of tunable parameters in Stateflow ........................................................................93
8.2.9. db_0127: MATLAB commands in Stateflow ................................................................................93
8.2.10. jm_0011: Pointers in Stateflow .................................................................................................94
8.3. EVENTS ...............................................................................................................................................95
8.3.1. db_0126: Scope of events ............................................................................................................95
8.3.2. jm_0012: Event broadcasts .........................................................................................................95
8.4. STATECHART PATTERNS ......................................................................................................................97
8.4.1. db_0150: State machine patterns for conditions .........................................................................97
8.4.2. db_0151: State machine patterns for transition actions ..............................................................98
8.5. FLOWCHART PATTERNS .......................................................................................................................98
8.5.1. db_0148: Flowchart patterns for conditions ...............................................................................98
8.5.2. db_0149: Flowchart patterns for condition actions ..................................................................100
8.5.3. db_0134: Flowchart patterns for If constructs ..........................................................................101
8.5.4. db_0159: Flowchart patterns for case constructs .....................................................................103
8.5.5. db_0135: Flowchart patterns for loop constructs .....................................................................105
8.6. STATE CHART ARCHITECTURE ...........................................................................................................106
8.6.1. na_0038: Levels in Stateflow charts ..........................................................................................106
8.6.2. na_0039: Use of Simulink in Stateflow charts ...........................................................................107
8.6.3. na_0040: Number of states per container .................................................................................108
8.6.4. na_0041: Selection of function type ..........................................................................................108
8.6.5. na_0042: Location of functions .................................................................................................109
9. ENUMERATED DATA ........................................................................................................................111
9.1.1. na_0033: Enumerated Types Usage ..........................................................................................111
9.1.2. na_0031: Definition of default enumerated value .....................................................................111
10. MATLAB FUNCTIONS .....................................................................................................................112
10.1. MATLAB FUNCTION APPEARANCE ................................................................................................112
10.1.1. na_0018: Number of nested if/else and case statement ..........................................................112
10.1.2. : na_0019: Restricted Variable Names ...................................................................................112
10.1.3. na_0025: MATLAB Function Header.....................................................................................113
10.2. MATLAB FUNCTION DATA AND OPERATIONS ...............................................................................113
10.2.1. na_0034: MATLAB Function block input/output settings ......................................................113
10.2.2. na_0024: Global Variables ....................................................................................................114
10.3. MATLAB FUNCTION PATTERNS .....................................................................................................115
10.3.1. na_0022: Recommended patterns for Switch / Case statements .............................................115
10.4. MATLAB FUNCTION USAGE ..........................................................................................................116
10.4.1. na_0016: Source lines of MATLAB Functions .......................................................................116
10.4.2. na_0017: Number of called function levels ............................................................................116
10.4.3. na_0021: Strings.....................................................................................................................117
11. APPENDIX A: RECOMMENDATIONS FOR AUTOMATION TOOLS ....................................119
12. APPENDIX B: GUIDELINE WRITING ..........................................................................................120
13. APPENDIX C: FLOWCHART REFERENCE ................................................................................121
14. OBSOLETE RULES ...........................................................................................................................127
14.1. REMOVED IN VERSION 2.2 ...............................................................................................................127
14.2. REMOVED IN VERSION 3.0 ...............................................................................................................127
15. GLOSSARY .........................................................................................................................................128
