CANister. Configurator. Manual. Version 3.0

Transcription

1 CANister Configurator Manual Version 3.0 Vector Informatik GmbH, Ingersheimer Straße 24, Stuttgart Phone , Fax , Internet

2

3 III Subsidiaries China Vector Informatik GmbH Shanghai Representative Office Unit 1701, Sunyoung Center No.398 Jiangsu Road Changning District Shanghai P.R. China Phone: Fax: France Vector France SAS 168, Boulevard Camélinat Malakoff France Phone: Fax: India Vector Informatik India Private Limited 4/1/1/1, 3 rd floor, Sutar Icon Sus Road Pashan Pune India Phone: Fax: Japan Vector Japan Co., Ltd. Seafort Square Center Bld. 18F Higashi-shinagawa Shinagawa-ku Tokyo Japan Phone: Fax: Korea Vector Korea IT Inc Mario Tower Guro-dong, Guro-gu Seoul Republic of Korea Phone: Fax: Sweden VecScan AB Theres Svenssons Gata Göteborg Sweden Phone: Fax: USA Vector CANtech, Inc. Suite Orchard Hill Place Novi, Mi USA Phone: Fax: United Kingdom Vector GB Limited Rhodium, Central Boulevard Blythe Valley Park Solihull, Birmingham West Midlands, B90 8AS United Kingdom Phone: Fax: For distributor addresses please have a look on our website:

4 IV International Quality Standard Certificate Vector Informatik GmbH has ISO 9001:2008 certification. The ISO standard is a globally recognized quality standard. Typographical Conventions Meaning Example Menu command, button, checkbox, File / Open menu Download checkbox Filename SAMPLE.CSK Key <Return> C code if (a == 5) { b = 6; }

5 V Chapter overview Chapter 1: This chapter explains the system requirements and provides information on copy protection. The user is given an introduction into the installation of the CANister Configurator. Chapter 2: The user is given an overview of the functions of the CANister Configurator. The various versions of the Configurator are introduced. New features of the CANister Configurator are also explained. Chapter 3: The individual functions of the CANister Configurator are described in detail. This includes events and actions as well as generating and downloading. General options are also explained in this section. Chapter 4: This chapter describes how to define and implement user functions that are compiled with the Tasking compiler. This also includes a description of the memory areas of CANister. The API of user C-library functions is described. Chapter 5: A tutorial leads the user through a detailed explanation of how to create configurations. In the process, the most important functions are introduced and explained step by step. Chapter 6: The examples included with delivery of CANister Configurator are explained in detail. Chapter 7: This chapter presents tips and tricks designed to help users create configurations more easily and to avoid errors. Chapter 8: Chapter 9: The most important terms and concepts are explained briefly in this chapter. Controlling the Configurator with menus, the tool bar or the keypad. This chapter also explains the help system. Chapters 10-13: Indices.

6 VI Contents 1 Preparations System Requirements Copy Protection Installation of the Software Introduction Compatibility Programs for CANister CANister Variants Functional Overview LIN Support Quick Start Loading a Configuration (New Format) Loading an Old Configuration (LKG or CBC File) New Configuration Creating a Total Configuration Settings for Single Configuration Generating Download Configuration Download Firmware Detailed View / Total View Options Dialog About Hardware Copy / Paste Drag and Drop CANister Terminal Online Help Switching over from CANister Configurator 2.x to Loading a *.cbc Configuration User functions Switching over from CANister Configurator 1.x to Download Loading a *.lkg Configuration INI File...16

7 VII User Functions CANister Assistant Basic Principles Overview List of Events List of Actions Function of the Interpreter Options Download Tasking Compatibility Total Configuration Settings Single Configuration Settings Databases Receiving Nodes Cyclic Messages Schedule Table Definitions Events Start CAN Connect CAN Disconnect Keys Digital Input Message Transmitted Message Received Timer User Events Serial Command Signal check Actions LED Keys Timer User Function...47

8 VIII Transmit Message (CAN) Set Message Signal (CAN) LIN communication (LIN) Transmitting messages (LIN) Set Message Signal (LIN) Network Management (CAN) Cyclic Messages (CAN) Digital Output PWM Output Relay Change of Configuration Signal check (CAN/LIN) Documentation Generate Overview C Header / Code Compile Generate Download Summary Download Download Configuration Download Configuration Directly Download Firmware CANdb Editor CANister Terminal About Hardware Programming User C Functions Introduction Interpreter and User C Functions User C Functions and Interpreter Startup Code Call Interface User C-Library Version of User C-Library Generated files...67

9 IX Header Usercfct.h C File Usercfct.c User-defined C Module Memory Areas Local Memory Global Memory Stack Generation Compiler Makefile Linker Error Files During Compilation File Format of the Configuration API of User C-Library Functions cbsetled cbsetoutput cbgetinput cbgetanaloginput cbsetpwm cbcontrolpwm cbsetrelay cbgethallposition cbsethallposition cbgetlinrxobject cbgetlintxobject cbsetlinsignal cblintransmit cblintransmitheader cblincommunication cbgetcanrxobject cbgetcantxobject cbsetcansignal cbcantransmit cbgetkeys cbgetkeymask cbsetkeymask cbgetconstant cbsetconstant...87

10 X cbgetsysconstant cbsetuserevent cbassert cbgetglobalusrmemory cbv24transmit cbv24senddata cbgetsiodataptr Tutorial New Configuration with LED and Keys Generate and Download Configuration with Multiple Single Configurations Configuration with Database Configuration with User C Function Configuration with Network Management Configuration for LIN Configuration for LIN Master Configuration for LIN Slave Examples Example Sample1 (Hardware Test) Brief Description General Settings Functions of the Keypad Example Sample2 (Timer) Brief Description General Settings Part_ Functions Part_ General Settings Part_ Functions Part_ Example Sample3 (CAN) Brief Description User Interface General Settings for Messages_HS Functions of the Keypad General Settings for Messages_LS Functions of the Keypad...129

11 XI C Functions Example Sample4 (LIN Master) Brief Description User Interface General Settings for LinMaster Functions of the Keypad General Settings for LinMasterFct Functions of the Keypad C Functions LinMasterFct Example Sample5 (LIN Slave) Brief Description User Interface General Settings for LinSlave Functions of the Keypad General Settings for LinSlaveFct Functions of the Keypad C Functions LinSlaveFct Example Sample6 (AL) Brief Description General Settings Functions of the Keypad Tips and Tricks Tips for Setting Parameters Tips for Generating and Download Tips on Display Tips on alternating between CANister Standard and CANister AL Tips on Switching Over from Configurator 2.x to Tips on Switching Over from Configurator 1.x to Glossary Appendix Overview of the Toolbar / Keypad Operation / Menu Toolbar and Using the Keypad The Help System...152

12 XII 10 Literature References Register of illustrations Summary of tables Index...157

13 1 1 Preparations The CANister Configurator is a product of Vector Informatik GmbH, Ingersheimer Strasse 24, Stuttgart, Germany. If you have questions or problems: Phone: +49 (0) , Fax: +49 (0) support@vector.com, Internet: System Requirements The CANister Configurator an CANister Assistant run on IBM-compatible computers with Pentium III or higher At least 256 MB RAM Screen resolution of at least 800x600 Operating system: Windows XP SP2 and higher / Vista (32 bit) / 7 (32 bit, 64 bit) Note: Installation of CANister Configurator and CANister Assistant requires administrator rights. 1.2 Copy Protection The software is copy protected by a USB license dongle. The dongle must be connected to the USB port, otherwise the following message is displayed: Error 7: Hardlock for CANister Configurator not found on the USB port. Hardlock für CANister Configurator wurde am USB Port nicht gefunden. The licensee is authorized to make one (single) backup copy. The licensee agrees to make note of the copyright of Vector Informatik GmbH on this copy. It is expressly prohibited to make additional copies and/or to convey the software to third parties. The terms of the Contract conditions for consent to use and maintain application programs of Vector Informatik GmbH must be observed. The delivered software has been provided with a license number and a text entry to identify the licensee. You can also display this information with the menu item Help About. The licensee must exercise due caution to ensure that no unlicensed copies are made from his or her copy. If the licensee becomes aware that such a copy is being used by a third party, he or she agrees to prevent the situation from continuing immediately or to bring the matter to the attention of Vector Informatik GmbH. Otherwise, the licensee is liable to Vector Informatik for damages thereby incurred. 1.3 Installation of the Software Please observe the terms of the Contract conditions for consent to use and maintain application programs of Vector Informatik GmbH. A USB dongle is included with delivery of CANister Configurator. The USB driver is automatically installed during installation of the software if necessary.

14 2 Please note, that the USB dongle must not be plugged before the installation of the USB driver. The installation of the USB driver could last for any length of time (up to max. 4 min). Start the program.\setup\setup.exe on the CD. Follow the instructions of the installation program. By default, the installation program will create the directory C:\Program Files\CANister on your hard drive. This directory will in turn contain sub-directories including COMMON and EXEC. You can find the examples here: C:\ Documents and Settings\All Users\Documents\Vector\CANister\3.0_SP5\Samples. The Start menu will contain the new entry CANister Configurator with the items CANdb Editor CANdb Editor Help CANister Manual CANister Configurator CANister Configurator Help CANister Configurator Manual CANister Configurator Sample (Hardware Test) CANister Configurator Sample (Timer) CANister Configurator Sample (CAN) CANister Configurator Sample (LIN Master) CANister Configurator Sample (LIN Slave) CANister Configurator Sample (AL) Readme Deinstallation of the Configurator You can start the CANister Configurator with the menu item CANister Configurator. Additionally, the CANdb++ Editor is available on the CD. Start the program.\candb++standard\setup.exe and follow the instructions of the installation program.

15 3 2 Introduction The CANister Configurator software package is a programming tool used to set parameters for CANister hardware. Networking of vehicle electronics by CAN and LIN requires new tools for production and testing areas. Frequently, electric motors can only be driven by a controller and consequently only by CAN and LIN. In addition to the actual adjustment commands, this also involves management functions such as variant coding and network management. These requirements have led to the development of the CANister. The CANister 3.0 contains, in a compact housing, the Siemens 80C167 microcontroller, Flash EPROM and RAM. The supply voltage may lie in the range of 8V to 32V. The interfaces include two channels with sockets for piggyback boards to permit adaptation to different physical layers. Additionally, there is a serial RS232 port. For driving conventional actuators CANister also provides eight digital outputs and two PWM outputs. CANister is controlled by keys or digital inputs, and it has an LED display. Additionally four analog inputs are available as control inputs. The CANister Configurator, a PC program, is provided for programming CANister. Among other things, it defines which actions should be performed in response to a key press or change of a control input. For example a CAN message can be sent out in response to a key press, or a LED can be set when a CAN message is received. In parameterizing the CANister, data from the CANdb database are used. These data include symbolic names for messages and message signals as well as attributes for transmission types and the control of network management. With this interrelationship to CANdb, the CANister is fully integrated in the toolbox that includes CANoe and CANalyzer. As a result, information from CANdb can be used consistently from development to production. CANister functionality can be expanded by the use of modules written in C. The functions of the system software are available for this purpose.

16 4 2.1 Compatibility Firmware must be used which is suitable for the specific versions of the CANister Configurator and CANister hardware; otherwise the generated configurations will not be executed properly in CANister. Possible combinations are shown in the following table. CANister Firmware CANister Configurator User functions Version 1.x Version 1.x used / not used Version 2.0 / 2.0.x Version 1.x used / not used Version 2.0 / 2.0.x Version 2.1 Version 1.x not used Version 2.0 / 2.0.x Version 2.1 used Version 3.0.x Version 3.0.x used / not used 2.2 Programs for CANister The following CANister products are available: Feature Configurator Assistant Demo Create configuration Yes Yes Yes Load configuration (*.csk,*.cbc,*.lkg) Yes Yes Yes Save configuration Yes No No Edit configuration Yes Yes Yes Generate documentation Yes No No Generate C header/code Yes No No Compile Yes No No Generate Yes No No Download Yes Yes No Download firmware Yes Yes No Download configuration Yes Yes No CANdb Editor Yes Yes Yes About hardware Yes Yes No CANister Terminal Yes Yes No

17 5 2.3 CANister Variants CANister is a flexible and freely configurable CAN and LIN node for the production and testing environment. The hardware module is event oriented, and actions can be assigned to multiple events. The CANister is available in three variants: CANister HL (high-speed & low-speed) and CANister LinL (LIN & low-speed) with a variety of connectors for the fast usage as well as CANister AL (assembly line) with relay and for customized cord set. Variant CANister HL CANister LinL CANister AL HL CAN/LINpiggy CANpiggy 251 CANpiggy 1054 LINpiggy 6259opto 1 CANpiggy 1054 CANpiggy 251 CANpiggy 1054 Connectors All connections to housing: D-SUB for download, CAN, inputs and outputs, 3-pin plug for voltage supply. To housing: D-SUB for download. On IO-Piggyback: Terminal strip for CAN, inputs and outputs, flat contacts for voltage supply. PWM outputs Yes No Relay No Yes Housing 185x106x32 mm 185x106x42 mm Table 1: CANister Variants For configurations in the CANister Configurator, the CANister HL and CANister LinL variants are organized under the name CANister Standard. For further information on the respective variants, please refer to the CANister Manual. 1 In future it is replaced by LINpiggy 7269mag

18 6 2.4 Functional Overview The CANister Configurator contains the following scope of functionality: User interface Display Action Generating / Download Databases Messages Baudrate About hardware Terminal File format Open multiple configurations Switch between loaded configurations Different arrangements of windows Toolbar Representation in overview with tree display and table in the main window Settings for configurations made by tables All single configurations in a single window Total view of all single configurations Parameters set with tables Set and delete multiple LEDs in a single dialog box (graphical display) Set multiple digital outputs in a single dialog box (graphical display) Disable and enable multiple keys in a single dialog box (graphical display) Switching for values: decimal / hexadecimal Automated, can be followed by download Download configuration Download firmware (standard and bootstrap mode) Multiple databases / Single configuration Transmit and receive simultaneously on 2 buses A channel is allocated to each database Network nodes (and thereby station address) for network management Start CANdb Editor from Configurator CAN: 11bit (STD) and 29 bit (XTD) IDs are supported LIN: Basic implementation (LIN specification V1.3, V2.0 and V2.1) Baudrate (bit timing register) can be adjusted with a dialog box Dialog box with display of CANister information, even during CANister operation (as long as the RS232 cable is not previously assigned) Dialog with display of CANister data that are sent over the serial port New format (everything in one file), but downward compatible

19 7 2.5 LIN Support The CANister supports a basic implementation of the LIN specification V1.3, V2.0 and V2.1. The following table shows the functions. Function Version 1.3 Version 2.0/2.1 Master Yes Yes Slave Yes Restricted Schedule table with timer Yes Yes Baudrate (1.2, 2.4, 4.8, 9.6, 10.4, 19.2, 20kBaud) Yes Yes Version specific checksum Yes Yes Import DBC Yes Yes Import LDF Yes Yes Diagnostic Restricted Restricted Error detection No No Automatic bit rate detection No Detection collision No Node configuration (Master) Restricted Node configuration (Slave) No Unconditional frame Yes Yes Sporadic frame No Event triggered frame No Diagnostic frame Restricted Mixing LIN 1.3 and LIN 2.0/2.1 frames No Table 2: LIN Support

20 8 2.6 Quick Start This section contains a brief introduction to the CANister Configurator. It assumes knowledge of how to create configurations with Configurator Version 1.x or 2.x. The following points are developed: Loading a configuration (new format) Loading an old configuration (LKG file or CBC file) New configuration Creating a total configuration Settings for single configuration New single configuration Generating Download configuration Download firmware Detailed display / total view Options dialog About hardware Copy / Paste Drag and Drop CANister Terminal Online help Loading a Configuration (New Format) Three examples in the new file format are included with delivery. You can find them in the sub-directory.\samples. Open the examples with the menu item File/Open. To do this, select the type *.CSK Loading an Old Configuration (LKG or CBC File) You can open configurations that were created with the old Configurator Version 1.x or 2.x by choosing the File/Open menu command. This involves selecting the *.LKG or *.CBC type New Configuration You can use the File/New menu item to create a new total configuration that has a single configuration with the name New. In the tree view in the left area, all necessary entries have already been made to allow you to make general settings and parameterization of events. Please note that the tree view cannot be edited. As soon as you click on a node in the tree view, a table corresponding to the selection of the node appears in the right area. If they can be activated, boxes in this table are activated by double-clicking on them. When the box is activated, the background changes to white.

21 Creating a Total Configuration Settings A comment can be entered for the total configuration. The comment is not carried over into CANister during download. The physical layer (for example Highspeed, Lowspeed, Single Wire, Truck & Trailer, LIN) can be specified for each channel. The default settings for baudrate must be tested. To change the CAN baudrate, click on the button in the table for the desired channel. Now change the baudrate in the dialog box (rate always indicated in kbaud) and then click on the Calculate bus timing register button. Then exit the dialog box with OK. For LIN, you can choose between pre-defined values Single Configurations The name of the single configuration can be changed here. The fields for version and comments serve only to display the entries from <Single configuration>/settings. A new single configuration can be created by double-clicking on the lowest box that is listed in the Name column and then entering the name of the new single configuration there. After you have exited the box, the new single configuration is automatically created. A new single configuration can also be generated by copying an existing single configuration (see Section ) and then pasting it by clicking on the lowest box of the Name column Settings for Single Configuration General settings are first made for each single configuration. After this, actions are added and parameters are set for them. The following procedure is recommended Settings Enter the version and the comment. Both pieces of information will be loaded into CANister during the download. If you are using C functions, you can specify the name of the C module here in which the C functions are implemented. The default name specified is function. You can always change this name if the Makefile and C module are not present. The Makefile will be created if necessary during the generation process with the setting C header/ code. An existing Makefile, however, will not be overwritten. Using the button, you can open the C file with a default editor. The prerequisite for this is that the Makefile and C module must exist Databases Select a database with the button. Assign the channel for which this database will apply to the database. If messages are to be transmitted and/or received on CAN1 and CAN2, you will generally need to select two different databases.

22 10 If the entry for network management is present in the database, the following boxes will be activated. In the NM column, mark the checkbox if network management is to be started with an action. Now select the network node, of which network management of CANister is to be simulated. The station address will be determined from the database by means of the network node and cannot be edited Receiving Nodes After you have selected the database, mark the receiving nodes (control units) that will be connected to CANister Cyclic Messages After you have selected the database, next select the cyclic CAN messages that are to be started or stopped in connection with the action Start/stop cyclic messages. The list of messages is now displayed if receiving nodes have previously been selected. The cycle time is derived from the database and cannot be edited Schedule Table All relevant data for the Schedule tables are taken from the LIN database and are shown at the Schedule table node. If a LIN Master was set up for the configuration, the user can have the Schedule table generated automatically in the form of timers and Send message actions by selecting the checkbox in the Generate column. After the checkbox is activated a dialog appears in which the user chooses whether the specific LIN message should be sent out as just a header, or as a header with data. The name of each generated timer is composed of the name of the Schedule table, the name of the message (Frame) and the Slot ID. The generated timers are added at the Definitions Timers and Events Timers nodes Definitions The following definitions can be made: Definitions Settings Adjustment to tree view Timer Name and type Yes (events/timer) User events Name Yes (events/user event) User constants Name and value No User functions Name No Serial command Name and value Yes (events/serial command) Signal check Name, operator and value Yes (events/signal check) Entries of timers, user events, signal checks and serial commands automatically cause the tree view to be adjusted under the Events node. A separate event is created for each definition.

23 Events After you have double-clicked on the Events node, a list of all available events appears. In some cases, an additional list is assigned to the individual events (for example Key Key 1 pressed, etc.) Set parameters for the actions as follows: Click on an event. Open the combo box in the table and select an action from the list. Depending on the action, different fields will be displayed. These fields can be used to set parameters for the action in question. The warning icon at the beginning of the line continues to be displayed as long as any inconsistencies are present, for example not all parameters are set for the action or invalid settings are displayed. Please note that the generation process (see Section 2.6.6) cannot be performed as long as any inconsistencies are present. For the events Message transmitted, Message received those messages for which there will be a response are first selected for the database. These are messages to which actions can be assigned, and moreover, during the generation process, handles are created in C functions for access to these messages by means of C header/ code. The selected messages are inserted in the tree view under the database. Actions can now be assigned to them. Under the node Events/Timers, timers that were entered under definitions are displayed. Each new entry under Definitions/Timers is automatically added to the timer list. The procedure is the same for user events, signal checks and serial commands Generating To generate download files, select the menu Generate/Generate If no Tasking compiler is present (see settings in the Option dialog, Section ), the checkboxes C header/code and Compile appear in gray in the Configuration tab. In this case, mark the Generate checkbox. In addition, mark the Download checkbox if the download is to take place immediately after generation is successfully complete. The download can always take place separately. The single configuration for which the generation process shall be executed can be selected. If you integrate C functions and would like to compile with the Tasking compiler, mark C header/code and click on Start. The Configurator generates the C file with the function list and the H file with handles for messages in the directory.\<name of total configuration>\<name of single configuration>. Furthermore, the C module for the code of the previously-defined C functions is created if neither the C module nor the Makefile are present. The Configurator creates the Makefile if it does not exist. To compile the C code with the Configurator (mark the checkbox Compile), a makefile must be present in the directory named above Download Configuration The menu path Generate/Download configuration can be used to bring up a dialog box with which you can load configurations. If a configuration has already been opened, its single configurations already appear as preselections. They can be loaded one after the other with the Start button. You can add Hex files of any configuration to a list with the setting Hex files without configuration. This selection is useful

24 12 if only the Hex files of a configuration are present and the configuration files themselves are missing. You can run the download here with the Start button Download Firmware Load the new firmware before the first download of a configuration Configurations that were created with CANister Configurator 3.0 require the new firmware Version 3.0. Start the download with the menu path Generate/Download firmware. Now select the Standard variant (CANister already contains the firmware). The Bootstrap variant is required for the first-time download, for example. In this case the Bootbox must be plugged into CANister. Next select the file CCFM_?F.HEX with the File... button. It was copied into the EXEC directory during the installation. Now click on Start. The progress of the download is displayed. After a successful download CANister shows a running light above the upper sixteen LEDs Detailed View / Total View The Display menu can be used to switch back and forth between a detailed view and a total view. No data can be edited in the total view. To obtain a better perspective in the Overall view the following options can be set from the View/Total view options menu: All: The entire configuration is displayed as a table. Definitions: Only the definitions of the configuration are shown. Events and Actions: Only the events and actions of the configuration are shown. Current Configuration: This must be selected in the tree view for an overview of a specific configuration. It should be noted that when selecting the entire configuration in the tree all configurations are shown. This is also true if this option is not activated Options Dialog Before you load an old configuration of the CANister Configurator 1.x (LKG file) or generate a download file for the first time, the following setting must be made in the Options dialog box, which you can bring up with the menu path File/Options: Indicate in the Tasking tab whether you have installed the Tasking compiler. If this is the case, the directory of the file mk166.exe of the Tasking compiler must be specified. It is located in the directory <Tasking Directory>\BIN. You can make the selection with the File button. To be able to read an old configuration (*.lkg) correctly, the file CANBOX.INI of the Configurator 1.x must be present. Now select the tab Compatibility. If you will be us-

25 13 ing a single file CANBOX.INI for all old configurations (*.lkg), select the option Global INI file. Now use the File button to select the directory in which the INI file is located. If you will be using different INI files for your configuration because of different settings, select the option Local INI file and copy the appropriate INI file into the directory of the LKG file. If the file CANBOX.INI cannot be opened when an old configuration is being read, the default setting for baudrate and system constants will be used. In this case, check the settings for this parameter after opening the configuration and change it if necessary About Hardware Information about the firmware and configurations that are loaded can be read from CANister and displayed as long as CANister contains the new firmware Version 3.0. The computer must be connected to CANister's RS232 port using a 1:1 RS232 cable Copy / Paste The CANister Configurator makes the Copy and Paste actions available for you. You can copy either using the tree view or from the table. Depending on the type, the data can be pasted within one or between more than one single configurations and/or into another configuration window. You should note that data can only be pasted into places where it would make sense to do so. Thus you cannot paste timers into user constants, for example. You can recognize invalid pasting by the fact that when you bring up the context menu, the Paste command appears in gray. There are various options available for performing the actions of copying and pasting after selecting the data to be copied: Bring up the context menu with the right mouse button and select copy or paste Use the keystroke combinations <Ctrl>+C for copying or <Ctrl>+V for pasting With the menu items Edit/Copy or Edit/Paste Use the buttons in the toolbar Drag and Drop You can copy data by selecting a node in the tree view and then, while the mouse button is held down, moving this node to another node (for example into another single configuration). After you release the mouse button, the data is pasted at the selected location. If you let the mouse pointer rest on a node for which pasting is not permissible, an icon of a circle with a diagonal line through it appears in addition. Releasing the mouse button on a node identified in this manner does not result in any data being pasted in CANister Terminal The menu item Tools/CANister Terminal opens a dialog which displays data that CANister outputs over the serial port. The user selects from the menu whether the data are sent by the Master or the Slave.

26 14 For outputs from the Master the Bootbox must be plugged in, and the computer's COM port must be connected to this Bootbox. For outputs from the Slave the COM port must be connected to CANister's RS232 port. The output can be stopped and restarted using the Connect/Disconnect buttons. The window contents are cleared by pressing the Clear button. It is also possible to display data in Hex format. The dialog may be used, for example, for computer display of information that was sent by a C function over the serial port. Additionally, if CANister exhibits faulty behavior that information is shown in this dialog. For further information please refer to section 3.11 CANister Terminal Online Help Information on how to use the CANister Configurator can be called up from the Help/Contents and Index... menu item. It is also possible to press the F1 key to have direct information displayed on whatever has been selected by mouse pointer. 2.7 Switching over from CANister Configurator 2.x to 3.0 When switching over from Configurator 2.x to Configurator 3.0 the following points should be observed Loading a *.cbc Configuration The CANister Configurator can load files of Configurators 2.x which have the *.cbc filename extension from the File/Open... menu item. In doing so, the *.cbc type must be selected in the opening dialog. Afterwards the configuration can be saved under the new format with the *.csk extension. It is not possible to save an old configuration with the *.cbc extension. After loading the configuration, the CANister variant has to be adjusted for <Total configuration/single configuration>. Figure 1: Loading a *.cbc configuration

27 15 Note: The microswitch event is no longer supported. The action Relay is only available with the CANister AL User functions The structures of the CAN messages were modified to permit processing of extended identifiers. Therefore in the configurations of Configurators 2.0 all uiidentifiers must be renamed to ulidentifiers. 2.8 Switching over from CANister Configurator 1.x to 3.0 When switching over from Configurator 1.x to Configurator 3.0 the following points should be observed Download With the CANister Configurator 3.0, the download takes place entirely with the graphical user interface. Previously, the download was performed with the aid of separate programs such as KONFASSI.EXE, FIRMASSI.EXE or BOOTASSI.EXE. In the CANister Configurator 3.0, the download is performed with the Generate/Generate... menu or with the button. The following dialog box, Generate/Download, contains three tabs Configuration, Firmware and Hex files. These can be used to select the download. Figure 2: Download You can find additional information in Section 3.9 Download.

28 Loading a *.lkg Configuration The CANister Configurator can load files of Configurators 1.x with the *.lkg filename extension using the File/Open... menu item. In doing so, the *.lkg type must be selected in the Open dialog. Afterwards the configuration may be saved under the new format with the *.csk extension. It is not possible to save an old configuration with the *.lkg extension. When loading a LKG file a CANBOX.INI file should exist (see Section INI File) After loading the configuration, the CANister variant has to be adjusted for <Total configuration/single configuration>. Figure 3: Loading a *.lkg configuration Note: The microswitch event is no longer supported. The action Relay is only available with the CANister AL INI File Previously, different settings were made with the file CANBOX.INI. In CANister Configurator 3.0, all settings are edited directly with the aid of the Configurator.

29 17 Figure 4: Download options The file CANBOX.INI is required when LKG files are being imported. Under the Compatibility tab you can adjust whether the INI file is always present in the directory of the LKG file (Local INI file checkbox) or is present globally (Global INI file checkbox). If only one INI file was used for all previously created configurations, the checkbox setting Global INI file can be selected for the import. In all other cases, the INI file in question should be copied into the directory of the LKG file and the setting Local INI file should be selected. You can find additional information in Section 3.2 Options User Functions With the Configurator 1.x it was possible to freely define the name of the C header, C codes and the generated Hex file. This is now no longer possible. Instead, the names of files are determined as follows: Header: USERCFCT.H C code: USERCFCT.H Hex file: USERCFCT.HEX The name of the C module in which the specific C functions are implemented is still identified by the keyword CFILE in the makefile. You can find additional information in Section Makefile. The generated files for single configurations are created in the subdirectory with the name of the single configuration. In the C module a modification must be made for all message defines, since now one database may be assigned to both CAN1 and CAN2, and the defines are now named differently in usercfct.h.

30 18 Before: CAN_RX_MESSAGE Now: CAN1_RX_MESSAGE or CAN2_RX_MESSAGE The structures of the CAN messages were changed to permit processing of extended identifiers. Therefore all uiidentifiers must be renamed to ulidentifiers. 2.9 CANister Assistant The CANister Assistant is an abbreviated version of CANister Configurator. No configurations can be saved in this version. However it is possible to download configurations or the firmware. This version may be used, for example, to load applications into CANister which were created as project jobs by Vector Informatik GmbH. The following Configurator functions are activated in the Assistant: Load and import file (for display) Modify configuration Options Download firmware Download configuration (Hex files) All display options Start CANdb Editor All window functions Read out hardware information CANister terminal Help The following functions of the CANister Configurator are deactivated in the CANister Assistant: Save a configuration Generation documentation Generate process

31 19 3 Basic Principles The CANister Configurator is capable of administering any number of total configurations simultaneously. A total configuration is composed of the general settings and a maximum of sixteen single configurations. A Hex file is generated from each single configuration for which parameters have been set during the generation process. This file is loaded into CANister and is capable of running there. As many as sixteen single configurations can be loaded into CANister. It is possible to switch back and forth between these by triggering an event. CANister runs in an event-oriented manner. Actions such as Transmit message or LED 1 on can be triggered in response to events such as Key 1 pressed or Message received. The main part involved in creating a configuration has to do with this assignment of events and actions. The event-oriented nature of a configuration is an important difference distinguishing it from common programming languages, which work linearly or recursively. For this reason, we don t speak of programming, but rather of parameterization of actions. CANister Configurator Generating Configuration 1 Configuration 2... Download Firmware Download Configuration RS232 RS232 CANister CAN bus Configuration n About Hardware RS232

32 Overview CANister runs in an event-oriented manner. There follows a list of possible events and actions that can be initiated. Multiple assignments between events and actions are possible. In other words, an event may trigger more than one action, and an action may be initiated by different events. For more specific details on events and actions, see Section 3.5 Events and Section 3.6 Actions List of Events The response to the events can be programmed by the user: On Start CAN connect CAN disconnect Press/release key Change on the digital input Message transmitted Message received Timer elapsed User-defined event Serial command Signal check Figure 5: Events

33 List of Actions The following actions can be initiated. CANister (all variants) Set/delete LEDs Transmit CAN message Set CAN message signal Start/stop cyclic CAN messages Transmit LIN message (header/header+data) Set LIN message signal Start/stop LIN communication Set/delete timers Execute user function (user C function) Disable/enable key Start/stop network management Digital output Change of configuration Signal check CANister Standard (CANister HL/LinL) Start/stop PWM output CANister AL Set relay (clockwise, counterclockwise, stop) The actions are explained in more detail in Section 3.6 Actions. Figure 6: List of actions

34 Function of the Interpreter A CANister application may be described as a table consisting of events and actions. When an event occurs, the interpreter is initiated. The interpreter searches for the actions that have been defined for the event that has been encountered. All events have a specifier (a 16-bit value) that describes the event in more detail. Multiple actions can be appended to each event. All events are first written to a buffer and then processed one after the other like the actions of an event. Figure 7: Interpreter 3.2 Options The options dialog box can be opened with the File/Options... menu. It consists of the three tabs Download, Tasking and Compatibility. Settings for download, the Tasking compiler and importing of old total configurations (LKG files) can be made in the dialog box Download All important parameters for communication between CANister and the computer can be set with this dialog box (Figure 8: Download options). The baudrate for downloading the firmware with the bootstrap loader can be adjusted in the range of 2400 baud to baud. After the installation, the rate is set by default at baud. The baudrate for downloading firmware in standard mode and for configurations cannot be modified and is fixed at a setting of 9600 baud.

35 23 Figure 8: Download options For a download the computer is connected to CANister over its serial port. The COM port for the download is automatically determined and set by the CANister Configurator. If the user wishes to suppress this and specify the COM port for the download in a fixed way for standard mode downloads or the bootstrap loader the COM port can be set in the INI file CANISTER.INI. Here the keyword DOWNLOAD_COMPORT_INI can be used for downloads in standard mode and the keyword BB_COMPORT_INI for downloads with the bootstrap loader on the specific port. If the bootstrap loader is to be used for a firmware download CANister must be connected to the PC via the Bootbox. In the dialog the user also configures the serial port (COM port) that should be used to operate the Slave Terminal (see section 3.11 CANister Terminal). The COM port for the Master Terminal is automatically determined by Configurator. The Bootbox must be plugged on CANister and be connected by a cable for this purpose Tasking This dialog box (Figure 9: Tasking options) is used to determine whether a Tasking compiler is present. The complete path and filename of the Tasking compiler must be specified here. The File... button can be used to open a dialog box with which the file MK166.EXE of the Tasking compiler can be selected. Also defined is the Tasking compiler version being used. If the Tasking compiler present checkbox is not selected, the two checkboxes in the Generate dialog box, C header/code and Compile, are generally deactivated.

36 24 Figure 9: Tasking options Compatibility This dialog box (Figure 10: Compatibility options) is used to specify the parameters for importing LKG files (Configurator up to and including Version 1.6). The file CAN- BOX.INI is required when LKG files are being imported. When selecting the checkbox Global INI file an INI file must be specified with the File... button which will then be used for each import. If the Local INI file checkbox is selected, the file CAN- BOX.INI must be present in the directory of an LKG file during import. This option should always be selected if different configurations have previously been created. If no INI file can be opened during the import of an LKG file, the default settings for baudrate and system constants are used. In this case, we urgently recommend that you check this setting in the CANister Configurator after the import is complete. Figure 10: Compatibility options

37 Total Configuration The following settings can be made for the total configuration: Settings: Setting for comments and CAN/LIN channels Single configuration: Pasting, deleting and renaming single configurations, etc Settings The user can enter a comment for each specific total configuration. The comment is not actually part of the configuration data that is loaded into CANister. Figure 11: Settings In addition, the physical layer and the corresponding baudrate can be adjusted (Figure 11: Settings) for the channels. The following physical layers are available for channels CAN1 and CAN2: Highspeed Lowspeed Single Wire Truck & Trailer LIN For further information on the hardware of the physical layer please refer to the CANister Manual included in the appendix of this document. The baudrate is adjusted separately for each physical layer. For CAN a convenient baudrate dialog box is available for this purpose. The desired baudrate can be entered in this dialog box in kbaud, after which the Calculate bus timing register button can be used to calculate the values for the bus timing register. It should be noted that the value in the Clock input field cannot be edited. For LIN, you can select predefined baudrates from a list. The value range of the baudrate depends on the selected physical layer. If the particular value range is not maintained, the baudrate is automatically limited to the minimum or maximum value. The CANister variants are also specified here. You can select between the "CANister Standard" and the "CANister AL" variants. The CANister HL and CANister LinL variants are organized under the name Standard. Depending on this setting, the action PWM output and action Relay are available.

38 Baudrate Dialog Box (CAN) All parameters related to the baudrate and bus timing can be entered or calculated in the CAN baudrate dialog box (Figure 12: Baudrate dialog box). Figure 12: Baudrate dialog box The quartz frequency is already adjusted in the baudrate dialog box. The quartz frequency always has to contain the value khz. This value may not be changed. The baudrate is entered in the Baudrate input box. Clicking on the Bus timing register button causes the values of the bus timing register to be calculated. If a baudrate is specified that cannot be adjusted directly with the bus timing register, the closest possible baudrate is suggested. Since there may be different settings for the bus timing register for a selected baudrate, depending on the sampling time, all possibilities are made available to the user in a list box.

39 27 The elements of the dialog box are now described individually in detail: Clock Frequency The clock frequency at which the CAN controller is operated is entered here. For additional information on this point, see the description of the CAN controller. Baudrate The desired baudrate is entered in the input box in kbaud as far as it will not be derived from the value of the bus timing register. Bus Timing Register The values of the bus timing register must be entered in hexadecimal format if they are not to be calculated from the baudrate. Calculate Baudrate The baudrate is calculated as a function of the specified values (quartz frequency and bus timing register values) by clicking on the Baudrate button. Calculate Bus Timing Register The values of the bus timing register can be calculated as a function of the specified values (quartz frequency and baudrate) by clicking on the Calculate bus timing register button. Since there are several combinations of the bus timing register values for one baudrate, the desired combination must be selected from the list box. Samples The number of possible sampling times can be specified here. For additional information on this point, see the description of the CAN controller. View You can switch back and forth between the bus timing view modes here. The information displayed provides a view of various data items that are calculated from the bus timing register. 3.4 Single Configuration The Configurator is capable of administering any number of total configurations. A total configuration can consist of as many as sixteen single configurations that can be loaded into CANister.

40 28 Figure 13: Single configuration It is possible to administer the single configuration in this node (Figure 13: Single configuration). They can be renamed, inserted, copied or deleted. A single configuration contains the following items for which settings must be made: Settings Databases Receiving nodes Cyclic messages Schedule table Definitions Events Clicking on a node in the tree view causes a table to appear in the right section, where the settings can be made. The structure of the table depends on the node selected Settings A version number with a maximum of seven characters and a comment with as many as 59 characters can be entered for each single configuration (Figure 14: Settings). This information is not absolutely required, but it is nonetheless recommended, since it will significantly facilitate version administration of configurations. This information is also read from CANister while running the Help / About hardware menu from CANister and is displayed in the About hardware dialog box (see Section 3.12 About Hardware). Figure 14: Settings The version and comments can be seen in the tree view under Total configuration/single configuration, but they cannot be changed there.

41 29 If C functions are used, you can specify the name of the file for C functions here. By default, the name function is entered. This name can always be changed if Makefile and C file are not present. During the generation process, the file for C functions is created as a template with the previously-defined C functions and the Makefile, insofar as the files do not exist yet. Using the button, you can open the C file if the Makefile and C file exist. Figure 15 contains sample code of the C file function.c with the template function initdata defined in the Configurator. Figure 15: Editor with file for C functions For LIN, you have to define the setting - whether CANister will function as the LIN Master or the LIN Slave. These setting have no effect on CAN. Depending on this setting, if you select the LIN Master, messages can be transmitted, if you select LIN Slave, only message signals can be set. The bus termination resistance is 1 kω for Master and 30 kω for Slave. Furthermore, you have to define, which basic implementation (see section 2.5 LIN Support) of the LIN specification V1.3 or V2.0/2.1 is used.

42 Databases A database is required if messages will be transmitted or if there will be a response to receiving them. A CAN database contains additional information on network management. The Configurator supports DBC databases for the CAN and LIN bus and LDF databases for the LIN bus. The following sections give an overview of how to work with databases Messages (CAN) All information on messages is stored in the CAN database (DBC). The CANister Configurator reads a number of items including the name of the messages and their signals, the identifier (standard ID or extended ID), the transmission type and in some cases the cycle times and the message type. Message attributes GenMsgSendType GenMsgCycleTime GenMsgNrOfRepetitions NmMessage Diagnose-Botschaft Description Transmission type of the CAN message Cycle time for transmission type cyclic and cyclic if active The number of repetitions of the transmission type spontaneously with repetition Indicates whether the message belongs to network management. NWMMessage is still supported. Specifies whether the message in question is a diagnostic message Table 3: Message attributes The transmission type of the messages is stored in the database in the message attribute GenMsgSendType. Not all possible transmission types are relevant for CANister, which means that complicated transmission types are depicted as simpler transmission types. The following provides a breakdown describing actual implementation. Attribute GenMsgSendType Description Implementation cyclicx cyclic cyclic cyclicandspontanx cyclic and spontaneous cyclic cyclicandspontanwithdelay cyclic and spontaneous with minimum delay cyclic cyclicifactivex cyclic if active cyclic if active cyclicifactiveandspontanwithdelay cyclic if active and spontaneous with minimum delay cyclic if active spontanx spontaneous spontaneous spontanwithdelay spontaneous with min. delay spontaneous spontanwithrepetition spontaneous with repetition spontaneous Table 4: Transmission type of messages

43 31 Messages can only be displayed in the Configurator if they were assigned one transmitter and at least one receiver assigned to a signal. Messages with the transmission type Cyclic if active are included with cyclic message, i.e. they are also affected by the action Stop cyclic messages. The action Start cyclic messages does not result in transmission for these messages until one of the signals takes on a non-zero value Message (LIN) All information on the messages is stored in the LIN database (LDF or DBC). Among others, the CANister Configurator reads out the names of the messages, their signals and the identifier. Messages can only be displayed in the Configurator if they were assigned one transmitter and at least one signal assigned a receiver Bus type In DBC databases via the database attribute BusType, a distinction is made between the CAN and LIN database. For LIN databases, the attribute BusType has to be assigned the name LIN Network Management CANister supports various versions of network management. The version that is actually used is customer-specific. The type of network management is determined in the database by the database attribute NWMType. The NWM address of the network nodes is determined by the NWMStationAddress node attribute. In newer databases the attributes NmType and NmStationAddress are used instead. The message attribute NmMessage identifies NWM messages. Attribute NWMType NmType NWMStationAddress NmStationAddress NmMessage Description Type of network management (database attribute). NWM-Typ can be used instead. The number of the control unit for network management (node attribute). NWM-Stationsadresse can be used instead. Indicates whether the message belongs to network management. NWM-Botschaft can be used instead. NWMMessage is still supported. Table 5: Attributes for network management

44 32 Note: The attribute NWMType is of type enumeration (enum) and is evaluated by the CANister Configurator based only on the order of the definition. The names do not play any role. Adding additional values may therefore cause confusion in the assignment. The given order is obligatory. If a database contains the attribute NWMType, CAN2 is automatically assigned as the CAN channel when the database is added, since the standard version of CANister has the Lowspeed piggyback plugged onto CAN2. However the other CAN channel can be selected if necessary Settings for the Database The button can be used to select a database. This database must now be assigned to a channel. For CAN databases which contain the attribute NWMType CAN2 is automatically assigned as the channel. If messages are to be transmitted and/or received on both CAN channels, you will generally need to select two different databases. If the entry for network management is present in the CAN database, the following boxes will be activated in the table. The button in the NM column must be marked if network management is to be started with an action. For marked network management, the network node of which network management will be simulated by CANister must be selected. The station address of the network node will be determined from the database and cannot be edited. Network management can only be selected for one CAN channel (Figure 16: Databases). Figure 16: Databases For LIN databases, there are no settings for network management. LIN databases can only be assigned one channel because the CANister can only support one LINpiggy. When assigning the channels, check whether the LIN physical layer was selected for the Total configuration Settings. The warning symbol displays whether this channel selection is missing. You can use the menu path Tools/CANdb Editor... or the button to start the CANdb Editor. The editor allows you to obtain information about a specific DBC database. The database can also be modified with the aid of the CANdb Editor. You will find a description of the CANdb Editor in the appendix to this manual. The display of LDF databases is not supported.

45 33 Figure 17: CANdb Editor Receiving Nodes A number of receiving nodes (control units) can be defined for each database that has been assigned to a single configuration (Figure 18: Receiving nodes). Receiving nodes are control units that are connected to CANister and from which messages can be received. The list of receiving nodes is derived from the database. Figure 18: Receiving nodes The selection of receiving nodes effects the list of cyclic and spontaneous messages, thereby in turn acting like a filter. If incomplete lists of messages are displayed when actions are being programmed, the list of receiving nodes must be checked Cyclic Messages All cyclic CAN messages that can be transmitted to the corresponding receiving nodes (control units) or that can be received from them are listed for the respective database. The cycle time that is entered in the database is displayed for cyclic messages. After cyclic messages have started, messages (Figure 19: Cyclic messages) marked in the list are transmitted periodically at the indicated cycle time. Figure 19: Cyclic messages

46 34 Note: Here, settings can only be adjusted for CAN databases, but not for LIN databases Schedule Table All relevant data for the Schedule tables are taken from the LIN database and are shown at the Schedule table node. Schedule tables with not supported frame types are not displayed. If a LIN Master was set up for the configuration, the user can have the Schedule table generated automatically in the form of timers and Send message actions by selecting the checkbox in the Generate column. After the checkbox is selected a dialog appears in which the user chooses whether the specific LIN message should be sent out as just a header, or as a header with data. The name of a generated timer is composed of the name of the Schedule table, the name of the message (Frame) and the Slot ID. The generated timers are added at the Definitions Timers and Events Timers nodes. In Figure 20 three Schedule tables of a LIN database are shown with their assigned messages, Slot ID and Delay time. Figure 21 shows an overall view of the generated timers and actions for the Schedule table named Polling Table. Figure 20: Schedule Table Figure 21: Total View Schedule Table

47 35 Note: Here, settings can only be adjusted for LIN databases, but not for CAN databases Definitions The functionality of the CANister Configurator is increased by user definitions. Figure 22: Definitions User can define their own timers, user events, user constants, functions, signal checks and serial commands. The definition of timers, serial commands, signal checks and user events automatically cause the tree view to be adjusted under the Events node. A separate event is created here for each definition. Any number of actions can be assigned to these events. Definitions Information Adjustment to tree view Timers Name and type Yes (events/timer) User events Name Yes (events/user events) User constants Name and value No Functions Name No Serial commands Name and value Yes (events/serial command) Signal checks Name, operator and value Yes (events/signal check) Table 6: Definitions There are applications (for example interpreting signals of messages received) for which the CANister Configurator does not have sufficient resources. For example, it is not possible to program conditions. In such cases, the functionality of the Configurator can be expanded by functions written in C. Functions, user constants and user events are required in connection with user C functions. Functions can be performed as an action. Programming of functions is described in detail in Section 4. C files are compiled with the C166 compiler from Tasking. This is not included with delivery of the CANister Configurator User Events User events defined by the user are events to which actions can be assigned, just like any other event. However, user events can only be initiated in a C function by the

48 36 library function cbsetuserevent() (see Section 4.11). All user events are defined in the CANister Configurator. Figure 23: Definition of a user event During the generation process (C header/code) user events are taken over into the header file USERCFCT.H, which must not be edited, with their symbolic name as a define (handle). The prefix UEVENT_ is placed before each name. This define is used in the library function as a parameter. Example: cbsetuserevent(uevent_ev_led_1) C files are compiled with the C166 compiler from Tasking. This is not included with delivery of the CANister Configurator User Constants It is a good idea to use user constants if values are required in C functions that may change in the course of the use of a configuration. User constants offer the advantage that they can easily be changed in the CANister Configurator so that the existing code in the C module remains unchanged. This approach is used especially if the configuration needs to be adjusted by users who do not have access to a Tasking compiler. Figure 24: Definition of user constants During the generation process (C code/header) user constants are taken over into the header file USERCFCT.H, which must not be edited, with their symbolic name as a define (handle). The prefix UCONST_ is placed before each name. This define is used as a parameter in the user C-library functions cbgetconstant() and cbsetcon-

49 37 stant() (see Section 4.11 API of User C-Library Functions) to set or read a user constant from the configuration. Example: cbsetconstant(uconst_max_for_led_1, 1 ) C files are compiled with the C166 compiler from Tasking. This is not included with delivery of the CANister Configurator Functions If applications requiring an extended range of functionality must be created, C functions can be defined and called as actions. C functions are freely programmable. It is possible to use the functionality of the firmware by means of user C-library functions (see Section 4.11 API of User C-Library Functions). Figure 25: Definition of functions During the generation process (C code/header) functions are taken over into the header file USERCFCT.H, which must not be edited, with their symbolic name as a prototype. In addition, the C file USERCFCT.C, which also must not be edited, is created with a function list. Users must write out their programs in a user-defined C module. Example: #include <userclib.h> //introduces the API functions #include "usercfct.h" //Prototypes!! #pragma class pr=userfunctions static uint8 u_const1; void initdata( void ) { cbsetuserevent(uevent_ev_function_started); u_const1 = cbgetconstant(uconst_max_for_led_1); } // end of initdata C files are compiled with the C166 compiler from Tasking. This is not included with delivery of the CANister Configurator.

50 Serial Commands Users can define their own serial commands and then respond to them as an event. The value range of serial commands is between 0 and 255. As soon as a command has been received via the serial interface, the corresponding command is initiated and the associated actions are performed. Figure 26: Definition of a serial command Serial commands are sent by the computer using a message with up to 251 bytes of effective data. Access to this data is possible by means of a pointer that must be specified with the user C-library function cbgetsiodataptr(). There is no direct handshaking over the V24 interface, i.e. the acknowledge of the serial event is transmitted immediately, and the evaluation of the serial data is not yet complete at that time. Each telegram consists of the following parts: Meaning Length Explanation STX = 0x02 1 byte Starting character Length 1 byte The number of characters after the length up to (but excluding) the check sum. Effective data bytes Effective or useful data consisting of the actual command and parameters. Checksum 1 byte The checksum is formed from the amount of effective data as the simple sum of the bytes without carry. Table 7: Telegram structure The effective data of the telegram is subdivided as follows: Meaning Index Length Explanation Command 0 1 byte Command for serial event: 0x50 Parameter bytes Serial command: Depends on the value for definitions Parameter bytes Additional data: The length and content can be freely selected. Table 8: Effective data of a telegram

51 39 CANister sends a short command as a response: ACK (0x06): NAK (0x15): Short response, no error Short response, an error occurred Meaning of a complete telegram of serial event no. 1: Byte Value Meaning 0 0x02 STX, start of the telegram 1 0x03 Length of the effective data 2 0x50 Command Initiate a serial event 3 0x01 Serial event 1 (low byte) 4 0x00 Serial event 1 (high byte) 5 0x51 Checksum Timer Time processes are implemented by timers. After the timer has elapsed, the event assigned to it is initiated. A timer can be set as cyclic or single. The amount of time until a timer goes off is indicated in milliseconds when setting parameters for the action Set timer. Deleting timers that are not set has no effect. Timers that are sent but which have not yet elapsed should not be deleted before they are reset. The CANister supports up to 255 timer. Figure 27: Definition of a timer

52 Signal check The check of signal values or ranges are implemented by signal checks. If the signal check condition is complied, the event assigned to it is initiated. Figure 28: Definition of signal check Following operators can be used for a check: Operator Description Sample [ ] Signal inside the range A <= Signal <= B ] [ Signal outside the range Signal < A OR Signal > B == Signal equal value Signal == A!= Signal unequal value Signal!= A >= Signal greater or equal value Signal >= A <= Signal less or equal value Signal <= A 3.5 Events CANister runs in an event-oriented manner. Events to which a response is possible are listed for each single configuration in the tree view. They will now be described in detail. Any actions at all can then be performed for each event Start The event is initiated each time the single configuration starts. A single configuration is started when the hardware is turned on and when the configuration is changed. Just as for any other event, actions can then be performed.

53 CAN Connect This event can only occur in combination with the start of network management. It is initiated if network management is started and a connection to at least one control unit can then be established with network management. Just as for any other event, actions can then be performed CAN Disconnect This event can only occur in combination with network management. It is initiated if network management is started and no connection to a control unit can then be established with network management, or if the connection is broken. Just as for any other event, actions can then be performed Keys Two events can occur for each of the sixteen keys. Key n pressed and Key n released. These events are initiated only after the keys are enabled. Keys are disabled and enabled by means of actions. It should be noted that keys are disabled by default. Just as for any other event, actions can then be performed Digital Input Two events can occur for each of the eight digital inputs. Digital input n High->Low and Digital input n Low->High. These events occur only at the change of a signal edge. C functions offer the possibility of determining the status of all digital inputs simultaneously by means of the user C-library function cbgetinput() (see Section 4.11 API of User C-Library Functions). Just as for any other event, actions can then be performed Message Transmitted This event is initiated if a CAN or LIN message has been sent successfully. In the tree view, this node contains the databases of the single configuration as additional nodes. The messages that can be transmitted by CANister are displayed in the table view for these databases. This list depends on the receiving nodes selected. The messages whose transmission will result in a response or which will be transmitted in C functions must be marked. The selected messages are automatically inserted into the tree view as nodes. Just as for any other event, actions can then be inserted here. Figure 29: Message transmitted

54 Message Received This event is initiated if a CAN or LIN message has been received successfully. In the tree view, this node contains the databases of the single configuration as additional nodes. The messages that can be received by CANister are displayed in the table view for these databases. This list depends on the receiving nodes selected. The messages whose reception will result in a response or of which the data will be interpreted in a C function must be marked. The selected messages are automatically inserted into the tree view as nodes. Just as for any other event, actions can then be inserted here. There is only a response to receiving a message for this event. No evaluation of the signals can take place at this spot. User C functions are required for this (see Section 4 Programming User C Functions). Figure 30: Message received Timer This node contains a separate event with timer names for each timer that has been defined in the single configuration (see Section Timer). The event is always initiated when the associated timer has elapsed. A timer can be set simply or cyclically. Just as for any other event, actions can then be inserted here. Figure 31: Timer User Events This node contains a separate event for each user event that has been defined in the single configuration (see Section User Events). User events can only be initiated by user C functions. Just as for any other event, actions can then be inserted here.

55 43 Figure 32: User event Serial Command This node contains a separate event for each serial command that has been defined in the single configuration (see Section Serial Commands). It is always initiated when the corresponding command has been received through the serial interface. Just as for any other event, actions can then be inserted here. Figure 33: Serial command Signal check This node contains a separate event for each signal check that has been defined in the single configuration (see Section Signal check). It is always initiated when the corresponding condition for the signal check is complied. Just as for any other event, actions can then be inserted here. Figure 34: Signal check 3.6 Actions More than one action can be assigned to an event. The action list can be displayed for the corresponding event by selecting it in the tree view of the associated nodes.

56 44 The actions will be displayed as a table in the right section of the configuration window. Parameters can also be set for actions in this table. The following illustration shows all actions with their parameters. Figure 35: Actions If the warning icon is displayed at the beginning of the line for an action, incorrect parameters have been set. Possible causes include missing parameters, for example. In addition, invalid parameters may occur, especially if databases have been modified LED LEDs can be turned on or off with this action. CANister has 20 freely programmable LEDs: 16 green LEDs (LEDs 1 to 12 and 17 to 20) and 4 red LEDs (LED 13 to 16). Figure 36: Action: LED You can call the following dialog box for setting parameters of LEDs by clicking on the... button in the second column: The LEDs of CANister are shown in the dialog box. The status of a LED can be switched by clicking on the corresponding button. Switching always takes place in the same order: On (bright green or bright red) Off (dark green or dark red with cross) Unchanged (gray)

57 45 Figure 37: LEDs Keys You can enable or disable keys with this action. To be able to respond to the event Key pressed or Key released, the keys must be enabled. Keys can be disabled to prevent functions from being initiated erroneously. This can make it impossible for the signals Window up and Window down to be set simultaneously in a message, for example. Figure 38: Action: Keys

58 46 You can call the following dialog box for setting parameters for the keypad by clicking on the... button in the second column of the action (Figure 38: Action: Keys): Sixteen keys are depicted in the dialog box. The status of a key can be switched by clicking on the corresponding key. Switching always takes place in the same order: Enable key (green) Disable key (red with cross) Key unchanged (gray) Figure 39: Keys Timer This action can be used to set or delete a timer (Figure 40: Action: Timer). You can select the timer with the list in the second column of actions. If this list does not contain a timer, no timer has yet been defined in the current single configuration. In the third column, you can select whether the timer should be deleted or set. For timers that are set, the cycle time is entered in the fourth column in milliseconds. This entry is not possible for timers that have been deleted. Figure 40: Action: Timer

59 User Function User functions can be started with this action. You can select which function (Figure 41: Action: User function) should be started in the second column of the action. If this list does not contain a function, no user function has yet been defined in the current single configuration. User functions can only be integrated if Tasking compiler is present or if the C functions are already available, compiled in Intel Hex format. All user functions must be programmed by the user in C so that they can be compiled with the Tasking compiler. Programming of C functions is described in detail in Section 4. Figure 41: Action: User function Transmit Message (CAN) This action can be used to transmit CAN messages with transmission type spontaneous (see Section Messages). The database in which the CAN message is defined can be selected in the second column of the action (Figure 42: Action: Transmit CAN message). If this list does not contain any database, no database has yet been added to the current single configuration. A database can be added with the node Single configuration / database. The CAN message to be transmitted can be selected in the third column. The list of messages here depends on the receiving nodes selected and on the transmission type of messages in the database. Of all the messages of the database, only those spontaneous messages that are received by one of the selected receiving nodes (control units) are available. If the list does not contain any messages, the list of receiving nodes and the message attributes should be checked. Figure 42: Action: Transmit CAN message Set Message Signal (CAN) Signals of CAN messages can be set with this action. The database in which the CAN message is defined can be selected in the second column of the action (Figure 43: Action: Set message signal). If this list does not contain any database, no database has yet been added to the current single configuration. A database can be added with the node Single configuration / Database. The CAN message containing the signal can be selected in the third column. The list of messages depends on the receiving nodes selected and on the database. Of all

60 48 the messages of the database, only those messages that are received by one of the selected receiving nodes (control units) are available. If the list does not contain any messages, the list of receiving nodes and the message attributes should therefore be checked. If the user selects a cyclic message which was not selected for the node under Cyclic messages then this message is also sent with the action Start cyclic messages. The signal can be selected in the fourth column. The list contains all signal names that have been defined for the selected CAN message in the database. The value of the signal is then entered. It is taken over directly into the CAN message. The physical value must not be entered, since no conversion of that value will take place in the database according to the specifications. When you are entering the value, make certain that signals have different lengths and thus different maximum values. Figure 43: Action: Set message signal (CAN) Transmitting the CAN message in which a signal has been set depends on their send protocol. For transmission type Spontaneous, transmission of the CAN message must be explicitly initiated after the message signal is set. For transmission type Cyclic, transmission is initiated by the action Start cyclic messages. For messages with transmission type Cyclic if active, setting a signal to a non-zero value results in transmitting this message as long as cyclic messages have previously been started. For additional information on the transmission type, please see Section Messages LIN communication (LIN) This action addresses LIN communication. In the second column, select the status which communication should be switched to. Figure 44: Action LIN communication Transmitting messages (LIN) This action transmits LIN messages. In the action's second column, select the database that defines the LIN message. If this list does not contain any databases, no database was added to the current single configuration. For node Single configuration/database, a database is added. In the third column, select the LIN message to be sent. The list of messages depends on the receiving nodes selected. Among all the messages selected in the database,

61 49 only those messages are available that are received by one of the selected receiving nodes (control units). If the list does not contain any messages, the list of receiving nodes has to be reviewed. In the fourth column, select the type of LIN message. It can be transmitted both as a header (Figure 45: Action Transmit message (LIN Header)) as well as a complete message, meaning header with the data (Figure 46: Action Transmit message (Header+Data)). LIN messages can only be sent if the CANister was set as a LIN Master. Figure 45: Action Transmit message (LIN Header) Figure 46: Action Transmit message (Header+Data) Set Message Signal (LIN) This action sets signals from LIN messages. In the second column, select the database in which the LIN message is defined (Figure 47: Action Set message signal (LIN)). If this list does not contain any databases, it means that no database was added to the current single configuration. A database is added for node Single configuration/database. In the third column, you can select the LIN message that contains the signal. The list of messages depends on the selected receiving nodes and the database. Of all database messages, only those messages are available that are received by one of the selected receiving nodes (control units). If the list does not contain any messages, the list of receiving nodes as well as the message attributes has to be reviewed. The signal is selected in the fourth column. The list contains all signal names that were assigned to the selected LIN message in the database. Lastly, enter the signal value which is directly adopted in the LIN message. The physical value may not be entered because no conversion takes place in the database according to the specifications. When entering the value, make sure that the signals have different lengths and therefore also different maximum values. Figure 47: Action Set message signal (LIN) If you adjust CANister as a LIN Master, you have to specifically prompt transmission of the LIN message in which the signal was set. If CANister is set as a LIN Slave,

62 50 only message signals may be set. In this case, the message header is transmitted from the connected LIN Master Network Management (CAN) This action allows you to control network management on a CAN channel. The CAN channel in which communication related to network management will be performed must be selected in the second column of the action (Figure 48: Action: Network management). In the third column, you can select the status to which you want to change network management. The action Network management is then only available if a CAN database was loaded with the network management option. It is not available to the channel that was assigned a LIN database. Figure 48: Action: Network management One precondition for starting network management is that one control unit must be connected to CANister which requires the network management message of another controller to achieve full functionality. It is also possible to monitor a connection to attached control units being established with network management. Network management can be used to permit functions of CANister only after a connection has successfully been established (CAN connect event) and to suppress them when the connection is broken (CAN disconnect event). Note: The events CAN connect and CAN disconnect only occur if network management has previously been started Cyclic Messages (CAN) The selected cyclic CAN messages can be started or stopped with this action. The selection is made in the second column of the action (Figure 49: Action: Cyclic messages). Cyclic messages can be selected in the tree view for the Single configuration / cyclic message node. The list of messages here depends on the receiving nodes selected and on the transmission type of messages in the database. Figure 49: Action: Cyclic messages

63 51 Note: If a signal of a cyclic message is set in a configuration, this cyclic message is handled as a selected cyclic message. Even if it is not selected in the list of cyclic messages Digital Output Digital outputs can be set to high or low with this action (Figure 50: Action: Digital output). If a load is connected to a digital output, it must be switched against the current. You will find a circuit diagram for the digital outputs in the CANister Manual attached to the documentation. Figure 50: Action: Digital output You can call the following dialog box for setting parameters of digital outputs by clicking on the... button in the second column of the action: The eight digital outputs are displayed in the dialog box (Figure 51: Digital outputs). The status of a digital output can be switched by clicking on the corresponding button. Switching always takes place in the same order: High (rising signal edge) Low (falling signal edge) unchanged (grey) Figure 51: Digital outputs Note: The digital outputs are inactive when the CANister is powered-up. The outputs are set to high.

64 PWM Output The two PWM outputs are controlled by this action. In the second column the user chooses whether the PWM output should be started or stopped. With a start the frequency in Hertz with which the PWM output should be pulsed is entered in the third column. The duty cycle pulse width/period (Ti/T) is entered in percent in the fourth column. An entry of 25% means that during one period the output signal is set to high for the first quarter of the period and is then set to low. If the PWM output is stopped, the signal level is set permanently to high. Figure 52: PWM output Note: The action PWM output is only available to CANister HL and CANister LinL, the action Relay is only available for CANister AL Relay The action Relay enables the system to alternate between the three statuses, clockwise operation or counterclockwise operation or delete. You can select between these operations in the second column of the action. Figure 53: Relay Note: The action Relay is only available for CANister AL and the action PWM output is only available for CANister HL and CANister LinL Change of Configuration You can use this action to switch from one single configuration specified under the total configuration to another. The single configuration you would like to select (Figure 54: Action: Configuration change), is displayed in the second column of the action. The current single configuration does not appear in the list. An empty list means that the total configuration contains only one single configuration.

65 53 Figure 54: Action: Configuration change Signal check (CAN/LIN) Signals of messages can be set with this action. The database in which the message is defined can be selected in the second column of the action (Figure 55: Action: Signal check (CAN/LIN)). If this list does not contain any database, no database has yet been added to the current single configuration. A database can be added with the node Single configuration / Database. The message containing the signal can be selected in the third column. The list of messages depends on the receiving nodes selected and on the database. Of all the messages of the database, only those messages that are sent by one of the selected receiving nodes (control units) are available. If the list does not contain any messages, the list of receiving nodes and the message attributes should therefore be checked. The signal can be selected in the fourth column. The list contains all signal names that have been defined for the selected message in the database. The condition for the signal check is then entered. For additional information to define a condition for a signal check, please see Section Signal check. Figure 55: Action: Signal check (CAN/LIN) 3.7 Documentation You can produce documentation for a total configuration with the menu Generate / Documentation. This generates a text file from a total configuration containing all settings for the total configuration and for the single configurations. The name of the text file can be freely selected. 3.8 Generate Overview During the generation process, Hex files are generated from the configurations and from the user functions if they are available. These Hex files can be loaded into CANister as independent applications. This can be controlled with the Generate dialog box, which can be called with the Generate menu.

66 54 The Generate dialog box (Figure 56: Generate) contains four checkboxes for controlling the generation process. When the individual checkboxes are activated, dependencies during the generation process have been taken into consideration. The dependencies are listed in summary format at the end of this chapter. Figure 56: Generate In the list box the user must select those individual configurations for which the generation process should be performed. During the generation process, files are created that are stored in a fixed directory structure. The files are located in the directory <Name of total configuration>/<name of single configuration>. This directory is given relative to the directory in which the configuration (*.CSK) is stored. For the purpose of illustration, the total configuration SAMPLE3.CSK will be used with the single configurations Messages_HS and Messages_LS. A separate directory is created for the total configuration with the name.\sample3. Then an additional subdirectory is created for each single configuration with the name of the single configuration. In the present example, these are the subdirectories.\sample3\messages_hs and.\sample3\messages_ls. All files belonging to the corresponding single configuration are then saved in one of these subdirectories. This directory structure and its content can also be generated when selecting the menu command File / Save as or when importing LKG files C Header / Code The C header/code checkbox is only available if at least one user function has been defined in at least one single configuration. After you have selected the checkbox and clicked on the Start button, the header file USERCFCT.H and the C file USERCFCT.C is generated for each single configuration with at least one user function. The generated files are located in the directory <Name of total configuration>/<name of single configuration>. This directory is given relative to the directory in which the configura-

67 55 tion (*.csk) is stored. The files must not be modified manually and must be referenced in the C module in which the user implements C functions. Various constants (defines) for messages, user events and user constants and the prototypes of user C functions are defined in the header USERCFCT.H. The names of user functions are stored again as a table serving as a jump table for the firmware in the file USERCFCT.C. You will find an exhaustive description of the files in Section 4.4 Generated files. The C header/code checkbox must always be selected if the configuration has been modified in such a manner that the number or the order of entries in the files USERCFCT.H or USERCFCT.C has been changed. The Compile checkbox can only be selected in these cases if the C header/code checkbox has also been selected. Using the C header/code checkbox, the C module for the implementation for user functions is created if the C module and Makefile do not exist yet. The C module already contains the Includes of the header files and the template of the user functions defined to that point. Note: The C module is not expanded by the Configurator if new C functions are defined in the Configurator. In addition, using the C header/code checkbox, the Makefile is created if it does not exist yet. Section Makefile describes the details and settings which are taken over in the Makefile. User functions must be interpreted with the Tasking compiler (see Section Compiler). The Tasking tab in the Options dialog box can be used to select whether the Tasking compiler is available. For a detailed description of the options, please see Section 3.2 Options Compile The Compile checkbox is only available if at least one user function has been defined in at least one single configuration and the user has programmed the corresponding C module. If this checkbox has been selected, the Tasking compiler is automatically called. The MAKEFILE must be present in each subdirectory of each single configuration with C functions. If the C header/code checkbox is checked, the Makefile is generated automatically by the Configurator during the generation process if it does not exist yet. The Makefile should be checked by the user for security if errors occur when compiling. In this case directories for the User C library and the name of the programmed C module must be adjusted in the Makefile (see Section 4.9). The Compile checkbox must always be selected if the configuration has been modified in such a manner that the number or the order of entries in the files USERCFCT.H or USERCFCT.C has been changed. This is also required if the C module has been modified. The Generate checkbox can only be selected in these cases if the Compile checkbox has also been selected. Protocol files are generated if errors are encountered during the compilation. The files are described in Section Error Files During Compilation.

68 Generate If the Generate checkbox has been selected, a binary file is first created from each single configuration. A Hex file that can be loaded into CANister is created from the binary file and possibly from the Hex file of the Tasking compiler. This checkbox can always be activated if no user functions have been defined in the single configurations. For single configurations with user functions, if the configuration or the C module has been changed, the Compile checkbox must be selected. Otherwise the Generate checkbox cannot be selected. Figure 57: Generating a configuration and user C functions Download If the Download checkbox has been selected, the single configurations that will be loaded into CANister can be marked in the list box. Download is described in more detail in Section 3.9. This checkbox can only be selected if the Generate checkbox has been selected or if the configuration or C module have not been modified Summary The requirements of the individual steps of the generation process and their interconnection are once more summarized in the following Table 9. At least one of the requirements must be satisfied for the corresponding checkbox to be capable of being activated and selected. The entire generation process can be started with the Start button. The selected steps of the generation process are only done for those single configurations that are selected in the listbox.

69 57 Checkbox C header/code Compile Generate Download Requirements At least one user function must be defined in at least one single configuration. At least one user function must be defined and the files USERCFCT.H and USERCFCT.C must be current and the MAKEFILE must be present. The C header/code checkbox is activated and the MAKE- FILE must be present. If at least one user function is defined: The results of all previous steps must be current. The Compile checkbox has been selected. If no user functions have been defined: Checkbox can always be selected. The results of all previous steps must be current and CAN databases must be unmodified. Table 9: Generation process While the process is being executed, a protocol output appears in a dialog window. The step that is currently active is displayed here. After the generation process is complete, the result of the individual steps is displayed. A list is generated indicating which sub-steps were successfully completed and which failed. 3.9 Download To load a configuration or firmware into CANister, CANister must be connected with the computer by means of a 1:1-RS232 cable. The connection for the serial cable is located on the upper covering of CANister. The assignment of the 9-pin D-SUB plug is as follows: Pin 2: Tx Pin 3: Rx Pin 5: Ground

70 58 It should be noted that the 9-pin D-SUB connector cannot be used for a bootstrap download, rather CANister must be connected to the PC via the Bootbox (at the 44- pin connector). Additionally, the following pins must be connected on the connection cable: Pin 7: RTS Pin 8: CTS The baudrate can also be specified in the Options dialog box. It is currently fixed in default mode at 9600 baud for downloading configurations and firmware. You can select between 2400 baud and baud for downloading firmware with the bootstrap loader. A prerequisite for successfully downloading configurations is CANister firmware Version 3.0. A current version of the firmware is included with delivery of the CANister Configurator Download Configuration After the Generate step has been performed in the generation process, a Hex file is present for each single configuration. These files can now be loaded into CANister. Figure 58: Download configuration Note: Put the cable always with the SUBD9 socket of the CANister. The socket is labeled with RS232 on the rear wall of the housing.

71 Download Configuration Directly If there is no configuration for Hex files that are present, or if the configuration is not loaded, it is also possible to select the Hex files and load them directly. The Hex files tab is selected in the Generate dialog box. Figure 59: Direct download After you have selected the checkbox Hex files without configuration, individual Hex files can be added to the list by using the Add button. It should be noted that these files have been generated with the CANister Configurator, since no test is performed here. Individual files or all the files can be removed from the list with the buttons Remove and Remove All. The files are now marked for download in the list box. The download can be started with the Start button. The list of files is saved when the CANister Configurator is closed, and is automatically displayed if this dialog box is brought up. The checkbox Hex files from current configuration can only be selected if a configuration has been opened with the CANister Configurator. The Hex files for the various single configurations can now be selected for the download without taking into account whether they are current. The assumption is made that Hex files are present that have already been generated. The download is started with the Start button. This list of files is not saved beyond the point at which the program is exited Download Firmware An application can only be run in CANister if CANister contains a copy of the CANister firmware. Applications that were created with the CANister Configurator Version

72 require the firmware Version 3.0. The firmware can be loaded with the Firmware tab in the Generate dialog box. Figure 60: Firmware Two variants are available for downloading the firmware: 1. When selecting the Standard checkbox, the download can only be performed if CANister already contains a copy of firmware capable of running. The download is performed over CANister's RS232 port. The CANister is directly connected to the computer via a 1:1-RS232 cable. 2. If the With bootstrap loader option is selected the firmware can even be loaded if no executable firmware exists. In this case the Bootbox must be connected to CANister HL/LinL respectively the Bootbox-Adapter AL to CANister AL, and it must be connected to the computer over a 1:1 RS232 cable. CANister HL/LinL: For downloading firmware in bootstrap mode, you can use the SUBD44 socket (labeled: ADIOX) located on the CANister HL/LinL. The Bootbox has to be connected using this socket. Note: Please make note of the order of the individual components: CANister Bootbox Serial cable PC. CANister AL: For downloading firmware in Bootstrap mode, there is an additional 9-pin D-SUB plug (labeled "Boot ) available on the CANister AL. The Bootbox with the Bootbox Adapter AL has to be connected to this plug. Note: Please make note of the order of the individual components: CANister Adapter AL Bootbox Serial cable PC.

73 61 The firmware CCFM_?F.HEX can be selected with the File button. It was copied into the EXEC directory during the installation. The selected firmware is always used for both download modes. The download is started by the Start button, and the progress of the download is displayed. During the standard download CANister's upper sixteen LEDs flash. During a bootstrap download a running light above the lower four LEDs can be seen in the initial phase. After a successful download CANister lights a running light above the upper sixteen LEDs CANdb Editor The CANdb Editor is started as an external program. If a configuration is opened which contains a CAN database the database is displayed in the CANdb Editor. Otherwise the CANdb Editor is opened without a CAN database. A CAN database may be modified with the CANdb Editor. After saving the data are automatically synchronized with the data of the CANister Configurator. The CANdb Editor is included with delivery of CANister Configurator. The new CANdb++ Editor is supported as soon as CANoe or CANalyzer from Vector Informatik GmbH is installed which uses the CANdb++ Editor. The CANdb Editor can continue to be used if the line "EDITOR=candb++" is deleted in the CANISTER.INI file CANister Terminal The Tools/CANister Terminal menu item opens a dialog which shows the data that CANister is outputting over the serial port. The user selects from the menu whether the data are sent by the Master or the Slave. For outputs from the Master the Bootbox must be plugged in, and the PC's COM port must be connected to the Bootbox. For outputs from the Slave the COM port must be connected to CANister directly via the RS232 port. The output can be stopped and restarted by screen buttons. The window contents can be cleared. It is also possible to display data in Hex format. The dialog serves, for example, to display information on the computer that is sent over the serial port by a C function. Additionally, if CANister exhibits faulty behavior that information can also be shown in this dialog. The COM port for the Slave Terminal must be set in the Options dialog (see section Download), whereby the COM port for the Master Terminal is determined automatically.

74 62 Figure 61: Slave Terminal 3.12 About Hardware This dialog is used to display data about firmware and configuration contained in CANister. Just as for download the computer must be connected to CANister s RS232 port using a 1:1 RS232 cable to read the information from the CANister.

75 63 Figure 62: About hardware The version of the real-time operating system and the date on which the firmware was created are displayed for the Master firmware in the dialog box. In addition, the version of the interpreter and of the user C-library are specified. The type of network management implemented in the firmware is also displayed. Additional information is also shown for individually created firmware. Displayed for the Slave firmware are the firmware version, date and version of the real-time operating system. Additional information is also shown here for individually created firmware. For channels CAN1 and CAN2 information is given on which piggybacks have been inserted. If the insertion slots are empty the text "not found" is output. The single configurations that have been loaded into CANister are displayed in table format. The numbering is based on the item that takes in the corresponding single configuration in the total configuration. The column designated with IP contains the version of the interpreter for which the configuration was generated. The comment

76 64 and the version (if they are present) are taken over directly from the single configuration. We recommend indicating the version and supplying comments for each single configuration. This will make version administration easier. In addition, the databases that are used in the single configuration are listed. Since the entries contained in CANister are not deleted when downloading single configurations of a total configuration, it is possible that more single configurations will be displayed in the dialog box than the current total configuration contains. These additional single configurations are only present in the table, however, and do not have any effect on the current configuration. Note: The computer cable must be connected to the RS232 port. The data cannot be read-out if the cable is connected to CANister via the Bootbox.

77 65 4 Programming User C Functions 4.1 Introduction Applications for CANister are created by creating an event-action table in the CANister Configurator. If the goal is to create applications that require an expanded range of functionality, user C functions can be called as actions. User C functions are written in the C programming language and must be interpreted with the Tasking C167 C compiler (Section 4.9.1). Except for a few limitations, user C functions can be programmed completely freely. It is possible to use the functionality of the CANister firmware by means of a function library Interpreter and User C Functions The interpreter's mode of operation means, for user C functions, that there are no concurrent processes. All functions are always processed consecutively, even if two events occur simultaneously. The event buffer serializes all events. Consequently, accesses to data exchanged between user C functions do not need to be specially synchronized User C Functions and Interpreter User events can be triggered by user C functions, and they are handled like other events. User events are defined in the CANister Configurator and can be transmitted with the library function cbsetuserevent Startup Code For initialized variables, the C167 ANSI C compiler works with a startup code, which is normally executed when the system is turned on. No startup code is executed for user C functions; therefore, no initialized variables may be used. If variables must be initialized, this is performed with the help of a (ROM) constant. huge const uint16 initarray[]= { 1, 2, 3, 4 }; huge uint16 array2[4]; void myinitfunction(void) { uint8 n; for (n= 0; n < sizeof(initarray)/sizeof(uint16); n++) array2[n]= initarray[n]; }

78 Call Interface User C functions must not expect any parameters. Any return value is ignored (void f(void)). A list with function names can be created in the CANister Configurator. The action User function with one of these function names can be assigned to each event. The CANister Configurator creates a C module in which pointers to all functions are entered in a table. The CANister Interpreter calls the C function by an index which references this table. f1 f2 f3 f4 f5 f1() f2() f3() ZERO Function pointer f4() f5() User C-functions Figure 63: Table of user C functions After compiling and linking the C modules, the generated Hex file must be linked to the events-actions table (binary configuration). The Hex file (configuration) that results from this linking process can be loaded into CANister. 4.3 User C-Library CANister firmware functions can be called from user C functions. Provided with the program are a library userclib.lib and a header with prototypes (userclib.h). These functions are described in the Section 4.11 API of User C-Library Functions. The call is implemented by a trap to obtain a call interface to the CANister firmware that is version-independent. A function number is passed in a register of the C167. This mechanism is completely encapsulated in the library. Since user C functions run in a separate memory (their own NEAR memory area) all calling parameters must be declared as huge Version of User C-Library The user C-library contains a variable uiusrlibversion which is checked by the CANister firmware when loading a configuration. If the version number of the application does not agree with the library version of the firmware, an error message is generated (flashing of LEDs 8 to 12 and output of an error text via V24).

79 Generated files The header USERCFCT.H and the C file USERCFCT.C is generated by the CANister Configurator by means of the Generate dialog box, selecting the C header/code checkbox (see Section C Header / Code). These are necessary for compiling user C functions. Neither the header nor the C file should be modified. The generated files are located in the directory <Name of total configuration>/<name of single configuration>. This directory is given relative to the directory in which the configuration (*.csk) is stored Header Usercfct.h Various constants (defines) and the prototypes of user C functions are defined in the header USERCFCT.H. The name of the header file must not be changed Channels If the database contains the attribute NWMType for network management (see Section Network Management (CAN)), the channel is determined by this means. The channel can be explicitly specified in user C functions for transmitting messages that are not contained in the database. // Defines for CAN chip #define CAN_CHIP_1 0 #define CAN_CHIP_2 1 // compatibility with older version #define W210_CAN CAN_CHIP_1 #define W220_CAN CAN_CHIP_ User Constants All user constants defined by the user are taken over into the header file with their symbolic name. The prefix UCONST_ is placed before each name. #define UCONST_myFirstConstant 0 #define UCONST_mySecondConstant 1 The value of a user constant can be read with the function cbgetconstant by specifying the symbolic name (index in a table). longconstant= cbgetconstant(uconst_myfirstconstant); CAN Receiving Messages All messages that were marked for the databases with the node Events / Message received are recorded in the header file with their symbolic name. Depending on the CAN channel over which the message is received, the prefix CAN1_RX_ or CAN2_RX_ is placed before each name. #define CAN1_RX_ReceiveMessage1 0 #define CAN1_RX_ReceiveMessage2 1

80 68 #define CAN2_RX_ReceiveMessage1 0 #define CAN2_RX_ReceiveMessage2 1 Calling a user C function can be linked to the event Message received. The function cbgetcanrxobject can be used to read the content of the message and then to interpret it by specifying the define. The data of the message is written into an area in memory that is transferred as a pointer. tcanrxobject rxobject; cbgetcanrxobject(can1_rx_receivemessage1, &rxobject); if (rxobject.aucdata[0] == 0x13) {... } CAN Transmission Messages All messages that were marked for the databases with the node Events / Message transmitted are recorded in the header file with their symbolic name. Depending on the CAN channel over which the message is transmitted, the prefix CAN1_TX_ or CAN2_TX_ is placed before each name. #define CAN1_TX_TransmitMessage1 0 #define CAN1_TX_TransmitMessage2 1 #define CAN2_TX_TransmitMessage1 0 #define CAN2_TX_TransmitMessage2 1 The function cbgetcantxobject can be used to read the content of the transmission message by specifying the define. The data of the message is written into an area in memory that is transferred as a pointer. This mechanism can be used so that the identifier does not need to be specified directly. The identifier can also be derived from the database. tcantxobject txobject; cbgetcantxobject(can1_tx_transmitmessage1, &txobject); txobject.aucdata[0]= 0x13; cbcantransmit(&txobject); LIN Receiving Messages All messages that were marked for the databases with the node Events / Message received are recorded in the header file with their symbolic name. Depending on the LIN channel over which the message is received, the prefix LIN1_RX_ or LIN2_RX_ is placed before each name. #define LIN1_RX_ReceiveMessage1 0 #define LIN1_RX_ReceiveMessage2 1

81 69 #define LIN2_RX_ReceiveMessage1 0 #define LIN2_RX_ReceiveMessage2 1 Calling a user C function can be linked to the event Message received. The function cbgetlinrxobject can be used to read the content of the message and then to interpret it by specifying the define. The data of the message is written into an area in memory that is transferred as a pointer. tlinrxobject rxobject; cbgetlinrxobject(lin_rx_receivemessage1, &rxobject); if (rxobject.aucdata[0] == 0x13) {... } LIN Transmission Messages All messages that were marked for the databases with the node Events / Message transmitted are recorded in the header file with their symbolic name. Depending on the LIN channel over which the message is transmitted, the prefix LIN1_TX_ or LIN2_TX_ is placed before each name. #define LIN1_TX_TransmitMessage1 0 #define LIN1_TX_TransmitMessage2 1 #define LIN2_TX_TransmitMessage1 0 #define LIN2_TX_TransmitMessage2 1 The function cbgetlintxobject can be used to read the content of the transmission message by specifying the define. The data of the message is written into an area in memory that is transferred as a pointer. This mechanism can be used so that the identifier does not need to be specified directly. The identifier can also be derived from the database. tlintxobject txobject; cbgetlintxobject(lin1_tx_transmitmessage1, &txobject); txobject.aucdata[0]= 0x13; cblintransmit(&txobject); // or cblintransmitheader(&txobject); User Events All user events are defined by the CANister Configurator and are taken over into the header file. The prefix UEVENT_ is placed before each name. #define UEVENT_initData 0 #define UEVENT_setData 1

82 70 User events are events that are handled like all other events. They can, however, be set by the user only in a user C function with the aid of the function cbsetuserevent. Any number of actions can be appended to each user event. cbsetuserevent(uevent_initdata); Prototypes All user C functions defined in the CANister Configurator are specified with a prototype. void initdata( void ); void setdata( void ); C File Usercfct.c All user C functions defined in the CANister Configurator are entered in the generated C file USERCFCT.C in the table afuncs. This table serves as a jump table for the CANister firmware. const huge voidfunc afuncs [] = { initdata, setdata } 4.5 User-defined C Module User C functions are written out as a user-programmed C module. Any name can be chosen as the name of the C module. Before the first compilation, the makefile must be adapted (see Section Makefile). The C module must be structured as follows: An Include for the header of the user C-library USERCLIB.H An include for the generated header USERCFCT.H. Pragma instruction #pragma class pr=userfunctions The C module is created automatically during the generation process if the C header/code checkbox is checked in the generate dialog and neither C module nor Makefile are present (see Section Generating). The name of the C module is thus taken over from the entry File for C functions for the node <Name of single configuration>/settings (see Section Settings). The C module already contains the Includes of the header files, the pragma instruction, and the template of the C functions defined to that point. Please note, that the C module is not expanded by the Configurator if new C functions are defined in the Configurator. The C module can also be created manually. The abovementioned structure should be noted. The following example contains the stub of a C module: #include <userclib.h> /* header file of library */ #include "usercfct.h" /* generated header file */

83 71 defineassertfilename; /* filename for user assertions */ #pragma class pr=userfunctions static mqhuge tcantxobject txobject; /* transmit object */ static mqhuge tcanrxobject rxobject; /* receive object */ static uint8 ucstate; void initdata(void) { ucstate = 0; } /* End of initdata */ 4.6 Memory Areas Up to 16 different configurations can be saved in the CANister. They all contain their own user C functions. In order to allocate all user C functions to a uniform memory area the user C functions are copied from Flash memory to the RAM before they are executed. User C routines have 64 kbyte RAM available to them, whereby 32 kbyte can be addressed as NEAR memory. DPP0 and DPP2 are set to this 32 kbyte memory. DPP1 points to the stack, and DPP3 to the register area of the C167. At the beginning of the 64 kbyte memory area are the library version and table with the function pointers C000 FAR- Memory NEAR- Memory Field with pointer of functions Version Figure 64: Memory layout for user C functions

84 Local Memory The local memory of 64 kbyte is completely available to the user. Functions, variables and constants must be located in this memory area. The local memory is located at addresses from 60000h to 6FFFFh. When a user C function is called, the processor's data page registers 0 and 2 are switched over, so that 32 kbyte of the local memory can be accessed as NEAR memory. Constants must lie in the NEAR memory. Functions can lie anywhere in the local memory. When linking the user C modules with the binary configuration, the Hex file generated by the C167 linker is read, and is converted to the Hex file of the configuration. In doing so, the entire memory area is assumed in the configuration, from the lowest occupied address to the highest occupied address. To generate a configuration as small as possible, gaps in the memory area should be avoided. 4.8 Global Memory In addition to the local memory, a global memory of 16 kbyte is available to the user. This memory must always be addressed with huge pointers. The start address of the global memory must be determined with the function cbgetglobalusrmemory. The size of the memory can be determined by the constant ksizeofglobalmemory (an external definition can be found in clibvers.h). The global memory is completely filled with the value 0 when the CANister is powered-up. Afterwards the CANister firmware does not access it any longer. The global memory can be used to exchange data between configurations. A nonzero value can thereby indicate the validity of data. huge uint8 * ptr; ptr= cbgetglobalusrmemory(); *ptr= 0x01; // data valid ptr++; *ptr= bresultoftest; Stack The C compiler C167 from Tasking creates a user stack in addition to the system stack for a C program. This user stack can be used to pass function parameters. The user C functions do not have their own stack, but rather they use the stack of the firmware. Exact information cannot be provided on the stack that is available, since the firmware can be in various states, and interrupts can occur at any time. Approximately 128 bytes of user stack can be used. User C functions should use the stack as little as possible. Variables that are local to a function should be defined as static.

85 Generation Compiler The C166 compiler from Tasking must be used to compile user C functions. The call interface, parameter transfer of library functions and user C-library do not permit the use of any other compiler. The command line options are already preset in the supplied template makefile. The following must be compiled: All user C functions The C module generated by the CANister Configurator Makefile The Makefile is created automatically during the generation process if the C header/code checkbox is checked in the generate dialog and no Makefile is present (see Section Generating). Existing Makefiles are not overwritten and can still be adjusted manually. Upon automatic generation of the Makefile, various data are taken over as follows: The name of the C module is taken over from the entry File for C functions for the node <Name of single configuration>/settings (see Section Settings). The Configurator acquires the directory of the Tasking Compiler from the Tasking tab of the options dialog (see Section Tasking). The directories for the Include files and User C library are taken over from the installation directory of the Configurator. The Tasking libraries are entered depending on the Compiler version that is set (see Section Tasking). By default the library c166s.lib is entered, and with Version 8.0 or higher the library rt166s.lib is also entered.

86 74 Figure 65: Automatic generation of Makefile The Makefile can also be adjusted manually. A template makefile is provided in the directory of the example Sample3 that can be used for system generation. The following adjustments must be made in the makefile: Macro name in the makefile CFILE C166_PATH INC_PATH USER_C_LIB Description Name of the C module Directory of the Tasking compiler Directory of the include files Directory of the user C-library Table 10: Adjustment of makefile The name usercfct must always be assigned to the macros CFUNCTAB and OUT- NAME. Changes are not permitted in this place. The makefile included with delivery begins with the following settings: CFILE = function CFUNCTAB = usercfct OUTNAME = usercfct C166_PATH= c:\bin\c166 INC_PATH =..\..\..\common\include USER_C_LIB =..\..\..\common\lib\userclib.lib The remaining settings in the makefile remain unchanged.

87 Linker The linker must set all memory areas of functions, constants and variables to absolute addresses. The data page pointers are set for the linker. novecinit snd(dpp0(72),dpp1(65),dpp2(73), DPP3(3)) IRAMSIZE(2048) CLASSES (USERLISTV (120000H TO H)) CLASSES (USERLIST (120002H TO 1200FFH)) CLASSES (CNEAR CNEARROM CROM (120100H TO 1204FFH)) CLASSES (USERFUNCTIONS USERCLIB CHUGE CHUGEROM SHAREDRTLIB SHAREDCLIB CLIBRARY CPROGRAM RTLIBRARY (120400H TO 12FFFFH) CLASSES (CUSTACK (104000H TO 107FFFH)) Options for the linker are set in the template makefile. Meanings of the memory classes: Memory class Description USERLISTV Version number of the user C-library, defined in the library USERLIST Table of user C functions USERFUNCTIONS Memory class for user C functions USERCLIB Memory class for user C-library CUSTACK For CUSTACK the address entry must correspond to the value for DPP1 so that no warnings will be generated when linking Table 11: Memory classes All other memory classes are standard C compiler classes. During linking, warnings of the following form may be output: W 152: LOCATE.INV, line 14: CLASSES control: class name 'CNEARROM' not found This warning is permitted, since the application does not require the use of any CNEARROM. All other errors and warnings must be corrected. Note: No startup code is executed. No initialized variables may be used. If initialized variables are erroneously included in the code, the linker does not issue a warning, since initialization values lie in the valid CROM!

88 76 The following must be linked: All user C functions The C module generated by the CANister Configurator The library userclib.lib The "linked" file must be converted to hex format using the program ihex Error Files During Compilation If the compilation fails, the file USERCFCT.HEX will not be created. You will find any error messages in the files TASKING.TXT and <NAME OF C MODULE>.ERR. The file TASKING.TXT contains the output of the Tasking compiler. The files *.ERR contain error messages and warnings that are generated by the compiler. After that, the user-defined C module and the file MAKEFILE should be tested. Possible sources of errors also include the compiler options. The path and name of the Tasking compiler must be correct in the options File Format of the Configuration Figure 66: Configuration The configuration is linked together from a binary configuration (header and header data) and from the Hex file of user C functions. The result of the linking process is a Hex file.

89 API of User C-Library Functions Function Description Section I/O cbsetled Sets/clears a LED cbsetoutput Sets/clears a digital output cbgetinput Reads a digital input cbgetanaloginput Reads an analog input cbsetpwm Configures a PWM output cbcontrolpwm Activates/deactivates a PWM output cbsetrelay Sets state of relay cbgethallposition Reads the current position of the rotary control cbsethallposition Sets the current position of the rotary control LIN cbgetlinrxobject Reads the data of a LIN Rx message cbgetlintxobject Reads the data of a LIN Tx message cbsetlinsignal Writes data to a LIN message 0 cblintransmit Transmits a LIN message (header and data) cblintransmitheader Transmits a LIN message (header only) cblincommunication Start/Stop of LIN communication CAN cbgetcanrxobject Reads the data of a CAN Rx message cbgetcantxobject Reads the data of a CAN Tx message cbsetcansignal Writes data to a CAN message cbcantransmit Sends a CAN message Keypad cbgetkeys Reads the current key states cbgetkeymask Reads the current key enable mask cbsetkeymask Sets the key enable mask Constant cbgetconstant Reads a constant from the configuration cbsetconstant Sets a constant in the copy of the configuration cbgetsysconstant Reads a system constant Event cbsetuserevent Sends an event to the interpreter Error cbassert Checks an assertion, error output Memory cbgetglobalusrmemory Returns the pointer to a global user memory V24 cbv24transmit Sends a string over the serial port cbv24senddata Sends a character string over the serial port cbgetsiodataptr Reads in effective data of the last received serial command Table 12: API of User C-Library Functions

90 cbsetled void cbsetled ( uint8 ucledno, uint8 ucstate ); Parameter Description ucledno Number of the LED ( ) ucstate New state of the LED 0.. LED off 1.. LED on Description: cbsetled sets the state of a LED. 20 user-definable LEDs can be addressed cbsetoutput void cbsetoutput.( uint8 ucoutno uint8 ucstate ); Parameter Description ucoutno Number of the digital output (0... 7) ucstate New state of the digital output: 0.. high (corresponds to the action: digital output low high) 1.. low (corresponds to the action: digital output high low) Description: cbsetoutput sets the state of a digital output cbgetinput uint16 cbgetinput ( void ); Description: cbgetinput reads the states of all digital inputs. The result is the states of the digital inputs as bit array cbgetanaloginput int16 cbgetanaloginput ( uint8 ucchannel ); Parameter Description ucchannel Number of the analog input (0 3) Description: cbgetanaloginput reads the value of the specific analog input specified by ucchannel.

91 cbsetpwm void cbsetpwm ( uint32 uipwmperiod, uint8 ucdutycycle, uint8 ucoutput ); Parameter uipwmperiod ucdutycycle Description Frequency f in Hertz (4Hz 32MHz). The frequency value is calculated as follows: 500 Hz f 32MHz f = 32MHz/n with n= Hz f < 500Hz Each value f = is allowed. Duty cycle in percent (0% 100%), calculated with pulse width (High level) / period (Ti/T). An entry of 25% means that during one period the output signal is set to high for the first quarter of the period and is then set to low. ucoutput Number of the PWM output (0 or 1) Description: Note: cbsetpwm sets the parameters for a PWM output. The PWM output is activated by the function cbcontrolpwm(). Calculation of the pulse width: pulse width [s] = n / (f * 100) with n = ucdutycycle [%], f = frequency [Hz] This function may only be performed with CANister HL/LinL cbcontrolpwm void cbcontrolpwm ( uint8 ucoutput, uint8 uccontrol ); Parameter Description ucoutput Number of the PWM output (0 or 1) uccontrol Start and stop of the PWM output: 0.. PWM stop 1.. PWM start Description: cbcontrolpwm activates or deactivates a PWM output. The parameters must have been previously set by the function cbsetpwm(). If the PWM output is stopped, the signal level is permanently set to high. To set the signal to low permanently, the output needs to be started and set to a duty cycle of 0%.

92 80 Note: This function may only be performed with CANister HL/LinL cbsetrelay void cbsetrelay ( uint8 ucstate ); Parameter ucstate Description Set state for relay: 0.. stop 1.. counterclockwise 2.. clockwise Description: Note: cbsetrelay sets the state of the relay. This function may only be performed with CANister AL cbgethallposition int16 cbgethallposition ( void ); Description: cbgethallposition reads the position of the rotary transducer determined by the driver. The driver evaluates each edge change of the rotary transducer. One revolution yields 4 units of the position value cbsethallposition void cbsethallposition ( uint16 inewposition ); Parameter inewposition Description The new position for rotary transducer. Description: cbsethallposition sets the new position in the driver of the rotary transducer cbgetlinrxobject uint8 cbgetclinrxobject ( uint16 hhandle, tlinrxobject *psrxobject ); Parameter hhandle psrxobject Description Handle to a LIN receive object (index to a table, which is made available as a DEFINE by the generation process). Pointer to a receive object to which all received data are copied. The structure has the following definition: typedef struct linrxobject {

93 81 struct linrxobject *psnext; uint16 uiidentifier; uint8 ucchipno; uint8 ucdlc; void (*linrxdataindication)(struct linrxobject *prxobj); uint8 aucdata[8]; uint8 reserved[6]; } tlinrxobject; Description: cbgetlinrxobject copies the data from a LIN receive object. The LIN receive object cannot be accessed directly, since the data could become inconsistent due to interrupt-driven receiving. The result of cbgetlinrxobject is: 0: (kok) if the specified CAN object could be read -1: (kerror) if the object was not defined (incorrect index) cbgetlintxobject uint8 cbgetlintxobject ( uint16 hhandle, tlintxobject *pstxobject ); Parameter hhandle pstxobject Description Handle to a LIN transmit object (index to a table, which is made available as a DEFINE by the generation process) Pointer to a transmit object, in which all data to be sent is copied: The structure has the following definition:: typedef struct lintxobject { struct linrxobject *psrxobj; uint16 uiidentifier; uint8 ucchipno; uint8 ucdlc; void (*lintxcompletion)(struct lintxobject *); uint8 aucdata[8]; uint8 reserved[6]; } tlintxobject; Description: cbgetlintxobject copies the data from a LIN transmit object. The result of cbgetlintxobject is: 0: (kok) if the specified CAN object could be read. -1: (kerror) if the object was not defined (incorrect index)

94 cbsetlinsignal void cbsetlinsignal ( uint16 hhandle, uint8 ucbytes, uint8 ucbyteoffset, uint8 *pucdata, uint8 *pucandmask ); Parameter Description hhandle Handle to the transmit message (DEFINES of the LIN messages are created by the generation process). ucbytes Number of bytes to be set (1 to 5). ucbyteoffset Index of the first byte in the message that is to be set. pucdata Pointer to the data bytes to be set; these data are logically "OR'd" with the bytes of the message. pucandmask Before the data can be logically combined by "OR" with the data bytes of the message they are logically combined by "AND" with the bytes to which pucandmask points. The mask bytes must contain 1 at the points that should not be manipulated and 0 at the points at which data bits should be logically "OR"d. Description: cbsetlinsignal is a command to manipulate any desired data bits in a LIN transmit message. Up to a maximum of 40 bits can be manipulated (a long value with associated bit offset) cblintransmit uint8 cblintransmit ( tlintxobject *pstxobject ); Parameter pstxobject Description Pointer to a transmit object. The structure has the following definition: typedef struct lintxobject { struct linrxobject *psrxobj; uint16 uiidentifier; uint8 ucchipno; uint8 ucdlc; void (*lintxcompletion)(struct lintxobject *); uint8 aucdata[8]; uint8 reserved[6]; } tlintxobject;

95 83 Description: cblintransmit transmits the header including data of a LIN message. The result of cblintransmit is: 0 (kok): If the transmit request was accepted in the queue. -1 (kerror): If transmission by the LIN driver is disabled cblintransmitheader uint8 cblintransmitheader ( tlintxobject *pstxobject ); Parameter pstxobject Description Pointer to a transmit object. The structure has the following definition: typedef struct lintxobject { struct linrxobject *psrxobj; uint16 uiidentifier; uint8 ucchipno; uint8 ucdlc; void (*lintxcompletion)(struct lintxobject *); uint8 aucdata[8]; uint8 reserved[6]; } tlintxobject; Description: cblintransmitheader transmits the header of a LIN message. The result of cblintransmitheader is: 0 (kok): If the transmit request was accepted in the queue. -1 (kerror): If transmission by the LIN driver is disabled cblincommunication uint8 cblincommunication ( uint8 uctype ); Parameter ucstate Description Set state of LIN communication #define LIN_COMMUNICATION_START 0 #define LIN_COMMUNICATION_STOP 1 Description: cblincommunication sets the state of the LIN communication (Start, Stop)

96 cbgetcanrxobject uint8 cbgetcanrxobject ( uint16 hhandle, tcanrxobject *psrxobject ); Parameter hhandle psrxobject Description Handle to a CAN receive object (index to a table, which is made available as a DEFINE by the generation process). Pointer to a receive object to which all received data are copied. The structure has the following definition: typedef struct canrxobject { struct canrxobject *psnext; uint32 ulidentifier; uint8 ucchipno; uint8 ucdlc; void (*canrxdataindication)(struct canrxobject *prxobj); uint8 aucdata[8]; uint8 ucextended; uint8 ucreserved; uint8 reserved[4]; } tcanrxobject; Description: cbgetcanrxobject copies the data from a CAN receive object. The CAN receive object cannot be accessed directly, since the data could become inconsistent due to interrupt-driven receiving. If ucextended is nonzero the message ID is interpreted as an extended ID (29 bit). The result of cbgetcanrxobject is: 0: (kok) if the specified CAN object could be read -1: (kerror) if the object was not defined (incorrect index) cbgetcantxobject uint8 cbgetcantxobject ( uint16 hhandle, tcantxobject *pstxobject ); Parameter hhandle pstxobject Description Handle to a CAN transmit object (index to a table, which is made available as a DEFINE by the generation process) Pointer to a transmit object, in which all data to be sent is copied: The structure has the following definition: typedef struct cantxobject { uint8 ucchipno; uint8 ucdlc;

97 85 void (*cantxcompletion)(struct cantxobject *); uint32 ulidentifier; uint32 ulvirtualnet; uint8 aucdata[8]; uint8 ucextended; uint8 ucreserved; uint32 ulisstarted; uint8 reserved[4]; } tcantxobject; Description: cbgetcantxobject copies the data from a CAN transmit object. If ucextended is nonzero the message ID is interpreted as an extended ID (29 bit). The result of cbgetcantxobject is: 0: (kok) if the specified CAN object could be read. -1: (kerror) if the object was not defined (incorrect index) cbsetcansignal void cbsetcansignal ( uint16 hhandle, uint8 ucbytes, uint8 ucbyteoffset, uint8 *pucdata, uint8 *pucandmask ); Parameter Description hhandle Handle to the transmit message (DEFINES of the CAN messages are created by the generation process). ucbytes Number of bytes to be set (1 to 5). ucbyteoffset Index of the first byte in the message that is to be set. pucdata Pointer to the data bytes to be set; these data are logically "OR'd" with the bytes of the message. pucandmask Before the data can be logically combined by "OR" with the data bytes of the message they are logically combined by "AND" with the bytes to which pucandmask points. The mask bytes must contain 1 at the points that should not be manipulated and 0 at the points at which data bits should be logically "OR"d. Description: cbsetcansignal is a command to manipulate any desired data bits in a CAN transmit message. Up to a maximum of 40 bits can be manipulated (a long value with associated bit offset).

98 cbcantransmit uint8 cbcantransmit ( tcantxobject *pstxobject ); Parameter pstxobject Description: Description Pointer to a transmit object. The structure has the following definition: typedef struct cantxobject { uint8 ucchipno; uint8 ucdlc; void (*cantxcompletion)(struct cantxobject *); uint32 ulidentifier; uint32 ulvirtualnet; uint8 aucdata[8]; uint8 ucextended; uint8 ucreserved; uint32 ulisstarted; uint8 reserved[4]; } tcantxobject; cbcantransmit transmits a CAN message. If ucextended is nonzero the message ID is interpreted as an extended ID (29 bit). The result of cbcantransmit is: 0 (kok): If the transmit request was accepted in the queue. -1 (kerror): If there was no space in the transmit queue, or if transmission by the CAN driver is disabled cbgetkeys uint16 cbgetkeys ( void ); Description: cbgetkeys reads the keypad buffer of the keypad driver. The momentary state of the: 0 : Key not pressed 1 : Key pressed The return value is independent of the enable mask set cbgetkeymask uint16 cbgetkeymask ( void ); Description: cbgetkeymask reads the enable mask for the keypad driver. Only enabled keys can generate events for the interpreter. The result of cbgetkeymask is the current key mask: Bit = 0: Key locked Bit = 1: Key unlocked

99 cbsetkeymask void cbsetkeymask ( uint16 uimask ); Parameter uimask Description The new enable mask. Description: cbsetkeymask sets the enable mask for the keypad driver. Only enabled keys can generate events for the interpreter cbgetconstant uint32 cbgetconstant ( uint16 hhandle ); Parameter hhandle Description Index to the table of constants. (The generation process makes the index available as a DEFINE in a header file.) Description: cbgetconstant reads a constant from the configuration that was defined with the CANister Configurator. The result of cbgetconstant is the constant stored in the configuration cbsetconstant void cbsetconstant ( uint16 hhandle, int32 lvalue ); Parameter hhandle lvalue Description Index to the table of constants. (The generation process makes the index available as a DEFINE in a header file.) The value to be entered Description: cbsetconstant replaces the value of an existing constant by a new value. The replaced value is only valid for the duration of the interpretation of the running configuration cbgetsysconstant uint32 cbgetsysconstant ( uint16 hhandle ); Parameter hhandle Description Index to the table of system constants. (The generation process makes the index available as a DEFINE in a header file.)

100 88 Description: cbgetsysconstant reads a system constant from the configuration that was defined with the CANister Configurator. The result of cbgetsysconstant is the system constant stored in the configuration. The user of the CANister Configurator cannot modify system constants cbsetuserevent void cbsetuserevent ( uint16 uispecifier ); Parameter uispecifier Description Specifier of user events permits subdivision of the class of user events and programming of different reactions in the Interpreter table. Description: cbsetuserevent writes an user event in the queue of interpreter events cbassert void cbassert ( condition ); Parameter condition Description Logical condition that is checked Description: cbassert checks the specified condition. If the result is kfalse the entire system is stopped. A running light above the lower four LEDs is shown and an error message is output periodically over the serial port. The error message has the following format: CANister User-C-Error in File: <Filename> Line: <Line> cbgetglobalusrmemory huge uint8* cbgetglobalusrmemory ( void ); Description: The global user memory has a size of 16 kbyte (The memory size can be queried by the constant ksizeofglobalmemory). The global user memory is initialized to 0 at the system software start (reset or power-up). The user memory can be used to transfer data from one configuration to another. The result of cbgetglobalusrmemory is a huge pointer to a memory area.

101 cbv24transmit void cbv24transmit ( huge char* huge cstring ); Parameter cstring Description Huge pointer to a huge string Description: cbv24transmit transmits a string via the serial port. The baudrate is permanently set to 9600 baud, 8 data bits, no parity. The string may be maximum 128 characters in length cbv24senddata void cbv24senddata ( huge char* huge cdata, uint16 uilength ); Parameter Description cdata Huge pointer to a huge char array uilength Number of characters to transmit (maximum 255) Description: cbv24senddata sends a character string over the serial port. The baudrate is permanently set to 9600 baud, 8 data bits, no parity. It should be noted that the character string may be a maximum of 255 characters in length cbgetsiodataptr huge uint8 *cbgetsiodataptr ( void ); Description: With cbgetsiodataptr the user obtains access to the useful data of the last received serial command. As a result cbgetsiodataptr returns a huge pointer to the memory area of the useful data. The useful data are described in Table 8: Effective data of a telegram.

102 90 5 Tutorial This tutorial is intended to make users who are using the CANister Configurator for the first time familiar with how to operate it and to briefly describe the most important features. To illustrate the basic principle, a simple configuration will first be created, generated and then loaded into CANister. Then additional features will be integrated into this basic configuration. Configurations of any type can then be created based on this basic principle. In the following sections, more features will be added to those already shown and will be explained in turn. Four tutorial configurations in which the most frequent application cases are treated are included with delivery. The following tutorials can be found in the subdirectory.\samples. TUTORIAL_1.CSK: Turning LEDs on and off by pressing a key TUTORIAL_2.CSK: Two single configurations, timers TUTORIAL_3.CSK: Databases, sending and receiving messages TUTORIAL_4.CSK: User functions The tutorial TUTORIAL_5.CSK is described in Section 5.6 Configuration with Network Management but is not included with delivery. 5.1 New Configuration with LED and Keys Exercise 1: Create a new total configuration, change the name of the single configuration to Tutorial_1. Save the total configuration under the name TUTORIAL_1.CSK. First start the CANister Configurator with the Start menu. To create a new configuration, select the command New in the File menu or click on the button in the toolbar. A window now appears with a new total configuration without a name. The total configuration contains a single configuration with the name Noname. The default settings are already made. In the tree view, switch to the Total configuration node. (Figure 67: New single configuration) and select the node Single configurations. Click in the table on the name Noname of the single configuration and directly enter the new name, Tutorial_1. You can also edit the name by double-clicking on the box. Please note that the version and comment cannot be changed in this place.

103 91 Figure 67: New single configuration Exercise 2: LED 12 is on continuously when the configuration starts. LED 1 is on as long as key 1 is pressed. To do this, switch in the tree view to the Events node under the single configuration Tutorial_1, and then select the event Start. An empty list now appears on the right side in the table view as shown in Figure 68: Empty list. Figure 68: Empty list Now select the action LED in the first column of the combo box (Figure 69: Incomplete action). The table will then be provided with column header. The second column now displays which LEDs are to be turned on with this action and which ones should be turned off. This setting should now be made. This is the reason why the warning icon appears on the left. This icon is always displayed if parameterization in the action is not yet complete or if individual parameters are no longer valid.

104 92 Figure 69: Incomplete action Now click on the button in the column with the header On/Off. A dialog box appears in which the LEDs of CANister are shown (Figure 70: LED dialog box). Click on LED 12. It is displayed in bright green. This means that this LED is turned on for this action. All LEDs can be switched to another state by clicking on the corresponding area in the dialog box. If the LED is displayed in bright, it is turned on. If it appears in dark with cross, it is turned off. If it is displayed in gray, it remains unchanged. Figure 70: LED dialog box

105 93 Close the dialog box by clicking on the OK button. The action with all the parameters set appears as follows: Figure 71: Complete action To be able to respond to a key, the key must first be unlocked, since to begin with all keys are locked. To do this, click on the button of the combo box in the second (free) line and select the Keys action. The program then displays in the second column (just as for the LEDs) which keys are enabled and which are disabled. To select keys, click on the button in the second column. A dialog box appears in which the keys of CANister are shown (Figure 72: Keys dialog box). Figure 72: Keys dialog box Click once on the surface of Key 1. It is now displayed in green, which means that the key is enabled. Clicking again will disable the key. It will then be shown in red with cross. If you click once more, the key will be displayed in gray in other words it remains unchanged. Now close the dialog box with the OK button. Figure 73 shows the actions with parameters set for them.

106 94 Figure 73: Actions of the event The next task is to make LED 1 stay lit as long as Key 1 is pressed. To do this, it is necessary to respond to two events, first to the event Key 1 pressed and then to the event Key 1 released. You will find these in the tree view underneath the Keys event (Figure 74: Keys event). First select the event Key 1 pressed. Now insert the LED action as described above. Open the LED dialog box again with the button in the second column. Click once on LED 1. It is displayed now in bright green. Exit the dialog box with OK. Insert the LED action for the event Key 1 released and open the LED dialog box. Now click twice on LED 1. It is now displayed in dark green with cross, which means it is turned off. All other LEDs remain unchanged. The result of this is that LED 12 stays lit after it has been turned on during the Start event. Exit the dialog box with OK. Figure 74: Keys event Save the total configuration under the name TUTORIAL_1.CSK. To do this, select the command Save as in the File menu or click in the toolbar on the icon. In the following dialog box, switch to the SAMPLES\ directory under the main directory of your CANister Configurator program if necessary and enter the name TUTO- RIAL_1.CSK. The subdirectory.\tutorial_1 has now been created for the total configuration and within it the subdirectory.\tutorial_1 has been created for the single configuration.

107 Generate and Download Exercise 3: Generate and download for the total configuration TUTORIAL_1.CSK. After you have saved the total configuration, next select the Generate command in the Generate menu or click in the toolbar on the icon. This brings up the Generate dialog box (Figure 75: Generate dialog box). Now select the Generate checkbox. The Download checkbox and the corresponding list box are activated. Select this checkbox as well. The single configuration Tutorial_1 is already selected in the list box. If this is not the case, select the single configuration by clicking on the corresponding line in the list box. Figure 75: Generate dialog box The generation process can be started with the Start button. First, the configuration is generated, in other words the files TUTORIAL_1.BIN, TUTORIAL_1.LST and TU- TORIAL_1.HEX are generated in subdirectory.\tutorial_1. After that the file TU- TORIAL_1.HEX is loaded into CANister. During the generation process, the protocol is displayed in a dialog box (Figure 77: Generation protocol) and a summary is then generated as output. If the download is started, a dialog box appears for the download of each Hex file with a display of the progress of the download (Figure 76: Download). The LEDs of CANister flash during the download. It takes a few seconds to enter the file into Flash memory. During this time the flashing lights stop. Upon completion, all the LEDs go out.

108 96 Figure 76: Download Figure 77 shows the protocol of a successful generation process followed by a download. If errors have occurred, this is indicated by an additional comment at the end of the protocol. Figure 77: Generation protocol After the download has finished successfully, the configuration is automatically started. The LED 12 is now lit on CANister. Now press the key 1. LED remains lit as long as the key is held down. 5.3 Configuration with Multiple Single Configurations Exercise 4: Using two single configurations. Use the keys 4 and 8 to switch back and forth between them. LEDs 11 and 12 display which single configuration is active. Switch to key 1 in a single configuration with LED 1 flashing. In the other single configuration, LED 1 and LED 2 flash in alternation for this key. The LEDs are stopped in response to key 5.

109 97 To do this, create a new total configuration and save it under the name TUTO- RIAL_2.CSK. In the tree view, switch to the node Single configurations under total configuration. Now change the name of the single configuration that is already present by default to LEDflash. To create an additional single configuration, click on the last cell in the column with the header Name. This empty line is now activated and is identified with yellow. Now enter the name LEDchange. The two single configurations are now displayed as in Figure 78: Single configurations. The second single configuration was automatically inserted in the tree view as a new node. Figure 78: Single configurations Now switch in tree view in the single configuration LEDflash to the Settings node. For version, enter 1.0 and for comment enter LED 1 flash. In the single configuration LEDchange, enter correspondingly 1.0 for the version and LEDs 1 and 2 flash in alternation for the comment. Figure 79: Version and comment

110 98 Timers are required to make a LED flash. Now switch in the tree view to the Definitions node of the single configuration LEDflash and from there to the Timer node. Select the first column in the first line. Now enter the name LEDon and acknowledge with <Return>. A combination box now appears in the same line. It already contains the entry Cyclic. Select the entry Single in this combo box. You have now defined a single timer with the name LEDon. Now define an additional single timer in the next line with the name LEDoff. The result is displayed in Figure 80: Timers. Figure 80: Timers Now switch in tree view in the single configuration LEDflash to the Events node. There you will find the event Timers. This contains the events for all defined timers since a separate response is possible to each timer. First select the node for the timer LEDon. When this timer has elapsed, LED 1 is supposed to light up. Now insert the corresponding action for LED 1. Then the timer LEDoff is supposed to be started to turn LED 1 back off again. To do this, select the action Timer as the next action. In the second column of this action, select the timer LEDoff in the combo box. The entry Set is already selected in the combo box. In the fourth column, the cycle time must be specified in milliseconds. Enter the value 500 here. The result is displayed in Figure 81: LEDon timer.

111 99 Figure 81: LEDon timer Select the timer LEDoff as the next element for the event. When this timer has elapsed, LED 1 will be turned off. Now insert the corresponding action for LED 1. Then the timer LEDon will be started to turn LED 1 back on again. Set the timer LE- Don accordingly and then select a cycle time of 500 ms. Now switch to the Start event of the single configuration LEDflash. To identify the active single configuration, LED 11 will light up for LEDflash and LED 12 will light up for LEDchange. Insert the corresponding action to turn on LED 11. The next step is to enable the required keys. Now enable keys 1, 5 (LED on and off) and key 8 (switch to single configuration LEDchange). The result is displayed in Figure 82: Start event. Figure 82: Start event To make LED 1 flash for key 1, switch to the event Key 1 pressed. First insert the action that will be used to turn LED 1 on. The timer LEDoff is set as the second action. Select a cycle time of 500 ms. LED 1 is turned off again with key 5. To do this, switch to the event Key 5 pressed. First insert the action Timer LEDon here. Now select the entry Cancel in the third column in the combo box. After that, enter the cycle time. Proceed in exactly the same manner for the timer LEDoff. Now turn LED 1 off, since it is possible that it will be

112 100 turned on at the time when the key is pressed. The result is displayed in Figure 83: Exiting flashing. Figure 83: Exiting flashing To complete parameterization for the single configuration LEDflash, switch to the event Key 8 pressed and insert the action Configuration change there. Select the entry LEDchange in the second column in the combo box. This causes the program to switch to the single configuration LEDchange with Key 8. Save the total configuration. Now set the parameters for the single configuration LEDchange. The entries are very similar to those for the single configuration LEDflash. The names of the timers will be different to help tell the two sets apart. Different LEDs will be turned on and off and in some cases different keys will be used. In the Start event, LED 12 is turned on to identify the active single configuration LEDflash. After that, keys 1, 5 and 4 are enabled here. Now define two single timers with the names LED1on and LED2on to make LED 1 and LED 2 flash in alternation. Please note that the timer is single and not cyclic. In the event for the timer LED1on, LED 1 is turned on and LED 2 is turned off. The timer LED2on is started with a cycle time of 500 ms. In the event for the timer LED2on, LED 1 is turned off and LED 2 is turned on. The timer LED1on is started with a cycle time of 500 ms. In the event Key 1 pressed, turn on LED 1 as above. Then start the timer LED2on with a cycle time of 500 ms. Delete both timers in the event Key 5 pressed and turn off LEDs 1 and 2, since it is not certain which LED is currently lit. Key 4 is used to switch to the single configuration LEDflash. Insert the corresponding action for the event Key 4 pressed. Now save the configuration. Generate the Hex files of the single configuration and load the two files into CANister. 5.4 Configuration with Database The main purpose of CANister is to transmit CAN messages or to receive CAN messages and respond to them. A CAN database is required to be able to integrate CAN messages. A database can be created with the CANdb Editor, which is included with delivery of the CANister Configurator. You will find a description of the CANdb Editor in the appendix to this manual. The database SAMPLE.DBC of the sample configuration SAMPLE3.CSK is used in the following. This database is located in the subdirectory.\sample3\dbc.

113 101 Exercise 5: The CAN message Msg_Tx_Spontan will be transmitted when key 1 is pressed. After the message has been successfully sent, LED 3 will light up for 300 ms. LED 4 will light up for 300 ms when CAN message Msg_Rx is received. At the beginning, the cyclic message Msg_Tx_Cyclic is started. As long as key 2 is pressed, the signal SignalCyclic is set to the value 100 in the cyclic message Msg_Tx_Cyclic, and after that back to 0. The two single configurations Highspeed and Lowspeed will be created. For the single configuration Highspeed, messages are transmitted and received on CAN1 and LED 11 lights up. For the single configuration Lowspeed, messages are transmitted and received on CAN2 and LED 12 lights up. First open the total configuration TUTORIAL_2.CSK from Section 5.3. Save this configuration under the new name TUTORIAL_3.CSK. Delete all actions from the events Key 1 pressed and Key 5 pressed in the two single configurations. You can delete an action by selecting a cell in the corresponding action and then either pressing the keys <Ctrl>+<D> or selecting Delete in the context menu of the right mouse button. You can select multiple actions simultaneously if you hold down the <Ctrl> key or the shift key while selecting the actions. Change the name of the first single configuration to Highspeed and the second to Lowspeed. The database will be added for the single configuration Highspeed. To do this, select the Databases node in the tree view. Click in the first column on the button. In the dialog box which then appears, you can select a database. Select the file SAM- PLE.DBC in directory.\sample3\dbc here. The database is automatically assigned to CAN channel 1 (Figure 84: Insert database). Figure 84: Insert database To transmit or receive CAN messages, you must define which additional network nodes (control units) are to be connected to CANister. To do this, switch in the tree view to the Receiving nodes node. An additional node with the name of the database is displayed in this node. Select this node. The table view gives a list of all network nodes that are defined in the database. In this case these nodes are Canister and Tester. Now select the receiving node Tester in the second column. It is now possible to transmit all CAN messages that the node Tester is able to receive, and to respond to all CAN messages that Tester is able to transmit. These settings are shown in Figure 85. The node for cyclic messages is based on the same principle. Mark the cyclic CAN message Msg_Tx_Cyclic here. The message marked here is transmitted with the action Start cyclic messages.

114 102 Figure 85: Receiving nodes Now switch to the Start event. Turn on LED 11. After that, enable keys 1, 5 and 8. Insert the action Cyclic messages. Select the entry Start in the second column. We recommend starting cyclic messages at the beginning. The result is displayed in Figure 86: Start event. Figure 86: Start event Switch to the event Key 1 pressed. Insert the action Transmit CAN message. Select the database SAMPLE.DBC in the second column and the message Msg_Tx_Spontan in column 3 (Figure 87: Transmit CAN message). Figure 87: Transmit CAN message Define a single timer with the name TransmitLedOff. Now under the node Message transmitted, select the node with the name of the database. Select the checkbox of the message Msg_Tx_Spontan. In the tree view, a new node now appears underneath the node of the database with the name Msg_Tx_Spontan. This node represents the event that is initiated if the message has been successfully transmitted. Turn LED 3 on for this event and set the timer TransmitLedOff to a cycle time of 300 ms. The result is displayed in Figure 88: CAN message sent.

115 103 Figure 88: CAN message sent If the timer TransmitLedOff has elapsed, LED is turned off again. To do this, insert the corresponding action. The result is displayed in Figure 89: Timer elapsed. After CAN message Msg_Tx_Spontan has been successfully transmitted, LED 3 now lights up for 300 ms. Figure 89: Timer elapsed As the next step, define a single timer with the name ReceiveLedOff. In the node for received messages, select the CAN message Msg_Rx based on the same principle as for transmitted messages. Turn on LED 4 in the event for this message and set the timer ReceiveLedOff to a cycle time of 300 ms. Turn LED 4 off in the event for this timer. To set the signal, insert the action Set message signal for the event Key 5 pressed. As for the action Transmit CAN message, you must select the database. In the third column, select the message Msg_Tx_Cyclic. In the fourth column select the signal SignalCyclic. In the fifth column, enter the value 100. This is shown in Figure 90: Set message signal. In the event Key 5 released, set the signal back to 0.

116 104 Figure 90: Set message signal Set the parameters of the single configuration Lowspeed in the same manner as for the single configuration Highspeed. In contrast to the single configuration Highspeed, assign the database to CAN channel 2. All messages are thus transmitted or received on the second CAN channel. LED 12 is turned on for the Start event. Now generate the total configuration and load the two single configurations into CANister. The single configuration Highspeed now transmits and receives on CAN channel 1 and the single configuration Lowspeed transmits and receives on channel 2. If no network user is connected to the CAN channels, it is only possible to switch back and forth between the single configurations. To transmit or receive messages, at least one additional user must be connected to each CAN channel. For example, the configurations can be tested with CANoe or CANalyzer. Connect the CAN channels of CANister to a CANcardX for this purpose. CANoe, CANalyzer and CANcardX are also standard products of Vector Informatik. 5.5 Configuration with User C Function. The functionality of CANister can be expanded with actions that are available in the CANister Configurator. C functions that can be programmed with functionality to match specific needs can be integrated into each single configuration. To do this, however, the Tasking compiler must be used. Thus the following assignment can only be solved if you have access to the Tasking compiler. Exercise 6: The total configuration from exercise 5 will be expanded by starting the C function SampleFct when key 1 is activated. This function transmits the message Msg_Tx_Spontan and initiates the user event Function- Started. The user event indicates that the function has been started. In response to this user event, LED 1 is turned on and is then turned off again after one half of a second. The value of the signal FunctionSignalVar is incremented by one after the message is transmitted. When a value of 255 is reached, the counter starts over again at 0. The signal FunctionSignalconst always takes on the value of the user constant Constant. Save the total configuration under the name TUTORIAL_3.CSK under the name TU- TORIAL_4.CSK. Now define a single timer with the name CLedOff in both single configurations. Switch to the Definitions/User event node and define two user events with the names FunctionStarted and InitData. To do this, enter these names into the empty box and acknowledge the entry with <Return>. After that, define a user constant with the name Constant. To do this, switch to the node User constants and enter the name in the first column. Enter any value between 0 and 255 for the constant in

117 105 the second column. As the last step, define the name of the C function. To do this, switch to the node Functions and enter the name SampleFct in the empty box. Replace the action Transmit CAN message of the Key 1 pressed event in the two single configurations with the action User function. Select the entry SampleFct in the second column. The result is displayed in Figure 91: Starting the user function. For events under User event, there is only the node FunctionStarted. Turn on LED 1 for this event and set the timer CLedOff to 500 ms. Then turn off LED 1 again in the event of the timer CLedOff. In the Start event, start the user function InitData in addition to the already existing actions. Figure 91: Starting the user function All parameters are now set for the two single configurations. As the next step, C functions must be implemented. To do this, first make certain that the checkbox for the Tasking compiler is activated in the Options dialog in the Tasking tab and that the path and filename for the Tasking compiler are correct. Start the Generate dialog. Select the checkbox C header/code and start the process. The files USERCFCT.H and USERCFCT.C are created for each single configuration. These are almost identical for the two single configurations in this case. They are shown for the Highspeed single configuration in Listing 1: USERCFCT.H and Listing 2: USERCFCT.C. The only difference for the Lowspeed single configuration is that the prefix CAN2_... is placed in front of the CAN messages in USERCFCT.H instead of CAN1_.... All references that can be used to gain access to the single configuration are defined in USERCFCT.H. These include: System constants User constants Received messages Transmitted messages User events User functions User functions are summarized in a list in the file usercfct.c. The generated files are described in detail in Section 4.4. Please note that neither of these two files should ever be edited under any circumstances.

118 106 /* *\ * d:\programme\canister\samples\tutorial_4\highspeed\usercfct.h * Produced with CANister Configurator Version 3.0 * as of * Current Date Fri Aug 30 14:54: * * Copyright (c) Vector Informatik GmbH \* */ #define CAN_CHIP1 0 #define CAN_CHIP2 1 // compatibility to older versions #define W210_CAN CAN_CHIP1 #define W220_CAN CAN_CHIP2 /* * system constants */ #define SCONST_nmStationAdr 0 #define SCONST_nmIstKonfig 1 #define SCONST_Control0 2 #define SCONST_Control1 3 #define SCONST_Control2 4 #define SCONST_Control3 5 /* * user constants */ #define UCONST_Constant 0 /* * CAN receive messages */ #define CAN1_RX_Msg_Rx 0 /* * CAN transmit messages */ #define CAN1_TX_Msg_Tx_Cyclic 1 #define CAN1_TX_Msg_Tx_Spontan 0

119 107 /* * user defined events */ #define UEVENT_FunctionStarted 0 /* * user functions */ void InitData( void ); void SampleFct( void ); Listing 1: USERCFCT.H /* *\ * d:\programme\canister\samples\tutorial_4\highspeed\usercfct.c * Produced with CANister Configurator Version 3.0 * as of * Current Date Fri Aug 30 14:54: * * Copyright (c) Vector Informatik GmbH \* */ #include <userclib.h> #include "usercfct.h" #pragma class hc=userlist /* * user functions */ const huge voidfunc afuncs [] = { InitData, SampleFct, (voidfunc) 0 }; Listing 2: USERCFCT.C

120 108 Copy the file MAKEFILE from one of the subdirectories of example Sample3 into the two subdirectories.\higspeed and.\lowspeed. The files USERCFCT.H and USERCFCT.C also reside in these directories. Create the file FUNCTION.C in both directories. The content of the file is illustrated for the single configuration Highspeed in Listing 3: FUNCTION.C. It is almost identical for both single configurations. All that needs to be done for the Lowspeed single configuration is to replace the CAN message CAN1_TX_Msg_Tx_Spontan with CAN2_TX_Msg_Tx_Spontan (similar to the defines in the file USERCFCT.H). The module is now briefly explained. A knowledge of C programming is assumed. The file USERCFCT.H must be integrated into the C module with #include. For this reason, all functions that are present in this file as a prototype must be implemented as a function. Functions that are implemented in this manner must not contain either parameters or return values. Additional functions with parameters or return values can also be added, however. All variables that are required must be declared as static and are global to the single configuration. This means that the content of a variable remains in memory until a switch is made to another single configuration. It is, however, possible to exchange data between single configurations. For this purpose, the corresponding variables must be stored in global memory. You will find more information on this in Section 4.8 Global Memory. Two user functions have been implemented in this example. The function InitData has been used to perform the initialization of all variables. User constants are also read in and global variables are assigned in this function. We recommend that you define a user function for this initialization and run it during the Start event. In this example, the function InitData first transmits the user event FunctionStarted. Parameters have been set for the configuration so that LED 1 lights up in response as an indication that a user function has been executed. After that, the user constant Constant is read in and assigned to the variable u_const. Next, the variable signalvar is initialized to 0. If key 1 is pressed, the user function SampleFct is executed. This also transmits the user event FunctionStarted as its first task. Next, data for a CAN message is read in by means of the reference from the USERCFCT.H file. The value of user constant that has already been read in is written into byte 0, which contains the signal Function- SignalConst. The value from signalvar is written into byte 1 of the message. Information about signals of a CAN message is contained in the database and can be displayed with the CANdb Editor. After this assignment, the variable signalvar is incremented. If it has exceeded the value 255, it is reset to 0. The value of the signal FunctionSignalVar is now incremented by 1 after each transmission.

121 109 /*********************************************************************** Project: Sample Configuration File name: function.c Description: Sample for User Functions C O P Y R I G H T Copyright (c) 2002 by Vector Informatik GmbH All rights reserved ***********************************************************************/ #include <userclib.h> #include "usercfct.h" //introduces the API functions //prototypes defineassertfilename; //file name for user assertions #pragma class pr=userfunctions static uint8 u_const; static uint8 signalvar; static mqhuge tcantxobject txobject; //CAN transmit object /* * Name: InitData * Function: Reads the user constants from the configuration * Parameter: none * Return: none * */ void InitData( void ) { cbsetuserevent(uevent_functionstarted); u_const = cbgetconstant(uconst_constant); signalvar = 0; } // end of InitData /* * Name: SampleFct

122 110 * Function: Sends a CAN message * Parameter: none * Return: none * */ void SampleFct( void ) { cbsetuserevent(uevent_functionstarted); if (cbgetcantxobject(can1_tx_msg_tx_spontan, &txobject)==0) { txobject.aucdata[0] = signalvar; txobject.aucdata[1] = u_const; if (cbcantransmit(&txobject)==0) { // automatic change from 255 to 0 because of type: unsigned char signalvar++; } } } // end of SampleFct Listing 3: FUNCTION.C Now bring up the Generate dialog in the CANister Configurator. Remove the marking from the checkbox C header/code. The two files USERCFCT.H and USERCFCT.C must first be reinstalled if the configuration has been modified in such a manner that relevant changes have resulted in these files. This is automatically recognized by the CANister Configurator so that this checkbox must be selected if necessary, making compilation possible. Since these two files would not be changed, however, it is possible to select the checkbox Compile. Now select the checkboxes Compile, Generate and Download. Select both single configurations in the list box. Now start the generation process. The Tasking compiler creates the file USERCFCT.HEX for both single configurations in their directories. During the generation process, the files HIGHSPEED.HEX and LOWSPEED.HEX are generated from this file and from the configuration. These are then loaded into CANister. If the compilation fails, the file USERCFCT.HEX will not be created. All additional steps will thus also fail. Since the configuration TUTORIAL_4 was created with Save As, however, all important files of the TUTORIAL_3 configuration, including the Hex files, are copied into the new directories. These files USERCFCT.HEX do already exist yet. They have therefore been loaded into CANister in the event of an error. You will find error messages in the files TASKING.TXT and <NAME OF SINGLE CONFIGURATION>.ERR. Check your own C module and the file MAKEFILE in addition for errors. Also check in the Options dialog box to see whether the path and name of the Tasking compiler are correct.

123 Configuration with Network Management In this example, the functionality of network management is used to permit functions of CANister by establishing a connection to a network node (CAN connect event) or to suppress such functions (CAN disconnect event). These two events can only occur in combination with the action Start network management. Please note that the attribute for network management must already be present in databases for real control units if you would like to use them. Only in these cases can it be assumed that network management is implemented even in the control unit. Exercise 7: The total configuration from Exercise 6 will be modified in such a manner that it would work correctly in a CAN network with network management. If there is a connection to network management, LED 9 is switched on. If there is no connection, LED 10 is switched on. First, save the total configuration from Exercise 6 again under the new name TUTO- RIAL_5.CSK. Now use the CANdb Editor to save the database SAMPLE.DBC under the name SAMPLENM.DBC. Expand this database so that it supports network management. For information on changing databases, refer to the documentation of the CANdb Editor. Insert the modified database into the two single configurations. To do this, switch in the tree view to the Databases node and click on the button for the free cell in the first column. Select the file SAMPLENM.DBC as the second database. Assign CAN channel CAN1 to this new database in the single configuration Highspeed and CAN channel CAN2 to it in the single configuration Lowspeed. Then perform the following instructions for both single configurations. There are no differences between them. The entire single configuration should be reworked so that all messages are used from the database SAMPLENM.DBC instead of database SAM- PLE.DBC. This is not a problem, since the two databases should be identical in all respects except for network management. To make this change, select the same receiving nodes and the same cyclic message for the second database. Then switch to the event Key 5 pressed and select the database SAMPLENM.DBC for the action Set message signal. Do the same for the event Key 5 released. In the node for the events Message transmitted and Message received, the database SAMPLENM.DBC is also displayed now. Select the same messages here as in the database SAM- PLE.DBC. All actions must now be copied from the database SAMPLE.DBC into the database SAMPLENM.DBC for the transmission event Msg_Tx_Spontan and for the receiving event Msg_Rx. The easiest way to do this is to drag the source event in the tree view with the mouse onto the target event and release it there. This is shown in Figure 92: Drag and Drop. Drag Msg_Tx_Spontan from SAMPLE.DBC into SAMPLENM.DBC. Do the same with Msg_Rx. Now copy all actions of the Start event into the CAN connect event.

124 112 Figure 92: Drag and Drop Now the SAMPLE.DBC database can be deleted from the single configurations. To do this, switch in the tree view to the Databases node and select a cell from the line with the SAMPLE.DBC database. Now press the keys <Ctrl>+<D> key or select the Delete command from the main Edit menu or from the context menu of the right mouse button. The dialog box Figure 93: References is then displayed. This means that the database is used four times in the single configuration. Figure 93: References The following references appear in this example: The receiving node Tester from SAMPLE.DBC The cyclic message Msg_Tx_Cyclic from SAMPLE.DBC The transmission event Msg_Tx_Spontan from SAMPLE.DBC The receiving event _Rx from SAMPLE.DBC If OK is selected, all of these references will also be deleted with the database. If you select Cancel, it will not be deleted. Now select OK.

125 113 The single configurations will now be changed so that a connection must first be established with network management before additional messages can be transmitted or received over the CAN bus. Everything else remains unchanged. For this purpose, the actions from the Start event must first be modified. The LED action is modified so that LED 10 is turned on in addition to indicate that there is no connection to network management. Only the key 8 should be enabled for the Highspeed single configuration and the key 4 for the Lowspeed configuration, so that it will be possible to switch from one single configuration to the other. This is a permissible action, since no access to the CAN bus results from it. To do this, change the action in the two single configurations accordingly. Delete the action Cyclic messages. The action User function remains unchanged. As the next step, the CAN connect event must be changed. It is always initiated when a connection has been established with network management for the first time with at least one additional network node. Change the LED action here so that LED 9 is turned on and LED 10 is turned off. All other LEDs will remain unchanged since the status LED for the single configuration in question has already been set in the Start event. Since access to the CAN bus can take place from this place on, change the Keys action so that keys 1 and 5 are enabled. All other keys remain unchanged. The Cyclic messages action also remains unchanged. Delete the action User function, since InitData has already been called during the Start event. As soon as a connection to network management has been established, messages can be transmitted to the CAN bus or received from it. If the connection to network management is broken now, there can be no more access to the CAN bus. When the connection is broken, the event CAN disconnect is always initiated. You should therefore stop cyclic messages in this event. Disable keys 1 and 5 as well, so that no CAN messages can be transmitted. Since the key 5 may possibly have already been depressed while the connection was being interrupted, set the signal of the cyclic message back to 0 as well. After that, turn LED 9 off and LED 10 on to indicate that there is no more connection present. You can see the results in Figure 94: CAN disconnect. Figure 94: CAN disconnect After you have made these changes to the two single configurations Highspeed and Lowspeed, the total configuration is now in a format that can be used with CANister on a CAN network with network management.

126 Configuration for LIN These samples demonstrate how you can implement a LIN Master and a LIN Slave using CANister. The process that you have already become familiar with in working with CAN can also be used for LIN. This means that you can also use a database whose LIN messages are transmitted via the CANister Configurator by means of actions. The Schedule table is implemented using timers. For LIN Master and LIN Slave configurations, the SAMPLE_LIN.DBC database is used. Three LIN nodes are defined in the database: one Master and two Slaves (Slave1 and Slave2). The table demonstrates the correlation between the defined LIN messages and the LIN nodes. LIN nodes Master Messages LinMsgMaster1 LinMsgMaster2 Slave1 LinMsgSlave1_1 LinMsgSlave1_2 Slave2 LinMsgSlave2_1 Table 13: LIN nodes for sample configurations The below figure shows the Schedule table with the timely sequence of messages as well as the time intervals of the individual slots. Figure 95: Schedule table (CANdb++)

127 115 The following is assumed for both configurations:: LIN node CANister as LIN Master CANister as LIN Slave Master CANister simulation Real node Slave1 CANister simulation Real node Slave2 Real node CANister simulation The configurations are set up in such a way that they complement one another. This means that with one CANister as a LIN Master and one CANister as a LIN Slave, the LIN network can be completely simulated. The bus termination resistance is 1 kω for Master and 30 kω for Slave. You will find a detailed description in both of the following samples included in the CANister Configurator's scope of delivery. You will find the LIN samples in the \SAMPLES directory. SAMPLE4.CSK: SAMPLE5.CSK: LIN Master LIN Slave Configuration for LIN Master The following explains how sample 4 is created (SAMPLE4.CSK). Exercise 8: Create a LIN Master using the Configurator. To do this, use the LIN database from sample 4. Implement the Schedule table using timers. Simulate the Master and Slave2 nodes. The Slave1 node is adopted as the real network node. Create a configuration using the LinMaster single configuration. Now, select the LIN setting for the channel in which the LINpiggy is inserted. The CANister LinL is delivered with the LINpiggy inserted into the CAN1 channel by default. Please note that only one channel can be used for LIN. Lastly, in the next column, select the baudrate for the LIN bus. The following explains how sample 4 is adjusted (SAMPLE4.CSK). Figure 96: Settings LIN channel For each single configuration, for the LIN Type, define separately whether you want to implement a Slave or a Master. In this sample, the CANister works as the Master. Additionally select the LIN version.

128 116 Figure 97: LIN type and version (Master) Now with the node Databases, insert the LIN database sample_lin.dbc from the.\samples\sample4\dbc directory. Afterwards, for node Receiving nodes, select all receiving nodes displayed. In contrast to CAN, here you should always select all receiving nodes. Figure 98: Receiving node for LIN The Schedule table (see Figure 99) is implemented in the Configurator using a spontaneous timer. During this process, the individual timers are activated one after the other. The user can have these timers and Send message actions generated automatically for this Schedule table by selecting the checkbox in the Generate column. When the checkbox is activated a dialog appears in which the user chooses whether the specific LIN message should be sent out as just a header, or as a header with data. Header+Data must be selected for the messages LinMsgMaster1, LinMsgMaster2 and LinMsgSlave2_1 in this dialog, but simply Header is selected for the messages LinMsgSlave1_1 and LinMsgSlave1_2. The name of a generated timer is composed of the name of the Schedule table, the name of the message (Frame) and the Slot ID. The generated timers are added at the Definitions Timers and Events Timers nodes. Figure 99: Display of Schedule Table in CANister Configurator

129 117 Before you can transmit or receive LIN messages, the action LIN Communication (Start) has to be called. In the sample, this action is called by pressing key 1, it can also be set using the event Start, for example. Communication should be stopped by using the action LIN Communication (Stop). Figure 100: LIN Communication For LIN messages that can be fully sent by CANister, select the action Transmit messages using the transmission type Header+Data. The column with transmission type (Type (LIN)) is only available for messages from LIN databases. LIN messages have to be completely transmitted for all LIN nodes that are simulated by CANister. Besides the Master, these can also be Slaves that are not really available. In order to transmit a LIN header, use the action Transmit message and select Header as the transmission type. This transmission type is only available for messages from LIN databases. The LIN header always has to be transmitted if the connected Slave places its data on the bus. Figure 101: Transmit LIN header and data The action Transmit message using the transmission type Header is used to transmit a LIN header. The LIN header always has to be transmitted if the connected Slave has to place its data on the bus. Figure 102: Transmit LIN header You can then change the data contained in the messages of the simulated Master or Slave by using the action Set message signal. Figure 103: Set LIN message signal If you have not already automatically generated the timers for the Schedule table, define five simple timers at the Definitions Timers node, in order to implement the Schedule table. The number of timers has to be identical to the number of slots in the Schedule table. In the sample, the timer for the first slot (Table1_LinMsgMaster1_S0) is started by pressing key 1 with 20 ms. Afterwards, for the Timer event, set for each

130 118 timer the following timer as well as the message that is supposed to be transmitted in the current slot. When doing so, make sure that the messages LinMsgMaster1, LinMsgMaster2 and LinMsgSlave2_1 are completely transmitted by CANister. Only the header of the messages LinMsgSlave1_1 and LinMsgSlave1_2 are transmitted because Slave 1 is adopted as a real network node according to the specification. The subsequent step from the overall overview demonstrates how the Schedule table is implemented using the timer as well as the LIN messages. Figure 104:Schedule table with timer Exercise 9: Create another single configuration with the functionality from Exercise 8 in which a signal from a received LIN message is additionally interpreted by means of a C function. Copy the single configuration LinMaster for node Total configuration Single configuration and name the new single configuration LinMasterFct. All settings and actions are automatically accepted in the new single configuration. Interpreting signals from LIN messages is done exactly the same way as CAN messages (see Tutorial Section 5.5). For the Message received event, select the LIN database with the LIN message to be interpreted. For this message, insert the action User function using the C function selectled after defining this C function for the node Definitions Functions. Your C module provides you with the LIN message data via the library function cbgetlinrxobject(). /************************************************************************** Project: CANister Configuration File name: function.c Description: C module for user C functions