UML - Getting Started EA v4.0

UML - Getting Started Codegeneration with Enterprise Architect How to generate Code from an Enterprise Architect UML Model with the help of and Willert Software Tools RXF (Realtime execution Framework) & LieberLieber Software GmbH!! Page - 1 - UML - Getting Started EA v4.0

Welcome to our UML - Getting Started. In this tutorial, everything revolves around the first practical steps in the world of Embedded UML. With the help of a tiny object-oriented UML-Blinky model, we will make a small journey through the UML and present the functions of the required software. We provide the necessary programs as free evaluation version for you either as download or as DVD. This will enable you to use the software without restrictions during a 30 day evaluation period. As target environment we use the Launchpad from Texas Instruments with an MSP430G2553. Unfortunately only a few people will probably be in the possession of this evaluation board, so you can test our final program at the end of this tutorial with help of the simulator built-in in IAR Embedded Workbench IDE. So, apart from a PC, you do not need additional hardware. If you want, however, you can purchase a Launchpad board from Willert Software Tools GmbH or directly from the TI Website. For the toolchain installation and implementation of this tutorial you should reserve about 60 minutes and two cups of. Have fun and success with it... - Sparx Systems Enterprise Architect - IAR Embedded Workbench for TI MSP430 - TI Launchpad MSP430 v. 1.5! & LieberLieber Software GmbH! Page - 2 - UML - Getting Started EA v4.0

Software & Installation We start with the installation of our toolchain. All software you need is located on our Willert Demo-DVD. In addition to the necessary tools you will also find an installation guide that will guide you quickly through the installation process. Therefore we will not describe the installation process in detail in this tutorial. We rather briefly discuss the possibilities of the individual tools. IAR Embedded Workbench You can order or download this free Demo-DVD on our website: TI Launchpad www.willert.de/uml-getting-started Tool description Sparx Systems Enterprise Architect First, we need a UML modeling tool, to create our UML model. In this tutorial, we will use Enterprise Architect for this job. Our example will be modeled completely with the help of this environment. LieberLieber Embedded Engineer RXF Lieber Lieber Embedded Engineer is a powerful and fast code generation solution for Enterprise Architect. We use this plug-in to generate efficient C code from our model. The RXF edition of Embedded Engineer allows a direct integration with the RXF. Realtime execution Framework (RXF) The UML notation is much more powerful than ANSI C. C doesn't know anything about object orientation, timer, events, etc. So, we need a framework to get the full advantage of the UML. The Willert Embedded UML RXF enables us to put all the UML benefit into our embedded system. The RXF also combines Enterprise Architect with different IDEs, such as IAR Embedded Workbench. & LieberLieber Software GmbH We need the IAR Embedded Workbench IDE to flash our executable model to the target or to let it run in the built-in simulator. On top of that the IDE offers additional debugging possibilities for our model. The code limitation of the evaluation version is 4 kbyte. If you want to use real hardware for your application we suggest the Launchpad (version 1.5 or higher) from Texas Instruments. This board supports the MSP430G product family. But not every target device of the MSP430G product family is suitable for our RXF framework. Make sure that the used target device has at least 8 kbyte of ROM and 512 kbyte of RAM. We suggest the MSP430G2553. In order to check for correct assembly, make sure that your board looks like in the following picture: Ensure that the jumpers for UART are set to HW UART mode, if you want to use the Willert Embedded UML T a r g e t Debugger. A d d i t i o n a l l y, make sure that the controller is placed correctly on the socket with the nose at top to avoid a short circuit. System Requirements (minimum) Win XP (SP1/SP2/SP3) / Win 7 1,5GB free disk space / 512MB RAM Page - 3 - UML - Getting Started EA v4.0

Start and Customize - Enterprise Architect Now let s start Enterprise Architect and model an object-oriented UML Blinky application. Of course, we could save a few pages, by omitting classes and objects in this simple Blinky. However, since we will later mostly work in an object oriented style, we'd rather just put a solid foundation. ;-) Close the EA Project dialog box. We want to make room, especially if we don't have a high resolution screen. Close the following subwindows on the left side. Learning Center Pan & Zoom Layout Tools Diagram Filters At the borders of the EA window, we find some pinned subwindows. We don t need them. You can close them. First of all, we will customize the Enterprise Architect window for our purposes. Please note: The following proposed view is only a suggestion. Of course, you can adjust everything according to your own wishes. But just for the first steps, we want to hide anything that is unnecessary in this tutorial. Make sure that the view System Output is opened. Open it by selecting View -> System Output from the menu. In the System Output view, select the tab LieberLieber Embedded Engineer RXF. Our Enterprise Architect window is now configured for our purposes. & LieberLieber Software GmbH! Page - 4 - UML - Getting Started EA v4.0

The Enterprise Architect Window Toolbox for Diagrams Diagram Area Project- Browser Codegeneration Output This is all we need... Project Browser The Enterprise Architect window is now composed of four areas. On the right side, we will find the project browser. Similar to the Windows Explorer, we can navigate in the model by using the (+/-) symbols. All elements of our UML model are accessible through the browser. Every element we can see inside a UML diagram, can also be found here. Diagram Area & Toolbox UML is a graphical notation. Today, the UML knows thirteen different types of diagrams. We need some space to draw these diagrams. In the middle of the EA window, we find the Digram Area and to the left of this area the toolbox. The toolbox automatically adapts to the displayed diagram type. E.g. if we draw a statechart, we will find states in the toolbox. If we have opened more than one diagram at the same time, we will find a tab bar below the diagram area. Here, we can switch easily between these diagrams. System Output We need the System Output area to be able to see the output from the Embedded Engineer code generator. There are a few tabs in the System Output area, which are used by different parts of Enterprise Architect. & LieberLieber Software GmbH! Page - 5 - UML - Getting Started EA v4.0

Create a Project and a Component Select File / New Project from the EA menu. Choose a location for your EA model. Your project will be stored as a single *.eap file. Select LieberLieber Embedded Engineer -> Embedded Engineer RXF Diagram as diagram type and enter Component Runtime as name and create the new diagram. The first element we need in our model is a package, which we use as container for other model elements. Create one by pressing the Add Package button in the Project Browser. The diagram will automatically be opened. Select RXF Component with RXF_Main from the Toolbox and create a new RXF Component in your diagram. If the tool is not available, you have to select More tools... and set the toolbox LieberLieber Embedded Engineer RXF as active. Double click on the component and set MSP430 as its name. Afterwards, a dialog will automatically open and ask for the name of the package. Enter Blinky as name and confirm the dialog by pressing OK. As main entry for our application, we need to create a component. You can think of a component as an executable piece of software. For creating a component, we need a new diagram at first. Therefore, select New Diagram in the Project Browser. In the properties dialog of the new component (double click on it), select to investigate its values for LieberLieber Embedded Engineer RXF. For the RXF Environment p r o p e r t y, s e t t h e Installation path of your RXF (i.e. C: \Willert\EA_C_OORTX_IAR_MPS430\). Confirm the dialog by pressing OK. Thereby, a connection between your model and the Willert RXF is made. & LieberLieber Software GmbH! Page - 6 - UML - Getting Started EA v4.0

Classes and Operations Now, we need a container for our methods and attributes - a class. The component is needed for code generation later. We could create the class inside the same diagram as we used for the component - or we could use a new diagram for this job. Let s create a new class diagram System Overview. Select the Blinky package and press the New Diagram button. A new dialog appears, in which you have to enter the name of the diagram and the diagram type. As diagram Type, select UML Structural -> Class. When closing the dialog, the new class diagram will automatically be opened. We can find the newly create class also in the project browser inside the Blinky package. If we had created the class directly in the browser, the class would not automatically appear in the System Overview diagram. Our class should get a more meaningful name. We can rename model elements quickly by a slow double click. This could either be done in the browser or diagram. Our class should be named LED. The LED class should turn a particular LED on and off. Therefore, we create two operations. Right click the LED class and select Features & Properties -> Operations... from the contextual menu. A new window called LED Operations will open. Select the Class element from the toolbox and click into the digram surface. Type off into the Name field, select void as Return Type and click the Save button. After that, click the New button and repeat the last steps with an operation named on. & LieberLieber Software GmbH! Page - 7 - UML - Getting Started EA v4.0

Initializer and Attributes The last operation we want to create is an initializer. Later, when we instantiate an object from the LED class, the initializer will automatically be called once. Right click on the LED class and select Features & Properties -> Attributes... from the contextual menu. In order to create the attribute, type bitnr into the Name field, select int as Type, enter 0 as Initial Value and click the Save button. In the operations dialog of the LED class, click the New button again and create a operation named init. Watch out, we must now select constructor as stereotype. Verify the result in the project browser or class diagram: In order to be able to turn the LED on and off, the port pin has to be set to operate as output. We do this inside the init() operation of the class LED. Double click on the operation to open a dialog LED Operation: init for it.in the dialog, select Behavior below Properties on the left side. Afterwards, enter the following code as Initial Code : The LED class needs an attribute, which contains a valid port pin in order to control a LED of the MSP430. Why is the attribute accessed by using a pointer me? ANSI C knows nothing about object orientation. We need a struct to imitate the encapsulation of a class. Our class attributes can be accessed by using the me-pointer. If we would generate code now, the code generator would create the struct and the declaration of the initializer operation like this: & LieberLieber Software GmbH! Page - 8 - UML - Getting Started EA v4.0

Operation Implementation & Interfaces Now our initializer is complete and we can deal with both on- and offoperations. These two operations should be responsible to set the Port-Pin, which we defined as output in our initializer, to low or high respectively. Set the behavior for these operations inside their dialogs as you have done with the initializer operation. Let s start with the content of the Initial Code field of the off operation. Enter the following code as Initial Code : Select Interface from the diagram toolbox and click on the diagram surface. As name for the interface, enter msp430g2553. It is specified in your model now, that there is a header file msp430g2553.h, but there is no relationship between your class LED and this header file. To address this, create a Usage Dependency from your LED to the interface. Make sure you select Usage Dependency from the toolbox and not another relationship which looks similar!...and after that, enter the following Initial Code for the on operation Now we should give our model a link to the header file that describes our specific hardware so that our compiler knows what to do with the hardware specific C -code in the Init -, off - and on - operations. After the next code generation, our LED.h header file, which is generated for the class LED, contains the code: #include msp430g2553.h & LieberLieber Software GmbH! Page - 9 - UML - Getting Started EA v4.0

Relationships Between Classes In order to show you some more advantages about object orientation, let s create another class, which communicates with our LED class. Create a new class in your diagram and name it Controller. An object of a Controller can access attributes of a related LED now, but not the other way around. Now, your class diagram should look like this: For creating relationships between elements, there is also the possibility to select an element and then click on the arrow that appears in the upper right corner and hold your mouse button down. Afterwards, move your mouse cursor to the intended target element and release the mouse button. A menu will appear, in which you can select what kind of relationship will be created. In this case, create a Directed Association This will result in the following struct for the Controller when generating code: After creating the association, open its dialog by making a double click on it. As Target Role, enter myled to define the name of the attribute which is generated in the struct of this class for the association. & LieberLieber Software GmbH! Page - 10 - UML - Getting Started EA v4.0

Statecharts Our initializer will be automatically called at the initialization of the LED class. But who will now call both our off - and on - operations? For that we use one of the most commonly used UML diagrams. The statechart (state machine). In the project browser, we right click on the LED class, and find our way through the menus. We begin to create two states. Select the State element in the toolbox and click into the diagram surface. A new window shows us the state features. We rename State1 in S_ON. Select Add / State Machine in the contex-tual menu. After this step, our model looks like it is shown on the right side. Close the window and create a S_OFF state in the same way. After that, our diagram should look like this: Make sure the StateMachine tab is selected at the bottom of the diagram area. We need a transition from the S_ON state to the S_OFF state. Select the S_ON state. Now we find an arrow symbol in the upper right corner. Left click this arrow drag it to the S_OFF state. Choose Transition from the menu. & LieberLieber Software GmbH! Page - 11 - UML - Getting Started EA v4.0

Statecharts Move the first transition a bit upwards and draw another transition from the S_OFF state back to the S_ON state. In the General tab, enter a name e.g. on, set Action to entry and click the save button. Now, select the Behavior tab and click the Element button. Now, we need an entry point for our statechart. Select Initial from the toolbox and click above the S_ON state on the diagram surface. We don t want to edit the Initial features. Close this appearing dialog. Select the Initial and drag the arrow to the S_ON state. Choose Transition from the contextual menu to create a transition from the initial state to the state S_ON. A new dialog pops up. We have to select the on() operation. Afterwards, click t h e OK button. Close the parent dialog. The S_ON state is finished. If our program enters the S_ON state, the on() operation should be called. Right click on the S_ON state and select Features & Properties -> Operations.. from the contextual menu. Repeat the same steps to define the behavior for the S_OFF state: Right click on the S_OFF state Select Features & Properties -> Operations... Enter the Name: off Set Action: entry Click on Save Select the Behavior tab Click on Element Select the off() operation Click on OK and Close the dialog & LieberLieber Software GmbH! Page - 12 - UML - Getting Started EA v4.0

Statecharts Now, our statechart would toggle between both states, as fast as the MSP430 allows. The transitions between these states would be executed immediately after starting the state machine. In order to change this, we have to set triggers for the transitions. We will use the same trigger for both transitions to toggle between the two states. Make a double click on a transition to open a new dialog. In the dialog, enter/select the following: Name: trigtoggle Type: Signal Now close and save all dialogs. Next, we have to set the trigger for the other transition. Therefore, open its dialog. We already have created a trigger for the first transition. There is no need to create another one, since both shall respond to the same signal. Click on the highlighted button and navigate to the existing time trigger. Close both windows with the OK button. When you select Signal as type, a new dialog will open to choose a signal from the model. Since there is none, create a new one by pressing the Add New button in the dialog. Another dialog appears, in which you have to enter a name for the signal. As name, enter sigtoggle and confirm the dialog by pressing Create. & LieberLieber Software GmbH! Page - 13 - UML - Getting Started EA v4.0

Statecharts The statechart for the LED is finished and should look like this: Now, let s create another statechart for the class Controller. We want to achieve, that the Controller lets the LED toggle between its two states. Create a state S_Blinking_LED inside your new statechart and an Initial State with a Transition to state S_Blinking_LED. Define a new Time Trigger by entering trigtimeout300ms as its name and setting the Type of the Trigger to Time. As Specification, enter 300, which is a value definition in ms. Before closing the dialog, also set an Effect for the transition. You can enter any code here which is executed, when the transition is followed. In our case, we want to send the toggle event to the LED class. We achieve this by entering the following code as effect: FIRE( me->myled, sigtoggle ); Finally, press Save and confirm the dialog with OK. In order to show you how to work with time triggers, we want our statechart to follow a transition every 300ms. The transition has the state S_Blinking _LED as source as well as as target. First, just create such a transition for the state. We want to add the time trigger to the transition now. As for setting the other triggers, open the dialog for the transition. Your statechart should look like this now: & LieberLieber Software GmbH! Page - 14 - UML - Getting Started EA v4.0

Create Instances/Objects Although we could generate and compile our UML model, there would be no blinking LED on the MSP430. A class is not being executed at runtime, because a class is only a blueprint for an object. To create objects for our classes at runtime, we have to instantiate them first. In Enterprise Architect, we can define objects inside our component, which we created at the beginning of this document. Open the previously created diagram Component Runtime again. Since we want to create objects inside the component, use the anchor points to make it larger. We have to explicitly set the type for each object. This can be done in the context menu of objects by selecting Advanced -> Instance Classifier.... As we created two classes, we want to create two objects - one for each class. Select the Object entry in the toolbar and create two objects inside the component. Name one object controller and the other one led. & LieberLieber Software GmbH! Page - 15 - UML - Getting Started EA v4.0

Create Instances / Objects For the object controller, set the class Controller as classifier and for the object led the class LED. Inside the diagram, the types of the objects are displayed after their names. Your diagram should look like this: We have to set the link s Target Role to the same as we did for the association. Open the dialog for the link and enter myled as role. The two objects are defined, but they can not communicate with each other. We already created an association between their classes - but we also have to define a Link between these objects. When selecting the object controller, you can drag the arrow, which appears in the upper right corner, to the object led. Afterwards, select to create a Directed Link. & LieberLieber Software GmbH! Page - 16 - UML - Getting Started EA v4.0

Generate / Deploy Finally, let us start with the code generation. Open the context menu for the component MSP430 in the Project Browser and select Extensions -> LieberLieber Embedded Engineer RXF -> Generate and Deploy Code Afterwards, the following dialog will appear. If it does not appear, make sure you have set the correct RXF Path for your component. in the dialog, set RXF Library is used. This option is needed for using precompiled libraries of the RXF, as they are delivered with Evaluation versions. Press Save to close the dialog and start the code generation and deployment, in which the generated code is added to the IDE project. If you want to take a look at the progress, make sure to open the System Output by selecting View -> System Output from the menu. In the System Output view, select the tab LieberLieber Embedded Engineer RXF. You can open the IDE project now by selecting Open IDE Project from the context menu of your component.. Best Practice Tip Inside the dialog, you have to select an IAR Embedded Workbench IDE Project. There are already templates for such projects inside your RXF installation path in the subdirectory \Samples\Code. Select the file GettingStarted.eww inside the folder \Samples\Code\GettingStarted. If you still want to use the project as template later, make a copy of it before selecting it as IDE Project. Furthermore, The deployer config dialog opens automatically at the first startup and stores your settings. The next time you generate code, it will not open again. If you want to edit the target IDE Project afterwards, click on the Open Deployer Configuration menu entry. & LieberLieber Software GmbH! Page - 17 - UML - Getting Started EA v4.0

IAR Embedded Workbench Of course, now we want to see if our LED's will flash in rhythm. First we need to compile the generated files with the make button. If we did everything correct until now we get 0 errors. You can also find a working Blinky sample inside the folder Sample/Model/Blinky/ of the installed product. If everything is assembled correctly you can connect the board via USB to the host. No additional programming hardware is needed. All you need to do is to flash the device or enter the simulator (if no hardware available). If you connect the launchpad for the first time, you will be asked to install the driver for the board. Just follow the instructions on the screen and the driver will be installed automatically. You don t need any additional driver software. The Launchpad will appear now as serial connection in your device manager. This connection can be used as any other serial connection with an ordinary terminal application. Now, it is time to enter the debug mode with the download and debug button in the toolbar. The application can be controlled by using the toolbar to run/stop the application and to step through the application on C level. In order to debug on C-level, you can use breakpoints and it is possible to step through the application. This makes it very difficult to check for a correct logical and timing behavior of the model e. g. display current states of instances or executed events. For this reason, we provide the UML Target Debugger, which can be used to display and affect the target behavior on runtime. You can find a detailed description about our Target Debugger on our webpage: http://www.willert.de/embedded-umltarget-debugger/ (in german) http://www.willert.de/embedded-umltarget-debugger-en-us/ (in english) & LieberLieber Software GmbH! Page - 18 - UML - Getting Started EA v4.0

Last But Not Least Please note that we can only scratch the surface of the UML with this tutorial. UML and Enterprise Architect are book filling, powerful subjects that can, unfortunately, not be packed in a short script. Please do not be discouraged by this! With just a few solid basic skills, most projects are not a big hurdle for you anymore. Even if the UML2 has over thirteen different types of diagrams, for your first projects, you need only three of them (which lowers the mountain a bit). Now, if you are looking for more, I can highly recommend you our "Embedded UML Start- Up Training". Find out all about the possibilities of the UML and how to deal with Enterprise Architect in a compact training. More information about this course is available on our homepage: http://www.willert.de/events/ For questions about Enterprise Architect and the UML, please use this forum: http://www.willert.de/uml-forum/ I hope I was able to arouse your curiosity in this fascinating subject and would be delighted to see you in our next UML - Startup Training. Editor: WILLERT SOFTWARE TOOLS GMBH Hannoversche Straße 21 31675 Bückeburg Tel.: +49 5722-9678 60 www.willert.de! info@willert.de Tel.: +49 5722 9678-60 Author:! Arne Noyer & LieberLieber Software GmbH! Page - 19 - UML - Getting Started EA v4.0

Other UML Tools, Targets and Requirements Management Willert Software Tools offers a wide range of adaptions to different microcontroller architectures, compiler toolchains, real time operating systems and hardware evaluation boards. Please check our website http://www.willert.de for a list of available platforms. Even custom adaptions can easily be done. Do not hesitate to contact us for details! We also offer other Getting Started Tutorials just like this one but for different target hardwares and different UML tools. For instance, there is also a Getting Started for the MSP430 with IBM Rational Rhapsody as UML tool. Furthermore, there is a Getting Started for using an ARM Cortex M3 hardware. It is based on using the Keil MDK-ARM compiler and prepared for the Keil MCB1700 evaluation board. You will find these tutorials including all the necessary evaluation software also on the DVD included in this package. Additionally, there is an evaluation version and Getting Started for the Willert Software Tools ReqXChanger on the DVD. The ReqXChanger allows for an easy integration between UML tools and Requirements Management tools (e.g. Polarion and DOORS). Thereby, a complete traceability from requirements to UML model elements can be achieved. Download www.willert.de/uml-getting-started-en/ Information For more information, take a look at our Embedded Software Engineering Report www.willert.de/sw-engineering-report/ or in our Techletter www.willert.de/techletter/ & LieberLieber Software GmbH! Page - 20 - UML - Getting Started EA v4.0