Introduction

As I always tell the people who attend my UML Trainings: without using Classes and Objects to split up the work your application must do, it is impossible to handle todays complexity.

Programming used to be easy, in the early days of computers and the early days of embedded. The first boards had small controllers on them that had a few kilobytes of ROM memory and a few bytes of RAM.

Getting these to work from scratch involved a day of reading some stuff and applying power to the board, then your first blinking LED was reality. (and how cool it was..)

Later using 16-bit controllers, still with Kilobytes but now more than a few,  but using ‘C’ instead of Assembler, this was already complex. Could take a few days to get the first stuff running. (Not to forget that you had to learn ‘C’ as well…

With UML the initial effort increases again, you have to learn UML, ‘C’ (or ‘C++’ ) and you have to install a lot more stuff. But this is also doable and after the initial effort you’ll notice that things go faster.

The complexity, however, is still increasing and the only way to master it will be to re-use existing stuff. This is only possible if we have “designed for re-use”.

Modeling or Programming?

That is the question. The difference is not clear to people who use Rhapsody for the first time, it is, however, crucial for the way you use your models and how you do the implementation. So just breaking up in multiple Classes and Objects is no longer sufficient, you need to be able to divide your models in “Components” that can be re-used without having to look deeply into them to understand what they do.

Rhapsody supports a couple of ways to do that in your model. You can use (parts of) other models. In the menu you have “File”, “Add to Model”.

Then a menu pops up that lets you select a Rhapsody model (Or a file in a model, i.e. a Unit like a Package or a Component) You can also select “As unit (with a “copy” tick) or as reference.

• As Reference, links the selected model element in the open model as a read-only reference. (Same GUIDs) You cannot edit the element in your Rhapsody model, you have to open the original model for that.
• As Unit, links the selected model element in the open model as a writable reference. (Same GUIDs) You can edit the element in your Rhapsody model and it will then change the original model as well.
• As Unit (with copy) copies the selected model element in the open model. (New GUIDs) You can change the element in your Rhapsody model but the original element will be left untouched.

GUIDs are the generated 128-bit ID’s that Rhapsody assigns to every Model element. Rhapsody uses the GUID to recognize model elements (It does NOT use the name for that!) So copying renews the GUIDs so there will be no name clashes with existing model elements.

Now try to model as independent as possible by using only unidirectional relations, eventually ports and interfaces. Use private attributes and operations when possible, at least describe the public interface as good as possible so re-use is easier while the re-user does not have to study the inside of your model.

Attention points.

• Paths. If you use referenced model elements, be sure that they are in the right path on all computers of all project members… Otherwise check-in  and -out will be a torture. You have to manually adapt the paths in your model. It helps to use relative paths in your model

  General::Model::ReferenceUnitPath
  General::Model::PathInProjectList
  can be helpful there. You might also use an Environment variable to point to your working directory and sync that with your colleagues. (Like the OMROOT variable that Rhapsody uses to make it independent where your Rhapsody Share directory is)

• Config Management. If you check in and out models and parts of models, it is easy to fetch a wrong version of a referenced model. Think about your CM structure!
• Names. Don’t use default names like “default” for the package, etc. Use meaningful names that can be used in their projects without causing collisions.
• Documentation. Is even more important when your model is re-used inside other models.

Tips and Tricks

• As long as you make changes in your model _and_ in the referenced model, load both models in a project (Using “File”, “Insert Project”. You have to switch the active project to make changes but it will reduce time. Rhapsody saves the Workspace separately! (You can even edit it if you make changes to your paths)
• Using Ports and Interfaces greatly improve the way you can use models in models.
• There are more ways to create Interfaces, see my Techletter about using Interfaces.

Dividing up your models.

If you have made a model that represents the hardware you use in multiple projects, you can easily use that model in all projects that use the same hardware. The nice thing is that if you have your version system right (perhaps even with a check in the model..) and really defined your interfaces, then you can use different versions of the hardware without really worrying about you model.
Another advantage is that referenced model load faster.

That’s it! Happy modeling with Rhapsody!

Walter van der Heiden (wvdheiden@willert.de)

What is it anyway?

Let me start by specifying what I mean when I say: reverse engineering, roundtrip engineering and forward engineering. All in the context of UML and Rhapsody of course.

• Reverse Engineering: Reading in existing source code and inserting it in a Rhapsody model in such a way that it continues to work.
• Roundtrip Engineering: Reading in source code that was generated by Rhapsody but was changed by the user. Note!: Please understand the difference between reverse and roundtrip! It is very different for Rhapsody to read in “strange” code then it is to read in “familiar” code.
• Forward Engineering: Something I invented myself (Or maybe it already exists then I just re-invented it…)  It is reverse engineering but the user will take the result and do the necessary steps to make a decent UML Model out of it.

So. As I already wrote in a previous post, I don’t like reverse engineering. Sometimes you need to do it but it is something that prevents good modeling IMHO.
Roundtrip Engineering is OK although Rhapsody knows 3 modes there: Basic, Advanced and Respect.

• Basic: Allows you to change code that is between the Rhapsody generated comments: /*#[ and #]*/ That is the code that you type in state-chart entry/exit/transition and in the implementation body of your operations. Nothing else, changes to other parts will be ignored when Rhapsody generates new code. Is not trivial since Rhapsody sometimes uses the same code twice and will then ignore your changes! (Of course without commenting it…. Rhapsody is a tool for real men…) ***Recommended Setting***
• Advanced: Same as Basic but also allows you to add attributes and operations. Is also OK if you know what you are doing but keep way from it until you know what the effects are of what you change.
• Respect: The “Evil Knievel” option. Or “Eddy the Eagle” if you prefer him. This allows you to change every line in the generated code. Rhapsody will try to keep it as long as it is syntactically OK. To make things worse, Rhapsody will store this information in “source artifacts” that are hidden by default. (I still wonder which sadistically inclined person designed that option….) ***Not Recommended at all Setting***. At least switch on “Show Source Artifacts” (“View”, “Browser Display Options”, “Show Source Artifacts”).

So you have to be careful using these options. This is all more valid for ‘C’ then it is for other languages like ‘C++’ and Java, these languages are much closer to the UML and can therefore produce much better results when doing reverse or roundtrip engineering!

LCD Display on the Keil MCB1700 Board

We use that board for our trainings. We do this since years and we use the LCD display on that board using some ‘C’ files that Keil provides. GLCD.C and GLCD.H. Here are these files: GLCD so you can check yourself.

The .h file has function prototypes (Useful for checking which functions are “public”!) and the defines for the colors. Reverse engineering will show these as types.

The .c file contains a couple of defines that are reverse engineered just as the all the defines in the .h file. Then there are all the functions. After examining the functions we can see that there are “public” functions (GLCD_xxxx() ) and “private” functions (spi_)

In the training we include glcd.h via the “external file” mechanism and the dependency with “Usage” stereotype. Glcd.c is inserted via the Component file and a “text element”. This works fine (And is of course aimed at learning different methods to use legacy code)

Reverse engineering also works, I tried, you can call the functions if you have reverse engineered them.

But we want something else: we want Classes that are completely generated from Rhapsody! So first we will create a class GLCD. Since SPI works a little bit different we will use a Singleton Object there.

Then we move all the functions to the respective class/object. Nice side-effect: the “me-pointer” is added automatically! But unfortunately… not to the code. This is where you have to do some work, add me-> to all uses of the attributes. I have created attributes from a few variables like orientation, bbps and position. You can add them to the init function. That is something that also needs to be done by hand: The init function must be converted into a constructor (initializer)

The SPI functions are moved to the SPI object. No me pointer is needed there but I used the variables that determine the exact version of the LCD hardware to attributes, you have to add the spi.<attribute> yourself.

The colors must be converted to an enum type. A bit of work which cannot be done automatically but it is worth it! (Why this is not done in the original ‘C’-code??)

I added some fine-tuning like converting some variables to enumerations or at least types, always a good habit in programming: let the compiler check as much as possible!

The result is quite nice: RhpGLCD, see for yourself.

Happy modeling with Rhapsody and greetings from the Bavarian Forest!

Walter van der Heiden (wvdheiden@willert.de)

Keep on dreaming…..

On the phone with a customer I noticed that the customer was disappointed in Rhapsody and in its ability to handle C source code that was externally written.
I always find it very difficult to deal with people who are not happy with the tools we sold them. But yes, it does happen sometimes and unfortunately, this was no different.

This particular customer wanted to use Rhapsody to more or less monitor his coding in C and in the meantime draw diagrams that represent his documentation. And also when it fitted better he wanted to draw in Rhapsody and then generate the C code according to his coding standard.
I never promised that such a scenario would work, I’m very sure, but this is what the customer understood from my words in earlier visits before buying.
I think that is OK, I am not offended, nor angry, nor do I take it personally. Customers are just as human as I am. I also hear what I want to hear and interpret until it’s right for me.
So, I do hear the ice cream man say: “I will be in your street today” and I do not hear him add: “but I wont be stopping…..” No problem.

The problem is that it I hate it when my customers are unhappy and I would like to change that but it I find it very difficult to transfer the correct information to a future customer during the sales process. Let’s give it a try here…

The truth, the whole truth and nothing but the truth.

NO! It is NOT possible! You cannot use Rhapsody and just continue coding C or C++ (or even Java).
Well… not entirely…. You can do some of that.
Is it any good? No, it’s not. Well.. it is OK but not more than that. If you just want to understand your fuzzy written code and expect Rhapsody to generate perfect UML diagrams so that you can understand some spaghetti code that you found on your hard disk: Keep on Dreaming. Never gonna happen.

As I always say: Reverse Engineering is a GiGo Process: Garbage in, Garbage out. There is no way that you can automatically make the incomprehensible understandable.
That is perfectly OK, badly written code should be re-designed and re-made….
(Yes, I know there are programmers that think otherwise…
– It was hard to write, it should be hard to read….
– Better write software with “built-in understandability protection” to ensure your pension plan.
…but I do not agree there…)

Now in C++ or Java the conversion to UML works reasonably well since these languages already support OO like UML does. But even in these languages you have to comply with Rhapsody coding, it is not a simple process. Reverse Engineering for C, however, is a totally different matter.
There are some YouTube movies in the internet describing RE in Rhapsody (see links at the bottom) but for these demo’s they all used Rhapsody in C++.
And there is a reason for that…

But before I tell you what is possible and what not in Rhapsody in C, may I gently remind you that Rhapsody is a UML Tool? Yes!, that is what it was built for. From the beginning in 1996 it was designed from the bottom up to be the worlds greatest UML Tool. And it is!
(It is possible that I am a bit prejudiced here)

For Rhapsody the same applies as for all tools: the best way to become happy with a tool is by using it as closely to the way the creators have intended it. The more you bend the tool to do things your way, the unhappily you will become.

I always tell that to my customers and to my future customers. Always. But funny enough nobody hears it. That is just not what they want to hear. They all want the holy grail of software developers: the tool that does exactly what you want without errors. And there is no such thing, sorry. But, enough ranting, let’s go through what you _can_ do.

(Re-) Using your code in Rhapsody

Basically there are 3 variants: Code-centric, Model-centric and Code-aware.

Model-centric:

This is the way to use Rhapsody. Your Model is the base of all. Code generation will generate your application. It can be compiled and linked to the framework (RXF) and you have a working application.
Code will be generated from Class and Object Diagrams, Structure Diagrams and from State-machine Diagrams and Activity Diagrams.
Rhapsody also supports flowcharts (Although these are NOT UML!) for the behavioral code of operations.

Code-centric:

Here you use Rhapsody only to visualize your code. You can change the code and Rhapsody can process it to reflect the code in your model and in (some) diagrams.

How does that work?

1. Switch your Rhapsody to Code-centric. How?
   – When you are working in the Rhapsody Architect for Software your project will be code-centric by default.
   – In Developer (or EUSIII) you can add the CodeCentric profile via the menu “Add Profile to Model”. In the next file selection screen go up one directory and then go to “Settings”. There you will find “CodeCentric” (Or if you have a Willert Install, “CodeCentric_Original) and load the newest file with the correct language)
2. You can now use “Tools”, “Reverse Engineering” (RE) from the menu to read-in the files that you want to use. Beware!: Starting RE makes changes to Rhapsody that might not be easy to revert.
3. Things you can (or should) do before using RE:
   • Create a new Component
4. Your reversed engineered code is now in Rhapsody. How does it look?
   • You will see Packages, Files with variables and functions.
   • These artefacts are NOT UML artefacts, they are introduced by Rhapsody to allow working with code.
5. Rhapsody will generate OMD’s (Object Model Diagrams) with the structure of your files. If you have a lot of include files this does not really help.
6. Rhapsody will NOT automatically generate Flow Diagrams (Activity Diagrams for functions). You can ask Rhapsody to do so (Right-click, “Populate FlowChart”).
   remember: there is always just one “leading” source. Either your code or your Diagram. Check your settings.
7. The best way to use the reversed engineered stuff is to convert it to “decent” Rhapsody elements like classes and objects. It is a bit of work but the result is very helpful.

Code-Aware:

The “hybrid” form. Not really supported.

Problems and possible solutions

• All the code-centric stuff is (current version is 8.2) only useable on 32-bit Rhapsody. 64-bit is improving but not there yet.
• Don’t expect miracles. If your code sucks, it will suck in Rhapsody as well. No way around it.
• Be prepared to experiment with re-reading in a new model. Sometimes that clears things.
• It’s 5 am…. do you know where your properties are? You better…. Check out what is set. Remember: Reverse Engineering sets properties by itself!

More information on YouTube

Gavin Arthurs speaks about Rhapsody mode/code centric:
Gavin on Rhapsody

Fraser Chadburn speaks about Code-centric development in C++:
Fraser on Code-centric

Chris Carson speaks about Code Reuse:
Chris about Code Reuse

Thomas Hall speaks about Reverse Engineering:
Thomas on Reverse Engineering