E4Coder Reference Manual

Transcription

1 E4Coder Reference Manual Code generation tools for embedded designs Version: 1.3 December 18, 2014

2 About Evidence S.r.l. Evidence is a company operating in the field of software for embedded real-time systems. It started in 2002 as a spin-off company of the Real-Time Systems (ReTiS) Lab of the Scuola Superiore Sant Anna (Pisa, Italy). Today, Evidence is a dynamic company having collaborations in the field of electronics, telecommunications, automotives, and industrial automation. People at Evidence are experts in the domain of embedded and real-time systems, with a deep knowledge on the design and specification flow of embedded software, especially for the embedded market. Besides providing consultancy services, Evidence also provides: BSPs based on Linux for embedded devices, evaluation boards featuring most innovative 8, 16 and 32-bit microcontrollers for the embedded market, development tools for making embedded software development easier, and tools for the schedulability analysis of real-time tasks running on your final product. For more information see: Contact Info Evidence Srl, Via Carducci 56 Località Ghezzano S.Giuliano Terme PISA Italy Tel: Fax: For more information about Evidence products, please send an to the following address: info@evidence.eu.com. Other information about the Evidence product line can be found at the Evidence web site at: This document is Copyright Evidence S.r.l. Information and images contained within this document are copyright and the property of Evidence S.r.l. All trademarks are hereby acknowledged to be the properties of their respective owners. The information, text and graphics contained in this document are provided for information purposes only by Evidence S.r.l. Evidence S.r.l. does not warrant the accuracy, or completeness of the information, text, and other items contained in this document. Matlab, Simulink, Mathworks are registered trademarks of Matworks Inc. Microsoft, Windows are registered trademarks of Microsoft Inc. Java is a registered trademark of Sun Microsystems. in the USA. and other countries, and are used under license. All other trademarks used are properties of their respective owners. This document has been written using L A TEX. 2

3 Contents 1. Introduction Quick feature list Requirements Licensing Feedback, bugs, and additional examples Technical support Installing E4Coder E4Coder Prerequisites Microsoft Windows Linux (Ubuntu LTS 32 bit) E4Coder installation How to launch E4Coder Unloading E4Coder E4Coder blocks Types of blocks E4Coder palettes E4CODER - SMCube SMCube block E4CODER - FLEX DemoBoard E4CODER - GUI Creator E4CoderGUI block E4CODER - MISCELLANEOUS sprintf block E4CODER - SOURCES Random block Step block Square block Sinus block E4CODER - IO ADC block Button block DAC block Digital Input block Digital Output block

4 Contents Buzzer block Encoder block LCD block LED block PWM / SERVO block Touch block Read and Write blocks E4CODER - NONLINEAR E4C Saturation block E4C Product block E4CODER - COM CG CAN CFG block CG CAN TX block CG CAN RX block CG SCI CFG block (OBSOLETE) CG SCI TX block (OBSOLETE) CG SCI RX block (OBSOLETE) CG SERIAL MSG TX block CG SERIAL MSG RX block CG EASYLAB SERIAL TX block CG EASYLAB SERIAL RX block E4CODER - CUSTOM E4Coder Custom block E4Coder User Pref Standard blocks supported by E4Coder EXPRESSION block DLR block RFILE f block WFILE f block Simulating a design The code generator Execution model of the generated code How to make a diagram ready for code generation How to run the code generator Global parameters Target selection Task selection Subsystem selection Target and I/O settings Symbol settings Structure of the generated code Additional options

5 Contents How to change the variable names How to change the data types Read and Write blocks Target run-time support OSEK/VDX ERIKA Enterprise RTOS target Compiler Options Supported target boards Evidence FLEX boards Evidence EasyLab / Microchip Microstick with dspic or PIC24 microcontroller Evidence FLEX Demo board Evidence FLEX Demo2 pack without plugins Evidence FLEX Demo2 Pack with DC Motor Plugin Amazing Ball - Evidence FLEX Demo2 Pack with Servo Motor plugin Arduino Uno Arduino Nano STM32F4 Discovery Microsoft Windows target Prerequisites needed to automatically compile a Windows application generated by E4Coder Compiler Options Target blocks Supported target boards Desktop - Standard PC with Qt Libraries Linux pthread target Compiler Options Target blocks Supported target boards Desktop - Standard x86 PC with Qt Libraries E4Box E4Box RTAI target Bridge threads Compiler Options Target blocks Supported target boards E4Box E4Box Bare Metal target Compiler Options Supported Target Boards Arduino Uno

6 Contents Arduino Nano STM32F4 Discovery LIBRARY - Target without generation of the software architecture Examples Multirate designs Customizations The Customization directory Where to find customizations examples Supporting additional target boards Structure of the board.txt file version section of the board.txt file board section of the board.txt file target section of the board.txt file The palette directory Structure of the target.txt file version section of the target.txt file settings section of the target.txt file Hooks functions that can be specified inside targetinclude and targetconfigs Typing of variables, and the types.h file Additional functions to be included inside targetinclude and targetconfigs build section of the target.txt file blocktype section of the target.txt file oil section of the target.txt file entrypoint section of the target.txt file Structure of the targetcode attribute specified in the blocktype section of the target.txt file Writing custom blocks Simulation behavior of a custom block Code Generation behavior of a custom block Override Options Structure of the directory used to specify a custom block version section of the custom-block.txt file customblock section of the custom-block.txt file customlibs section of the custom-block.txt file customsources section of the custom-block.txt file customheaders section of the custom-block.txt file oil section of the custom-block.txt file Additional tools SMCube

7 Contents E4Coder GUI FLEX Demo Board Simulator Examples How to load the examples A. Comparison between E4Coder and the Scicos Pack 168 B. License Manager 171 B.1. The License File B.2. Errors C. ScicosLab License 176 D. Qt Libraries Licensing 179 7

8 List of Figures 2.1. Starting ScicosLab The directory where the E4Coder installer has been extracted. Tip: you can copy the top directory and paste it into ScicosLab instead of typing it! Run the installer The install window Question whether the installer should remove an old installation of E4Coder Installing the E4Coder Toolbox Question about the Microchip compiler directory You need to specify the compiler location in case you want to compile code for Microchip dspic Patching some standard blocks and palettes Final message of a successful installation Loading E4Coder in the Toolbox menu Confirming the license file location You will be asked to specify the License File if the installer cannot find one License found correctly License file or Dongle not found You can retry the License step in case of problems SMCube: specifying the compiler to be used for compiling the simulation models E4Coder has been correctly loaded Error message on the ScicosLab console in case you did not connect o not have the USB Dongle installed How to launch the ScicosLab Demos window The ScicosLab Demos window The E4Coder menu under Scicos The E4Coder Palettes in the Scicos Palette Tree Unloading E4Coder An SMCube block The E4Coder GUI block The sprintf block The random block The step block The square block The sine block

9 List of Figures 4.8. The ADC block The Button block The ADC block The Digital-Input block The Digital-Output block The Buzzer block The Encoder block The LCD block The LED block The PWM block The Touch block The Read block The Write block The E4C SATURATION block The E4C PRODUCT block The CG CAN CFG block The CG CAN TX block The CG CAN RX block The CG SCI CFG block The CG SCI TX block The CG SCI RX block The CG SERIAL MSG TX block The CG SERIAL MSG RX block The CG EASYLAB SERIAL TX block The CG EASYLAB SERIAL RX block The CUSTOM block The USER-PREF block The standard Scicos blocks supported by the E4Coder Code Generator The EXPRESSION block The DLR block The RFILE f block The WFILE f block Only superblocks with one clock input can be correctly generated Example of correct connection of a simulation input port The code generation process is started by selecting a USER PREF block, and then choosing the appropriate menu option The E4Coder Code Generation wizard splash screen The Code Generation Project settings Target selection, used to specify which target board will be used for code generation The Panel allowing the specification of the tasks in the system Creating or Editing a Task Subsystem selection

10 List of Figures Superblock to task mapping Target, I/O block, and message settings Selecting the mapping for an Encoder block among the two encoders available in the FLEX MTB DCMOTOR board This dialog box allows the specification of data messages which can be mapped to the Read/Write blocks This Dialog Box allows the specification of the kind of message. At the moment only the RAM option is available Enter the name of the global buffer Symbols and data types, for an ERIKA target The block number is visible in the information window for the block, line Typical output directory after E4coder code generation (project type: EE PROJECT) Final E4coder message and the compilation window Identification names for links and blocks Use of link identification names enabled User types definition Use of standard types How to manage superblock ports and Read/Write blocks Custom block uses: I/O and algorithm OIL and Compiler options for the OSEK/VDX operating system ERIKA Enterprise Arduino Flash programming Dialog Box. You need to specify the serial port where the Arduino board is connected, and afterwards press the Flash button to program the board STM32F4 Discovery programming Dialog Box. You need to specify the path of the ST-LINK/V2 executable, and afterwards press the Flash button to program the board Microsoft Windows Compiler options Code generated for graphical applications on RTAI Compiler options for the Bare Metal target The multirate demo in the list The Multirate demo, implementing a simple multirate DC motor controller Multirate demo: the task-set Multirate demo: superblocks-task association Multirate demo: I/O and Read / Write mapping. A Read block and a Write block has been generated automatically, and configured to refer to a common buffer The SMCube editor window

11 List of Figures SMCube Simulation Dialog Box (1 - start/stop simulation, 2 - state machine with highlighted states, 3 - state history trace, 4 - detail of a single step) An E4CoderGUI block with two inputs and two outputs The E4CoderGUI editor window An example of E4CoderGUI user interface during simulation The FLEX Demo Board Simulator FLEX Demo Board blocks Open the ScicosLab Demos You are prompted with a destination directory when opening a demo Open the Example. The actual installation may have more examples available than shown in this picture B.1. The About panel in E4CoderGUI B.2. The License panel in E4CoderGUI B.3. E4Coder did not find the dongle matching the current license B.4. E4Coder found that the installed license has expired B.5. E4Coder could not find the license file

12 List of Tables 7.1. Peripherals supported by the FLEX board target Peripherals supported by the EasyLab board target Peripherals supported by the FLEX Demo board target Peripherals supported by the FLEX Demo2 board target Peripherals supported by the FLEX Demo2 board target Peripherals supported by the FLEX Demo2 board target Peripherals supported by the Arduino Uno board target Peripherals supported by the Arduino Nano board target Peripherals supported by the STM32F4 Discovery board target Qt Priorities. Values refers to the QThread::Priority enum ADC peripherals supported by E4Box DAC peripherals supported by E4Box DIGITAL INPUT/OUTPUT peripherals supported by E4Box ENCODER peripherals supported by E4Box 1.0 The initial value of these encoders is set to ADC peripherals supported by E4Box DAC peripherals supported by E4Box DIGITAL INPUT/OUTPUT peripherals supported by E4Box ENCODER peripherals supported by E4Box 1.1 The initial value of these encoders is set to Peripherals supported by the Arduino Uno board target Peripherals supported by the Arduino Nano board target Peripherals supported by the STM32F4 Discovery board target Hooks in the generated code that can be specified inside a target board Special strings used when parsing the pre and post commands in the build section Special strings used when parsing the OIL file template Peripheral block description - init section Peripheral block description - step section Peripheral block description - end section A.1. Comparison between E4Coder and Scicos-Pack. next stands for the next version of the code generator A.2. Footprint comparison of a similar example compiled with E4Coder and with the Scicos Pack. Numbers in bytes

13 List of Algorithms 6.1. Extract from types.h Extract from data.c as generated by the diagram in Figure Extract from data.c generated from the diagram in Figure Extract from conf.oil Simulation behavior of a custom block, part Simulation behavior of a custom block, part Example of the custom block section from data.h Example of user-supplied C functions declarations for a CUSTOM block Target code for the CUSTOM block, part Target code for the CUSTOM block, part

14 About this document This document describes E4Coder, a set of tools enabling simulation and automatic code generation of complex designs for small microcontrollers. Function of the document The function of this document is to provide an overall view of the tools composing E4Coder, as well as a reference manual for the various options related to the code generator. 14

15 List of Algorithms Document history Version Date Author Company Change Description 0.1 Sept 2012 Paolo Gai Evidence Srl Initial version 1.0 Nov 2012 Paolo Gai, Dario Evidence Srl First version Di Stefano, Alessandro Passaro Nov 2012 Paolo Gai Evidence Srl Updated installation procedure 1.1 May 2013 Paolo Gai, Dario Di Stefano, Bruno Morelli, Alessandro Biasci Evidence Srl Added Linux host support; Added E4CoderGUI code generation; rewritten Chapter 7 and 9; added description of new blocks in July 2013 Paolo Gai, Dario Di Stefano Evidence Srl Chapter 4. Updated Target boards E4Box and Flex Demo Board. 1.2 Nov 2013 Paolo Gai Evidence Srl Updated code generation wizard, added RTAI and Bare Metal targets. 1.3 May 2014 Paolo Gai, Giuseppe Serano, Alessandro Biasci, Bruno Morelli 1.4 Nov 2014 Paolo Gai, Giuseppe Serano, Alessandro Biasci, Bruno Morelli Evidence Srl Evidence Srl Added EasyLab Serial TX/RX Blocks. CPP files now can be used in ERIKA Projects. Better checks during sw architecture generations. Added STM32F4Discovery board, Serial Msg blocks, various fixes and typos. 15

16 List of Algorithms Acronyms Acronym E4Coder E4Coder GUI FSM HIL SMCube Meaning E4Coder is a factorized acronym meaning Evidence Erika Enterprise Embedded Coder. Initially meant as a code generation tool supporting the ERIKA Enterprise RTOS, it is now a general purpose code generation toolset. In that sense, it can be now also interpreted as Evidence For Coder, as a set of tools for simulation and code generation of complex designs. E4Coder GUI is the GUI editor for fast prototyping of graphical user interfaces. Finite State Machine Hardware In the Loop SMCube, or SM 3, is a recursive factorized acronym which means SMCube is a State Machine System Modeler. 16

17 1. Introduction E4Coder is a set of tools to simulate and generate code for embedded controllers in a standalone configuration or running a real-time operating system. E4Coder is composed by the following tools: ScicosLab, free software for simulation of complex designs [2]; E4Coder Code Generator, an efficient embedded code generator; SMCube, a finite state machine modeler; E4Coder GUI, a prototyping tool for Graphical User Interfaces. The main usages of E4Coder are: E4Coder is meant to be a complete tool suite allowing companies to start the development of a model-based development flow that starts from the modeling of a complex system down to its implementation on one or more microcontroller systems. E4Coder can be used as a tool for prototyping embedded graphical user interfaces, thanks to the possibility of simulating a complex model including SMCube state machines that can be shown using E4Coder GUI panels. E4Coder can be used as a tool for Processor In the Loop (PIL), Hardware In the Loop (HIL) and calibration. Thanks to its communication blocks, E4Coder can be used to log data from the target, post-process it, and for sending control information to the target in real-time. The idea driving the development of E4Coder was the need for a lightweight set of tools, based on open-source libraries and using open-source software on the target microcontroller, which could help designing complex systems at reasonable license costs Quick feature list Using the E4Coder toolset, you can easily: Simulate continuous time and discrete time designs. Edit, simulate and generate code for Finite State Machines (FSM) using SMCube. Hierarchical state machines with parallel states are supported, with additional support for junction points. 17

18 Chapter 1. Introduction Simulate and generate code from the same ScicosLab diagram without changes. In other words, the diagram contains both the superblocks to be generated part as well as a simulation of the environment where they will run. Generate compact and readable code for your embedded single and multirate algorithm, that can be easily integrated in your mass-production project. Generate pure library code for small microcontrollers without an RTOS. Generate a complete Real-Time / Soft Real-Time project for a number of operating systems, including OSEK/VDX based kernels (with the open-source OSEK/VDX RTOS Erika Enterprise [8]), Linux pthreads, Windows Customize the variable names used in the generated code using link names. Create custom blocks to integrate existing legacy applications, functions, and data in your Scicos project. Edit and simulate embedded panels using E4CoderGUI Requirements E4Coder is currently distributed as an additional package to the ScicosLab official distribution, and has the following requirements: Linux or Windows hosts 1 ; ScicosLab 4.4.1; On Microsoft Windows: Microsoft Visual C++ (supported versions: Express edition 2008, 2010); On Linux: tested on Ubuntu LTS 10.04, other 32 bit versions should also work 2. E4Coder includes a stand-alone version of RT-Druid and a full version of Erika Enterprise to simplify the installation procedure. For further info about Erika and RT-Druid refer to the web sites E4Coder by default supports code generation for various microcontrollers and hardware boards, included the FLEX and EASYLAB boards produced by Evidence. For more information of the Evidence boards, please refer to: 1 Screenshots in this document refers to the Windows version. 2 Please contact us in case of issues in supporting a specific Linux distribution. 18

19 Chapter 1. Introduction If you plan to generate code for the Microchip dspic embedded target mounted on the FLEX and EASYLAB boards, you will need the complete toolchain: Microchip C30 compiler (at least 3.31). GNU make (Cygwin on Microsoft Windows) A minimal version of Cygwin that contains all the packages needed to compile any Erika projects can be downloaded from: An updated Java installation Licensing ScicosLab is distributed under the Scilab License (see Appendix C). E4Coder, E4Coder GUI, and SMCube are packaged as independent toolboxes, and are distributed under a commercial license. SMCube and E4Coder GUI uses the Qt Libraries, which are dynamically linked to allow you to change the library with new versions at your choice. Licensing information about the Qt Libraries is available in Appendix D Feedback, bugs, and additional examples We hope that you will enjoy E4Coder and its features for your embedded projects. If you have any suggestions on how to improve E4Coder and the surrounding tools, please do not hesitate contact us by writing to info@evidence.eu.com. Please also periodically check the E4Coder website (see below) for additional information, demos, and examples: on the E4Coder website: on the E4Coder Wiki (containing additional examples): Technical support Technical support for E4Coder is available directly from Evidence. Many information can be found directly on the E4Coder website, at the following address: 19

20 Chapter 1. Introduction For sales, pricing, order status, license renewals and general information, please contact Evidence Srl directly at the address and phone numbers available at the following web page: 20

21 2. Installing E4Coder E4Coder is packaged as a set of ScicosLab toolboxes. To install E4Coder, you need to perform the following steps: 2.1. E4Coder Prerequisites In the following section are listed required programs/libraries needed by E4Coder Microsoft Windows 1. Microsoft Visual Studio Express edition version 2008 or Visual Studio is required by Scicos and by SMCube. Studio Express edition will not work. Other versions of Visual The location to start the download is eng/downloads. 2. ScicosLab You need to install the windows version as downloaded from org. If you are going to use also Modelica blocks, it is recommended to install the patch available at (the file is named modipar.zip). 3. Microchip Tools If you are going to use the code generation for the Evidence s FLEX boards[4], you will need to install the Microchip tools. In particular, you will need the following: a) Microchip MPLAB IDE or MPLAB X. It is required to program the dspic microcontroller mounted on the FLEX board. b) Microchip C30 or XC16 compiler. This is required in order to be able to automatically compile the code generated. c) Microchip MPLAB ICD3 programmer/debugger for dspic microcontroller. This is required to program/debug the target boards. See the Microchip web site for more information. ( 21

22 Chapter 2. Installing E4Coder d) Cygwin and GNU make. Cygwin is required to compile the source code generated from your Scicos diagram, when it is integrated with ERIKA Enterprise. If you do not have Cygwin installed, we suggest to install Cygwin from the minimal installation pack available at erika/webdownload/eecygwin_1_7_9.zip. This installer of Cygwin for Erika will install all the Cygwin packages needed to compile the generated Erika projects. Please note that the suggested installation path is C:\cygwin. Cygwin64 is also supported. e) An up to date Java Runtime Environment This is required by RT-Druid to parse the OIL/OSEK configuration files. You can download a java Runtime Environment at the following address: f) If you are going to generate code for a windows target using E4CoderGUI, then you need the Qt Libraries SDK installed, with MinGW support. A local copy of the two packages needed are available at: (which should be installed first, and at: which should be installed afterwards. Note that when installing the Qt package you ll may get a compatibility warning that you can just ignore answering yes Linux (Ubuntu LTS 32 bit) 1. Qt Can be found as single download or inside the Qt SDK In the latter case you can choose the desktop section only. Other tools such QtCreator, QtDesigner and QtAssistant are recommended. Other packages can be safely discarded. A local copy of the package is available at the following link: 2. Scicoslab Must be downloaded from ScicosLab site. Please choose the right version (Lucid 32-bit in this case). Possibly install ScicosLab dependencies such as tcl8.5, tk8.5, libgfortran3 if not yet installed. 22

23 Chapter 2. Installing E4Coder 3. Java JRE 6+ You can install openjdk-6-jre from standard repositories or install Oracle package. Note: In order to install/uninstall E4Coder you must have root privileges. Normal usage does not require administrator privileges E4Coder installation 1. E4Coder is typically distributed as a zip archive. Please extract it in a directory of your choice. In the following paragraphs, the directory chosen was C:\Users\E4Coder v1 1 You should also have a License file provided by Evidence. It will be needed later at the first load of the E4Coder toolbox Start ScicosLab with Administrator privileges, as shown in Figure Please note again: you need Administrator Privileges to run the installer. To gain Administrator Privileges, you need to right-click on the ScicosLab program icon, and select Run as Administrator. 4. Change directory by typing the command: cd C:\Users\E4Coder v1 ; As shown in Figure 2.2 and Type and run the following command: exec installer.sce; The command will start the installation, as shown in Figure 2.3. Tip: please remember to put the semicolon at the end of the line to avoid unnecessary output on the console. 6. A window will appear, asking whether to install or uninstall the package (see Figure 2.4). Please choose Install. By clicking on Uninstall E4coder will be uninstalled and the folder containing the code generator (named SCI+ \contrib\e4coder\e4coder-cg ) will be deleted. In case you developed customizations for build 40 of E4Coder, stored in E4Coder/E4coder-customizations, please note that these configurations will not be removed by the installer. Also note that the templates for adding custom boards and custom blocks have been simplified, see Section 9. 1 On a Linux host, $HOME/E4Coder v1 2 It will not be required during the installation procedure itself, because the installation is done with administrator privileges, whereas the License file is copied in the user home. 23

24 Chapter 2. Installing E4Coder Figure 2.1.: Starting ScicosLab. 7. If you previously installed another version of E4Coder, then you will be asked whether you want to proceed with the uninstall of the previous version (see Figure 2.5). WARNING: Please note that the uninstaller removes the folder named E4coder-cg inside the E4coder installation directory. If you put the License.xml file in this folder, it will be deleted. We suggest to check the license file location before to continue. Your custom files stored in the E4coder-customizations will not be deleted. 8. After that, you will be required to definitely confirm the installation of the E4Coder Toolbox (see Figure 2.6). After you press Yes, the copy of the E4Coder files will start. WARNING: Please do not close the black window that shows the copied files. It will be automatically closed at the end of copy. 9. At this point, E4Coder will configure the Microchip C compiler for its usage with 24

25 Chapter 2. Installing E4Coder Figure 2.2.: The directory where the E4Coder installer has been extracted. Tip: you can copy the top directory and paste it into ScicosLab instead of typing it! the FLEX and EASYLAB boards. This step is needed only if you are going to generate code using the Microchip dspic C compilers for the FLEX or EASYLAB boards (see Figure 2.7 and 2.8). 10. Finally, the installer will ask about the installing of some patches provided with E4coder (e.g. replacement of some standard blocks and palettes, in particular REGISTER.sci and Others.cosf), which includes bugs fixing not present yet in the official ScicosLab release, and which could be needed for the code generation process (see Figure 2.9). 11. At the end of the install process, an E4coder window is opened (see Figure 2.10). Please close the window and restart ScicosLab in order to be able to load E4Coder without Administrator privileges. 25

26 Chapter 2. Installing E4Coder Figure 2.3.: Run the installer. Figure 2.4.: The install window. Figure 2.5.: Question whether the installer should remove an old installation of E4Coder. 26

27 Chapter 2. Installing E4Coder Figure 2.6.: Installing the E4Coder Toolbox. Figure 2.7.: Question about the Microchip compiler directory. Figure 2.8.: You need to specify the compiler location in case you want to compile code for Microchip dspic. Figure 2.9.: Patching some standard blocks and palettes. 27

28 Chapter 2. Installing E4Coder Figure 2.10.: Final message of a successful installation. 28

29 3. How to launch E4Coder As the first thing before loading E4Coder, please remember to connect the USB Dongle provided by Evidence on your PC. E4Coder is packaged as a ScicosLab Toolbox. For this reason, it is not loaded by default when the system starts, and in order to be able to load Scicos diagrams made using E4Coder, you need to first configure the environment by loading E4Coder from the Toolbox Menu (see Figure 3.1). Figure 3.1.: Loading E4Coder in the Toolbox menu. The first time E4Coder will be loaded, the loader will check for the License file. In case the License file will not be found, or it is invalid, the loader will ask you to install the License file. We suggest to maintain the default directory named E4Coder inside the current user directory, as shown in Figure 3.2. WARNING: Please do not put the License.xml file inside the E4coder installation directory because it could be deleted the next time you ll update E4Coder. We suggest to maintain the default path. After that, the Installer will check the presence of the License file in the directory you specified. If the License file is not found by the Installer, you will be prompted to specify a License file as shown in Figure 3.3. Please Click Yes, and provide the License file provided by Evidence. At this point, the Installer will check for the presence of the USB Dongle, and will perform a License check. Figures 3.4 and 3.5 show two possible results (License found 29

30 Chapter 3. How to launch E4Coder Figure 3.2.: Confirming the license file location. Figure 3.3.: You will be asked to specify the License File if the installer cannot find one. and correct, or License not found). In case of a License error, you will be asked to redo the license installation as shown in Figure 3.6. Figure 3.4.: License found correctly. At the end of the License check (if any), you need to specify which compiler will be used by SMCube (the state machine simulator/code generator) to compile the state machine models for simulation purposes (see Figure 3.7). Finally, a set of E4Coder libraries will be loaded as in Figure 3.8 (please remember to insert the USB Dongle, otherwise you will get a Dongle not found window as in Figure 3.5, and an error message on the ScicosLab console as in Figure 3.9). As a result of the load process, additional palettes, Scicos blocks, examples and menu items will be available in the Scicos environment. In particular, the following additional tools will be available after loading E4Coder: Additional Demos, available in the ScicosLab Demos menu (see Figures 3.10 and 3.11, as well as Chapter 11); 30

31 Chapter 3. How to launch E4Coder Figure 3.5.: License file or Dongle not found. After opening Scicos 1, you will have the following additional features: The E4Coder menu (see Figure 3.12), from where you can start the Code Generation process, as well as launch the demos or displaying an online help about the code generation process. The E4Coder Palettes (see Figure 3.13), including all the additional Scicos block which are the hearth of the E4Coder Code Generator. These palettes include the SMCube and E4CoderGUI blocks, as well as the generic I/O and custom blocks Unloading E4Coder After using E4Coder, you may need to unload it from memory. E4Coder can be unloaded from ScicosLab in a very simple way: from the ScicosLab console, just launch again E4Coder as in Figure 3.1. The launcher this time will detect that E4Coder is already loaded, and will unload it. The result of the unload operation is available in Figure Just type scicos(); on the ScicosLab console (Tip: do not forget the final semicolon to avoid messages on the console!). 31

32 Chapter 3. How to launch E4Coder Figure 3.6.: You can retry the License step in case of problems. Figure 3.7.: SMCube: specifying the compiler to be used for compiling the simulation models. 32

33 Chapter 3. How to launch E4Coder Figure 3.8.: E4Coder has been correctly loaded. 33

34 Chapter 3. How to launch E4Coder Figure 3.9.: Error message on the ScicosLab console in case you did not connect o not have the USB Dongle installed. Figure 3.10.: How to launch the ScicosLab Demos window. 34

35 Chapter 3. How to launch E4Coder Figure 3.11.: The ScicosLab Demos window. Figure 3.12.: The E4Coder menu under Scicos. 35

36 Chapter 3. How to launch E4Coder Figure 3.13.: The E4Coder Palettes in the Scicos Palette Tree. Figure 3.14.: Unloading E4Coder. 36

37 4. E4Coder blocks 4.1. Types of blocks E4Coder provides a rich set of customized ScicosLab blocks that can be used for simulating a design and (for most of them) for code generation. These blocks can be divided in the following categories: Blocks linked to external tools. These blocks works in simulation by running external programs on the same machine for managing the simulation input and outputs. Examples of this kind of blocks are: SMCube block, E4Coder GUI block, FLEX DemoBoard block. Please note that out of these, the SMCube block can also generate the code for implementing a state machines on the target. Most of these blocks have a varying number of inputs and outputs depending on the specific block content (for example, the inputs and outputs of a SMCube block derive from the State Machine Data Model). Utility blocks. These blocks provide useful functions available both in simulation and code generation. For example, these blocks include random, step, sinus, square functionalities. Code Generation Properties block. This block is used to store all the configuration needed to generate the code. It also stores the mapping between first-level superblocks and RTOS tasks, as well as the mapping between generic I/O blocks and the real peripherals on the target. As a result, you can have more than one peripheral block in a single design. In this way, we obtain the following two important properties: the design is kept independent from the target board you are generating code for; it is possible to have different configuration (boards, mapping of pins,...) for the same diagram. I/O blocks. These blocks are generic blocks mapped to external peripherals. They are generic because the mapping between the specific block and the peripheral really used on the target is defined only at code generation time. As an example, if you put a PWM block in a design, you need not to specify which PWM peripheral you want to control on the target board or on the specific microcontroller (this information is instead stored in the Code Generation properties block, allowing the porting of the same diagram to more than one design). Moreover, all blocks provide a simulation port, either input (e.g., for an ADC converter), or output (e.g., for a 37

38 Chapter 4. E4Coder blocks PWM). The simulation port is used to simulate the peripheral behavior during simulation, and is then ignored when generating code. The simulation port allows the possibility to use the same diagram for simulation and for code generation. In order for a superblock to generate code successfully, the simulation ports of the E4coder I/O blocks should be directly connected to the superblock I/O ports. See the E4coder-IO palette description for more info. By default, all blocks listed in this chapter can be used for code generation. There will be a specific note when a block cannot be used for code generation E4Coder palettes E4CODER - SMCube SMCube block Figure 4.1.: An SMCube block. This palette contains the SMCube block. SMCube is an external tool which can be used to graphically simulate and generate code for finite state machines. The SMCube Block (see Figure 4.1) is used to reference a state machine contained in an external XML file (the file name is printed in the block picture). For more information about SMCube, please refer to Section E4CODER - FLEX DemoBoard This palette contains the FLEX DemoBoard block, described in Section E4CODER - GUI Creator E4CoderGUI block This palette contains the E4Coder GUI block (see Figure 4.2). E4Coder GUI is an application part of E4Coder that can be used to prototype graphical interfaces or to make nice simulation panels for your simulation environment. The E4Coder GUI Block 38

39 Chapter 4. E4Coder blocks Figure 4.2.: The E4Coder GUI block. is used to reference a GUI panel contained in an external XML file (the file name is printed in the block picture). Code generation of E4CoderGUI blocks is currently supported for Windows and Linux targets (see Chapter 7). For more information about E4Coder GUI, please refer to Section E4CODER - MISCELLANEOUS sprintf block Figure 4.3.: The sprintf block. This palette contains a block named sprintf (see Figure 4.3). The sprintf block is used to generate a vector of chars in a way that mimics the specification of the C Language sprintf function. The idea is that the vector of chars produced by the sprintf block will be then connected to a text input of an E4Coder GUI block (see Section 4.2.3) or to the LCD input of the FLEX Demo Board Simulator (see Section 4.2.2) How to use the sprintf block The sprintf block mimics the sprintf function behavior, allowing some kind of formatted output to be produced. The block supports a simulation output and code generation as well compatible with most libraries available for small microcontrollers. To support small microcontrollers with limited sprintf functionality, the block mimics the behavior of a sprintf function by separating a traditional sprintf format string in tokens. Each token is basically a string with a single sprintf parameter to be expanded. An input port is also generated for each token, to allow the input of the data. For example, if we need to obtain an output following the sprintf format string: Temperature: %2d Pressure: %4d Time: %2d:%2d 39

40 Chapter 4. E4Coder blocks then you need to initialize the sprintf block with one of the following token sequences (their output is equivalent): Sequence 1: Temperature: %2d Pressure: %4d Time: %2d :%2d Sequence 2: Temperature: %2d Pressure: %4d Time: %2d : %2d As a result of the split, the resulting sprintf block will have 4 input wires. The block accepts the following parameters: Formats This parameter contains the list of tokens, stored inside a list. The possible format option for displaying variables is a subset of the C Language sprintf rules, and have to follow the following pattern: where: %[flags][width][.precision][length]specifier flags if 0 is specified, then the value printed will be always formatted with exactly that number of characters, with zero-filling on the left. width is used to specify the maximum number of characters that should be used to print the value of the string. precision is used to specify any characters after the comma in a float value. length if l is specified, then the parameter will be considered a long value. We suggest to use the long specifier if your target is a 16 bit machine with 16 bit integers. In this way, the width on the target generated code and on the simulation will be the same (the simulation integer is 32 bit). specifier is one of the following (the corresponding ScicosLab types are in parenthesis): d (int32), u (uint32), f (real), c (int8). For example, possible legal strings for the list of tokens are: %2d an integer printed with maximum 2 characters; Time:%2d same as before, with the addition of a constant string; %03f a float printed with 3 characters, 0-filled on the left; 40

41 Chapter 4. E4Coder blocks WARNING: Please, note that the PC and the embedded target may have different size for the same type. For example, the %d format could not be equally interpreted by the Microsoft Visual C++ compiler ( %d interpreted as 32-bit integer) and the embedded device compiler (e.g. %d interpreted as 16-bit integer for Microchip dspic compiler). This different behavior can produce subtle errors in the generated code, thus only formats that can be equally interpreted should be used (for example, you can use the l length specifier to guarantee that both types with be 32 bit). Sizes This parameter is an array containing the maximum number of characters needed for each token, not including the null-terminator. Output size This contains the output container size including the null-terminator. The function will output an int8 row/column vector filled with the ASCII characters resulting from the parsing of the Formats strings. The maximum number of characters is 64. The last character filled by the Formats strings is the null-terminator and the remaining characters will contain undefined values, 0 at the beginning of the simulation. If the sum of each token sizes is greater than or equal to Output size then the output vector will contain only null characters (0x00). Example This example is taken from the E4Coder Demo named SMCube: digital clock with flat-fsms. The sprintf block is the one in the top right of the Digital Clock/Time superblock. In the example, the block is used to print the current time on the second line of the 16x2 LCD display of a FLEX Demo Board[5]. The sprintf string we would like to print is: %02ld:%02ld:%02ld that is of course used to print Hour:Minute:Seconds of the digital clock. For that reason, the three parameters of the block have been filled in the following way: Formats The string needs to be divided in at least three tokens containing each one one variable to expand. For this reason, the value of the Formats parameter is: list( %02ld:, %02ld:, %02ld ) Sizes The parameter stores the output length in characters of each token listed in the Formats parameter. In this case, the value of the first two tokens will be 3 (2 chars for the input variable, plus the colon), whereas the last token will be 2. As a result, the value of the Sizes parameter is: [3; 3; 2] Output Size In this case, since the output will be sent to a 16 character LCD line, we want a 16 chars output. For that reason, the value of the parameter is [16,1] As a result, the formats string will fill 9 chars including the null-terminator ( 0x00 ), and the other 7 characters will not be filled. 41

42 Chapter 4. E4Coder blocks E4CODER - SOURCES This palette contains a set of reference sources blocks, which can be used to generate simple waves such as random signals, steps, square waves, and sinusoids. The blocks which are present in this Palette are listed in the next subsections Random block Figure 4.4.: The random block. The Random block (see Figure 4.4) can be used to generate a pseudo-random signal. The parameters available for the block are: Amplitude This parameter gives the maximum amplitude of the signal, starting from 0. Seed This parameter provides the initial seed of the pseudo-random number generator Step block Figure 4.5.: The step block. The Step block (see Figure 4.5) can be used to generate a step signal, that starts from 0 and goes to a given Amplitude after some Delay time. The parameters available for the block are: Amplitude This parameter gives the value of the step signal after the Delay. Delay This parameter provides the initial time after which the value of the signal goes from 0 to Amplitude. 42

43 Chapter 4. E4Coder blocks Figure 4.6.: The square block Square block The Square block (see Figure 4.6) can be used to generate a square wave. In particular, the output of this block can be summarized as output = 0.0 for kt < Delay output = Amplitude + Bias for kt Delay and in active state. output = Bias for kt Delay and in passive state. where T is the sampling time, k is the current sample, and the others are the parameters available for the block, which are: Amplitude This parameter gives the Amplitude of the square wave. Period This parameter provides the period of the square wave. Impulse Width This parameter gives the amount of time the signal remains in the active value. It can be used to obtain a variable duty cycle. Bias This parameter can be used to specify a offset value for the data. The output signal in passive state will always have the Bias value, in the active state the value will be equal to Bias + Amplitude. Delay This parameter provides an initial delay after which the square wave will start. It can be used to provide the phase of the square wave Sinus block The Sinus block (see Figure 4.7) can be used to generate a sine wave. In particular, the output of this block can be summarized as output = 0.0 for kt < Delay output = Amplitude sin((kt ) 2π F requency P hase) + Bias for kt Delay where T is the sampling time, k is the current sample, and the others are the parameters available for the block, which are: 43

44 Chapter 4. E4Coder blocks Figure 4.7.: The sine block. Amplitude This parameter gives the amplitude of the sine wave. Frequency This parameter provides the frequency of the sine wave. Phase This parameter gives the initial phase of the sine wave. Bias This parameter can be used to specify an offset value for the sine wave. Delay This parameter provides an initial delay after which the square wave will start E4CODER - IO These blocks are used to implement the input/output interfacing to specific I/O peripherals on the target microcontrollers. The main features which are common to all these blocks are the following: Symbolic naming All blocks have a Symbol Name, which is used to reference the specific block during the code generation process. Independency from the target hardware All the blocks in the I/O palette represent a category of peripherals. For example, a PWM block represents a generic PWM device on a generic target. The mapping between a block and the corresponding PWM peripheral is done when configuring the Code Generation process. In this way we obtain two important features: The target-specific configuration are not stored inside the block but stored in an E4Coder User Preference block (see Section ), making possible to map all blocks to specific peripherals on the target board in one single step (which is a step in the code generation process). The diagram containing the blocks does not need to be modified when changing target board. More than one target can be configured on the same diagram, using more than one E4Coder User Preference block. Simulation support These blocks support an additional simulation port, to allow the simulation of the peripheral inputs and outputs. 44

45 Chapter 4. E4Coder blocks In particular, peripherals that produce values (e.g, an ADC block, that at each sampling time generates one value result of an Analog to Digital converter read), will have the possibility to have an additional input simulation port (these blocks are also named E4coder-Input blocks); peripherals that consume values (e.g., a PWM block, that at each sampling time will be programmed using a duty cycle computed by a control algorithm) will have the possibility to have an additional output simulation port (these blocks are also named E4coder-Output blocks). The idea behind these additional simulation ports is that they will be used to simulate the behavior of the generic peripheral. The typical control diagram in fact will be composed by one or more first-level superblocks (containing all the controllers object of the code generation process, see Section 6), plus a simulation of the plant outside these superblocks. The I/O blocks will be contained inside the Superblock object of the code generation, and the simulation ports will be connected outside the superblock to provide a simulation of the plant to be controlled. In order for a superblock to generate code successfully, the simulation ports of the E4coder I/O blocks should be directly connected to the superblock I/O ports. As a result, the same diagram will be used both for simulation and for code generation, without the need of having a diagram for simulation purposes only, and another diagram for code generation only ADC block Figure 4.8.: The ADC block. This block models an Analog to Digital Converter (see Figure 4.8). The idea is that the block will provide one output with the latest value read from the ADC. Depending on the target implementation, the ADC may be read on the fly when the ADC Block is evaluated, or may read the latest value read from the ADC (if the ADC is read asynchronously with respect to the evaluation of the ADC block). The parameters of the block are the following: Symbol The symbolic name of the block. Show simulation ports When this parameter is 1, the block will have one additional input simulation port which will simply pass the value at the input port to the out- 45

46 Chapter 4. E4Coder blocks put port. There is currently no rounding of the ADC data following the precision available on the ADC. Signal Type The output signal as well as the input signal has size [1,1] and Scicos type 7 (unsigned int16) Button block Figure 4.9.: The Button block. This block models a button (see Figure 4.9). The idea is that the block will provide one output with the button status (1 when pressed, 0 when not pressed). The button status is typically read as is from a button pin on a microcontroller, without interrupts: for that reason, please note that you may loose events if the sampling time is longer than a button press (that is, the button is pressed and then released between two sampling instants). The parameters of the block are the following: Symbol The symbolic name of the block. Show simulation ports When this parameter is 1, the block will have one additional input simulation port which will simply pass the value at the input port to the output port. Signal Type The output signal as well as the input signal has size [1,1] and Scicos type 5 (int8) DAC block Figure 4.10.: The ADC block. 46

47 Chapter 4. E4Coder blocks This block models a Digital to Analog Converter (see Figure 4.10). The idea is that the block provides one input with the latest value to be written to the DAC peripheral. Depending on the target implementation, the DAC may write on the fly the value to the peripheral, or may write the value asynchronously. The parameters of the block are the following: Symbol The symbolic name of the block. Show simulation ports When this parameter is 1, the block will have one additional output simulation port which will simply pass the value received from the input port. Signal Type The output signal as well as the input signal has size [1,1] and Scicos type 1 (double) Digital Input block Figure 4.11.: The Digital-Input block. This block models a general purpose digital input (see Figure 4.11). The idea is that the block will provide one output with the pin status (1 when high, 0 when low). The pin status is typically read as is from a pin on a microcontroller, without interrupts: for that reason, please note that you may loose events if the sampling time is longer than the active time. The parameters of the block are the following: Symbol The symbolic name of the block. Show simulation ports When this parameter is 1, the block will have one additional input simulation port which will simply pass the value at the input port to the output port. Signal Type The output signal as well as the input signal has size [1,1] and Scicos type 5 (int8). 47

48 Chapter 4. E4Coder blocks Figure 4.12.: The Digital-Output block Digital Output block This block models a general purpose digital output (see Figure 4.12). The idea is that the block will write the value on the mapped pin (1 when high, 0 when low). The parameters of the block are the following: Symbol The symbolic name of the block. Show simulation ports When this parameter is 1, the block will have one additional output simulation port which will simply pass the value at the input port to the output port. Signal Type The output signal as well as the input signal has size [1,1] and Scicos type 5 (int8) Buzzer block Figure 4.13.: The Buzzer block. This block models a buzzer (see Figure 4.13), which is a sort of really cheap speaker capable to play a single frequency at a time. The idea is that the block receives as input a frequency that is maintained until a new frequency is provided. The parameters of the block are the following: Symbol The symbolic name of the block. Show simulation ports When this parameter is 1, the block will have one additional output simulation port which will simply pass through he input value. Signal Type The output signal as well as the input signal has size [1,1] and Scicos type 1 (double). 48

49 Chapter 4. E4Coder blocks Encoder block Figure 4.14.: The Encoder block. This block models a quadrature encoder (see Figure 4.14). At each sampling time, the Encoder block will return the latest value read from the peripheral on the first output, and the encoder index on the second output. Please note that the behavior of the block in code generation depends on the specific peripheral available on the target hardware. In particular: if the real quadrature encoder peripheral is not present then the system will use two GPIOs for counting the encoder ticks. the index value is typically 0, and has a value 1 when the index tick happens. The reference implementation says that the index should have a value equal to 1 for at least 1 tick. Please note that not all targets have the index input, and for that reason on some target architectures the index information may not be generated. The parameters of the block are the following: Symbol The symbolic name of the block. Show simulation ports When this parameter is 1, the block will have two additional input simulation ports composed by an uint32 for the encoder counter, and an uint8 for the index. In simulation, the block will implement a simple pass-through of the input values to the output values. Signal Type The output signals as well as the input signals have sizes [1,1;1,1] and Scicos types [3;8] (int32; uint8) LCD block This block models a 16x2 characters LCD peripheral (see Figure 4.15). At each sampling time, the LCD will be programmed with the characters coming from the input values. Please note that the real peripheral, depending on the target, may not be programmed at each sampling time (often the sampling time is faster than the refresh time of the 16x2 characters LCD). The typical implementation with an RTOS is that there will be a dedicated low-priority task devoted to the periodic update of the LCD (e.g, every 0.5 seconds). 49

50 Chapter 4. E4Coder blocks Figure 4.15.: The LCD block. The block has two input ports, accepting two vectors of 16 uint8 values each, which will be mapped to the respective lines of the LCD. The parameters of the block are the following: Symbol The symbolic name of the block. Show simulation ports When this parameter is 1, the block will have two additional output simulation ports composed by two vectors of 16 int8 values. In simulation, the block will implement a simple pass-through of the input values to the output values. You can use for example a FLEX Demo Board block (see Section 4.2.2) or E4Coder GUI blocks (see Section 4.2.3) to display these data during simulation. Signal Type The output signals as well as the input signals have sizes [1,1;1,1] and Scicos types [8;8] (uint8; uint8) LED block Figure 4.16.: The LED block. This block models a LED peripheral (see Figure 4.16). At each sampling time, the LED will be programmed either on or off. The block has a single input port. The LED will be turned on depending on the input signal value. The parameters of the block are the following: Symbol The symbolic name of the block. Show simulation ports When this parameter is 1, the block will have one additional output simulation port of type real. In simulation, the block will implement a simple pass-through of the input value to the output value. 50

51 Chapter 4. E4Coder blocks Signal Type The output signal as well as the input signal has size [1,1] and Scicos type 5 (int8) PWM / SERVO block Figure 4.17.: The PWM block. This block models a Pulse Width Modulation (PWM) peripheral, which can also be used to control a Servo motor (see Figure 4.17). At each sampling time, the PWM peripheral will be programmed with a duty cycle coming from the input value. The block has a single input port which is a real value representing an useful signal during the simulation and the input of the target function in code generation. On the target, the PWM frequency is currently hard-coded in the PWM block implementation and it is currently not available as a parameter. The parameters of the block are the following: Symbol The symbolic name of the block. Show simulation ports When this parameter is 1, the block will have one additional output simulation port of type real. In simulation, the block will implement a simple pass-through of the input value to the output value, without simulating a real PWM. Signal Type The output signal as well as the input signal has size [1,1] and Scicos type 1 (double) Touch block Figure 4.18.: The Touch block. 51

52 Chapter 4. E4Coder blocks This block models a resistive touchscreen (see Figure 4.18). At each sampling time, the block will return the latest position read from the touchscreen. The output ports of the blocks are two integer values representing the latest x and y position read from the touchscreen. The parameters of the block are the following: Symbol The symbolic name of the block. Resolution This parameter is the touch panel resolution. For example, a value of [240;180] maps to a touch panel with a resolution of 240 by 180 pixels. Show simulation ports When this parameter is 1, the block will have 2 additional input simulation ports of type integer. In simulation, the block will implement a simple pass-through of the input values to the output values. Signal Type The output signals as well as the input signals have sizes [1,1;1,1] and Scicos types [4;4] (int16; int16) Read and Write blocks Figure 4.19.: The Read block. Figure 4.20.: The Write block. The Read and Write blocks (see Figures 4.19 and 4.20) are used to map data exchanges in and out a superblock (the typical scenario is when you have to exchange data between two superblocks running at different frequencies or even on a distributed network). The idea is that the system maintains a set of global values which are read and written by the various concurrent tasks in the system. Each instance of a Read (Write) block then implements the read (write) of a global value available in the system. The global 52

53 Chapter 4. E4Coder blocks value will be implemented in different ways depending on the superblocks which are connected together by means of these blocks (see Section 6). Please note that Read and Write blocks can be added implicitly by the code generator each time a block not belonging to the I/O or Custom palettes (see Sections and 4.2.9) is directly connected to an I/O port of the superblock (see Section 6). To force Read and Write block code generation you can add manually these blocks in a superblock. This is very useful when an E4coder custom block is used, because the code generator cannot made any assumption on the behavior of the block. For that reason, if the E4coder custom block is directly connected to an I/O port of the superblock, the automatic insertion of Read and Write blocks is not executed and the block is assumed as an I/O block. The parameters of the two blocks are the following: Symbol The symbolic name of the block. IO size and type This parameter maps the size and type of the variable to be read- /written, in the typical ScicosLab notation. Show simulation ports When this parameter is 1, the block will have 1 additional simulation port (input port in the case of the Read block, output port in the case of the Write block) of the same time specified in the IO size and type parameter. In simulation, the block will implement a simple pass-through of the input values to the output values. Signal Type See IO Size and type above E4CODER - NONLINEAR E4C Saturation block Figure 4.21.: The E4C SATURATION block. This block models a Saturation block (see Figure 4.21). The block has a single input port and a single output port. The type of the input is inherited from the previous block. Integers are supported. Basically this block was explicitly made for implementing integer saturation. For this block, the code generator is able to generate appropriate code which does not make use 53

54 Chapter 4. E4Coder blocks of floating point. If a floating point value is given on the limits below, then it is casted to the correct type before its usage. Zero crossing for this block is disabled. If you need zero-crossing we suggest the usage of the standard saturation block available in ScicosLab (see Section 4.3). The parameters of the block are the following: Upper Limit The upper limit of the saturation. Lower Limit The lower limit of the saturation E4C Product block Figure 4.22.: The E4C PRODUCT block. This block models a Product/Division block (see Figure 4.22). The block has one or more input port(s) and a single output port. Compared to the standard block available in Section 4.3, this block also supports Integers. Basically this block was explicitly made for implementing integer Product/- Division. For this block, the code generator is able to generate appropriate code which does not make use of floating point. Type inheritance is disabled for this block. The parameters of the block are the following: Sign Vector A vector specifying if the correspondent input should be part of a product (value 1) or a division (value -1). Input Type This value specifies the type of all the input values. Output Type This value specifies the type of the output values E4CODER - COM The communication blocks provided by E4Coder can be classified in various groups: CAN Blocks These blocks can be used to send and receive single CAN messages. The blocks provide a Trigger port which is used to trigger the send when needed or to signal the reception of a message. 54

55 Chapter 4. E4Coder blocks Serial Blocks These blocks (CG SCI CFG, CG SCI TX, CG SCI RX) can be used during simulation to read and write raw serial data (array of characters) into the serial line. The raw data is written without any framing nor checks whatsoever on the serial line. These blocks are going to be obsoleted in future versions of E4Coder. Serial Message Blocks These blocks (CG SERIAL MSG TX, CG SERIAL MSG RX) implement a complete simulation/target board supported raw serial transmission. EasyLab Serial Blocks These blocks (CG EASYLAB SERIAL TX, CG EASYLAB SERIAL RX) implement a serial transmission of two float variables, which are incorporated in a simple framing with CRC. These blocks can be used whenever you want to have a quick way of sending receiving data (up to 2 floats with 1 Ksample/s) without taking care of transmission errors CG CAN CFG block Figure 4.23.: The CG CAN CFG block. This block should be used to configure a CAN port (see Figure 4.23); at least one instance of this block should be present in the diagram in order to correctly use the CAN blocks described below. The block has no input/output ports and can only be used in simulation mode (in other words, it is not yet supported by the code generator). The parameters of the block are the following: Bit rate Working bit rate of the CAN port. Hardware Type CAN port type. The current version of the blocks supports only two types: 0 means that no external device is connected to the PC and the block executes a simulation with no action, 5 means PCAN USB (a CAN sniffer from PEAK System Device ID The device number, in case of multiple devices (in the current version only a single device is supported). 55

56 Chapter 4. E4Coder blocks Figure 4.24.: The CG CAN TX block CG CAN TX block This block should be used in a simulation to transmit a CAN message (see Figure 4.24). The block has 5 input ports and one output port. The first input port ([1,1], uint32) is the identifier of the message. The second input port ([1,1], uint8) is the type of the message (0 for a standard message, 1 for an extended identifier message). The third input port ([1,1], uint8) is the length of the message payload. The fourth input port ([8,1], uint8) is the payload. The fifth input port ([1,1], uint8) is the transmission trigger (0 to not transmit, 1 to transmit). The output port ([1,1], uint32) is the number of the currently queued messages on the interface (in this version is always 0). The number of queued messages can be more than 0 when the system is trying to send message at a higher rate than what the CAN network can receive. The parameters of the block are the following: Hardware Type CAN port type. The current version of the blocks supports only two types: 0 means that no external device is connected to the PC and the block executes a simulation with no action, 5 means PCAN USB (see Section ). Device ID The device number, in case of multiple devices (in the current version only a single device is supported). Queue length Length of the TX queue (not supported in this version, only 1 is accepted). A value greater than one means that the driver must be able to queue at least a given number of messages before dropping packets CG CAN RX block Figure 4.25.: The CG CAN RX block. This block should be used in a simulation to receive a CAN message (see Figure 4.25). The block has 5 output ports and no input port. The first output port ([1,1], uint32) 56

57 Chapter 4. E4Coder blocks is the identifier of the message. The second output port ([1,1], uint8) is the type of the message (0 for a standard message, 1 for an extended identifier message). The third output port ([1,1], uint8) is the length of the message payload. The fourth output port ([8,1], uint8) is the payload. The fifth output port ([1,1], uint8) is the reception trigger (1 if a new message is returned at a given sampling time). The parameters of the block are the following: Hardware Type CAN port type. The current version of the blocks supports only two types: 0 means that no external device is connected to the PC and the block executes a simulation with no action, 5 means PCAN USB (see Section ). Device ID The device number, in case of multiple devices (in the current version only a single device is supported). Queue length Length of the RX queue (not supported in this version, only 1 is accepted). A value greater than one means that the driver must be able to queue at least a given number of messages before dropping received packets CG SCI CFG block (OBSOLETE) Figure 4.26.: The CG SCI CFG block. This block should be used to configure a COM port for serial communication (see Figure 4.26); at least one instance of this block should be present in the diagram in order to correctly use the SCI blocks described below. The block has no input/output ports and can only be used in simulation mode (in other words, it is not yet supported by the code generator). This block is going to be obsoleted in future versions of E4Coder. Use The parameters of the block are the following: COM port COM port to be used. 0 to have a void simulation, a number x to open the COMx port. Baudrate Bit rate [bps] to be used for the communication. 57

58 Chapter 4. E4Coder blocks Figure 4.27.: The CG SCI TX block CG SCI TX block (OBSOLETE) This block should be used in a simulation diagram to transmit an array of characters using a serial communication COM port (see Figure 4.27); The block has two input ports. The first input port accepts an array of data to be transmitted ([n,1], uint8). The second input port is the trigger that enable the transmission. If the trigger is equal to 0 data will not be transmitted, if trigger is 1 data will be transmitted. This block should be used only in a pc-side diagram, it is not yet supported by the code generator. This block is going to be obsoleted in future versions of E4Coder. Use CG SERIAL MSG TX instead. The parameters of the block are the following: Hardware type COM port to be used. 0 to have a void simulation, a number x to use the COMx port. Data length Length of the array of characters (size of the first input port) CG SCI RX block (OBSOLETE) Figure 4.28.: The CG SCI RX block. This block should be used in a simulation diagram to receive an array of characters by a serial communication port (see Figure 4.28); The block has two output ports. The first output port contains the array of the received data ([n,1], uint8). The second output port is the trigger, the flag used to signal if new characters have been received. If the trigger is equal to 0 the data port contains old characters, if the trigger is 1, the data array contains new received data. This block should be used only in a pc-side diagram, it is not yet supported by the code generator. 58

59 Chapter 4. E4Coder blocks This block is going to be obsoleted in future versions of E4Coder. CG SERIAL MSG RX instead. The parameters of the block are the following: Use Hardware type COM port to be used. 0 to have a void simulation, a number x to use the COMx port. Data length Length of the array of characters (size of the first output port) CG SERIAL MSG TX block Figure 4.29.: The CG SERIAL MSG TX block. This block can be used in simulation and code generation to send an array of characters to a serial communication COM port (see Figure 4.29); The block has two input ports and one output port. The first input port contains the array of the received data ([n,1], uint8). The second input port is the trigger: when the trigger is equal to 1, the block eventually sends the data to the serial line. The overflow output is used to inform about the successful transmission of the data and should be interpreted in the following way: If the trigger is 0, then the overflow is 0 (nothing is being sent). If the trigger is 1, and the overflow is 0, it means that the data has been successfully queued into the serial buffer for transmission. If the trigger is 1, and the overflow is 1, it means that the remaining free space into the serial transmission buffer is not enough to store the data sent. In this case, the data is not queued into the transmission buffer 1. Using more than one TX block linked to the same serial port is allowed. The result will be that all sent messages will be queued on the output buffer. The parameters of the block are the following: Port index COM port to be used during simulation. Msg Size Length of the array of characters (size of the first input port). 1 As an example, if the data size is 10 bytes, but there are only 3 free bytes into the serial output buffer, then none of the 10 bytes will be copied into the 3 free bytes. 59

60 Chapter 4. E4Coder blocks Baud Rate Serial line baud rate used for transmission. When using more than one block linked to the same serial line, all blocks must have the same baud rate. If they are specified with different values, it is unspecified which of the available values will be eventually used during simulation and code generation 2. Symbol The block symbol used in the generated code CG SERIAL MSG RX block Figure 4.30.: The CG SERIAL MSG RX block. This block can be used in simulation and code generation to receive an array of characters from a serial communication port (see Figure 4.30); The block has three output ports. The first input port contains the array of the received data ([n,1], uint8). The second input port is the trigger: when the trigger is equal to 1, the data contains fresh information from the serial line. Please note that the reading from the serial line is non-blocking: in other words, if there are not enough data to be read, the block will return setting trigger to 0. The overflow output is used to inform about the fact that some characters have been lost due to an overflow in the serial read buffer. Please also note that lost characters due to noise on the serial line will not be noticed using the overflow port, simply because these characters will never arrive to the target system. You can only use one block of this kind for each serial port. If using more than one, it is unspecified where characters will be delivered. The parameters of the block are the following: Port index COM port to be used during simulation. Msg Size Length of the array of characters (size of the first input port). Baud Rate Serial line baud rate used for transmission. See Section for further restrictions on baud rate specification. Symbol The block symbol used in the generated code. 60

61 Chapter 4. E4Coder blocks Figure 4.31.: The CG EASYLAB SERIAL TX block CG EASYLAB SERIAL TX block This block can be used to implement a data link communication layer mapped over a serial line (see Figure 4.31) 3. The block has two input ports. Protocol description. Each activation of the block takes the two inputs values and converts them into floats. Afterwards, the pair of values is queued into the transmission queue. At transmission time, each pair is packed forming a 10 bytes packet with the following structure: S F 1 1 F 1 2 F 1 3 F 1 4 F 2 1 F 2 2 F 2 3 F 2 4 CRC where S is the start byte, with value AA, and the last byte is a simple CRC. The protocol is meant to be transmitted over a baud serial line at a frequency of 1000 packets per second. The parameters of the block are the following: COM port COM port to be used during simulation. Baudrate Bit rate [bps] to be used for the communication. Typically Symbol The symbolic name of the block CG EASYLAB SERIAL RX block This block can be used to implement a data link communication layer mapped over a serial line (see Figure 4.32). The block has two output ports. The protocol implemented by this block is the same as the one described for the CG EASYLAB TX block (Section ). The block will propose as output the content of the latest block packet correctly, basically implementing a sample and hold mechanism. There is no guarantee of correct reception, or queuing mechanism. The parameters of the block are the following: 2 In practice, the first block which will be initialized during simulation / runtime on the target will provide the baud rate used. 3 the block name recalls the Evidence EasyLab board, because the protocol implemented was the one used in the serial line communication demos of that board. 61

62 Chapter 4. E4Coder blocks Figure 4.32.: The CG EASYLAB SERIAL RX block. COM port COM port to be used during simulation. Baudrate Bit rate [bps] to be used for the communication. Typically Symbol The symbolic name of the block E4CODER - CUSTOM E4Coder Custom block Figure 4.33.: The CUSTOM block. This block can be used to implement a customized Scicos block for the E4coder code generator (see Figure 4.33). The idea behind this block is that you will be able to provide in a reasonably simple way two versions of the behavior of this block, one to be used in simulation and another to be used for code generation. For more information about the usage of this block please refer to Section 9.4. Please note that the custom block has no simulation ports to be shown/hidden, as it happens with the blocks of the I/O Palette (see Section 4.2.6), because a custom block can have different behaviors: If the block is not directly connected to superblocks IO ports, then the block is assumed to be an algorithm block. In this case all input and output ports of the blocks are also considered in code generation. 62

63 Chapter 4. E4Coder blocks If the block is directly connected to an input port of the superblock, then the custom block is assumed to be an input block. In this case the corresponding input ports of the block will be ignored in code generation. Lastly, if the block is directly connected to an output port of the superblock, then the custom block is assumed to be an output block. In this last case the corresponding output ports of the blocks will be ignored in code generation. If the custom block is assumed to be an input or an output block, the code generator will not implicitly put any Read or Write blocks next to a custom block and the user needs to explicitly put these blocks when needed, see Section 8). The parameters of the block are the following: Name The symbolic name of the block. For example, myblock. This is also the name of the function executed in simulation as well as in the generated code. States initialization This contains the values used as initial values for the internal status vector of the block. In simulation the status vector should be a vector of real values. In code generation you can overwrite this behavior specifying a different status structure. Further information about this kind of customization can be found in Section 9.4 Parameters values This contains a list of the values that can be passed as parameter to the block. In the list you can specify value of different types. Also this structure can be overwritten, further information can be found in Section 9.4 Parameters names This contains the list of names to be used for the various parameters. These names are used by the code generator for structure definition. If the user specifies the names only for the first subset of the parameters, the code generator will use default names, like this p# (#, is the number) for the other fields. Inputs sizes and types This parameter maps the size and type of the various input ports (to be specified in the ScicosLab notation). Output sizes and types This parameter maps the size and type of the various output ports (to be specified in the ScicosLab notation). Direct feed-through The value is 1 if the block has a direct feed-through (meaning that the output of the block is a function which instantly depends on the input values), 0 otherwise. If direct feed-through is enabled the custom block function will be called in according to the blocks execution order, otherwise, if direct feed-through is disabled, the custom block function will be called first not following the block execution order. The user should take care of this during block s configuration. 63

64 Chapter 4. E4Coder blocks Figure 4.34.: The USER-PREF block E4Coder User Pref The User Pref block (see Figure 4.34) is a container of the settings used for generating code with the E4Coder code generator. The basic idea is that all parameters which are selectable from the code generation panel (see Chapter 6) will be stored inside a User Pref block. In this way, we obtain the possibility to reuse the same diagram in various code generation configurations. The code generator properties are not selectable from the block properties, but are accessed from the Code Generation wizard. For that reason, the only parameter of the block is the following: Symbol The symbolic name of the block. For example, my settings, or any other name useful to discern different code generation settings Standard blocks supported by E4Coder In addition to the custom blocks provided by the E4Coder palettes, the E4Coder code generator can handle the standard Scicos blocks, replicated for user convenience in the palette E4CODER-LIBRARY (see Figure 4.35), which are part of the standard ScicosLab palettes: SUM PRODUCT and GAIN COUNTER and MODULO-COUNTER CONSTANTS SYNCHRONOUS CLOCK DISCRETE-TIME DELAY MULTIPLEX (MUX, DEMUX) LOGICAL and RELATIONAL OPERATORS SWITCH and MULTIPLE-SWITCH 4 4 Please note that the switch input for these blocks should not be a double. 64

65 Chapter 4. E4Coder blocks Figure 4.35.: The standard Scicos blocks supported by the E4Coder Code Generator. SATURATION TYPE CONVERSION EXPRESSION DLR RFILE f WFILE f SIGN EXTRACTOR For all them, the system provides an implementation on the target that implements the same behavior of the simulation implementation shipped with the unmodified ScicosLab, with the exception of the blocks listed in the subsections below EXPRESSION block This block is a standard ScicosLab block which can be used to compute a mathematical expression. When generating code, the expression is coded in RPN form inside the block 65

66 Chapter 4. E4Coder blocks Figure 4.36.: The EXPRESSION block. data structures; after that, the expression is evaluated on the fly when the block step function is called. The block works during code generation in the same way of the original ScicosLab block, with the following limitations: Zero crossing is not supported; The code generation version of the block supports all the mathematical operation available in simulation; thus, the system will link all the functions despite they will not be used in the expression under evaluation; The evaluation of user variables in the Scicos context is not supported; We do not suggest using this block on small microcontroller projects due to its overhead in both time and footprint. However, the block is very nice for a fast and quick prototyping DLR block Figure 4.37.: The DLR block. This block is a standard ScicosLab block which can be used to compute a z-transform expression composed by a numerator and a denominator which can be expressed as a Scicos Rational, Polynomial or Constant expression RFILE f block This block is a standard ScicosLab block which can be used to read an input file. The parameters of the block are the following: Time record selection Not supported. 66

67 Chapter 4. E4Coder blocks Figure 4.38.: The RFILE f block. Output Record selection Not supported. The output vector is always written at each step. Input File Name Is the filename to be read. Note that the filename must be present in the simulation directory when simulating the diagram, and in the directory from where the generated executable is launched when running the code generated by E4CoderCG. Input format During simulation, the input format of each line must be specified as if it would have been analyzed by a fscanf function. During code generation, this parameter is ignored and the format used by default is %f, %f, %f (one %f for each input). Buffer size Not supported. The block execution always reads one line. Please note that this block is only supported on Linux pthread (see Section 7.3), RTAI (see Section 7.4), and Windows (see Section 7.2) targets. A demo of the usage of this block is available under E4Coder Demos / E4CoderGUI / Read Write Demo WFILE f block Figure 4.39.: The WFILE f block. This block is a standard ScicosLab block which can be used to write an output to a text file. Input Size This is the size of the input vector, which is the number of values that will be stored in each line of the file. 67

68 Chapter 4. E4Coder blocks Output File Name This is the name of the file to be written.the file will be generated in a position relative to current directory where the generated application will be executed. Output Format Not supported. Values are always written using an fprintf pattern like %f, %f, %f\n. Buffer Size Not supported. The block execution always writes one line. Please note that this block is only supported on Linux pthread (see Section 7.3), RTAI (see Section 7.4), and Windows (see Section 7.2) targets. A demo of the usage of this block is available under E4Coder Demos / E4CoderGUI / Read Write Demo. 68

69 5. Simulating a design The simulation of a diagram containing E4Coder blocks works in the same way of normal ScicosLab simulations. In particular: All blocks provided by the E4Coder palettes can be part of a simulation. When starting a simulation some blocks (SMCube, E4Coder GUI, FLEX Demo Board) will start external programs that will provide additional features (e.g., the SMCube simulator, and so on). Before starting a simulation, the DLL of the custom blocks, used in the diagram, should be previously loaded (see Section 9.4). When simulating I/O blocks you are supposed to configure appropriate simulation input/output ports. The simulation input ports will be useful to provide a simulated input for the input block (for example, you can simulate the data produced by an ADC converter), and the simulation output ports will be useful to plot the data which are computed by your controller. Moreover, using the simulation input/output ports you can add blocks to be used only for simulation. In this way you can validate the control algorithm before generating your code. In other words, the same diagram can be used for both simulation and code generation. Please note that the simulation ports are, unless specified, implemented as a passthrough during simulation. In other words, this means that the I/O blocks do not manage specific peripheral models. This is not a problem since the user can simulate any behavior or disturbance, i.e. quantization effects, by using the standard Scicos blocks library outside of the superblock object of the code generation. That superblock instead will contain only the logic to be implemented on the target. As an example, you can consider an ADC block. The ADC block will have one simulation input and one output. The code which is generated for the ADC will read the real ADC peripheral providing an output with a given number of bits of precision (which depends on the specific target microcontroller). The code which will simulate the ADC in simulation will instead just copy the simulation input to the output without doing any action. As an example of design, please consider the E4Coder demo named DC Motor control algorithm (PID) demo, which implements a PID controller with an Encoder and a PWM block. The controller is enclosed in a superblock, which is connected to a linear model 69

70 Chapter 5. Simulating a design of a DC motor. As a result, the diagram can be simulated, and code can be generated without modifying the diagram. In simulation, the Encoder simulated inputs are taken from the simulated motor output position, whereas the PWM simulated outputs are used to simulate the command sent to the simulated motor. As a result of the simulation, the reference signal and the motor position are displayed on a ScicosLab scope. 70

71 6. The code generator 6.1. Execution model of the generated code This Section briefly describes the execution model which is at the basis of the E4Coder Code Generator. The input information used by the Code Generator to generate C code is a Scicos Diagram. A Scicos diagram is basically a data-flow model composed by a set of blocks which are interconnected, exchanging data passed through the data links (the black wires on the diagram). The activation model of the data flow is controlled by clocks, that provide a discrete activation timing to the various blocks (the red lines on the diagram). The objective of the code generation process is to generate one or more C functions, named Runnables, that the user will be able to compile on a target system (typically a microcontroller). Depending on the settings, the code generator will generate either one Runnable for the entire diagram, or one Runnable for each first-level superblock 1. The Runnable which is generated is the result of a total ordering of the blocks in one superblock (or in the diagram if the entire diagram has been selected). The idea is that each superblock (or the entire diagram) must have a single clock providing the discrete reference time. The total ordering of the blocks is performed by the ScicosLab compiler and is the same total ordering used during the simulation of the diagram. For each Runnable, the code generator considers the total ordering of the blocks and generates some C code following a customized pattern which implements the simulated behavior of the block. When the target system is an operating system supported by the code generator (currently only the open-source OSEK/VDX operating system ERIKA Enterprise [8]), the code generator allows a deeper integration, providing the following support: The code generator allows the specification of a task set. Each task has a period, which is used to configure a per-task periodic timer (a periodic alarm in the OSEK/VDX jargon); The code generation allows the specification of a mapping between Runnables and task. In other words, a Task body will be generated as a sequence of Runnables, each one implementing a first-level superblock. The code generation allows the specification of a mapping between the generic peripheral I/O blocks and the actual peripheral available in the target board. The tool allows the selection among a list of supported boards, and allows the possibility 1 A first-level superblock is a block placed in the main diagram. 71

72 Chapter 6. The code generator to map each peripheral to a specific instance of the same kind available in the target board. A main() function and a corresponding makefile will be generated integrating the task activations and the specific RTOS drivers to allow the direct generation of a binary image implementing the diagram How to make a diagram ready for code generation The E4Coder Code Generator is able to generate code starting from a ScicosLab Diagram. However, not all diagrams are suitable for code generation. WARNING: Please note that the code generator will work only on a Scicos diagram/superblock containing only E4coder blocks and/or the standard blocks contained in the E4coder-LIBRARY palette. This also applies to the clock-source block used for blocks activation. Only the synchronous-clock block can be connected to superblocks to be generated, and the superblock cannot have more than one activation inputs. In any case, we suggest to use the synchronous clock even in Scicos diagrams used only for simulation purpose. In particular, when drawing your diagram you need to follow the rules below: Content of the Diagram or Superblock. When generating code from an entire diagram, the diagram must only contain blocks supported by the code generator, as listed in Chapter 4 2. When generating code from first-level superblocks, this limitation applies only to the subset of superblocks for which the code is going to be generated. Single clock input. When generating code for an entire diagram, only one clock is allowed. When generating code for first-level superblocks, the clocks must reside outside the superblocks, and only one clock (i.e., one red line) should enter the superblocks for which the code is going to be generated (see Figure 6.1). Simulation ports. If the superblock contains I/O blocks with simulation ports, then the simulation ports should go outside the superblock (that is, they should not be connected to any block inside the superblock; see Figure 6.2). Input simulation ports cannot be used if you want to generate code for the entire diagram. Memory blocks. Memory Blocks are supported when connecting two wires inside the same superblock, or if they are used when generating code for the entire diagram. Other usages will not work with the code generator. 2 Blocks in Chapter 4 which does not support code generation are explicitly marked. 72

73 Chapter 6. The code generator Figure 6.1.: Only superblocks with one clock input can be correctly generated. Figure 6.2.: Example of correct connection of a simulation input port How to run the code generator This Section will guide through the various steps needed to run the code generation process. The screenshots of this Section refer to the E4Coder demo named DC Motor control algorithm (PID demo) available from the E4Coder demos menu (see Figure??). To start the code generation process, you need to select a User Preferences block (see Section ), and after that you need to choose the E4Coder Code Generator from the Scicos menu as shown in Figure6.3. As a result of the selection, a wizard dialog box will be shown (see Figure 6.4). The purpose of the wizard is to guide you through the code generation process, presenting the various steps in a logical sequence. Please note that: All changes to the settings that will be done in the following panels can be saved in the USER PREF block after starting the code generation process or when closing the wizard. You can use more than one USER PREF block to store more than one code generation configuration on a single diagram. You can move between each panel using the Next / Back buttons. 73

74 Chapter 6. The code generator Figure 6.3.: The code generation process is started by selecting a USER PREF block, and then choosing the appropriate menu option. Before the dialog box will appear, you may see some windows flashing. This happens because the Code Generator has to perform a ScicosLab sequence of simulation initialization/end in order to obtain the correct total ordering of the blocks. As part of the simulation initialization there is the visualization of the scopes and/or other windows, which immediately disappear after the init sequence has been performed successfully. The additional option named E4Coder Regenerate Code can be used to directly generate the code with the information stored inside the USER PREF block, without displaying any wizard (this is useful during development to speedup the code generation process) Global parameters The first panel shown by the Wizard let you set the global parameters for the code generation process (see Figure 6.5). In particular, the following settings have to be noted: Project name This is the project name. This name will be used for some output files and to name the algorithm function in case of entire diagram code generation. Output directory This is the directory where the generated files will be put by the E4Coder code generator. The target directory will be automatically created if it does not exist. Please note that the output directory can be an arbitrary Scicos expression. In Figure 6.5, for example, the string used creates a relative path with respect to the E4Coder installation directory (stored in the variable E4CODERCG PATH), in a way to generate the code directly in the E4Coder examples directory. Scope This option selects the scope that should be considered by the code generator (see also Section 6.2). In particular, you can select one of the two following options: SUPER BLOCK SELECTION When this option is set, the code generation process will be performed only on a subset of the first level superblocks which are present 74

75 Chapter 6. The code generator Figure 6.4.: The E4Coder Code Generation wizard splash screen. in the diagram. By selecting this option, an additional panel will be shown, allowing the selection of which superblock will be part of the code generation (see Section 6.3.4). ENTIRE DIAGRAM When this option is set, the code generation process will generate code for all the blocks which are present in the diagram. Project Type This option let you select the kind of target runtime environment that is available. Currently, the following targets are available: LIBRARY This option configures the code generator to generate code for each superblock (or for the entire diagram) without any direct reference to an operating system, or to tasks. A single C function will be generated for each superblock (or one C function for the entire diagram). It is responsibility of the user to integrate the generated code inside the target system. This option is specially suited for target microcontrollers without an operating system. See Section 7.6 for more information. OSEK ERIKA PROJECT This option configures the code generator to generate code for the OSEK/VDX operating system ERIKA Enterprise [8]. See Section 7.1 for more information. LINUX PROJECT This option configures the code generator to generate code for the 75

76 Chapter 6. The code generator GNU/Linux operating system, using the pthread library. The Qt Library is also used to generate code for E4CoderGUI objects. See Section 7.3 for more information. WINDOWS PROJECT This option configures the code generator to generate code for the Microsoft Windows operating system, using multithread support provided by the Qt Library. The Qt Library is also used to generate code for E4CoderGUI objects. Please note that an E4CoderGUI object needs to be present to generate a valid application 3. See Section 7.3 for more information. LINUX RTAI PROJECT This option configures the code generator to generate code for the GNU/Linux RTAI operating system. Superblocks are mapped inside RTAI lxrt tasks (for better realtime performance) while graphics blocks (if any) are mapped in regular linux pthreads. The Qt Library is used to generate code for E4CoderGUI objects. See Section 7.4 for more information. BARE METAL PROJECT This option configures the code generator to generate code for a board without operating system. In this case, the periodic execution of the Superblocks is mapped inside code sections of the main() function. See Section 7.5 for more information. Please note that two additional panels for the selections of the tasks and the I/O mappings will appear when the project type is different from LIBRARY. The first one (see Section 6.3.3) allows the specification of the tasks in the system; the second one (see Section 6.3.5) allows the mapping of I/O blocks to the target peripherals Target selection This panel will appear only if the code generation Project Type is different from LIBRARY. This panel is used to specify which target board will be used among those configured for the Project Type selected in the previous window (see Figure 6.6). The target board selected will influence the number of entry points (see Section and ) and peripherals (see Section 6.3.5) available during code generation. Note that it is possible to add your own target boards and peripherals, as specified in Section Task selection This panel will appear only if the code generation Project Type is different from LIBRARY. The idea of this panel (see Figure 6.7) is to list the various tasks and entry points (see Section ) that can be used for the mapping process of Runnables to Tasks. By pressing the Add (Edit) button, you will be able to add (edit) new (existing) tasks (see Figure 6.8). The task properties that you can edit are the following: 3 This limitation will be removed in the next release of E4Coder. 76

77 Chapter 6. The code generator Figure 6.5.: The Code Generation Project settings. Task name Is the name of the task. In OSEK/VDX operating systems, this will correspond to the Task name in the OIL file. Task period Is the period of the task, in seconds. In OSEK/VDX operating systems, given the periodicity of the tick in the underlying target hardware (see Section 6.3.5), the code generator will compute a multiple of the base tick and initialize an alarm linked to the task accordingly. Then, the alarm will be started in the StartOS() primitive of the runtime environment. Note, if the chosen period/offset is not a multiple of the minimum period (target-dependent), the resulting value used for the task activation will be rounded to the nearest integer (see Section 7.1). On Linux and Windows systems, the internal operating system timer will be used to guarantee the periodicity (see Sections 7.3 and 7.2). Task priority Is the Task priority. In OSEK/VDX operating systems, this will correspond to the PRIORITY task attribute in the OIL file. On Linux system, this will be mapped to a pthread priority. On Windows systems, it will be mapped to a Qt priority (see 7.2). Task offset This is the initial offset of the task, that is the initial time after which the task will start. In OSEK/VDX operating systems, this will correspond to the interval attribute of the call to SetRelAlarm used to activate the task. In other 77

78 Chapter 6. The code generator Figure 6.6.: Target selection, used to specify which target board will be used for code generation. 78

79 Chapter 6. The code generator Figure 6.7.: The Panel allowing the specification of the tasks in the system. systems, an initial blocking wait will ensure the initial offset. Finally, by pressing the C-compiler configurator button, this panel allows the specification of a set of parameters which are dependent on the operating system selected in the step described into Section Please see the specific target operating system description for more information: ERIKA Enterprise, Section Linux pthread, Section Microsoft Windows, Section RTAI, Section Subsystem selection After the specification of the tasks which will compose the target application, this panel allows to specify two aspects of the code generation: Which are the first-level superblocks that will be generated. 79

80 Chapter 6. The code generator Figure 6.8.: Creating or Editing a Task. The selection of the mapping between the tasks/entrypoints defined in the previous panel and the runnables (which are the C functions generated for each superblock). The Task mapping is not available if LIBRARY has been selected as Project Type. This panel is only available when the Scope SUPERBLOCK SELECTION has been selected, and it is divided in two parts (see Figure 6.9). The top part initially contains all the firstlevel superblocks available in the diagram. The bottom part contains the superblocks which have been selected for code generation. Each superblock is identified by its IDN (see Section 6.3.6). To move a superblock from the top part to the bottom part and viceversa, you can use the Enable / Disable / Enable all / Disable all buttons available in the panel. You can use the Properties button to get information about the superblocks, and about their periods and offsets. Once enabled, you can press on the Properties button to select to which task/entrypoint the specific superblock is mapped (see Figure 6.10). You can also specify an ordering of the superblocks using the Move Up / Move down buttons. The order between superblocks allocated to the same task/entrypoint will be preserved in the order with which the runnables will be called in the generated code Target and I/O settings This panel is used to perform the selection of the mapping of I/O blocks to the actual peripherals available on the target board selected in Section Moreover, the panel allows the specification of the message boxes used for the communication using Read/Write I/O blocks. The panel is shown in Figure The following rules apply: If the Project Type is LIBRARY, then this panel will not appear. The idea is that with a LIBRARY implementation it is responsibility of the user to manually provide the mapping between the peripheral blocks and the real target peripherals, as well as the mapping of the Read/Write blocks to the actual buffers. All peripheral blocks must have a mapping in order to proceed with the code 80

81 Chapter 6. The code generator Figure 6.9.: Subsystem selection. generation process. You cannot proceed with the code generation if the target you selected does not support all peripheral blocks used in the diagram. If you changed target board in Section 6.3.2, all the mapping settings will be reset to UNDEFINED, including the Read/Write block mappings. It is possible to add your own target boards and peripherals, as specified in Section 9.3 The idea is that each target board selected in Section has a number of possible input/output peripherals, which become available for the mapping of each I/O block present in the superblocks selected for code generation. By Clicking on the Properties button, it is possible to change the mapping of a block among all the peripherals of the same kind available on the target (see Figure 6.12). If the block is of type Read or Write, then the choice can be done among all the user messages defined using the Button Data Exchange configurator (see Figure 6.11). When pressing the button, a dialog box will be open (see Figure 6.13) enabling the creation of data structure to be used as user messages sent by the Write Blocks and read by the Read blocks. The Add/Edit buttons can be then used to define the various message properties: the first property is about the kind of message that is specified 81

82 Chapter 6. The code generator Figure 6.10.: Superblock to task mapping. (for now, only RAM can be selected 4 ; see Figure 6.14). After that, you can specify the symbol that will contain the message object (see Figure 6.15). Please note that as a result of the association between a Read/Write block and a user message of type RAM, a global variable will be created with a name corresponding to the user message name. Type and size of the messages are inherited from the block port associated to the message. E4Coder executes also a consistency check on the message block association to avoid conflicts regarding size or type. The implementation of read/write functions will be automatically generated by E4Coder Symbol settings This final panel (see Figure 6.16) is used to customize the name of the variables generated by the E4Coder code generator. The idea is that each output port generates a global variable which can have a default name which is generated from a pattern, or can have a specific name whenever the designer gave a link identification name to the wire. For that reason, the first thing that can be specified is a template for the variable names. The default template is as follows: %BLOCK TYPE% %BLOCK ID% %BLOCK NUMBER% outport %OUTPORT NUMBER% where the names surrounded by a % are the macros that are expanded during code generation. The macros are substitute in the following way: %BLOCK TYPE% is substituted with the type of the block (for example, switch, rt square, product,... ). %BLOCK ID% is substituted with the ID of the block, which is the ID of the containing superblock (it will be typically a number sequence separated by underscores, where each number is the superblock number in the diagram; for example, 14 4 means that the block is contained in a superblock number 4, which is contained in the top-level superblock number 14). %BLOCK NUMBER% is substituted with the block number. 4 In future versions other kinds will be available, such as network messages. 82

83 Chapter 6. The code generator Figure 6.11.: Target, I/O block, and message settings. %OUTPORT NUMBER% is substituted with the number of the output port of the block generating the signal. An example of name generated with this template is the summation block output port which is present in the integrator superblock in the example named DC motor control algorithm (PID) demo. The output port generates a global variable with the following name: where: sum block outport 0 sum is the type of the block (in this case, a SUMMATION block). block is the BLOCK ID. If the block has an identification name, E4coder assumes that the BLOCK ID is this identification string. Viceversa, the BLOCK ID will be block as shown in this example is the BLOCK NUMBER, which means that this summation block is contained in a third-level superblock (13/4/4), whereas the first level superblock has number 13, the second has number 4, the fourth as number 4. The last number (9) is the relative block number inside the nearest superblock. Please note that the block 83

84 Chapter 6. The code generator Figure 6.12.: Selecting the mapping for an Encoder block among the two encoders available in the FLEX MTB DCMOTOR board. number can be obtained by opening the GetInfo window. To open the GetInfo window you can press i when the block is selected or right-click on the block and choosing Get Info under Block Properties (see Figure 6.17). 0 is the OUTPORT NUMBER and it means the first output port of the block (in the generated code all the numbers start from zero). Below the template, the second option that can be specified is the possibility to use the identification string of a link for the name of a variable. In this way, it is possible to give customizable names to specific signals that have a special meaning in the system. For example, the demo DC motor control algorithm (PID) demo uses the link identification names to tag the proportional component, the integrative component, and the derivative component of a PID algorithm. These names can be found afterward in the generated code as variables with exactly that names, making in this way the code more readable. This applies only for the link directly connected to the output ports of a block. 84

85 Chapter 6. The code generator Figure 6.13.: This dialog box allows the specification of data messages which can be mapped to the Read/Write blocks. Figure 6.14.: This Dialog Box allows the specification of the kind of message. At the moment only the RAM option is available. WARNING: Please note, you can specify the identification strings for any connection in Scicos but only a subset of all the connections is actually handled by E4coder. In particular, E4coder handles only the identification strings of the links directly connected to an output port of a block. If you name an output link of an inner superblock, this string will be ignored in the code generation step. In this way, E4coder can avoid conflicts on the link names. Finally, it is possible to specify specific names for data types used internally by ScicosLab. In this way, the generated code will use the types defined by the target environment instead of the standard ones. Note that the Bare Metal target (see Section 7.5) has also two additional types (Time and Signed Time) used in the interfacing functions of the generated code (see Section ). The code generation can be started by pressing on the Finish button and may take a few seconds to run. The changes made to the code generation properties can be saved in the user preference block selected at the end of the code generation process. If the code is generated for the EE PROJECT target, then a compilation process can be 85

86 Chapter 6. The code generator Figure 6.15.: Enter the name of the global buffer enabled, providing in this way the possibility to s a ERIKA Enterprise application to be programmed on the target board (see Figure 6.18, for the compilation output window generated by the code generation on a Microchip dspic FLEX board[5]) Structure of the generated code The code generated by the E4Coder Code Generator is structured as a set of source files (see Figure 6.19), each one with a well specified content: data.c C-file containing the functional code obtained from the Scicos diagram. This file contains the implementation of the initialization, calculus and ending functions for each generated superblock. The code produced is highly readable and contains comments for every line to allow code traceability. data.h Header file containing the function-prototypes of the functional code contained in data.c. types.h Header file containing the user type definitions specified in the last panel of the E4coder Code-Generator wizard (see Figure 6.16). target.h Header file containing the prototypes of the target-specific functions. target.c C-file containing the implementation of the target-specific functions. This file will not be generated in case of a LIBRARY project. target names.h Header file containing target-specific macros and header inclusions.this file will not be generated in case of a LIBRARY project. task.c C-file containing the implementation of the tasks (sequence of Runnables) as specified by the the user in the superblock-to-task mapping step (see Section 6.3.4). This file will not be generated in case of LIBRARY project. main.c C-file containing the main entry point of the application. This file will not be generated in case of LIBRARY project. conf.oil OIL-file containing kernel configuration. This file will not be generated in case of LIBRARY project. 86

87 Chapter 6. The code generator Figure 6.16.: Symbols and data types, for an ERIKA target. Debug When compiling a project with ERIKA Enterprise, the folder contains the compilation results. The output folder also contains some other files, i.e script for project building and log files. 87

88 Chapter 6. The code generator Figure 6.17.: The block number is visible in the information window for the block, line 3. Figure 6.19.: Typical output directory after E4coder code generation (project type: EE PROJECT) 88

89 Chapter 6. The code generator Figure 6.18.: Final E4coder message and the compilation window Additional options The following sections shortly describe some useful additional options which can be used to customize the E4Coder code generator How to change the variable names This section shows how to customize the names of the variables in the generated code. Customizations are provided from the E4Coder code generator and are available in the last panel named E4Coder-Symbols (see Section 6.3.6). Although the example shown below is related to the Sine block of the E4coder-SOURCES palette, all the features described in this section are available for all the blocks supported by the E4Coder code generator. The block diagram used for this example is shown in Figure Figure 6.20.: Identification names for links and blocks The Code Generator allows the specification of a reference pattern that can be applied to all the variable names that the needs to be created, with the purpose of creating a unique name. In particular, the field Name of variables of Figure 6.16 shows you the reference pattern for the creation of the variable names in the generated code. 89

90 Chapter 6. The code generator Please note that the special symbols %BLOCK TYPE% and %BLOCK ID% are not mandatory but they can significantly improve the code readability. The following paragraphs show the code generator outputs with various pattern configurations, with and without the use of the identification strings of the links. %BLOCK TYPE% %BLOCK ID% %BLOCK NUMBER% outport %OUTPORT NUMBER% In this case the code generator output is: rt sinus sine generator 9 21 outport 0 = rt sinus(&rt sinus 9 21 tick, 0.1, 2, 1, 0, 0); The code is readable but the variable name is very long. %BLOCK ID% %BLOCK NUMBER% outport %OUTPORT NUMBER% In this case the code generator output is: sine generator 9 21 outport 0 = rt sinus(&rt sinus 9 21 tick, 0.1, 2, 1, 0, 0); The code is readable but again not so lean. %BLOCK NUMBER% outport %OUTPORT NUMBER% In this case the code generator output is: 9 21 outport 0 = rt sinus(&rt sinus 9 21 tick, 0.1, 2, 1, 0, 0); The output value of the Sine block is put in the variable named 9 6 output 0. This choice makes the code difficult to read, because it is impossible for the user to trace back the type of the block starting from the name of the variable. If the use of the link identification strings is enabled (see Figure 6.21) any choice about the pattern will be overridden by the link names. Figure 6.21.: Use of link identification names enabled The output in this case will be the following: sine signal = rt sinus(&rt sinus 9 21 tick, 0.1, 2, 1, 0, 0); This is of course the most readable solution, but the user is free to choose the preferred output format according to his needs. Our suggestion is that the link identification should be given at least to the main signals that will be used afterward during the debug of the code. 90

91 Chapter 6. The code generator How to change the data types The default choice of E4Coder for type names is shown in Figure6.22. Figure 6.22.: User types definition With this choice E4coder will create an header file named types.h with the type definitions shown in Algorithm 6.1. Algorithm 6.1 Extract from types.h # include < stdint.h> /* ************************* */ /* Type definitions */ /* ************************* */ typedef int32_t int32 ; typedef uint16_t uint16 ; typedef float real ; typedef uint64_t uint64 ; typedef int64_t int64 ; typedef int8_ t int8 ; typedef int16_t int16 ; typedef uint32_t uint32 ; typedef uint8_t uint8 ; /* ************************ */ /* SM3 type definitions */ /* ************************ */ typedef int8 INT8 ; typedef int16 INT16 ; typedef int32 INT32 ; typedef uint8 UINT8 ; typedef uint16 UINT16 ; typedef uint32 UINT32 ; typedef real REAL ; To use standard types, as defined in the header <stdint.h> you can change settings as shown in the figure

92 Chapter 6. The code generator Figure 6.23.: Use of standard types. With this choice E4Coder will create an header file named types.h where only the type definitions which differs from the standard ones will be generated. WARNING: Please note, the header file <stdint.h> is always included in the project and typically several compilers provide this header. If your compiler does not provide this file you have to create it and specify the path of the directory in the E4coder C-compiler configurator. How to add include path in the configurator is described in Section Read and Write blocks E4Coder Read and Write blocks (see Figures 4.19 and 4.20) are used to map data exchanges in and out a superblock (the typical scenario is when you have to exchange data between two superblocks running at different frequencies or even on a distributed network). The idea is that the system maintains a set of global values which are read and written, in a secure way, by the various concurrent tasks in the system. Each instance of a Read (Write) block then implements the read (write) of a global value available in the system. The global value will be implemented in different ways depending on the signals which are connected together by means of these blocks (see Section 6). Please note that the Read and Write blocks can be added implicitly by the code generator each time a block not belonging to the E4coder I/O or Custom palettes (see Sections and 4.2.9) is directly connected to an I/O port of the superblock (see Section 6). See the Figure 6.24 to better understand how Read/Write blocks are managed. 92

93 Chapter 6. The code generator Figure 6.24.: How to manage superblock ports and Read/Write blocks. In the figure 6.24 the input port 1 of the superblock is connected to a digital input block and no Read block will be automatically inserted by the code generator. For input port 2 a Read block will be automatically added because the port is directly connected to a Sum block. Multiple uses of the input ports of a superblock are not allowed as shown in the figure. The output port 1 of the superblock is directly connected to a digital output block so no Write blocks is needed. The output port 2 is redundant because is the same as the port 1. This use is tolerated by E4coder but we suggest to avoid redundant output ports inside a superblock. The output port 3 needs an E4coder Write block that will be automatically inserted by the code generator. The output code is shown in Algorithm

94 Chapter 6. The code generator Algorithm 6.2 Extract from data.c as generated by the diagram in Figure / CG READ: <auto RW 9>/c g r e a d 9 4 / CG read (AUTO READ, 0, &c g r e a d 9 4 o u t 0 ) ; / CG DIGITAL INPUT : <auto RW 9>/c g d i g i n 9 7 / CG gpio read (CG DIGITAL INPUT, &c g d i g i n 9 7 o u t 0 ) ; / SUMMATION: <auto RW 9>/sum 9 6 / sum 9 6 out 0 = c g d i g i n 9 7 o u t 0 + c g d i g i n 9 7 o u t 0 + c g r e a d 9 4 o u t 0 ; / CG DIGITAL OUTPUT: <auto RW 9>/c g d i g o u t / CG gpio write (CG DIGITAL OUTPUT, sum 9 6 out 0 ) ; / CG WRITE: <auto RW 9>/c g w r i t e / CG write (AUTO WRITE, 0, sum 9 6 out 0 ) ; In the generated code you can identify the function call related to E4Coder Read and Write blocks. Please note that E4Coder used the names of I/O ports of the superblock (AUTO READ and AUTO WRITE in upper case). This improve the traceability of the generated code. You can manually add Read and Write blocks to force their code generation in a superblock. This is typically useful when working with E4Coder Custom blocks. In fact it would be incorrect to insert an E4coder Read block connected to a simulation input port of an E4coder input block because these blocks represent HW peripherals of the target and the simulated input is not really part of the code generation process. E4coder Read and Write blocks can be used with an E4coder custom block instead, because if the custom block is directly connected to an I/O port of the superblock, the automatic insertion of Read / Write blocks is not executed and the block is assumed to be an I/O block (see Figure 6.25). 94

95 Chapter 6. The code generator Algorithm 6.3 Extract from data.c generated from the diagram in Figure /* CG_READ : < user_rw_custom_12 >/ cg_read_12_5 */ CG_read ( USERCSTM_READ_BLOCK, 0, cg_read_12_5_out_0 ); /* CG_CUSTOM_BLOCK : < user_rw_custom_12 >/ cg_custom_12_8 */ custom_for_algorithm_outputupdate (& cg_custom_12_8_params, cg_read_12_5_out_0, cg_custom_12_8_out_0 ); /* CG_WRITE : < user_rw_custom_12 >/ cg_write_12_3 */ CG_write ( USERCSTM_WRITE_BLOCK, 0, cg_custom_12_8_out_0 ); /* CG_CUSTOM_BLOCK : < user_rw_custom_12 >/ cg_custom_12_11 */ custom_for_io_outputupdate (& cg_custom_12_11_params ); Figure 6.25.: Custom block uses: I/O and algorithm The output code for this case is in Algorithm 6.3. For the custom for ALGORITHM block, if the application needs to read and write on global buffers you need to force Read / Write function generation by explicitly inserting these blocks in the diagram. If the application does not need external buffers only the custom block can be put in the diagram as shown for the custom for IO block. WARNING: A diagram where Read / Write blocks are inserted by hand and a diagram where Read / Write blocks are inserted automatically by E4coder are not equivalent and they could produce different output code. This aspect should be taken into account by the user and is related to optimizations on the execution order of the blocks applied by the Scicos compiler. When the user does not insert by hand Read / Write blocks, the wires will be connected outside the superblock, and the block total ordering will reflect those connections, including possible Scicos compiler optimizations. Scicos in fact uses internal rules for 95

96 Chapter 6. The code generator blocks activation inheritance: as an example, if constant blocks are used in some superblock Scicos could not insert these blocks in the execution order but also some other blocks, considered as never activated, may not be inserted in the execution order. These optimizations cannot be disabled and you should take care about this aspect when you design the superblocks enabled for code generation. The safer and simpler way to limit this kind of optimizations on the connections exchanged between superblocks is to manually insert Read / Write blocks inside superblocks to have a complete control of the interface ports of the superblock with the external world. If you are only generating the functional code, by enabling the option LIBRARY for your project, then it is up to the user to write the Read/Write function implementation. Viceversa, for projects of type EE PROJECT, the Read/Write functions are generated by E4Coder. To read or write properly on a global variable, the code has to accede the critical section using appropriate synchronization mechanisms, such as semaphores or using interrupts disabling, see the examples of the FLEX boards for further information about this topic. 96

97 7. Target run-time support This Section gives additional information about the various targets supported by the E4Coder Code Generator OSEK/VDX ERIKA Enterprise RTOS target E4Coder is able to generate code for OSEK/VDX kernels, including a basic OIL language file that can be used to configure the RTOS to run the generated code. In particular, E4Coder supports the OSEK/VDX kernel ERIKA Enterprise[8]. The setting of the Project Type in the E4Coder Code Generator must be EE PROJECT (see Section 6.3.1). The basic idea of the integration of the generated code with the OSEK/VDX Kernel ERIKA Enterprise is the following: The generator generates an OIL file named conf.oil following the task set specified in Section For each task, an OSEK alarm is generated. Starting from the entered task periods and offset values, E4coder computes the greatest common divisor. If the values entered are greater than the minimum acceptable value for the selected target, then E4Coder will find the proper scaling factor for the alarms to be defined. Algorithm 7.1 shows a snippet of the OIL parts related to tasks and alarms, with the result of the alarms auto-set results. The time unit is the period of the faster task/superblock (0.01 sec) because the period of the slower task is a multiple of this value. Offset values equal to zero are not accepted by Erika so they are changed in one Counter tick (0.01 sec in this case). Each superblock object of the code generation generates a C function. The initialization of the superblock is called inside the main() function before the call to StartOS(). The step function is called inside a Task body The body of a task is generated inside the task.c file. Each task body is generated as a sequence of function calls which are the step functions of the superblocks allocated to that specific task. The target.c file is generated with an implementation of the various peripheral functions, including oscillator settings when needed. The main.c file is generated, with an almost empty main() function which main purpose is to call StartOS(). A startup task named maintask is also created, which is responsible of initializing the superblock code, as well as setting the alarm ans starting the timer linked to the counter. 97

98 Chapter 7. Target run-time support The compile.bat / compile.sh files are also generated. These files are responsible for calling the OIL compiler (in the case of ERIKA Enterprise, RT-Druid is called) for generating the RTOS configuration file, and for calling the makefile to compile the application. 98

99 Chapter 7. Target run-time support Algorithm 7.1 Extract from conf.oil / APPLICATION TASKs / / OIL s e c t i o n f o r Task1 / TASK Task1 { PRIORITY = 2 ; STACK = SHARED; SCHEDULE = FULL; } ; ALARM Task1 alarm { COUNTER = maincounter ; ACTION = ACTIVATETASK { TASK = Task1 ; } ; AUTOSTART = TRUE { / Task1 o f f s e t and period ( o r i g i n a l v a l u e s in seconds ) : 0, 0.01 / ALARMTIME = 1 ; / Task1 o f f s e t and period ( v a l u e s in seconds a f t e r code generator auto s e t ) : 0.01, 0.01 / CYCLETIME = 1 ; } ; } ; / OIL s e c t i o n f o r Task2 / TASK Task2 { PRIORITY = 3 ; STACK = SHARED; SCHEDULE = FULL; } ; ALARM Task2 alarm { COUNTER = maincounter ; ACTION = ACTIVATETASK { TASK = Task2 ; } ; AUTOSTART = TRUE { / Task2 o f f s e t and period ( o r i g i n a l v a l u e s in seconds ) : 0, 0.1 / ALARMTIME = 1 ; / Task2 o f f s e t and period ( v a l u e s in seconds a f t e r code generator auto s e t ) : 0.01, 0.1 / CYCLETIME = 1 0 ; } ; } ; 99

100 Chapter 7. Target run-time support Compiler Options In the case of ERIKA Enterprise, the Compiler Options settings referenced in Section allows the specification of a set of options used in the default OIL file. In particular, it allows the specification of the following parameters 1 : Compiler options This textbox allows the specification of additional customized compiler options that will be inserted in the CFLAGS OIL attribute of the ERIKA Enterprise operating system. Linker options This textbox allows the specification of additional customized compiler options that will be inserted in the LDFLAGS OIL attribute of the ERIKA Enterprise operating system. Run compilation after code generation This checkbox allows to run the compilation process after the code generation. If not ticked, the E4Coder will only generate the code without compiling the resulting application and without running the post build scripts described in Section Figure 7.1.: OIL and Compiler options for the OSEK/VDX operating system ERIKA Enterprise Supported target boards The following sections provide information about the boards currently supported by E4Coder. for each board, a reference website is given, together with a list of the currently supported peripherals. When reading the board description, please note that the lists below only include the peripherals currently supported by the code generator. The board itself may host more (not yet supported) peripherals: if you need to add support for a new peripheral please contact us. 1 Please note that E4Coder Build 40 allowed the specification of two additional parameters, named Include search paths and User sources. These two parameters have been removed and included in the custom block parameters, see Section

101 Chapter 7. Target run-time support Peripheral Symbol Description ADC ADC AN0... ADC AN3 PIN25...PIN22 ADC AN22... ADC AN23 PIN91...PIN92 LED USER SYS LED User led on the FLEX board. PWM PWM 1, PWM 2 Table 7.1.: Peripherals supported by the FLEX board target. Peripheral Symbol Description ADC ADC AN1... ADC AN4 The four ADC input available on the EasyLab board. BUZZER USER SYS BUZZER The EasyLab buzzer. DIO DIO 1... DIO 8 The eight digital inputs/outputs available on the EasyLab board. LED USER SYS LED User led on the Microchip Microstick board. LED 1... LED 8 The 8 LEDs available on the EasyLab board. PWM PWM 1 2 The first PWM channel available on the EasyLab board. PWM 3 4 The second PWM channel available on the EasyLab board. SERIAL TX/RX UART 0 EasyLab TX/RX serial protocol. Table 7.2.: Peripherals supported by the EasyLab board target Evidence FLEX boards Target name: FLEX Reference web site: Supported peripherals: See Table Evidence EasyLab / Microchip Microstick with dspic or PIC24 microcontroller Target names: EASYLAB DSPIC, EASY PIC24 Reference web site: Supported peripherals: See Table

102 Chapter 7. Target run-time support Peripheral Symbol Description ADC ADC CH1... ADC CH3 ADC input 12-bit channels available on the board. ADC CH1: AN19, pin 9 on CON8 ADC CH2: AN20, pin 18 on CON8 ADC CH3: AN21, pin 20 on CON8 ADC AX: AN16, acceleration on X ADC AY: AN17, acceleration on Y ADC AZ: AN18, acceleration on Z ADC TEMP: AN12, thermistor output ADC LIGHT: AN13, light sensor output Note that the values returned are the raw ADC values. DAC DAC 1, DAC 2 DAC output 12-bit [0,4095] channels. DAC 1: pin1 on MORS1 DAC 2: pin3 on MORS1 BUTTON BUTTON 1... BUTTON 4 The Four buttons available on the FLEX Demo board. BUZZER USER SYS BUZZER The Flex Demo board buzzer. LCD USER SYS LCD The 16x2 LCD available on the FLEXDemo board. LED USER SYS LED LED 1... LED 8 User led on the FLEX base board board. The 8 LEDs available on the FLEX Demo board. Table 7.3.: Peripherals supported by the FLEX Demo board target Evidence FLEX Demo board Target name: FLEX DMB Reference web site: Supported peripherals: See Table Evidence FLEX Demo2 pack without plugins Target name: FLEX MTB Reference web site: Supported peripherals: See Table

103 Chapter 7. Target run-time support Peripheral Symbol Description ADC ADC GP1... ADC GP3 The three ADC input which are connected to the plugin board when present (PIN22, PIN41, PIN42). BUTTON BUTTON 1... BUTTON 2 The two buttons available on the FLEX Demo2 board. LED USER SYS LED LED 1, LED 2 User led on the FLEX base board board. The 2 LEDs available on the FLEX Demo2 board. PWM PWM 1, PWM 2 Two PWM outputs which are connected to the plugin board when present. Table 7.4.: Peripherals supported by the FLEX Demo2 board target Evidence FLEX Demo2 Pack with DC Motor Plugin Target name: FLEX MTB DCMOTOR Reference web site: Supported peripherals: See Table Amazing Ball - Evidence FLEX Demo2 Pack with Servo Motor plugin Target name: FLEX MTB SERVOMOTOR Reference web site: Supported peripherals: See Table Arduino Uno Target name: Arduino Uno Reference web site: Supported peripherals: See Table 7.7. Special note: although the code is generated for ERIKA Enterprise, the system uses as a basis the Arduino drivers. For that reason, the board support defined a never-ending task with priority 1. That task is used to continuously run the background activities specified by the Arduino software, and must be always the lowest priority task in the generated code. The minimum period tick is set to 1ms. 103

104 Chapter 7. Target run-time support Peripheral Symbol Description ADC ADC CUR This ADC can be used to sense the cumulative current on the two DC Motors (PIN19). ADC VOUT This ADC senses the Vout generated by the controller that is used to power the DC Motors (PIN34) ADC FAULT This ADC senses the Fault case of the DC Motor, which happens when the current consumption for both motors is too high (PIN18). BUTTON BUTTON 1, BUTTON 2 The two buttons available on the FLEX Demo2 board. ENCODER ENCODER 1, ENCODER 2 Two Encoders, ideally to be used to sense the DC Motors positions. Please note that ENCODER 1 is mapped to the dspic Quadrature encoder pin, whereas ENCODER 2 is implemented using GPIO and interrupts. LED USER SYS LED User led on the FLEX base board LED 1, LED 2 board. The 2 LEDs available on the FLEX Demo2 board. PWM PWM 1, PWM 2 Two PWM outputs used to control the 2 DC Motors. Table 7.5.: Peripherals supported by the FLEX Demo2 board target. 104

105 Chapter 7. Target run-time support Peripheral Symbol Description ADC ADC TOUCH BOTTOM This ADC can be used to sense the bottom part of a resistive Touchscreen. ADC TOUCH RIGHT This ADC can be used to sense the right part of a resistive touchscreen. BUTTON BUTTON 1, BUTTON 2 The two buttons available on the FLEX Demo2 board. LED USER SYS LED User led on the FLEX base board board. LED 1, LED 2 The 2 LEDs available on the FLEX Demo2 board. PWM PWM 1, PWM 2 Two PWM outputs used to control the 2 Servo Motors. TOUCH TOUCH 1 The resistive touchscreen of the Amazing Ball. Table 7.6.: Peripherals supported by the FLEX Demo2 board target. Please note that you do not need to install the Arduino software on your host machine in order to compile the target code generated by E4Coder. in fact, E4Coder includes a copy of the AVR compiler, as well as the command-line programmer for the Arduino boards. After a successful compilation of the code for Arduino, a specific dialog box will appear to automatically handle the serial programming of the board (see Figure 7.2). Please note that the standard Arduino serial drivers provide a 16 byte circular array. Writing more than this number of bytes on the ERIKA target is currently not supported. Please note that the Easylab Serial blocks write at max 10 bytes every millisecond, which can be handled at a speed of baud/s Arduino Nano Target name: Arduino Nano Reference web site: Supported peripherals: See Table 7.8. Same notes specified in Section apply to this board STM32F4 Discovery Target name: STM32F4 DISCOVERY 105

106 Chapter 7. Target run-time support Peripheral Symbol Description ADC USER ADC ADC channels. USER ADC 5 BUTTON USER BUTTON 2... USER BUTTON 9 8 buttons remapped to the digital I/O pins. DIO USER DIO IN 2... USER DIO IN 9 8 Digital Input and output pins on pins ENCODER USER ENCODER 0 A quadrature encoder mapped on pins 2 and 3. LED USER LED SYS, USER LED 2... A system led plus 8 additional leds remapped on the digital I/O pins. USER LED 9 PWM USER PWM 0 [A,B]... USER PWM 2 [A,B] Three PWM mapped on pins [6,5], [9,10], [11,3]. Each pair shares the same hardware timer; The software however currently has a fixed reference frequency. SERIAL TX/RX USER UART 0 EasyLab TX/RX serial protocol. Table 7.7.: Peripherals supported by the Arduino Uno board target. Figure 7.2.: Arduino Flash programming Dialog Box. You need to specify the serial port where the Arduino board is connected, and afterwards press the Flash button to program the board. 106

107 Chapter 7. Target run-time support Peripheral Symbol Description ADC USER ADC ADC channels. USER ADC 7 BUTTON USER BUTTON 2... USER BUTTON 9 8 buttons remapped to the digital I/O pins. DIO USER DIO IN 2... USER DIO IN 9 8 Digital Input and output pins on pins ENCODER USER ENCODER 0 A quadrature encoder mapped on pins 2 and 3. LED USER LED SYS, USER LED 2... A system led plus 8 additional leds remapped on the digital I/O pins. USER LED 9 PWM USER PWM 0 [A,B]... USER PWM 2 [A,B] Three PWM mapped on pins [6,5], [9,10], [11,3]. Each pair shares the same hardware timer; The software however currently has a fixed reference frequency. SERIAL TX/RX USER UART 0 EasyLab TX/RX serial protocol. Table 7.8.: Peripherals supported by the Arduino Nano board target. Reference web site: PF Core Frequency: 168 MHz. Supported peripherals: See Table 7.9. The minimum period tick is set to 1ms. Please note that you do not need to install the software on your host machine in order to compile the target code generated by E4Coder. in fact, E4Coder includes a copy of the GNU GCC ARM compiler. For Windows distributions of E4Coder, in order to program the STM32F4 Discovery board, the ST-LINK/V2 in-circuit debugger/programmer for STM8 and STM32 USB Driver and Utility SHOULD be downloaded from reference web site: sc=internet/evalboard/product/ jsp After a successful compilation of the code for STM32F4 Discovery, a specific dialog box will appear to automatically handle the serial programming of the board (see Figure 7.3). For Linux distributions of E4Coder, the command-line programmer (ST-LINK/V2) for the STM32F4 Discovery boards is included in E4Coder. After a successful com- 107

108 Chapter 7. Target run-time support Figure 7.3.: STM32F4 Discovery programming Dialog Box. You need to specify the path of the ST-LINK/V2 executable, and afterwards press the Flash button to program the board. pilation of the code for STM32F4 Discovery, a specific dialog box will appear to automatically handle the serial programming of the board (see Figure 7.3) Microsoft Windows target E4Coder is able to generate C code as well as the runtime support needed to generate a Microsoft Windows executable on a standard PC (x86) machine. The typical usage for this target is the generation of a standalone executable including a model of the controller, a model of the plant, and one or more E4CoderGUI item. In other words, this allows the generation of an all-in-one application which can be used to fast prototype a complete solution in a separate application which can be sent to a customer for review. Please note that the current version of the code generation for Windows is limited to diagrams containing an E4CoderGUI block. Diagrams without an E4CoderGUI block will not compile correctly 2. The structure of the code generated in the case of the presence of a E4CoderGUI block is as follows: Each periodic task is mapped to a Qt thread. 2 This limitation will be removed in the next release of E4Coder. 108

109 Chapter 7. Target run-time support Peripheral Symbol Description ADC USER ADCx Pyz ADC channels. Each channel selects Pin z [0..15] of the Input Port y [A..E] connected to the ADC Device x [1..3] BUTTON USER BUTTON 1 button remapped to the PA0 GPIO Port Pin. DIO USER DIO IN Pxy USER DIO OUT Pxy Digital Input and Output channels. Each channel selects Pin z [0..15] of the Input and Output Port y [A..E] ENCODER USER ENCx Pyz Pjk Quadrature Encoder channels. Each channel select a Timer Device x [1..5,8,9,12] mapped on Pin z [0..15] of the Input Port y [A..E] and Pin j [0..15] of the Input Port k [A..E]. Note: Encoder has the same resolution (16bit) of the Timer Device hardware counter. LED USER LED x 4 System Leds. Each led x [4,3,5,6] is remapped on Pin y [12,13,14,15] (respectively) of Output Port D. PWM USER PWMx Pyz PWM Channels. Each channel select a Timer Device x [1..5,8..14] Pin z [0..15] of the Output Port y [A..E]. Some pin may shares the same hardware timer; The software however currently has a fixed reference period of 780μs. SERIAL MSG RX/TX USER UARTx Pyz Serial (Raw) Message RX/TX channels. Each channel select an UART Device x [1..6] mapped on Pin z [0..15] of the Input/Output Port y [A..E]. Table 7.9.: Peripherals supported by the STM32F4 Discovery board target. 109

110 Chapter 7. Target run-time support Symbolic Qt name Number Description IdlePriority 0 Scheduled only when no other threads are running. LowestPriority 1 Scheduled less often than LowPriority. LowPriority 2 Scheduled less often than NormalPriority. NormalPriority 3 The default priority of the operating system. HighPriority 4 Scheduled more often than NormalPriority. HighestPriority 5 Scheduled more often than HighPriority. TimeCriticalPriority 6 Scheduled as often as possible. Table 7.10.: Qt Priorities. Values refers to the QThread::Priority enum. The task priority specified at code generation time is mapped to a Qt thread priority (see Table 7.10). Priorities with values less than IdlePriority will be mapped to IdlePriority. Priorities with values higher than TimeCriticalPriority will be mapped to TimeCriticalPriority. Please note that the Qt priorities are unrelated to the Windows priorities. As a result, the resulting application may not have a real-time behavior similar to the one obtained when generating code for a real-time operating system. The E4CoderGUI block is also generated as a separate Qt window. All the system runs as a normal multithread Qt application Prerequisites needed to automatically compile a Windows application generated by E4Coder Once generated, the E4Coder code generator is able to automatically compile the code generated in order to create a Microsoft Windows application. In order to be able to do this, you need to have the following packages installed: MinGW C and C++ compiler. Please note that not all the versions of MinGW will work with the Qt Libraries listed below. In particular, this combination has been reported to work: You need to install MinGW from the MinGW website: org/ We suggest using the MinGW automated installer listed at the page: sourceforge.net/projects/mingw/files/installer/mingw-get-inst/ as described in the wiki page 110

111 Chapter 7. Target run-time support You need to select the following target directory: C:\MinGW The packages needed for the install are only the C and C++ compiler. Please do the following crosscheck: the installed compiler should be GCC If the version is 4.7 or greater, then the compilation may fail. An easy way to check the version is to go in the following directory: C:\MinGW\var\cache\mingw-get\packages and check whether the names of the gcc packages downloaded by the automatic installer start with gcc Qt Libraries You need the package currently available at the address ftp://ftp.qt-project.org/qt/source/qt-win-opensource mingw.exe Please note that the Qt installer will emit a warning that only MinGW w32api.h version 3.13 is supported. The version installed with MinGW is likely to be 3.17 (newer). You can safely ignore the warning and continue Compiler Options In the case of Microsoft Windows, the Compiler Options settings referenced in Section allows the specification of a set of options passed to the compiler scripts, plus the location of the QMake application (see 7.2.1). In particular, it allows the specification of the following parameters: Compiler options This textbox allows the specification of additional customized compiler options. Linker options This textbox allows the specification of additional customized linker options. QMake location This textbox should contain the location of the qmake executable. If the specified path is not correct, an error message will be displayed asking to provide the correct path. Run compilation after code generation This checkbox allows to run the compilation process after the code generation. If not ticked, the E4Coder will only generate the code without compiling the resulting application and without running the post build scripts described in Section Target blocks The Windows target supports in particular the RFILE f (see Section ) and WFILE f (see Section ) blocks which can be used to read and write output files when running the generated code. The read/write operation are executed in the exact point where the read/write block function is called. 111

112 Chapter 7. Target run-time support Figure 7.4.: Microsoft Windows Compiler options Supported target boards Currently the windows target only supports a single target board, which is a standard PC equipped with Microsoft Windows Desktop - Standard PC with Qt Libraries Target name: Desktop Reference web site: none. Supported peripherals: none. In other words, when generating Windows code you cannot use any peripheral block. This is rather normal since default PCs does not have peripherals such as those present in many microcontrollers Linux pthread target E4Coder is able to generate code for Linux machines using the pthread library. The structure of the code generated is as follows: Each Task defined in the Task Selection panel (see Section 6.3.3) is mapped to a POSIX thread. The Priority specified for each task is mapped to the thread real-time priority. The thread is created with a detach state joinable, inherit schedulability explicit, and with the scheduling policy SCHED FIFO. The Periodicity specified for each thread is implemented using the clock nanosleep POSIX primitive. The Offset specified for each thread is implemented as an initial sleep value 3 which is computed from a common Start time. The common Start time is specified as the instant after which all threads have been created and are ready to start. A POSIX barrier is used to enforce that all thread have been correctly created before setting the Start time. 3 Again implemented using the clock nanosleep POSIX primitive. 112

113 Chapter 7. Target run-time support If the design includes an E4CoderGUI block, all the correspondent Qt library code is also generated. The Qt GUI run loop is located into the main() function, thus executing all the graphical interface in background with respect to the real-time threads. If the application does not include Qt graphics (e.g. an E4Coder GUI block), then the application exits when a signal SIGTERM or SIGINT is received. If the application includes Qt graphics, the application will close also when the Qt Window will be closed. The generated application has a set of additional commandline parameters described below: --silent This option suppress all prints made on the console by the application. --verbose This option adds additional per-thread prints to the console Compiler Options In the case of Linux, the Compiler Options settings referenced in Section allows the specification of a set of options passed to the compiler scripts, plus the location of the QMake application. In particular, it allows the specification of the following parameters: Compiler options This textbox allows the specification of additional customized compiler options. Linker options This textbox allows the specification of additional customized linker options. QMake location This textbox should contain the location of the qmake executable. If the specified path is not correct, an error message will be displayed asking to provide the correct path. Run compilation after code generation This checkbox allows to run the compilation process after the code generation. If not ticked, the E4Coder will only generate the code without compiling the resulting application and without running the post build scripts described in Section Target blocks The Linux pthread target supports in particular the RFILE f (see Section ) and WFILE f (see Section ) blocks which can be used to read and write output files when running the generated code. The read/write operation are executed in the exact point where the read/write block function is called. 113

114 Chapter 7. Target run-time support Supported target boards Desktop - Standard x86 PC with Qt Libraries Target name: Desktop Reference web site: none. Supported peripherals: none. This target is useful in case there is a need to generate a standalone graphical application based on the Qt libraries, without interfacing with external I/O E4Box 1.0 E4Box is a ready to use all-in-one embedded computing box which includes all hardware and software needed to perform automatic generation of code, rapid prototyping of control algorithms, allowing you to simulate and run complex control schemes. Target name: e4box 1.0 Reference web site: Supported peripherals: ADC (see Table 7.11), DAC (see Table 7.12), DIGITAL INPUT (see Table 7.13), DIGITAL OUTPUT (see Table 7.13), ENCODER (see Table 7.14), accessible through the Comedi Libraries E4Box 1.1 Version 1.1 of E4Box interfaces with a slightly different version of NI-6221 with 37 pin instead of 68 pin. Target name: e4box 1.1 Reference web site: Supported peripherals: ADC (see Table 7.15), DAC (see Table 7.16), DIGITAL INPUT (see Table 7.17), DIGITAL OUTPUT (see Table 7.17), ENCODER (see Table 7.18), accessible through the Comedi Libraries. 114

115 Chapter 7. Target run-time support Mapping Name Connector pins Comedi class type Comedi subdev Comedi channel ADC0 68 COMEDI SUBD AI 0 0 ADC1 33 COMEDI SUBD AI 0 1 ADC2 65 COMEDI SUBD AI 0 2 ADC3 30 COMEDI SUBD AI 0 3 ADC4 28 COMEDI SUBD AI 0 4 ADC5 60 COMEDI SUBD AI 0 5 ADC6 25 COMEDI SUBD AI 0 6 ADC7 57 COMEDI SUBD AI 0 7 ADC8 34 COMEDI SUBD AI 0 8 ADC9 66 COMEDI SUBD AI 0 9 ADC10 31 COMEDI SUBD AI 0 10 ADC11 63 COMEDI SUBD AI 0 11 ADC12 61 COMEDI SUBD AI 0 12 ADC13 26 COMEDI SUBD AI 0 13 ADC14 58 COMEDI SUBD AI 0 14 ADC15 23 COMEDI SUBD AI 0 15 Table 7.11.: ADC peripherals supported by E4Box 1.0. Mapping Name Connector pins Comedi class type Comedi subdev Comedi channel DAC0 22 COMEDI SUBD AO 0 0 DAC1 21 COMEDI SUBD AO 0 1 Table 7.12.: DAC peripherals supported by E4Box

116 Chapter 7. Target run-time support Mapping Name Connector pins Comedi class type Comedi subdev Comedi channel DIO 0 52 COMEDI SUBD DIO 0 0 DIO 1 17 COMEDI SUBD DIO 0 1 DIO 2 49 COMEDI SUBD DIO 0 2 DIO 3 47 COMEDI SUBD DIO 0 3 DIO 4 19 COMEDI SUBD DIO 0 4 DIO 5 51 COMEDI SUBD DIO 0 5 DIO 6 16 COMEDI SUBD DIO 0 6 DIO 7 48 COMEDI SUBD DIO 0 7 DIO 8 11 COMEDI SUBD DIO 1 0 DIO 9 10 COMEDI SUBD DIO 1 1 DIO COMEDI SUBD DIO 1 2 DIO COMEDI SUBD DIO 1 3 DIO COMEDI SUBD DIO 1 4 DIO 13 6 COMEDI SUBD DIO 1 5 DIO 14 5 COMEDI SUBD DIO 1 6 DIO COMEDI SUBD DIO 1 7 DIO COMEDI SUBD DIO 2 0 DIO 17 3 COMEDI SUBD DIO 2 1 DIO COMEDI SUBD DIO 2 2 DIO COMEDI SUBD DIO 2 3 DIO 20 2 COMEDI SUBD DIO 2 4 DIO COMEDI SUBD DIO 2 5 DIO 22 1 COMEDI SUBD DIO 2 6 DIO COMEDI SUBD DIO 2 7 Table 7.13.: DIGITAL INPUT/OUTPUT peripherals supported by E4Box

117 Chapter 7. Target run-time support Mapping Names ENCODER 0 X1 INDEX 0 ENCODER 0 X1 INDEX 1 ENCODER 0 X4 INDEX 0 ENCODER 0 X4 INDEX 1 ENCODER 1 X1 INDEX 0 ENCODER 1 X1 INDEX 1 ENCODER 1 X4 INDEX 0 ENCODER 1 X4 INDEX 1 Connector pins, Comedi class type 37, 3, 45 COMEDI SUBD COUNTER 42, 41, 46 COMEDI SUBD COUNTER Comedi subdev / channel PFI (A,B,Z) 0, 0 8, 10, 9 0, 0 3, 11, 4 Mode X1 X4 X1 X4 Index Disabled Enabled Disabled Enabled Disabled Enabled Disabled Enabled Table 7.14.: ENCODER peripherals supported by E4Box 1.0 The initial value of these encoders is set to 0. Mapping Name Connector pins Comedi class type Comedi subdev Comedi channel ADC0 1 COMEDI SUBD AI 0 0 ADC1 21 COMEDI SUBD AI 0 1 ADC2 22 COMEDI SUBD AI 0 2 ADC3 5 COMEDI SUBD AI 0 3 ADC4 6 COMEDI SUBD AI 0 4 ADC5 26 COMEDI SUBD AI 0 5 ADC6 25 COMEDI SUBD AI 0 6 ADC7 28 COMEDI SUBD AI 0 7 ADC8 34 COMEDI SUBD AI 0 8 ADC9 2 COMEDI SUBD AI 0 9 ADC10 4 COMEDI SUBD AI 0 10 ADC11 23 COMEDI SUBD AI 0 11 ADC12 25 COMEDI SUBD AI 0 12 ADC13 7 COMEDI SUBD AI 0 13 ADC14 9 COMEDI SUBD AI 0 14 ADC15 10 COMEDI SUBD AI 0 15 Table 7.15.: ADC peripherals supported by E4Box

118 Chapter 7. Target run-time support Mapping Name Connector pins Comedi class type Comedi subdev Comedi channel DAC0 12 COMEDI SUBD AO 0 0 DAC1 30 COMEDI SUBD AO 0 1 Table 7.16.: DAC peripherals supported by E4Box 1.1. Mapping Name Connector pins Comedi class type Comedi subdev Comedi channel DIO 0 37 COMEDI SUBD DIO 0 0 DIO 1 19 COMEDI SUBD DIO 0 1 DIO 2 13 COMEDI SUBD DIO 0 2 DIO 3 32 COMEDI SUBD DIO 0 3 DIO 4 33 COMEDI SUBD DIO 0 4 DIO 5 15 COMEDI SUBD DIO 0 5 DIO 6 34 COMEDI SUBD DIO 0 6 DIO 7 35 COMEDI SUBD DIO 0 7 DIO 8 17 COMEDI SUBD DIO 1 0 DIO 9 36 COMEDI SUBD DIO 1 1 Table 7.17.: DIGITAL INPUT/OUTPUT peripherals supported by E4Box 1.1. Mapping Names ENCODER 0 X4 INDEX 0 ENCODER 0 X4 INDEX 1 ENCODER 1 X4 INDEX 0 ENCODER 1 X4 INDEX 1 Connector pins, Comedi class type 13, 33, 32 COMEDI SUBD COUNTER 15, 35, 34 COMEDI SUBD COUNTER Comedi subdev / channel PFI (A,B,Z) 0, 0 0, 2, 1 0, 0 3, 5, 4 Mode X1 X4 X1 X4 Index Disabled Enabled Disabled Enabled Disabled Enabled Disabled Enabled Table 7.18.: ENCODER peripherals supported by E4Box 1.1 The initial value of these encoders is set to

119 Chapter 7. Target run-time support 7.4. RTAI target E4Coder is able to generate code for Linux machines using RTAI patch[1]. The structure of the code generated is as follows: Each Task defined in the Task Selection panel (see Section 6.3.3) is mapped to a RTAI lxrt thread. The Priority specified for each task is mapped to the thread real-time priority. The thread is created with a detach state joinable, and its priority is passed to RTAI using rt task init schmod. The Periodicity specified for each thread is implemented using the support provided by RTAI and in particular using the primitives rt task make periodic and rt task wait period. The Offset specified for each thread is implemented using the support provided by RTAI and in particular using the primitive rt task make periodic. The common Start time is specified as the instant after which all threads have been created and are ready to start. A RTAI barrier is used to enforce that all thread have been correctly created before setting the Start time. If the design includes an E4CoderGUI block, all the correspondent Qt library code is also generated. The Qt GUI run loop is located into the main() function, thus executing all the graphical interface in background with respect to the real-time threads. Bridge threads (see Section 7.4.1) are used to guarantee the real-time performances of the periodic tasks. If the application does not include Qt graphics (e.g. an E4Coder GUI block), then the application exits when a signal SIGTERM or SIGINT is received. If the application includes Qt graphics, the application will close also when the Qt Window will be closed. Please note that the RTAI target can directly interface with the Comedi Libraries, thus all data acquisition cards supported by Comedi are also available and supportable by E4Coder. The generated application has a set of additional commandline parameters described below: --rt-cpu This parameter can be used to map the RTAI threads to a subset of the available CPUs. This option together with the --lx-cpu is very useful to limit the interference between the real-time and non-real-time part of the application by statically mapping specific class of threads to a subset of the available CPUs. --lx-cpu This parameter can be used to map the Linux threads (handling the main() and the Qt library) to a subset of the available CPUs. 119

120 Chapter 7. Target run-time support Figure 7.5.: Code generated for graphical applications on RTAI. --silent This option suppress all prints made on the console by the application. --verbose This option adds additional per-thread prints to the console Bridge threads The implementation on RTAI is basically similar to the one on Linux pthreads with the exception of the communication with the GUI panels generated through E4CoderGUI. The reason for the difference is that the communication between a real-time periodic task and the main Qt loop is done through Qt slots. However, the Qt code may call normal Linux primitives, leading to an automatic transition of the task from the RTAI real-time mode to the normal Linux mode. To avoid this risk, the code generator adds one additional bridge thread for each E4CoderGUI block (see Figure 7.5). The bridge thread is responsible for the communication between the real-time task and the Qt framework. The communication with the real-time task is provided by a circular buffer that is not blocking for write operations (i.e., data is overwritten in case of buffer full). Thus, the real-time performance of the periodic task is not affected, while the E4CoderGUI panels execute in background using the Qt libraries. When possible, the bridge thread is executed in the RTAI real-time user-space mode at the lowest priority. However, when calling Qt signals/slots it may enter normal 120

121 Chapter 7. Target run-time support Linux mode. In this case, it is executed at the maximum (i.e., SCHED FIFO) priority as implemented by the following code: void *GUI io gui th(void *args) { RT TASK *rt task; th param t *par = (th param t*)args; int in elem = 100; int elem, i; gui gui data in t in[in elem]; rt task = rt task init schmod(nam2num(par->name), par->prio, 16 * 1024, 0, SCHED FIFO, pthread sync param.rt cpu mask); rt make hard real time(); par->queue in = e4c rt queue init(par->qi name, in elem, sizeof(gui gui data in t)); e4c rt barrier wait(&pthread sync param.main barrier); while (!par->end) { e4c rt queue wait data(par->queue in); elem = e4c rt queue get all(par->queue in, in); e4c rt queue unlock(par->queue in); rt make soft real time(); for (i = 0; i < elem; ++i) GUI io gui(par->handle, in[i].input 0); rt make hard real time(); } rt make soft real time(); rt task delete(rt task); return NULL; } Compiler Options In the case of RTAI, the Compiler Options settings referenced in Section allows the specification of a set of options passed to the compiler scripts, plus the location of the QMake application. In particular, it allows the specification of the following parameters: Compiler options This textbox allows the specification of additional customized compiler options. Linker options This textbox allows the specification of additional customized linker options. QMake location This textbox should contain the location of the qmake executable. If the specified path is not correct, an error message will be displayed asking to provide the correct path. 121

122 Chapter 7. Target run-time support Run compilation after code generation This checkbox allows to run the compilation process after the code generation. If not ticked, the E4Coder will only generate the code without compiling the resulting application and without running the post build scripts described in Section Target blocks The Linux pthread target supports in particular the RFILE f (see Section ) and WFILE f (see Section ) blocks which can be used to read and write output files when running the generated code. The read/file operation are executed using bridge threads as done when interfacing with the Qt Libraries (see Section 7.4.1) Supported target boards E4Box 1.0 E4Box is a ready to use all-in-one embedded computing box which includes all hardware and software needed to perform automatic generation of code, rapid prototyping of control algorithms, allowing you to simulate and run complex control schemes. Target name: e4box 1.0 Reference web site: The peripheral supported in this case are the same as described for the Linux pthread target in Section E4Box 1.1 E4Box is a ready to use all-in-one embedded computing box which includes all hardware and software needed to perform automatic generation of code, rapid prototyping of control algorithms, allowing you to simulate and run complex control schemes. Target name: e4box 1.1 Reference web site: The peripheral supported in this case are the same as described for the Linux pthread target in Section Bare Metal target E4Coder is able to generate code for Bare Metal targets. A Bare Metal target is typically a microcontroller running without an RTOS. In this case, the code generator will create a basic scheduler which will be able to schedule tasks as non-preemptive function calls. The structure of the code generated is as follows: 122

123 Chapter 7. Target run-time support Each Task defined in the Task Selection panel (see Section 6.3.3) is mapped to an if clause in the main() loop. The Priority specified for each task is mapped to the order in which the if clause appears in the main() loop. The idea is that after each if clause there will be a continue statement to ensure that Tasks are handled in non-preemptive fashion and in priority order. The Periodicity specified for each thread is implemented using flags triggered by timer interrupts. The flags are checked inside the if statements. The Offset specified for each thread is implemented using an appropriate handling of the timers and the flags. The common Start time is specified as the instant when the timer interrupt starts, just before the main loop. E4CoderGUI blocks are not supported by this target Compiler Options In the case of Bare Metal, the Compiler Options settings referenced in Section allows the specification of just the compiler and linker options: Compiler options This textbox allows the specification of additional customized compiler options that will be inserted in the CFLAGS OIL attribute of the ERIKA Enterprise operating system. Linker options This textbox allows the specification of additional customized compiler options that will be inserted in the LDFLAGS OIL attribute of the ERIKA Enterprise operating system. Please note that there is not a Run compilation after code generation for Bare Metal targets. The fact that the generated code is always compiled or not after code generation is controlled by the pre attribute in the build section of each board configuration (see Section ) Supported Target Boards Arduino Uno Target name: Arduino Uno Reference web site: Supported peripherals: See Table

124 Chapter 7. Target run-time support Figure 7.6.: Compiler options for the Bare Metal target. Peripheral Symbol Description ADC USER ADC ADC channels on pins USER ADC 5 BUTTON USER BUTTON buttons remapped to the digital I/O pins. USER BUTTON 9 DIO USER DIO IN 2... USER DIO IN 9 8 Digital Input and output pins on pins ENCODER USER ENCODER 0 A quadrature encoder mapped on pins 2 and 3. LED USER LED SYS, USER LED 2... A system led plus 8 additional leds remapped on the digital I/O pins. USER LED 9 PWM USER PWM 0 [A,B]... USER PWM 2 [A,B] Three PWM mapped on pins [6,5], [9,10], [11,3]. Each pair shares the same hardware timer; The software however currently has a fixed reference frequency. SERIAL TX/RX USER UART 0 EasyLab TX/RX serial protocol. Table 7.19.: Peripherals supported by the Arduino Uno board target. Special note: the bare metal target for Arduino boards directly interfaces with Arduino drivers. The main loop generated in the Arduino template also supports the background activities which are defined by standard Arduino programs. The minimum period tick is set to 1ms. Please note that you do not need to install the Arduino software on your host machine in order to compile the target code generated by E4Coder. in fact, E4Coder includes a copy of the AVR compiler, as well as the command-line programmer for the Arduino boards. After a successful compilation of the code for Arduino, a specific dialog box will appear to automatically handle the serial programming of the board (see Figure 7.2). 124

125 Chapter 7. Target run-time support Peripheral Symbol Description ADC USER ADC ADC channels on pins USER ADC 7 BUTTON USER BUTTON buttons remapped to the digital I/O pins. USER BUTTON 9 DIO USER DIO IN 2... USER DIO IN 9 8 Digital Input and output pins on pins ENCODER USER ENCODER 0 A quadrature encoder mapped on pins 2 and 3. LED USER LED SYS, USER LED 2... A system led plus 8 additional leds remapped on the digital I/O pins. USER LED 9 PWM USER PWM 0 [A,B]... USER PWM 2 [A,B] Three PWM mapped on pins [6,5], [9,10], [11,3]. Each pair shares the same hardware timer; The software however currently has a fixed reference frequency. SERIAL TX/RX USER UART 0 EasyLab TX/RX serial protocol. Table 7.20.: Peripherals supported by the Arduino Nano board target Arduino Nano Target name: Arduino Nano Reference web site: Supported peripherals: See Table Same notes specified in Section apply to this board STM32F4 Discovery Target name: STM32F4 DISCOVERY Reference web site: PF Core Frequency: 168 MHz. Time and Signed Time Types MUST be set to uint32 and int32 because internal Cortex Sys-Tick (24bit Hardware Counter) is used to keep track of time. Supported peripherals: See Table The minimum period tick is set to 1ms. 125

126 Chapter 7. Target run-time support Please note that you do not need to install the software on your host machine in order to compile the target code generated by E4Coder. in fact, E4Coder includes a copy of the GNU GCC ARM compiler. For Windows distributions of E4Coder, in order to program the STM32F4 Discovery board, the ST-LINK/V2 in-circuit debugger/programmer for STM8 and STM32 USB Driver and Utility SHOULD be downloaded from reference web site: sc=internet/evalboard/product/ jsp After a successful compilation of the code for STM32F4 Discovery, a specific dialog box will appear to automatically handle the serial programming of the board (see Figure 7.3). For Linux distributions of E4Coder, the command-line programmer (ST-LINK/V2) for the STM32F4 Discovery boards is included in E4Coder. After a successful compilation of the code for STM32F4 Discovery, a specific dialog box will appear to automatically handle the serial programming of the board (see Figure 7.3) LIBRARY - Target without generation of the software architecture E4Coder is able to generate pure C code to be used without an RTOS (or with a generic RTOS not currently supported). In This case, the setting of the Project Type in the E4Coder Code Generator must be LIBRARY (see Section 6.3.1). The code which is generated in this case is made by a set of files that define the behavior of the generated superblocks. It is responsibility of the user to provide additional functionalities that are needed to link the code to the target peripherals. Moreover, it is responsibility of the user to periodically call the step functions generated for each superblock, using the same periodicity used in the diagram clocks Examples A generic example of infrastructure that does all the above can be found in the E4coder\ E4coder-cg\examples\FlexDemoBoard\MPLAB directory. The code is written to work with Microchip MPLAB X, and can be adapted easily to other microcontrollers. 126

127 Chapter 7. Target run-time support Peripheral Symbol Description ADC USER ADCx Pyz ADC channels. Each channel selects Pin z [0..15] of the Input Port y [A..E] connected to the ADC Device x [1..3] BUTTON USER BUTTON 1 button remapped to the PA0 GPIO Port Pin. DIO USER DIO IN Pxy USER DIO OUT Pxy Digital Input and Output channels. Each channel selects Pin z [0..15] of the Input and Output Port y [A..E] ENCODER USER ENCx Pyz Pjk Quadrature Encoder channels. Each channel select a Timer Device x [1..5,8,9,12] mapped on Pin z [0..15] of the Input Port y [A..E] and Pin j [0..15] of the Input Port k [A..E]. Note: Encoder has the same resolution (16bit) of the Timer Device hardware counter. LED USER LED x 4 System Leds. Each led x [4,3,5,6] is remapped on Pin y [12,13,14,15] (respectively) of Output Port D. PWM USER PWMx Pyz PWM Channels. Each channel select a Timer Device x [1..5,8..14] Pin z [0..15] of the Output Port y [A..E]. Some pin may shares the same hardware timer; The software however currently has a fixed reference period of 780μs. SERIAL MSG RX/TX USER UARTx Pyz Serial (Raw) Message RX/TX channels. Each channel select an UART Device x [1..6] mapped on Pin z [0..15] of the Input/Output Port y [A..E]. Table 7.21.: Peripherals supported by the STM32F4 Discovery board target. 127

128 8. Multirate designs The E4Coder Code Generator supports simulation and code generation for multirate designs, which are designs with more than one sample rate. A simple example of a multirate design is provided with E4coder. The directory of the example is the following: E4coder\E4coder-cg\examples\FlexDemoBoard\FLEX\Multirate custom The example is also available from the E4coder demos list (see Figure 6.25). Figure 8.1.: The multirate demo in the list. The diagram implements a motor control application (see Figure 6.25). The plant is a DC motor simulated with a mathematical linear model. The control algorithm is contained in the superblock named Controller. The algorithm accepts a reference signal calculated in the superblock Reference generator that is activated at a slow rate. 128

129 Chapter 8. Multirate designs Figure 8.2.: The Multirate demo, implementing a simple multirate DC motor controller. As shown in Figure 8.2, a multirate diagram compatible with the E4Coder Code Generator should respect the following guidelines: The algorithm should be divided in different parts, typically one for each rate. Every part should be contained in a dedicated superblock activated with the proper clock. Only synchronous clocks are supported for code generation. Code generation with support for a RTOS should be configured with a proper taskset, i.e a superblock which must be executed before other superblocks, when active, should be associated to a task with higher priority. When there are no precedence constraints, the simplest suggestion would be to assign priorities following a Rate Monotonic priority assignment 1. Figure 8.3 below shows the task-set. Two tasks will be used with different priorities. 1 The Rate Monotonic priority assignment gives a priority proportional to the frequency (where higher numbers means higher priority). 129

130 Chapter 8. Multirate designs Figure 8.3.: Multirate demo: the task-set Figure 8.4 shows the subsystems panel: the controller is associated to the faster task but with lower priority. Viceversa the reference generator is associated to the slower task but has higher priority than the controller. Figure 8.4.: Multirate demo: superblocks-task association. The user should configure the mapping for peripheral and Read / Write blocks. Please note that data exchange between superblocks is always managed by Read / Write blocks. In this diagram, however, we did not put any explicit Read / Write blocks, and E4coder automatically inserted the Read / Write blocks automatically to protect the superblocks borders. To better understand this aspect see Section Figure 8.5.: Multirate demo: I/O and Read / Write mapping. A Read block and a Write block has been generated automatically, and configured to refer to a common buffer. 130

131 Chapter 8. Multirate designs Finally, special care must be taken into account when using peripheral blocks in a concurrent way. In particular, not all the target implementations implement the device drivers to support concurrent execution of the same driver functionality on concurrent preempting threads. As a recommendation, we suggest to incorporate all the usages of a given type of peripheral in the same superblock 2. 2 In reality the requirement should be that the device driver functionalities should be called in a single thread. Which means the peripheral blocks can be spread to different superblocks which are mapped to the same thread during code generation. 131

132 9. Customizations Although the default build of E4Coder supports various general purpose embedded boards, the typical usage of the code generator will be to directly support custom hardware. For that reason, E4Coder allows the customization of various features to adapt the code generated to specific scenarios, boards, algorithms. This chapter describes the kind of customizations which are currently implementable with E4Coder The Customization directory To better distinguish the code which is shipped by default with E4Coder, and the code which is part of the customizations, E4Coder provides a specific directory named $HOME/E4Coder/E4coder-customizations which must contain all the customer specific files 1. Only that directory is guaranteed to remain the same upon update/uninstall of the E4Coder plugins. If the customizations directory does not exists, it is created at E4Coder loading time. Using the customizations directory, an expert user can add support for other target boards (see Section 9.3) and custom blocks (see Section 9.4). Each instance of a target board and of a custom block is stored in a separate directory under the customizations directory. After adding a new item (directory) under the customizations directory, please remember to unload and reload E4Coder, as shown in Section Where to find customizations examples All boards and custom blocks in E4Coder are described using the specification o this Chapter. For this reason, whenever you need to create a custom target board or a custom block support, we suggest to: First of all, find a target board/custom block similar in features to the one you need to implement. To do this, you can start trying the current supported boards/blocks, trying to generate code for them from one of the available examples (see Section 3). Once you identified a customization similar to the one you need to implement, you need to locate it in one of the default repositories provided with E4Coder. In particular, custom blocks distributed with E4Coder are stored in the directory 1 Please note that older versions provided the support for a customization directory which was relative to the E4Coder installation path. That has been removed in favor of the current one to better support Linux hosts and Windows Vista and later host operating systems. 132

133 Chapter 9. Customizations install dir /contrib/e4coder/e4coder-cg/codegen/custom-blocks whereas the target boards are stored under install dir /contrib/e4coder/e4coder-cg/codegen/target-board At that point, we suggest to copy and paste the entire directory containing the specification of a board/custom block. You must copy the directory under your local customization directory, because the default repositories provided with E4Coder will be removed when upgrading E4Coder to a newer version. You need to change the name of the board/custom block in order not to conflict with existing customizations. Please note that customizations names must be unique; in case two boards or two blocks have the same name, only the first one will be loaded and configured. Finally, please pay attention when giving a name to a custom block. A change of a custom block name means changing every diagram using it! 9.3. Supporting additional target boards Supporting new target boards under the E4Coder Code Generator is relatively simple and does not involve ScicosLab programming effort for the definition and configuration of the target peripherals present in the board. Basically, each new target board is stored in a separate directory under one of the customization folders. The directory contains a file named board.txt, which describes the various properties of the target board. Then, each board has a set of sub-directories, containing a target.txt file. The target.txt file contains the specification of the custom code generated for the custom board for one of the operating systems supported by the code generator (OSEK/VDX, Linux Pthread, RTAI,...). The following subsections contain a description of the various files involved in the configuration of the code generator Structure of the board.txt file Every directory containing a file named board.txt located under one of the customization directory is interpreted as an additional custom board. Each board.txt file will be read and interpreted at the beginning of the code generation wizard. The structure of the board.txt file is as follows: The board.txt file is a text file. Comment lines start with the # sign. Example: 133

134 Chapter 9. Customizations # This is a comment The file is divided in sections, with section names surrounded by brackets. The current list of supported sections are version, board and target. The parser supports section name appearing more than once. In this case, the section content will be union of all contents. Example: # This is a comment [version 1.0] [board] # content of the board section [target] # content of the target section [board] # continuing the board section The section content is given by a set of attributes and values in the form or attribute=value attribute= value The list of attributes supported in each section is detailed in the following paragraphs. When an attribute refers to a directory name, all paths are intended relative to the directory containing the board.txt file. In other words, the idea is that you may have one level of sub-directories each one containing specific content relative to the board version section of the board.txt file This section is only used to mark the version number of the board.txt file. The current version of E4Coder accepts version 1.0 only. Example: [version 1.0] board section of the board.txt file The board section contains the name of the board as well as additional custom palettes which can be used to better describe the blocks available in a specific board. The attributes supported by the board section are the following: name Contains the name of the target board. palette Contains the name of the directory containing additional palettes (see Section 9.3.2). This attribute is optional. Only a single palette directory can be specified. Example: 134

135 Chapter 9. Customizations [board] name= e4box 1.0 palette= palettedir target section of the board.txt file This section contains a set of attributes which are related to the target OS implementation. If a target boards supports a target implementation for a specific Operating System, then the corresponding attribute is specified linking to a subdirectory with the specific OS content. The attributes supported by the target section are the following: LINUX PROJECT This is used to specify the support for the GNU/Linux operating system with pthread library and soft-realtime features (see Section 7.3). OSEK ERIKA PROJECT This is used to specify the support for the ERIKA Enterprise OSEK/VDX operating system (see Section 7.1). WINDOWS PROJECT This is used to specify the support for the Microsoft Windows operating system (see Section 7.2). LINUX RTAI PROJECT This is used to specify the support for the RTAI operating system (see Section 7.4). BARE METAL PROJECT This is used to specify the support for the Bare Metal systems (see Section 7.5). The values of all attributes above represent the name of a directory containing the specific information allowing the code generator to generate the target-dependent files. Each of those directories will contain a target.txt file (see Section 9.3.3) The palette directory When defining a custom board or a custom block, it is often useful to define a customizable palette containing an instance of the blocks which can be used in a specific context. To add a custom palette to the palette tree available when loading E4Coder, you need to: create a Palette file with extension.cosf; place the Palette file inside a directory under the target board/custom block directory; add a palette attribute in the board section of the board.txt file, providing the name of the palette directory. As a result, when loading E4Coder all the.cosf files stored in the Palette directory will be loaded as part of the loading process of E4Coder. 135

136 Chapter 9. Customizations Structure of the target.txt file The target.txt file is stored in the the directories linked to the board specific configurations for a given target (see Section ). The file lists the various peripherals supported by the target board on the specific operating system, as well as additional code and libraries which needs to be added to a standard project in order to compile a complete system. The structure of the target.txt file is as follows: The target.txt file is a text file. Comment lines start with the # sign. Example: # This is a comment The file is divided in sections, with section names surrounded by brackets. The current list of supported sections are version, blocktype, settings and oil. The parser supports an additional symbol after the section name. The parser supports section name appearing more than once. In this case, the section content will be union of all contents. Example: # This is a comment [version 1.0] [blocktype dac] # details on the DAC peripherals present in the board [blocktype digout] # details on the digital I/O peripherals present in the board The section content is given by a set of attributes and values in the form or attribute=value attribute= value The list of attributes supported in each section is detailed in the following paragraphs. When an attribute refers to a directory name, all paths are intended relative to the directory containing the target.txt file. In other words, the idea is that you may have one level of sub-directories each one containing specific content relative to a specific aspect of a target board support version section of the target.txt file This section is only used to mark the version number of the target.txt file. The current version of E4Coder accepts version 1.0 only. Example: [version 1.0] 136

137 Chapter 9. Customizations settings section of the target.txt file This section contains the following attribute: librarycode This is the name of the directory containing additional code and files which will be added to the generated code when using this board type. This attribute is optional. Typical usages of this attribute is for adding specific library files (e.g.,.c files implementing specific functionalities called by the target code). This attribute can be specified also inside the blocktype section, see Section Example: [settings] librarycode=core lib targettick This attribute can be used to specify (in seconds) the default minimum periodic interrupt (often called tick) used by the target board. The default tick time is used in some target operating systems (e.g., OSEK/VDX, see Section 7.1) to scale all periods to an integer number of the base tick. Please note that the tick duration specified in this parameter must be corresponding to the real one on the target board otherwise the timings on the target board will not work. Example: [settings] targettick=1e-3 targetinclude This attribute can be used to specify an additional file to be added verbatim into the file target names.h. Example: targetinclude=target include.txt targetconfigs This attribute can be used to specify an additional C file which will be included verbatim inside the file target.c. Example: targetconfigs=targetcfg.txt targetinclude and targetconfigs are used to specify a set of hooks functions as well as a set of other functions that are used by the code generator to interface the target with the generated code. These two sets of functions are described in Sections and

138 Chapter 9. Customizations Hooks functions that can be specified inside targetinclude and targetconfigs As explained in Section , targetinclude and targetconfigs attributes can be used to specify special hooks called in specific points of the generated code. These hooks works as follows: The selection of the operating system (ERIKA Enterprise, Linux, Windows) automatically selects a template used for the main() function and for the most general parameters and settings which are typical of a vanilla setting. In many cases, some target boards needs some additional target-specific configurations which needs to be executed in various places, such as just after the application startup (for example, it could be an oscillator PLL setting on a microcontroller, or some application specific logging/watchdog/... ), at the end of the application, after the OS initialization, and so on. These target specific settings must be included into hook functions, which are customizable functions inserted by default into pre-defined places into the vanilla target startup code. In order to activate a hook function, you need to proceed as follows: inside the file specified in the targetinclude setting you need to include a #define to activate a specific hook. As an example: #define E4C BOARD INIT inside the file specified in the targetconfigs setting you need to specify the body of the function implementing the hook. As an example: #ifdef E4C BOARD INIT void e4c board init(void) {... } #endif /* E4C BOARD INIT */ The list of available hooks are described in Table Typing of variables, and the types.h file When E4CoderCG generates the code, it also generates a file named types.h, which contains all the types declarations which are used in the generated code (including the types used by SMCube blocks). In order for all the code to compile properly, it is fundamental that all the target dependent.c files will include the types.h file, and afterwards use those types. Please see Section for more information on the types.h file.. 138

139 Chapter 9. Customizations #define Function prototype Description E4C BOARD INIT void e4c board init(void); Called before the superblock init functions. E4C BOARD DEINIT void e4c board deinit(void); Called before the end of the main() function. E4C OS INIT void e4c os init(void); Called after the OS initialization 2. E4C OS DEINIT void e4c os deinit(void); Called before the superblock end functions. E4C EXIT HOOK int e4c exit hook(void); Called inside the main loop of a Bare-Metal target to provide the possibility to exit the main loop. Table 9.1.: Hooks in the generated code that can be specified inside a target board Additional functions to be included inside targetinclude and targetconfigs This Section describe the set of additional functions that have to be defined inside the targetinclude and targetconfigs files in order to enable a complete compilation of the generated code. This section does not apply for Linux pthreads, RTAI and Windows targets, but only for Bare Metal and ERIKA enterprise targets. For each function described below, you need to: include the declaration inside the targetinclude file. Example: extern void e4c disable all interrupts(void); include the definition inside the targetconfigs file. Example: void e4c disable all interrupts(void) {... } Bare Metal target. For the Bare Metal target, the functions to be implemented are: void e4c disable all interrupts(void); void e4c enable all interrupts(void); time e4c get tick(void); Interrupt disabling and enabling is used by the generated code to protect the data exchange between blocks allocated on different superblocks (see Section 8). The e4c get tick function is used to get the current tick number. The idea is that the system accounts for the time passed inside a counter that is returned by this function. Afterwards, the counter is checked against the next periodic event of each periodic task generated by the code generator. 139

140 Chapter 9. Customizations For the ERIKA Enterprise target, the functions to be im- ERIKA Enterprise target. plemented are: void e4c disable all interrupts(void); void e4c enable all interrupts(void); Interrupt disabling and enabling is used by the generated code to protect the data exchange between blocks allocated on different superblocks (see Section 8). In addition to this, the code has the responsibility to init and configure the timer. The initialization of the timer must take into account the following hypothesis: The timer must be programmed as an ISR2, which needs to call the timer callback function generated by the code generator. The timer callback function implemented by the code generators simply calls CounterTick on the counter linked to the alarms whose notification is the activation of the periodic tasks generated by the code generator. The frequency of the timer must be the GCD of the periods of all tasks generated by the code generator. The amount of microseconds representing the GCD is generated by the code generator inside the macro ALARMS GCD US build section of the target.txt file The code generation process is only a part of the process involved in the compilation, programming and execution of code in an embedded target. Whereas some basic processes (like code generation and program compilation on Windows/Linux/ERIKA Enterprise targets) can be envisioned in general, there are other which are target dependent. As an example, consider the following two examples: you may need to prepare the environment where the code will be generated, for example by copying some set of files contained in a remote repository, after the code is generated but before the code is compiled; you may want an automatic programming of the board after a successful compilation. For this reason, E4Coder provides a build section inside the target.txt file. This section can be used to specify an additional command (typically a script) to be executed before the code generation process (pre) or after the successful project generation/compilation (post). Please note that the post command will not be run in those cases: in the Bare Metal target, because the Bare Metal target does not specify by default a way to compile the application. If you need to automatically compile a Bare Metal target generated code use the pre command; 3 Note that this macro will be revised in future versions of the code generator 140

141 Chapter 9. Customizations Special string %%SCI%% %%OUTPUT PATH%% %%PROJECT NAME%% %%E4CODER USER PATH%% %%BOARD PATH%% Value ScicosLab install directory. Project output path. The project name as specified in the wizard. The $HOME/E4Coder user directory where the user stores E4Coder related information. The directory where the current target board in use is stored. Table 9.2.: Special strings used when parsing the pre and post commands in the build section. if the Run compilation after code generation checkbox has not been specified in the Compiler options for the target. The syntax of the build section is as follows: if the pre and post commands are valid for both Windows and Linux hosts, then the section should be declared with the following: [build] pre=... post=... if the pre and post commands are different in the two host OSes, then you need to specify two sections, such as in the example below 4 : Windows Host: [build WINDOWS] pre=... post=... Linux Host: [build LINUX] pre=... post=... The pre and post command strings typically contain a path to a script, with additional parameters. The path can be absolute, or can contain the special strings described in Table 9.2. An example of the [board] section is included below: [build LINUX] pre= %%OUTPUT PATH%%/erika-lib/core lib/mio file.sh post= %%SCI%%/contrib/E4coder/E4coder-cg/bin/avrdude wrapper 4 If both versions ([build] and [build LINUX] / [build WINDOWS] are specified, then the [build] section will be ignored. 141

142 Chapter 9. Customizations blocktype section of the target.txt file This section is used to define the instances of a peripheral block (those stored inside the IO palette, see Section 4.2.6) existing on a specific target board. The peripheral block type referred by the section is specified in a symbol after the blocktype section name. Possible symbols are: adc ADC block, see Section button Button block, see Section buzzer Buzzer block, see Section dac DAC block, see Section digin Digital Input block, see Section digout Digital Output block, see Section easylab serial rx Serial input block using the EasyLab protocol, see Section easylab serial tx Serial output block using the EasyLab protocol, see Section encoder Encoder block, see Section lcd LCD block, see Section led LED block, see Section pwm PWM/Servo block, see Section touch Resistive touchscreen block, see Section The section allows the presence of the following three attributes: librarycode This is the name of the directory containing additional code and files which will be added to the generated code when using this block type. This attribute is optional. Typical usages of this attribute is for adding specific library files (e.g.,.c files implementing specific functionalities called by the target code specified with the targetcode attribute below). If the same library is used by different block types, and more than one of these types are in use in the board, then the library code is copied only once in the target code generated by the code generator. This attribute can be used also in the setting section, see section Example: [blocktype encoder] librarycode=encoder lib 142

143 Chapter 9. Customizations targetcode This is the name of a separate file containing the specification of the code which will be generated for this type of block into the target.c 5 file. See section peripheral This attribute can be repeated more than one and is used to list one instance of the peripheral block on a given target board. The attribute must be specified in the following form: where: Example: peripheral=name,feature1 feature2... featuren NAME is the name of the specific peripheral on the target board (for example, ENCODER 1, DIGOUT 17, as well as all those listed in the tables in Chapter 7). feature1... featuren are generic features of the generated code. These features are optional, and can be used to map resources, peripherals, pins used by the specific block. The idea is that the code generator will check that there are no more than one peripheral block requiring the same feature. As an example, consider a target board with pin 3 which can be configured both as digital input or as digital output. We need to avoid a situation where a user will map a digital input and a digital output peripheral on the same pin 3. For that reason, the peripheral attribute of both configuration will include a pin 3 feature. [blocktype digin] librarycode=gpio lib targetcode=digin.txt peripheral=digin 0,pin0 peripheral=digin 1,pin1 peripheral=digin 2,pin2 [blocktype digout] librarycode=gpio lib targetcode=digout.txt peripheral=digout 0,pin0 peripheral=digout 1,pin1 peripheral=digout 2,pin oil section of the target.txt file When using the OSEK/VDX Kernel ERIKA Enterprise, the E4Coder Code generator allows the user to specify an additional OIL configuration file which contains the configuration of the operating system. The file is specified using the section oil of the target.txt file. The section is optional. 5 See Section

144 Chapter 9. Customizations Special string %%MONTH%% %%DAY%% %%YEAR%% %%HOUR%% %%MINUTE%% %%SECOND%% %%CFLAGS%% %%LDFLAGS%% %%INC PATHS%% %%APP SRCS%% %%TASKS%% %%OIL BLOCKS%% %%E4CODER VERSION%% %%E4CODER RELEASE%% Value The current month number. The current day number. The current year. The current hour. The current minute. The current seconds. The CFLAGS options specified in the code generation wizard (see Section 6.3.3). The LDFLAGS options specified in the code generation wizard (see Section 6.3.3). The Include Paths specified in the code generation wizard (see Section 6.3.3). All source files automatically added by E4Coder in the form APP SRC= filename ; All the task specification added by E4Coder following the parameters specified in Section This is substituted with a concatenation of all the OIL snippets coming from the peripheral blocks in use. This is substituted with the current E4Coder version. This is substituted with the current E4Coder build number. Table 9.3.: Special strings used when parsing the OIL file template. The following example specifies an OIL file template to be used when generating the code: [oil] oilcode=oil.txt At generation time, the code generator will read the filename specified in the oilcode attribute, and will perform a string replacement of the strings described in Table entrypoint section of the target.txt file The typical way of handling the code generation in E4Coder is to define a set of tasks inside the code generation wizard, and then afterward to map a set of superblocks to the specific tasks (see Section 6.3.4). As a result, the code generator will call the 144

145 Chapter 9. Customizations initialization, step and end functions generated from the superblocks in specific points of the task s code. The entrypoint mechanism can be used to add flexibility in this mapping step. The typical use cases where entrypoints can be used are: The board includes custom-programmed interrupt handlers where the user may wish to call specific code as part of the interrupt handler code; The board includes additional pre-defined threads, which may not be periodic, or which may include custom hand-written code to be intermixed with automatically generated code. In these cases, the entrypoint mechanism is really useful, allowing the code generation of customized functions. Given the entrypoint myentrypoint, the system will generate three functions with the following declarations: void myentrypoint init(void); void myentrypoint step(void); void myentrypoint end(void); which contains respectively the calls to the initialization, step and end functions of the superblocks mapped to the specific entrypoint. These functions have to be called inside the board code in a proper way 6. An example of entrypoint section is as follows: [entrypoint TorqueCtrl] type=function description=torque control called inside the ADC interrupt Which defines the entrypoint TorqueCtrl. Please note that the type attribute can be only function. The description is a single line free text, which will be displayed in Figure Structure of the targetcode attribute specified in the blocktype section of the target.txt file As part of the code generation process, the E4Coder code generator produces two files named target.c and target names.h, which contains all the functions implementing the interfacing with the various peripheral blocks used in the diagram (see Section 6.4). The targetcode attribute in the blocktype section (see Section ) contains the name of a text file describing the code which is generated for a single kind of peripheral block. The text file has the following structure: C-style comment lines are allowed. Please note that these comment lines will be part of the content copied in the output files. 6 The responsibility of placing the calls to these functions is up to the board developer 145

146 Chapter 9. Customizations The file is divided in sections, with section names surrounded by brackets. The current list of supported sections are header, init, step and end. The parser requires, depending on the block name, that additional parameters names are specified after the sections init, step and end. The idea is that the parameter names are then parsed and used for the real function prototypes generated for the block interfacing. The code written after the header section is stored inside the file target names.h, whereas the code between the various sections then becomes the body of the interfacing functions stored into target.c. As an example, for example, for the peripheral block ADC, the typical step section will be as follows: [step adc id, value] /* Read sample from peripheral */ e4box adc read(adc id, value); As a result, the code generated in the target.c will be as follows: /** ADC block implementation */ void CG adc read(int adc id, uint16 *value) { /* Read sample from peripheral */ e4box adc read(adc id, value); } As you can see, the code generator integrates the parameters adc id and value into the function prototypes of the ADC block. The section parameters give the possibility to write each code snippet without depending on the variable names but only on their types, which are described in Tables 9.4, 9.5, and Writing custom blocks The functionalities of existing blocks can be extended by adding custom blocks of type CG CUSTOM BLOCK (see Figure 4.33). These blocks implement a custom behavior which can be specified by writing four C functions. The Name property of the block is used to identify the name of the C header file that contains the declaration of the functions to use for a block. Multiple CUSTOM blocks can share the same name, and thus have the same general behavior. The other block properties, described in Section , allow to specify the input and output ports, the internal states, and the block parameters names and values. These properties contribute to define the expected custom functions signature. It is also possible to write various CUSTOM blocks with the same Name and that differ only for the parameters values. This 146

147 Chapter 9. Customizations Block Type Function prototype Section example adc void CG adc init(int adc id) [init adc id] button void CG button init(int button id) [init button id] buzzer void CG buzzer init(int buzzer id) [init buzzer id] dac void CG dac init(int dac id) [init dac id] digin void CG gpio init input(int gpio id) [init gpio id] digout void CG gpio init output(int gpio id) [init gpio id] encoder void CG encoder init(int encoder id) [init encoder id] lcd void CG lcd init(int lcd id) [init lcd id] led void CG led init(int led id) [init led id] pwm void CG pwm init(int pwm id) [init pwm id] touch void CG touch init(int touch id, int16 x range, int16 y range) Table 9.4.: Peripheral block description - init section. [init touch id, x range, y range] Block Type Function prototype Section example adc void CG adc read(int adc id, uint16 [step adc id, value] *value) button void CG button read(int button id, [step button id, value] *value) buzzer void CG buzzer write(int buzzer id, [step buzzer id, value] real value) dac void CG dac write(int dac id, real [step dac id, value] value) digin void CG gpio read(int gpio id, int8 [step gpio id, value] *value) digout void CG gpio write(int gpio id, int8 [step gpio id, value] value) encoder int32 CG encoder read(int encoder id, [step encoder id, value] uint8 *value) lcd void CG lcd write(int led id, uint8* [step lcd id, row1, row2] row1, uint8* row2) led void CG led write(int led id, int8 [step led id, value] value) pwm void CG pwm write(int pwm id, real [step pwm id, value] value) touch void CG touch read(int touch id, int16 *x value, int16 *y value) [step touch id, x value, y value] Table 9.5.: Peripheral block description - step section. 147

148 Chapter 9. Customizations Block Type Function prototype Section example adc void CG adc end(int adc id) [end adc id] button void CG button end(int button id) [end button id] buzzer void CG buzzer end(int buzzer id) [end buzzer id] dac void CG dac end(int dac id) [end dac id] digin void CG gpio end input(int gpio id) [end gpio id] digout void CG gpio end output(int gpio id) [end gpio id] encoder void CG encoder end(int encoder id) [end encoder id] lcd void CG lcd end(int led id) [end lcd id] led void CG led end(int led id) [end led id] pwm void CG pwm end(int pwm id) [end pwm id] touch void CG touch end(int touch id) [end touch id] Table 9.6.: Peripheral block description - end section. can be used to create a class of CUSTOM blocks which behaves differently but based on the same code base. In order to implement a CUSTOM block, the user has to provide two implementations, one to be used in simulation (see Section 9.4.1) and one to be used in code generation (see Section 9.4.2). Finally, Section specifies the structure of the customization directory used to specify a custom block. At least one example of custom block can be found under the following directory: install dir /contrib/e4coder/e4coder-cg/codegen/custom-blocks The example under the subdirectory custom OUTPUT contains an example for a new target to be supported by the E4Coder code generator and also an example of custom computational function for the simulation Simulation behavior of a custom block The code reported below shows how the custom OUTPUT computational function has been defined for the block in the example. For the complete code refer to the source files contained in the directory custom OUTPUT/sim sources of the custom OUTPUT example noted above. As you can see in Algorithms 9.1 and 9.2, the structure for the parameters of the block is defined and initialized by the user. The functions for simulation are different from the corresponding functions used in the target application but they can share some parts of the code if you want. Please refer to the Scicos manual for further information about computational functions. 148

149 Chapter 9. Customizations Algorithm 9.1 Simulation behavior of a custom block, part 1. /* * File : my_scicos_blocks. c * Description : Scicos block module * Author : Evidence Srl. */ # include " my_common.h" # include " custom_output.h" typedef struct custom_output_param_ { int8_ t numcycle ; } custom_output_param ; /* Global parameters of the block */ custom_output_param global_data ; static void custom_output_init ( scicos_block * block ) { global_ data. numcycle = * Getint8OparPtrs ( block, 1); custom_output_init (& global_data, Getint8InPortPtrs ( block,1), Getint8OutPortPtrs ( block,1)); } static void custom_output_output ( scicos_block * block ) { custom_output_outputupdate (& global_data, Getint8InPortPtrs ( block,1), Getint8OutPortPtrs ( block,1)); } static void cu stom_o UTPUT_ end ( scicos_block * block ) { custom_output_terminate (& global_data, Getint8InPortPtrs ( block,1), Getint8OutPortPtrs ( block,1)); } static void custom_output_state ( scicos_block * block ) { custom_output_stateupdate (& global_data, Getint8InPortPtrs ( block,1), Getint8OutPortPtrs ( block,1)); } 149

150 Chapter 9. Customizations Algorithm 9.2 Simulation behavior of a custom block, part 2. declspec ( dllexport ) void < Proprietà Name del blocco > ( scicos_block * block, int flag ) { if ( flag == OutputUpdate ) /* Write to the output ports */ custom_output_output ( block ); else if ( flag == Ending ) /* Termination ( called at the end of the simulation )*/ custom_output_end ( block ); else if ( flag == Initialization ) /* Initialization ( called at the beginning of the simulation ) */ custom_output_init ( block ); } else if ( flag == StateUpdate ) /* Update the state vector of the block */ custom_output_state ( block ); Code Generation behavior of a custom block When generating code for a custom block, E4Coder will include an header file named <identifier>.h, where identifier is replaced with the value of the Name property. This header file must be provided by the user and must contain the definitions of the functions to be used for the 3 phases: initialization (Init), output updates and state update (Step), and termination (End). The functions must have the following signatures: void <identifier> Init(<identifier> State *state, <identifier> Param *params, <input ports values>, <output ports addresses>); void <identifier> OutputUpdate(<identifier> State *state, <identifier> Param *params, <input ports values>, <output ports addresses>); void <identifier> StateUpdate(<identifier> State *state, <identifier> Param *params, <input ports values>, <output ports addresses>); void <identifier> Terminate(<identifier> State *state, <identifier> Param *params, 150

151 Chapter 9. Customizations <input ports values>, <output ports addresses>); The types <identifier> State and <identifier> Param are normally defined in data.h, based on the block properties States Initialization and Parameters Names and Values. The states type will be an array of reals whose length matches that of the array specified in States Initialization. In case the latter was left empty, the type will not be defined at all, and the parameter will be omitted in the functions prototypes. The <identifier> Param type is a C struct whose fields match the parameters specified in Parameters Names and have the type of the initial values specified in Parameters Values. Inputs are passed to the functions by value, in case of scalars, or by const pointers for vectors. Outputs are always passed by pointers. As an example, consider a custom block with the following properties: Name: myfunc ; States Initialization: [0, 0, 0, 0] (4 reals); Parameters names: list( param1, param2 ); Parameters values: list(int16(1), real(0.5)); Input sizes and types: [1 1 1; ] (a real scalar, and a row vector of unsigned 8-bit integer); Output sizes and types: [1 1 7] (an unsigned 16-bit integer scalar). The code generated for this block is reported in the listing in Algorithm 9.3, while the prototypes for the functions to be declared in custom.h are shown in Algorithm 9.4. Algorithms 9.5 and 9.6 show and example of the target code for the custom block. As you can see the code contains the definitions of the custom block s functions called by the automatically generated functional code Override Options It is possible to specify alternative definitions to the standard ones provided by E4Coder in a C header named custom.h. This header can contain alternative typedefs for the param and the state types, as well as an alternative value for the initial state. For each overriding type provided, a C macro must also be defined with the name CUSTOM <identifier> <type> OVERRIDE, where type should be either Param or State. When CUSTOM <identifier> State OVERRIDE is defined, meaning that a custom state type is used, then the following applies: for a given block block-symbol the macro CUSTOM <block-symbol> INITIAL STATE must be defined. Moreover, the compiler will 151

152 Chapter 9. Customizations Algorithm 9.3 Example of the custom block section from data.h. /* CG_CUSTOM_BLOCK */ /***************************/ /* Custom Blocks API */ /***************************/ /* * Compile with - DCUSTOM_HEADER to include user - generated * header " custom. h". The header should provide alternative * definitions for some ( or all ) of the Custom Blocks APIs. * For each symbol XXX defined in " custom. h", the macro * CUSTOM_XXX_OVERRIDE must also be defined. * Moreover, if CUSTOM_ < identifier > _State_OVERRIDE and * CUSTOM_ < block - symbol > _INITIAL_STATE are defined, the value * in < block - symbol > _initial_state will be used as the * initial state. */ # ifdef CUSTOM_HEADER # include " custom.h" # endif /* myfunc */ # ifndef CUSTOM_myfunc_Param_OVERRIDE typedef struct myfunc_param_ { real param1 ; int16 param2 ; } myfunc_param ; # endif # ifndef CUSTOM_myfunc_State_OVERRIDE typedef real myfunc_ State [ 4]; # endif # include " myfunc.h" 152

153 Chapter 9. Customizations Algorithm 9.4 Example of user-supplied C functions declarations for a CUSTOM block. /* Initialization function */ void myfunc_init ( myfunc_state * state, myfunc_param * params, real in1, const uint8 * in2, uint16 * out1 ); /* Output update function */ void myfunc_outputupdate ( myfunc_state * state, myfunc_param * params, real in1, const uint8 * in2, uint16 * out1 ); /* State update function */ void myfunc_stateupdate ( myfunc_state * state, myfunc_param * params, real in1, const uint8 * in2, uint16 * out1 ); /* Termination function */ void myfunc_terminate ( myfunc_state * state, myfunc_param * params, real in1, const uint8 * in2, uint16 * out1 ); 153

154 Chapter 9. Customizations Algorithm 9.5 Target code for the CUSTOM block, part 1. # include " data.h" void custom_output_internal ( custom_output_param * Param, int8_t *In1, int8_t * Out1 ) { static int8_ t var = 0; static int8_ t out1 [2] = {1,0}; var ++; if(var == Param -> numcycle ) { var = 0; out1 [0] ^= 1; out1 [1] ^= 1; } } if(in1 [0]){ Out1 [0] = out1 [0]; Out1 [1] = out1 [1]; } else { Out1 [0] = 0; Out1 [1] = 0; } 154

155 Chapter 9. Customizations Algorithm 9.6 Target code for the CUSTOM block, part 2. # include " data.h" # include " ee_pic30regs.h" /* output update */ void custom_output_outputupdate ( custom_output_param * Param, int8_t In1 ) { int8_t Out1 [2]; custom_output_internal ( Param, &In1, Out1 ); if( Out1 [0]) LATDbits. LATD0 = 1; else LATDbits. LATD0 = 0; if( Out1 [1]) LATDbits. LATD2 = 1; else LATDbits. LATD2 = 0; } /* state update */ void custom_output_stateupdate ( custom_output_param * Param, int8_t In1 ) { /* Void in this case. } void custom_output_init ( custom_output_param * Param, int8_t In1 ) { /* set LEDs drive state low */ LATDbits. LATD0 = 0; LATDbits. LATD2 = 0; /* set LEDs pin as output */ TRISDbits. TRISD0 = 0; TRISDbits. TRISD2 = 0; } void custom_output_terminate ( custom_output_param * Param, int8_t In1 ) { /* Void in this case */ } 155

156 Chapter 9. Customizations expect a symbol <block-symbol> initial state to be declared in custom.h, whose value will be used to set the initial state for the block. In order to include the overriding header custom.h, the compiler must be invoked with the option -DCUSTOM HEADER Structure of the directory used to specify a custom block Supporting a new custom block under the E4Coder Code Generator requires the creation of a separate directory under one of the customization folders. The directory contains a file named custom-block.txt, which describes the various properties of the custom block. The structure of the file custom-block.txt is as follows: The custom-block.txt file is a text file. Comment lines start with the # sign. Example: # This is a comment The file is divided in sections, with section names surrounded by brackets. The parser supports section name appearing more than once. The current list of supported sections are version, oil, customblock, customlibs, customsources, and customheaders. In this case, the section content will be union of all contents. Example: # This is a comment [version 1.0] [customblock] # content of the customblock section... The section content is given by a set of attributes and values in the form or attribute=value attribute= value The list of attributes supported in each section is detailed in the following paragraphs. When an attribute refers to a directory name, all paths are intended relative to the directory containing the custom-block.txt file. In other words, the idea is that you may have one level of sub-directories each one containing specific content relative to the board version section of the custom-block.txt file This section is only used to mark the version number of the custom-block.txt file. The current version of E4Coder accepts version 1.0 only. Example: [version 1.0] 156

157 Chapter 9. Customizations customblock section of the custom-block.txt file This section contains the following attributes: blockname This attribute is used to specify the name of the custom block. Example: blockname=ctrl PID simlibpath This attribute is used to specify the simulation library implementing the simulation behavior of the block. This library will be loaded during the E4Coder loading process. The name of the library must be specified without extension (a default extension will be added depending on the host type,.so for Linux hosts and.dll for Windows hosts). A special symbol %%PREFIX PATH%% is also supported as part of the value. This symbol is substituted with the absolute path of the file custom-block.txt. If %%PREFIX PATH%% is not specified, you need to provide an absolute path to the library, allowing you to specify a common path containing all libraries of all custom blocks you defined 7. Example: simlibpath=%%prefix PATH%%/sim/libctrlPid simlibcode This attribute is used to specify the asm linkage of the library. This attribute is optional. Possible values of this attribute are: c if the library has been written in C language (this is the default); f if the library has been written in FORTRAN. Example: simlibcode=c palette This attribute is used to specify a directory containing.cosf palette files. Example: palette=palettes customlibs section of the custom-block.txt file This optional section contains a set of lines specifying additional libraries which need to be loaded in addition to the library specified with the simlibpath attribute. The special symbol %%PREFIX PATH%% is supported. Example [customlibs] %%PREFIX PATH%%/sim/libctrlPid c:/users/pj/mylibrarydirectory/mylib 7 We strongly suggest the usage of %%PREFIX PATH%%, because absolute paths syntax depend on the host operating system thus making these files non-portable (e.g, Windows hosts will specify absolute paths in the form c:/users/username/... whereas Linux hosts in the form /home/username/

158 Chapter 9. Customizations customsources section of the custom-block.txt file This section contains a set of lines specifying the source files which should be compiled in the final project when using this custom block. The source files should implement the interface defined in Section The special symbol %%PREFIX PATH%% is supported. Example: [customsources] %%PREFIX PATH%%/sources/ctrl PID.c customheaders section of the custom-block.txt file This section contains a set of lines specifying the path of a set of include directories which should be added to the final project when using this custom block 8. The special symbol %%PREFIX PATH%% is supported. Example: [customheaders] %%PREFIX PATH%%/sources/ %%PREFIX PATH%%/mylibs/ oil section of the custom-block.txt file This section works in the same way as Section You may think at this list as a set of additional -Idirectory option to a C compiler. 158

159 10. Additional tools SMCube Figure 10.1.: The SMCube editor window. SMCube is a tool for modeling, simulation, and code generation of discrete time state machines. Automatic code generation from functional models is a clear trend in automotive, industrial control and in other industrial sectors. Most of the application descriptions used for code generation often include both data-flow subsystems and finite state automatas. The Data Flow part is typically used to perform filters and control algorithms. Finite state automatas are used to map complex behaviors that are not easily expressed with data flow concepts (as, for example, application modes, alarms, and so on). SMCube is a lightweight State Machine editor, simulator, and code generator which can be used in conjunction with ScicosLab [2] and the E4Coder code generator, allowing 159

160 Chapter 10. Additional tools the creation of hybrid diagrams composed of both a data-flow part as well as finite state machines. Using SMCube, you can easily: Design your own state machine, drawing states and transitions and configuring their parameters (see Figure 10.1). Define a data model for the state machine, with inputs, outputs and local variables. Save your state machine into a XML file. Simulate the state machine response given an input pattern. The simulation can be interactive (you can monitor graphically the evolution of the simulation with a proper highlighting of the states, see Figure 10.2) or in background (no graphical output is given, useful for simulating at maximum speed). Generate a C++ language implementation of the state machine for simulation purposes. Generate a C language implementation of the state machine, for execution on embedded targets. Together with E4Coder, SMCube provides the following additional functionalities: Integration of a SMCube state machine inside a ScicosLab diagram, using a customized SMCube block. Integration of the simulation and code generator engines of ScicosLab with SM- Cube for starting, running, stopping a simulation. Simulation of a ScicosLab diagram including one or more state machines. Code generation of a ScicosLab diagram including one or more state machine with the E4Coder code generator and ERIKA Enterprise [8]. For more information, please refer to the SMCube Reference Manual [6] E4Coder GUI E4CoderGUI is a tool for designing graphical user interfaces and is shipped as part of E4Coder. E4CoderGUI enables the following functionalities: Integration of a E4CoderGUI user interface inside a ScicosLab diagram, using a customized E4CoderGUI block. Integration of the simulation engines of ScicosLab with E4CoderGUI for starting, running, stopping a simulation. 160

161 Chapter 10. Additional tools Figure 10.2.: SMCube Simulation Dialog Box (1 - start/stop simulation, 2 - state machine with highlighted states, 3 - state history trace, 4 - detail of a single step). Simulation of a ScicosLab diagram including one or more user interface blocks. Generation of target code using Qt Libraries for Linux (see Section 7.3) and Windows (see Section 7.2) targets. Figure 10.3 shows an E4CoderGUI block: the number and type of the input and output ports can be configured in the E4CoderGUI editor, shown in Figure The editor also allows to visually design the user interface. Figure 10.5 shows a GUI during simulation. For more information, please refer to the E4CoderGUI Reference Manual [3]. Figure 10.3.: An E4CoderGUI block with two inputs and two outputs. 161

162 Chapter 10. Additional tools Figure 10.4.: The E4CoderGUI editor window. Figure 10.5.: An example of E4CoderGUI user interface during simulation. 162

163 Chapter 10. Additional tools FLEX Demo Board Simulator Figure 10.6.: The FLEX Demo Board Simulator. This palette contains the FLEX DemoBoard blocks, which has been initially introduced with the open-source code generator described in Appendix A. WARNING: This block is provided in E4Coder for backward compatibility in simulation mode, and cannot be used for code generation. To create nice looking interactive panels we suggest the usage of E4Coder GUI (see Section 10.2). The reason to develop a FLEX Demo Board Simulator was triggered by the fact that we wanted a simple method to obtain ScicosLab diagrams which could be both simulated and for which we could generate C code for an embedded target. As a result, we developed what we called the FLEX Demo Board Simulator 1. The simulator is used by using two custom blocks shown in Figure The two blocks represents the inputs from the board (in this case the four buttons), the outputs which can be generated (in this case 8 LEDs, a 2x16 LCD and a Buzzer). 1 The simulator is distributed as part of the E4Coder toolbox. 163

164 Chapter 10. Additional tools Figure 10.7.: FLEX Demo Board blocks. When generating code for the FLEX board, the superblock should not contain this block. The blocks of the E4coder-IO palette should be used instead: these blocks in fact will be translated into the C code really controlling the board peripherals. When simulated, the blocks open a separate window, shown in Figure 10.6, which shows a FLEX Demo Board [5]. The user can interact with the simulated board in the following ways (please refer to the red highlighted zones in Figure 10.6): 1. Buttons can be pressed, and their output is presented on the output signals of the simulator output block. Button 1 is the button on the left, Button 4 is the button of the right. In the following examples, they will be named B1, B2, B3, B4. Please note that the pointer shape changes when the mouse is over the button. 2. LEDs can be controlled from the input of the simulator input block. 3. The 2x16 characters LCD can be controlled from the inputs of the simulator input block. 4. The Buzzer can be controlled from the input of the simulator block. The input should be in the range from zero to one to modulate the sound to be reproduced (if the input is zero no sound will be emitted). The Buzzer can be enable and disabled by clicking on the speaker symbol (a cross is displayed instead of the sound wave if the buzzer is mute). 164

165 11. Examples The E4Coder toolbox is distributed together with a set of examples able to demonstrate some of the E4Coder functionalities. This section describes how to load the examples and shows their list with the description or the reference to the manual actually describing them How to load the examples The examples are distributed together with the E4Coder toolbox. Once installed, the examples can be found inside the following directory: SCICOSLAB INST DIR /contrib/e4coder/e4coder-cg/examples/ where SCICOSLAB INST DIR is the directory where you have installed ScicosLab. To run those examples, you need to: Open ScicosLab; Load the E4Coder toolbox as described in Chapter 3; Open the ScicosLab Demos as shown in (see Figure 11.1); Select the E4Coder demos, and then select one of the examples in the list (see Figure 11.2); As a result, ScicosLab will ask for a destination directory where the files related to the demo will be copied (see Figure 11.3). Once specified, the demo files will be copied, and the example diagram will be opened. Figure 11.1.: Open the ScicosLab Demos. 165

166 Chapter 11. Examples Figure 11.3.: You are prompted with a destination directory when opening a demo. Figure 11.2.: Open the Example. The actual installation may have more examples available than shown in this picture. 166

167 Bibliography [1] DIAPM. Rtai - the realtime application interface for linux. [2] INRIA and ENPC. Scicoslab. and scicoslab.org/. [3] Evidence Srl. E4codergui reference manual, rapid user interface prototyping for scicos models. [4] Evidence Srl. Evidence hardware boards. hardware. [5] Evidence Srl. Flex demo board. flex-daugheter-boards.html. [6] Evidence Srl. Smcube reference manual, state machines for everyday usage. [7] Evidence Srl, Simone Mannori, and Roberto Bucher. Scicos-flex code generator. [8] Evidence Srl and many other contributors. Erika enterprise and rt-druid. http: //erika.tuxfamily.org. 167

168 A. Comparison between E4Coder and the Scicos Pack Before the release of E4Coder, Evidence, Roberto Bucher and Simone Mannori distributed an embedded code generator for ScicosLab named Scicos-Pack [7]. This code generator is still available open-source on the ERIKA Enterprise Website, and will be maintained to provide a free, open-source code generator for embedded targets. However, the Scicos-Flex should not be confused with E4Coder, which is a complete rewrite of the code generator, with many additional functionalities. Table A.1 can be used to better understand the differences between the Scicos-Pack release and the E4Coder product.c Finally, Table A.2 compares the Flash and data size of a similar diagram compiled with E4Coder and with the Scicos-Pack code generator. The diagram is a PID control of a DC motor, with around 40 blocks, compiled on a Microchip dspic DSC microcontroller. Here are a set of short notes explaining these numbers: About the total flash size, both diagrams include the startup code, as well as the ERIKA Enterprise kernel, with drivers for ADC, Encoder, PWM, and LEDs. The kernel has been configured to run one periodic task activated by an alarm linked to a counter. The total data size is completely different because the Scicos-Pack generates one scicos block structure for each block, thus using a lot of RAM space. The E4Coder expands the blocks inline, allocating only what is needed for the target code. In this sense, E4Coder scales well with complex designs. Although the Control loop flash size used in both cases is similar, it has to be remembered that the Scicos-Pack version includes only the function calls to the block implementations (whose size is include in the Total flash size), whereas the E4Coder numbers comes from an inline expansion of the control code itself. Finally, the Control loop init is different mainly because the Scicos-Pack code directly initializes in the code all the member fields of the scicos block data structure; on the other hand, E4Coder uses automatic data initialization performed by the compiler when defining the C variables. 168

169 Appendix A. Comparison between E4Coder and the Scicos Pack Feature Scicos-Pack E4Coder Control algorithm simulation Same design for simulation and code generation Scicos code generator (derived from SUPSI) E4Coder with inline code expansion SMCube state machines (flat) SMCube state machines (hierarchical and junction points) OSEK/VDX integration (ERIKA Enterprise) OSEK/VDX integration, multiple tasks and rates FLEX boards support AUTOSAR component generation next Configurable target peripheral blocks Easy retargeting to new MCUs Generation of test vectors next efficient usage of RAM and Flash custom data types custom variable names pure code (no RTOS) code generation gen. for multiple subsystems in a single diagram multirate code generation multitask and mapping of subsystems to tasks E4CoderGUI Code generation of embedded Qt Panels Code generation for Linux and Windows targets traceability of code generated by blocks next MISRA C next customizable data initialization next Table A.1.: Comparison between E4Coder and Scicos-Pack. next stands for the next version of the code generator 169

170 Appendix A. Comparison between E4Coder and the Scicos Pack Description Scicos Pack E4Coder Total flash size Total data size Control loop flash size Control loop flash size with init Table A.2.: Footprint comparison of a similar example compiled with E4Coder and with the Scicos Pack. Numbers in bytes. 170

171 B. License Manager In order to run the E4Coder toolset needs a License file and a matching USB dongle, both issued by Evidence. E4Coder can be installed on multiple systems with the same valid License file, but at any one time it can be run only on the system where the USB dongle is connected. B.1. The License File The License file provided by Evidence enable a set of features of the toolset, and can set different licensing for each of them. The features specified in a License are: E4Coder The main component of the toolset, needed to install and load the ScicosLab extension pack. SMCube Complete The SMCube feature; if not specified in the License, simulation and code generation for state machines is disabled. E4CoderGUI The user interface simulation feature; if not specified in the License, GUI blocks are disabled. For each feature, the following types of licensing are available: TIME LIMITED Enables the specific feature up to a given expiration date. TIMED Enables the feature indefinitely, allowing to use any version released before the expiration date. The License.xml file is installed by default in the E4Coder directory under the current user home directory. A different location can be selected during the installation procedure, by calling the function E4Coder license manager() in ScicosLab. After the installation, the currently installed license can be examined by calling the function E4Coder info() in ScicosLab (see Figure B.1). The licensing information is accessed by clicking on the License... button (see Figure B.1). The License panel, shown in Figure B.2, displays all the information about the current license: the customer name; the serial number of the USB dongle linked to the license; 171

172 Appendix B. License Manager Figure B.1.: The About panel in E4CoderGUI. Figure B.2.: The License panel in E4CoderGUI. 172

173 Appendix B. License Manager the license serial number; for each feature, the release date, the license type, and the expiration date. the path of the current license directory. Moreover, the Dongles section (see Figure B.2) allows to check the serial number of the dongle that is currently connected to the system. If the user connects another dongle, he/she can force the system to read its serial number by hitting the Refresh button. Obtaining the serial number of the dongles can be useful when contacting Evidence (e.g. for license renewals). If you need to know the location of the License File from the command line, you can run the following command: E4CoderStarter -printlicensepath which is located in the directory scicoslab installation directory /contrib/e4coder/e4coder-cg/bin B.2. Errors When working with E4Coder, a number of errors can occur which are related to licensing issues. The most common type of errors involves the use of the USB dongle. If E4Coder cannot find the correct dongle, matching the installed license, an error will occur, as shown in Figure B.3. Note that the error dialog shown in the figure reports a case in which E4Coder could not find the valid dongle, but instead found another one with a different serial number, shown in blue in the Connected Dongles section at the bottom. Another common error results from a license expiration: if the installed license for the feature in use is of type TIME LIMITED and its expiration date has passed, an error like that in Figure B.4 will be shown. Please contact Evidence to renew your license. Finally, if E4Coder could not find the License file in the chosen location, it will show a message like that in Figure B.5. If this happens, please check the path you chose for the license during installation (the default is <user home directory>\e4coder ): it should contain the file License.xml. Otherwise, and if you have a copy of the license file, copy it to that location and restart E4Coder. If the problem persists, try reinstalling E4Coder. If you need to obtain a new copy of your license file, contact Evidence and please be sure to provide the serial number of you USB dongle, which you can read at the bottom of the error dialog, as shown in Figure B

174 Appendix B. License Manager Figure B.3.: E4Coder did not find the dongle matching the current license. Figure B.4.: E4Coder found that the installed license has expired. 174

175 Appendix B. License Manager Figure B.5.: E4Coder could not find the license file. 175