Newsletters - MATLAB Digest

Automatic Code Generation from Stateflow™
for Palm OS™ handhelds: a Tutorial

by David Maclay

Automatic code generation from Stateflow^® is frequently associated with embedded implementation of control or DSP algorithms. However, the utility of Stateflow extends beyond these traditional areas into more general application development, including user interface and general purpose algorithm design.

Palm OS^® software is a widely used operating system for handheld computers. Originally developed to run on the PalmPilot^™ handheld computer, it can now be found in handheld devices from a range of manufacturers, using processors such as the Motorola 68328. This article explains how Stateflow, along with the standard Palm OS development tools, can be used to develop a complete application for a handheld device.

All files associated with the article can be obtained as a ZIP Archive.

Application Development Tools

Applications for Palm OS devices are most commonly developed in C or C++, typically using the Metrowerks CodeWarrior Integrated Development Environment (IDE). The visual interface for a Palm OS application can be built using a tool called Constructor^™ for Palm OS platform.

The ANSI C compiler supports 16- and 32-bit integer data types. It is therefore straightforward to include C code from different sources, provided that it uses only the supported data types and does not rely on any library that is unavailable on the Palm platform.

The Palm OS SDK (Software Development Kit) provides functions for interacting with the operating system and with buttons and displays on the Palm device.

Applications and Events

Palm OS applications are generally single-threaded, event driven programs. When an application is running, it executes in response to events posted on its event queue; these events may be posted either by the operating system, or by the application itself. Types of events an application can be designed to respond to include:

• program launch event
• button press event
• low battery warning
• a user-defined event posted by the application
• a screen tap event

The application handles an event by executing an appropriate section of code to perform the required function. Because a Palm OS application is an event-driven system, it is amenable to development in Stateflow.

A Simple Example of Code Generation from Stateflow

Both Simulink^® and Stateflow have code generation add-ons that convert a block diagram or graphical representation of a system into efficient, embeddable C code. This article focuses on code generation from Stateflow using Stateflow Coder.

The example below illustrates how code can be generated from Stateflow to update the display on the handheld device. The following model, sfdemo.mdl, is included with the files accompanying this article:

Click on image to see enlarged view

The above Stateflow chart illustrates a system with two states, State_1 and State_2, and two graphical functions, broadcast_E and draw. Each of the states has an 'entry' action associated with it that results in a call to the function draw. The behaviour of the graphical functions is defined using the flow chart notation available in Stateflow.

The function draw contains calls to WinDrawChars and WinEraseChars; these are functions specific to Palm OS for updating the display on the handheld device. The generated code for this system includes a definition of both draw and broadcast_E. The following code snippet shows the automatically generated code for draw:

void draw(int8_T cmd)
{
int8_T previousEvent;
previousEvent=_sfEvent_sfdemo_;
_sfEvent_sfdemo_=CALL_EVENT;
if(cmd == 2) {
WinEraseChars("State 1",7,30,50);
WinDrawChars("State 2",7,100,50);
} else {
WinDrawChars("State 1",7,30,50);
WinEraseChars("State 2",7,100,50);
}
_sfEvent_sfdemo_=previousEvent;
}

In addition to generating output on the display, the application must be able to respond to input events, such as the user tapping on a button. A button tap will be handled by the operating system and posted as an event on the application's event queue. The application must handle this event by initiating an appropriate action in the Stateflow code. This is achieved using the graphical function broadcast_E.

When the function broadcast_E is called, the only effect is to broadcast the local event E. This results in a state transition within the chart. In this way, a user action can trigger a Stateflow event broadcast and the consequent processing.

Writing the Stateflow/Palm OS Interface

In general, the more code that can be automatically generated, the better. However, in many applications some hand coding will be required. In this case, the only code that must be written by hand is the section for processing the Palm OS event queue and re-broadcasting the appropriate Stateflow event. The entire section of handwritten code for this example follows. Note the function call broadcast_E() in response to MainEventButton.

/***********************************************************************
*
* FUNCTION: SfMainFormHandleEvent
*
* DESCRIPTION: Event handler for the main form. In this example
* most of the events are handled by Stateflow. Each
* event that Stateflow should handle must be
* intercepted and broadcast to the Stateflow machine.
*
* PARAMETERS: event - a pointer to an EventType structure
*
* RETURNED: true if the event has been handled and should
* not be passed to a higher level handler.
*
* REVISION HISTORY:
*
*
***********************************************************************/
Boolean SfMainFormHandleEvent( EventPtr eventP)
{
Boolean handled = false;

switch (eventP->eType) {

case frmOpenEvent:
FrmDrawForm ( FrmGetActiveForm() );
handled = true;
break;

case ctlSelectEvent:

switch (eventP->data.ctlSelect.controlID) {

case MainEventButton:
broadcast_E();
handled = true;
break;

default:
break;

}

default:
break;
}

return handled;
}

Instructions for Running the Example

First, configure the tools as described in the appendix. Next, perform the following steps:

• Start MATLAB^® and change the working directory to sfexamples/Palm OS Stateflow App/Stateflow
• Run the M-file startup.m in this directory
• Open the model sfdemo.mdl
• Open the Stateflow chart and from the Tools menu select 'Open palm Target'
• Click on the Build button to generate and compile code; on successful completion of the build, a file sfexamples/Palm OS Stateflow App/Obj/starter.prc is created.
• Load the file starter.prc, either onto the Palm OS Emulator, or a real Palm handheld.
• Running the application should give the screen shown below, where the display toggles each time the button is pressed.

Click on image to see enlarged view

An Advanced Example of Code Generation from Stateflow

In the above example, the complete application was implemented using a single Stateflow chart. This chart includes Palm OS function calls for driving the display and the entire application. In the next example, the section that contains Palm OS specific code is separated from the main part of the application. This partitioning makes it easy to swap the hardware specific part in order to run the system either in simulation, or on a different target, for example a device running Windows CE.

The following are top-level Simulink diagrams for the Palm OS and simulation versions of the model.

Click on image to see enlarged view

Note that in both the simulation version and the Palm OS version, the main logic is contained in the Stateflow chart labelled gamecontrol. The same version of this chart is used in both variations of the model.

The simulation version is contained in the file tictacflow_ml.mdl. By running this model in simulation, Stateflow animation - and if necessary, the Stateflow debugger - can be used to validate the game algorithms prior to automatic code generation for the target device.

A MATLAB GUI for driving the game in simulation mode	Animation of the Stateflow chart during simulation
Click on image to see enlarged view	The Palm OS version is contained in the file tictacflow.mdl. To run this model follow the same steps as for the simple example, except use tictacflow.mdl instead of sfdemo.mdl and use sfexamples/tictacflow instead of sfexamples/Palm OS Stateflow App. A screenshot of the result is shown to the left.