[ReaGeniX home]

Learning ReaGeniX by Example

Note: The details, as file paths, menu structures, form layouts, etc., may vary depending on the tool versions. Consult documentation of the specific tool version for the details.

This is a quick start tutorial to learn the concepts you need to develop software with the ReaGeniX code generation tool. We use an example to explain the software development phases from application design till software is running on a target environment:

how Visio is used to draw an application,
how the application is generated to ANSI C-source files,
how a compiler and other software tools are installed,
how the generated files are (cross) compiled to a target environment,
how the target environment must be configured, and
how the application is downloaded and executed on the target environment.

This tutorial aims to explain briefly all aspects that are needed to enter ReaGeniX based software development, therefore we also describe how ReaGeniX generated software is bound into a target environment:

how to initialize a target environment and ReaGeniX generated software,
how to implement a main loop (with sleep) with/without operating system,
how to handle events from/to ReaGeniX applications, and
how to make accurate timing in a target environment.

ReaGeniX requirements to a software development process and target environment resources are very lightweight. You can use this document to integrate ReaGeniX within your existing software environment, or you can also use this document as it is to jump start your software development.

Contents

ReaGeniX example Blink

Create a new Visio design for Blink

Rename Blink drawing

Define Blink interfaces

Implement Blink functionality

Generate Blink source and header files with ReaGeniX

Execute Blink on Windows

Execute Blink on ATmega128

Advanced procedure

Install the AVR tools

Build Blink using AVR tools

Configure PC and STK500 board

Flash Blink to ATmega128 micro-controller

Conclusion

ReaGeniX example Blink

Blink is used as an example application throughout this tutorial. Blink is a simple application that has two states: blink_led_is_ON and blink_led_is_OFF. Blink control transfers between these two states at 0,5s interval, thus a LED is blinking at 1 Hz frequency. Figure 1 shows Blink functionality.

Figure 1. Blink state diagram.

We use Blink instead of traditional Hello example. The reason is that Hello requires keyboard input and screen output (or serial drivers) that are not readily available in all target environments. Blink uses simply a LED (or a GUI widget) to indicate that software is running so it is much more convenient to implement in constrained devices. In addition, console software (like Hello) would be rather akward to demonstrate proper timing functionality, which is most essential to many embedded programs.

Create a new Visio design for Blink.

Open Visio.

Select File / New / ReaGeniX / Rgx3w.

Rgx3w ReaGeniX template is a good starting point to create a new application. The template opens the ReaGeniX stencil and creates an empty ReaGeniX component that can be used as basis for a new application.

ReaGeniX development method is based on components. A simple application may be implemented in one component, and when complexity increases the application may be composed of many hierarchical components. Each ReaGeniX component has:

a specification that contains interfaces, and
a body that contains implementation.

An application has one top-level component so it is a typical custom to name a top-level component after an application. Blink is a very simple application so we implement it in one component and within this tutorial we use the name Blink to refer to the Blink application, the Blink component, and the Blink example.

Rename Blink drawing

Rename the page name (page-1) and drawing’s title as Blink.

The page name is used when the source and header files are generated. If you do not rename page-1 as blink, the generated files will be named as page-1.h and page-1.c instead of blink.c and blink.h.

Define Blink interfaces

Rename the component specification (smaller rectangle) as Blink.

Drag a Port symbol from the ReaGeniX stencil to the drawing and set its properties as shown below.

Position the led_pin output onto the Blink component specification.

The name led_pin is used here to emphasize that Blink drives a pin that is connected to a LED in a target hardware. GUI developers probably prefer some GUI widget terminology, but before changing the name notice that the output port is refered from component's implementation later using the name led_pin.

Blink interfaces are now ready. As shown above, Blink has the flag (boolean) output led_pin, and no inputs at all. Indeed, Blink is a simple application.

The concept of interfaces is fundamental to ReaGeniX architecture. A component communicates through its interfaces with other software. We connect Blink's led_pin output later to a hardware pin (or a GUI widget).

Implement Blink functionality

Rename component body (large rectangle) as Blink; the body name must match the specification name.

Create a new State: blink_led_is_OFF.

Create another State: blink_led_is_ON.

Create an initial transition to blink_led_is_OFF; start point must not be connected and condition (before =>) must be empty. Add the actions (after =>) to set output LED OFF (l=lower) and start 0.5s timer (ov = own variable/value).

=>
l(led_pin);
ov(blinking_timer) = Second/2;

Create a transition from blink_led_is_OFF to blink_led_is_ON. Add a condition for blinking_timer timeout. Add the actions to set LED ON (r=raise) and restart the blinking_timer to expire again after 0.5s.

when(timeout(blinking_timer))
=>
r(led_pin);
ov(blinking_timer) = Second/2;

Create a transition back from blink_led_is_ON to blink_led_is_OFF. Add a condition for blinking_timer timeout. Add the actions to set LED OFF and restart the blinking_timer to expire again after 0.5s:

when(timeout(blinking_timer))
=>
l(led_pin);
ov(blinking_timer) = Second/2;

Create the blinking_timer timer by dragging a Textual Declaration into drawing.

The both interfaces and implementation of Blink are now ready, as shown below.

An application can be in one component and one state at a moment. The application reacts only to those transitions that leave from the current state. After a condition of any transition is fulfilled the application executes the actions that are defined in the transition, and then transfers from the current state to the next one along the transition.

Blink has just one component so it is always in the state blink_led_is_ON or blink_led_is_OFF. Because all transitions into these two states start a blinking_timer, and because both states have a leaving condition for blinking_timer, the application transfers between the two states at 500ms interval. Furthermore, the actions defined in transitions after the blinking_timer timeout condition make led_pin output raise and lower causing a blinking LED at 1 Hz frequency.

Generate Blink source and header files with ReaGeniX

Save the Visio design (Blink.vsd) as ReaGeniX/Example/Blink/Blink.vsd.

Generate the source files from Visio: Tools / Macros / ReaGeniX / ReaGeniX.

ReaGeniX generates source files from the Visio design. The files blink.c and blink.h can be found from the same folder where you saved Blink application (that is ReaGeniX/Example/Blink).

Execute Blink on Windows

This tutorial explains how Blink is executed on Windows. The tools used are:

Microsoft Visual 6 C++ compiler to build Blink sources

Build Blink using Visual C++ 6

Create a new workspace VisualC located at the folder ReaGeniX\Example\Blink.

Insert a new Win32 Application project Blink to the VisualC-workspace (use the same location).

Create an empty project.

Accept a new project.

Add the ReaGeniX generated files located at the folder ReaGeniX\Example\Blink to the Blink project.

Add the ReaGeniX integration kit files located at the folder ReaGeniX\Platform\Console into the Blink project.

Add the Blink user interface files located at the folder ReaGeniX\Platform\Console into the Blink project.

Set preprocessor include directories: ..,..\..\..\Platform\Console to Blink project settings.

Build the Blink project.

Execute Blink and select Start / One more Blink.

Conclusion

Congratulations! Blink that you created using Visio, generated using ReaGeniX and compiled using Visual C++ 6 is now running on Windows. You can see:

Check button is blinking at 1 Hz frequency.
You can open more ReaGeniX Blink instances and they all blink at 1 Hz frequency.

See ReaGeniX User’s Manual, Interfacing Manual and other tutorials for more about Windows programming and ReaGeniX integration.

Execute Blink on ATmega128

This tutorial explains how Blink can be executed on an ATmega128 microcontroller. The tools used are:

GNU AVR compiler to build Blink sources

Atmel AVR Studio 4 to flash Blink to target ATmega128 microcontroller

ATmega128 and its target environment STK500/501 board

Advanced procedure

If you are already familiar with the compiler tool chain and target environment or you use different tools, do the following:

Configure ATmega128 oscillator to 3.69 MHz (otherwise blinking frequency is not 1 Hz, it work's though!)

Build the source files main.c, blink.c and sys_time.c together

Flash the software into a target ATMega128

If you have not yet installed the tools or configured the target environment, then you need to continue reading.

Install the AVR tools

Windows AVR GNU tools are used to cross-compile Blink sources for ATmega128. Install WinAVR that can be found from

http://winavr.sourceforge.net/index.html.

Atmel AVR Studio 4 is used to flash Blink to ATmega128. Install AVR Studio 4 that can be found from Atmel home page:

www.atmel.com.

Build Blink using AVR tools

Open DOS Command prompt and go to the folder ReaGeniX/Example/Blink were you generated Blink source files.

Compile the Blink source file blink.c. This step is to check that the Blink application was drawn and generated properly:

avr-gcc –mmcu=atmega128 –c blink.c

To build Blink: You can 1. enter Blink's ATmega128 folder and type make, or 2. copy to the same folder with blink.c the source files; Blink's main.c file from ReaGeniX/Example/Blink/ATmega128, and the files sys_time.c, sys_time.h, machine.h, reactime.h and reactime.p from ReaGeniX/Platform/ATmega128.

avr-gcc –mmcu=atmega128 –o blink.out main.c blink.c sys_time.c

-mmcu=atmega128 tells the target processor to the compiler
-o blink.out renames output file as blink.out

main.c initializes Blink application, configures ATmega128, contains main loop with sleep
sys_time.c implements ATmega128 timer 0 ticking at 1 ms interval

Convert the file blink.out to IHEX format so that AVR Studio 4 can handle it.

avr-objcopy –O ihex blink.out blink.hex.

Configure PC and STK500 board

Connect a COM1 port from PC to RS232 CTRL port of STK500 using RS232-cable. We use CTRL-port since we configure STK500 and ATmega128 timing parameters.

Connect XTAL1 jumper and bridge OSCSEL 1-2 jumper on STK500 board. This configuration is board default.

Connect STK500 PA0 pin to STK500 LED0 pin. The Blink application drives PA0, so LED0 will start blinking once per second (1 Hz) when Blink is flashed.

Connect STK500 PA1 pin to STK500 LED1 pin. ReaGeniX event handler main loop (in main.c) drives PA1 to show how much time ATmega128 sleeps; the less bright LED1 is the more ATmega128 has idle time.

Power Up STK500 board.

Flash Blink to ATmega128 micro-controller

Open AVRStudio 4.

Select AVRStudio 4 Tools / STK500 / STK500 ICE. We use AVRStudio 4 to flash software, but if you prefer some other download software (like AVRPROG/DUDE) then you should also recall to update the STK500 and ATmega128 timing parameters as we do or blinking time is not correct.

Select only the Fuses that are shown below.

Set STK500 Oscillator frequency to 3.69 MHz (which is default).

At program/Flash open Input HEX File and select the Blink.hex file.

Click Program button to flash blink.hex to target ATmega128.

Conclusion

Congratulations! Blink is now running on an ATmega128 microcontroller. You can see LEDs blinking:

LED0 blinkds at 1 Hz frequency; implemented in blink.c of Blink application.
LED1 shows the ATmega128 workload; implemented in main.c of ReaGeniX main loop.

ReaGeniX® is a trademark of OBP Research Oy.