UPT Programming Tool
This document is part of the online help system for MKT's Terminal Programming
tools for UPT (User Programmable Terminals with CANopen)
and devices without CANopen (like MKT-View II/III/IV - see feature matrix).
The original purpose and design goals of the programmable devices was...
- show signals received via CAN bus in numeric form on the built-in display
- switch between different programmable display pages (like 'motor', 'gearbox', 'brakes'), controlled by the operator
- send special ("programmable") CAN messages in response to user input
- fast boot, only a few seconds between power-on and execution of the user's application
- low cost (the original device used an 8-bit controller and just a 128 * 64 pixel LC display)
- graphic display- and control elements like bitmaps, buttons, bargraphs, diagrams, tables
- a device simulator, integrated in the programming tool, to develop applications without 'real' hardware
- a script language to control those elements, and to 'talk' to external devices and control units
- support for larger displays (in 2015, up to 800 * 480 pixel TFT displays with 64k colours)
Example for a recent user-programmable display (2013) : MKT-View III with 2*CAN and Ethernet on the right side.
A list of devices supported by MKT's programming tool can be found in the feature matrix.
Beginners may want to start with the
presentation of the programming tool,
which is heavily linked to this help system (only in German language so far).
Some of the new functions explained in this manual are available since
( = compilation date in ISO-Format, applies to the device firmware and the programming tool) .
Terminal programming tool - Help Contents
- Program start with or without 'Disclaimer'
- The Main Window
LCD simulator window and LCD device selection
- Device Selection / LCD Settings (screen resolution, colour model, landscape/portrait mode)
- Communication Channels
- General properties of Variables
- Finding all references to a variable, function, signal, string, etc (globally)
- Variables on SDO channels
- Variables on PDO channels
- Variables connected to the own CANopen object dictionary
- Variables connected to "CANdb"-Signals
- CANopen SYNC configuration
- CANopen NMT configuration
- Devices with 'CANopen V4' (most terminals with 32-bit CPU)
- The CANopen object dictionary (OD)
- PDO-Mapping with the Terminal Programming Tool (for CANopen V4 only)
- EDS files (electronic device specification)
- EDS/DCF-Generator to transfer the CANopen-configuration into a PLC software (like CoDeSys)
- General Terminal Options
- Checking the supported graphic functions
- Checking external file references (in the application)
- Programming tool 'Settings' tab (for CAN, serial port, memory, ..)
- CAN bus timing parameters (dialog window)
- Programming Tool Settings (with directory paths, etc)
- UPT File Description (string displayed in the 'App-Selector')
- Simulation of the memory card (on a PC, as replacement for the memory card in a 'real' device)
- Definition of a Text Array
Introduction to programmable display pages, with an
overview of available display elements
- The page definition header
- Definition of display lines (manually, without the graphic editor)
- Properties of a display line (position, font, colour, text, ... )
- The Format String with backslash sequences and HTML-like 'tags'
- Edit Fields on a programmed display page
- Buttons (and similar 'active graphic areas')
- Icons (bitmap graphics)
- Using Display Lines as Menu Items
- Bargraph diagrams (optional)
- Y(t)- and X/Y-diagrams (optional)
- Multi-Line Text Panels (for the script language)
- Inserting other grahic elements on a display page
- Overlapping graphics
Touchscreen support (in certain terminals)
- Introduction to programmable display pages, with an
The "simple" editor for display pages
- The page editor's toolbar
- Dialog box for alphanumeric display elements
- Creating and modifying polygons
- Creating an anlog meter (needle instrument)
- Defining Events overview
- Display Page Overview ("all pages")
- Display Page Gallery
- The Icon import screen
- User defined fonts
- Settings (tabsheet in the programming tool)
Data Transfer between programming tool and device
- Transferring the application into the terminal ("Upload")
- Screen Snapshot via CAN (or HTTP?)
- The PC's CAN-Interface
- Terminals with integrated virtual COM port (USB-to-Serial adapter)
- Remote control (for devices without a keyboard)
- Transferring other files (with the File Transfer Utility)
- The UPTs internal System Menu
- Advanced Information
- The Error Page
The Display Command Interpreter
- Numeric Expressions
- Keyboard Functions
- Detailed explanation of 'kh' and 'kc' (keyboard functions)
- System Key Codes returned by the kc function
- Arithmetic and other functions
- PDO Functions of the UPT-Display-Interpreter (CANopen)
- SDO access functions (CANopen)
- CAN bus status flag, CAN reception (generic)
- String Functions
- String Expressions
- Real Time Clock functions
- Timer functions
- Bit-Counting function ("nbit")
- Functions to access non-volatile values (nv[0..31])
- Functions to read (onboard-) analog and digital inputs
- Functions for the rotary encoder knob (rot.xxx)
- Functions for an (optional) analog joystick
- Interpreter Commands
- "System" functions and -commands of the interpreter
- The script editor / compiler / debugger (only for certain devices with 32-bit CPU)
- Advanced Information for the experienced user.
- Audio Recorder (only available in certain terminals)
- CANopen configuration (only for terminals with "CANopen", not for MKT-View with "CANdb")
- CAN Logger (controllable via interpreter commands, MKT-View only)
- Channels define Communication Channels (PDO, SDO, possibly CANdb).
- Debugging helps to find errors in your application.
- Diagram function (not for UPT515)
- Display Page Overview shows all programmed display pages.
- Error page shows all kinds of errors and other messages.
- Examples for UPT515 (CANopen), MKT-View "+"
- Feature Matrix with an overview of programmable CAN-bus terminals
- Settings display and modify some terminal settings.
- Global and Local Events and reactions for your application.
- Glossary (abbreviations and definition of technical terms)
- Help On Help gives you more info about this Help System.
- Icon screen to import icons (graphic images) into your program.
- LCD Simulator Window describes the window of the LCD simulator.
- LEDs (how to control LEDs on the keyboard panel through interpreter commands)
- Interpreter Commands like goto, special graphic commands etc.
- Main Window describes the programming tools main window and its main menu
- Menu Link Dialog to assign new 'jump destinations' for menu lines
- Numeric Expressions for events and other purposes: Numbers , Operators , Variables , ...
- Overview of numeric Interpreter-functions, and a few string-functions
- Other optional functions: using the serial port, GPS-decoder
Page Definitions defines everything on a certain
including lines with a format string, edit fields, menus, icons, bargraphs and buttons.
- Program Upload - how to transfer the application into the target
- Revision History to trace compatibility problems.
- System menu (inside the programmable terminal) - adjust contrast, illumination, etc
- Text Array can be used for indexed error messages
- Unlocking special features (in the terminal's system menu)
- User-defined fonts - only avalilable for certain terminals !
- Variables define Variables for your application.
- XMODEM, YMODEM (file transfer via RS-232 or Telnet)
Use your browser's back button to return here.
Hint: If you use a good browser like Firefox, and open the help system from the utility, this document will automtically be scrolled to the right position. The same was possible with IE6. But with IE7 and IE8, this doesn't work anymore. Now it's your decision which browser to use.
The HTML-browser used by the programming tool to show the help pages is freely adjustable (regardless of the "Default Browser" on your system). To define the browser for showing the help pages, select "Help" in the programming tool's main menu, then "Define HTML Browser Command Line".
(Example using an alternative browser, on the author's PC installed under "P:\Iron_Browser")
Note: This help file is still quite "preliminary".
Some 'printable' manuals are located in "DOKU\MANUAL.DOC": "DOKU" ( a bit outdated), furthermore a description of the System Menu, and finally the special functions for terminals with CANdb (instead of CANopen). Note: The latter document is available in german language only.
Eine deutsche Übersetzung ist mittlerweile verfügbar, das englische Original ist aber grundsätzlich am aktuellsten, weil uns die Zeit fehlt nach jeder Änderung auch alle Übersetzungen zu überarbeiten. Sorry folks !
Namings for products in this manual, that are registered trademarks, are not separately marked. The same applies to copyrighted material. Therefore the missing ®(r) or ©(c) does not implicate, that the naming is a free trade name. Furthermore the used names do not indicate patent rights or anything similar.
CANdb® is registered trademark of Vector Informatik GmbH.
NTCAN API is copyright (c) by ESD electronic system design GmbH.
PCAN Dongle and the PCAN API is copyright (c) by PEAK-Service GmbH.
Microsoft, Windows, Win95, WinNT, WinXP® are registered trademarks of Microsoft Corporation.
The Hershey fonts are a collection of vector fonts developed circa 1967 (!)
by Dr. Allen Vincent Hershey while working at the U.S. National Bureau of Standards.
The software and accompanying written materials (including instructions for use) are provided "as is" without warranty of any kind. Further, MKT Systemtechnik does not warrant, guarantee, or make any representations regarding the use, or the results of the use, of the software or written materials in terms of correctness, accuracy, reliability, currentness, or otherwise.
The entire risk as to the results and performance of the software is assumed by Licensee and not by MKT Systemtechnik or its distributors, agents or employees.
THERE ARE NO OTHER WARRANTIES, EITHER EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE,
WITH RESPECT TO THE SOFTWARE, THE ACCOMPANYING
WRITTEN MATERIALS, AND ANY ACCOMPANYING HARDWARE.
32257 Bünde (Germany)
This software and appendant hardware may influence or control a CAN-based system or network. Your actions can therefore lead to severe damages. For this reason, only persons which have understood the possible consequences of their actions with this product may use it.
The manufacturer's warranty shall be restricted to the terminal hardware itself, but does not cover effects caused by its use in a CAN network. Neither MKT Systemtechnik nor its employees or partners will be liable for improper use of these products.
HIGH RISK ACTIVITIES
The Software is not fault-tolerant and is not designed, manufactured or intended for use or resale as on-line control equipment in hazardous environments requiring fail- safe performance, such as in the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, direct life support machines, or weapons systems, in which the failure of the Software could lead directly to death, personal injury, or severe physical or environmental damage ("High Risk Activities").
MKT Systemtechnik specifically disclaim any express or implied warranty of fitness for High Risk Activities.
If you do not agree to the above limitations, please uninstall the software, and send the hardware back to the distributor IMMEDIATELY. He will then refund the price you paid for the unit. Customers of MKT Systemtechnik please contact via email, info (at) mkt (minus) sys (dot) de.
- Press F1 if you need help on any component of the programming tools user interface, for example if you want to know what the "display property"-window is for. Before pressing F1, click on the element (to set the "focus" to the dialog element).
Press F2 if you need help on one of the
interpreter commands of the User
For "simple" edit-fields, place the blinking cursor on the command you need help about, then press F2.
For "tables", click into the cell with a command, leave the mouse on the command, then press F2.
The programming tool will then try to analyze the contents of the input field where the cursor is blinking, and switch to the help page with information on that particular command.
Note on both types of "specific help":
- These help functions only work, if the main window of the programming tool is the "active" window. You can tell the active window from all other windows by the color of the window title, a blue window title usually indicates the active window.
Also try the table of contents if you need further help.
For translators of the help system into other languages: please contact the author for details on the HTML anchor names !
Download the programming tool which matches your hardware from the MKT-Webseite . For devices with 'CANdb' support, use the installer named 'InstallCANdbTerminal.exe'. For devices with CANopen 'V4', use 'InstallUptTool2.exe'. For ancient devices (like "UPT515") with CANopen V3, use the installer named 'InstallUptTool1.exe'.
If you also wonder why there are these three different programming tools, follow this link .
If the HTML-based help system doesn't work properly, you may modify the
command line to invoke the browser (e.g. Firefox, Chrome / Iron, or if nothing else is available "Internet Explorer"),
as described here. That way, you can use any
browser as 'help system' for the programming tool, not necessarily the system's "default browser".
The installed program, as well as its installer, must be executed with administrator priviledges (at least with a 'local administrator' account) !
Unfortunately we never saw the installation on a PC with 'english' windows 7, so below is the german original, describing how to update the CANdb-Terminal Programming Tool
- Programm starten (rechte Maustaste > Als Administrator ausführen)
- Menüpunkt Hilfe / Auf Updates prüfen (per Browser)
Das MKT-Browserfenster öffnet. Wählen Sie den Link >here<,
Download wird automatisch gestartet.
Schließen Sie das CANdb-Terminal Programming Tool nachdem
Download beendet ist.
Wichtig: Installieren Sie dieses Update aus dem Download-Ordner Ihrer
lokalen Festplatte (rechte Maustaste > Als Administrator ausführen)!
Folgen Sie den Anweisungen. Danach starten Sie das CANdb-Terminal
Programming Tool neu,
Sie arbeiten nun mit der aktuellsten Version.
Another annoyance related with Windows 7/8/9(?) are the desktop icons, created by the installer.
By default, they will also try to launch the program without admin rights.
Consequence: The program is unable to write its own configuration file (*.INI), located in its own directory. Thank you, Microsoft. Workaround: Modify the desktop shortcut ("icon on the desktop") to launch the programming tool as administrator.
Here is how to achive this with a certain flavour of windows 7 (as usual, things may be different in other and future versions of windows..) :
- After installing the program, right-click the shortcut ("icon on the desktop")
- In the context menu, select 'Properties' ( ? - 'Eigenschaften' on a German PC )
- In the dialog window which appears then, select 'Compatibility' (tab or menu or whatever..)
- Set the checkmark for option 'Run this program as administrator' ( ? - 'Programm als Administrator ausführen' on a German PC)
- Click OK to close the dialog window
Reason for the necessity of an administrator accound under Windows 7 / 8 / 10 :
In opposition to earlier windows versions, these days Windows doesn't grant write permission for files which have been placed in the application's own directory (see examples below). But, for tradional reasons, the installation script keeps 'all files in one place' instead of spilling all over different folders of your harddisk (like, in german, those annoying "Eigene Dateien", "Dokumente und Einstellungen", and similar crap which changes with each new version of Windows). For that reason, you will still find the examples in the following folder :
- PC with 'german windows' :
- C:\Programme\MKT\CANdbTerminalProgTool\Programs\*.cvt; *.upt
- PC with 'english windows' :
- C:\Program Files\MKT\CANdbTerminalProgTool\Programs\*.cvt; *.upt
oder (possibly, depending on where Microsoft wants to have 32-bit applications
- PC with 'german windows' :
- C:\Programme (x86)\MKT\CANdbTerminalProgTool\Programs\*.cvt; *.upt
If you prefer to follow the "new rules" (by Microsoft) and store 'your files' where they want you to, you can change the default directories after installation of the programming tool, on the tool's 'settings' tab.
Alternative to circumvent the trouble with "Vista" or Windows 7 and non-writeable folders and stupidly padlocked files ():
Do not install the program where Microsoft wants you to install everything.
Instead, install the software in a directory of your choice (where you will have unlimited write permission), outside the Microsoft-dictated 'Programs' folder. For example (again, on a German PC):
- Instead of installing the software somewhere under
- "C:\Programme\MKT\xyz", alias "C:\Program Files\MKT\xyz", or wherever they want you to,
- install the software under
- "C:\MKT\xyz" .
- C:\Documents and Settings\All Users\Documents\no idea where.. (Windows XP, english)
- C:\Dokumente und Einstellungen\Alle Benutzer\Faselblah\keine Ahnung wo.. (Windows XP, deutsch)
- C:\Users\Public\Public Documents\...?...\no idea where.. ("Vista", english)
- C:\Users\Frustrated Windows User\Documents\Where the heck are MY FILES\..??.. (some other PC)
If you used the suggested destination (for the programming tool), you will find the samples for your target device at:
|c:\MKT\CANdbTerminalProgTool\programs||(with subdirectories for different targets)|
|c:\MKT\CANdbTerminalProgTool\programs\script_demos||(Examples for devices with script support)|
|c:\MKT\CANdbTerminalProgTool\programs\MKTview2||(Examples for MKT-View II / III, most without script)|
|c:\MKT\CANdbTerminalProgTool\programs\MKTview4||(Examples for MKT-View IV, most using scripts)|
After installing a new programming tool, there will usually be new functions available.
To make sure that these new functions are also available (functional) in the programmable device,
the device's firmware may have to be updated, too. Otherwise, the new functions will only be available
in the simulator (which is part of the programming tool) but those functions won't work on devices
with outdated firmware..
- When invoking 'Check for Update (via browser)' in the tool's 'Help' menu,
you will see an excerpt from the version history, with the latest changes
on the beginning of the list. Some of these modifications don't just apply
to the programming tool, but to the device firmware.
So you can decide for yourself if you need those 'new features' or not.
If your web browser cannot be invoked via the tool's Help menu, you can reach the same website from here through the following link:
MKT-View III with CANdb + Logger ISO-Date: 2013-07-22 16:24:00 Software: art11392 V0.2.4-1 (...) Compiled: Jul 24 2013 (RV) (...) press ENTER to quit
'ISO-Date' is the current date and time in ISO-format. It doesn't have anything to do with the firmware compilation date !
'Software' is the identification of the device firmware, including the software article number (art...) and the version number (Vx.y.z-b) .
'Compiled' is the the firmware compilation date. Details about this in the next sub-chapter.
Details about how to update the firmware can be found in the programming tool's 'firmware' folder (after installing the tool, of course). The 'firmware' folder contains the most recent firmware files for the most common devices by MKT, and a description of how to update the firmware (fwupdate.htm) .
For rarely sold, or custom developments, the firmware is not included in the programming tool.
If the programming tool was installed into the recommended directory, you will find the firmware in the following folders:
|c:\MKT\CANdbTerminalProgTool\firmware||(for devices with 'DBC', e.g. MKT-View II / III / IV)|
|c:\MKT\UPT_ProgTool2\firmware||(for devices with CANopen, e.g. UPT128, UPT800 )|
In some cases, there is a 'DBC' (CANdb)- as well as a CANopen-firmware aviablable for the same hardware - see Feature-Matrix.
(Links to the Feature-Matrix - click on image to check if there's a "CANdb" or "CANopen" firmware available for your device)
This entry in the table of 'Terminal Constants' is the compilation date, in ISO8601 format (YYYYMMDD) of the firmware used in the programmable device. The programming tool needs to know this parameter to decide if a certain function is available in the target system (or, if some functions use a different syntax, etc). Also, if the programming tool "knows" the firmware compilation date of your target device, it will not offer certain function in selection lists ("combo boxes") to avoid problems later, when you transfer the display application via memory card.
- On November 27, 2009, the syntax of certain graphic display elements has been modified in both the programming tools, and in the firmware of a few devices produced by MKT. Since then, the width and height of a display element is entered in two extra columns of a page's display definition table. Older devices (for example the old "MKT-View") don't support this, and thus loading a "new" application into such an "old" device would cause problems.
To avoid such problems, the programming tool will only show the columns "W" and "H", if the firmware compilation date is at least 20091127 (ISO8601, YYYYMMDD).
Originally, the programming tool was always connected 'directly' (via CAN or RS-232) to the programmable device, and could read the compilation date of the device when downloading or uploading the application.
With the more-common method of "transferring" the application "as a file on the memory card", this is not possible anymore, because no data can be transferred from the programmable device back to the PC / programming tool !
Due to this 'unidirectional' transfer (from PC via memory card into the device), the programming tool can only be informed 'manually' if about the firmware revision / compilation date of the to-be-programmed device. The device's firmware compilation date can be read out through the system menu . Details, and how to invoke the system menu, are in document #85115.
- Example: "Old" MKT-View (MKT-View "Plus"), Firmware #11089 .
Compilation date 2008-12-02 (shown as "Compiled: Dec 2 2008" in the
ugly __DATE__-format of the C-Compiler)
The value displayed in the programming tool under "Settings"..."Terminal constants"..."Firmware compilation date" must never exceed 20081202 then.
Otherwise, there may be the risk that you use a feature in the programming tool which doesn't exist in the firmware yet !
If necessary, the date can be modified via mouse click on the compilation date (numeric value in ISO-8601 format)
You can check if there is a newer firmware (along with a newer programming tool) through the menu "Help" .. "Check for Update", or (if a stupid or paranoid web browser doesn't co-operate) in the file readme.txt in the "firmware" folder after installing a new programming tool .
Known problems with older firmware are listed in the firmware Release Notes .
The disclaimer is a dialog window in which the user's language and his self-assessed expertise level ("user profile", Novice / Intermediate / Expert) can be selected.
"Disclaimer" dialog, displayed on program start
You will know that password after reading this documentation - especially the chapter about firmware updates.
In the main menu, select "Tools"..."Remove disclaimer on startup".
You will be prompted for a password. Enter "i agree" (without the double quotes) and click OK. Next time you launch the programming tool, the disclaimer will not show up. If you enter a wrong password, the disclaimer message will appear again.
The same password dialog may also pop up in other situations which require a higher level of authorisation, for example when updating device firmware.
1.4 The Main Window
The main form represents the window that you see after starting the program.
Depending on the user's proficiency level ("Novice"/"Intermediate"/"Expert"), some parts of the user interface may actually be hidden.
- define Communication Channels
- configure the supported communication protocols like CANopen or CANdb (depends on the tool used)
- define Variables that use Communication Channels
- define Display Pages that you want to have on the User Programmable Terminal
- define Icons for your terminal application
- show an overview of all your "programmed" display screens
- display and modify some settings of the device and the programming tool
- show errors in an error history window
At the bottom of the main window you will see a status bar, which displays system information and the latest error message.
return to the table of contents
The programming tool's main menu contains the usual functions to load and save files, editing functions, some more specific functions to transfer the application into the terminal, and functions to change settings and options of the programming tool.
- Functions to load application from a file (*.upt or *.cvt), save as file, define password for the application, etc.
- may help you to create simple applications, or invoke dialog screens to link menus in the terminal, and replace variables (which are shown on the current display page)
- Contains a global search function, and functions to create and modify display pages. Many other "editing" functions can be invoked through popup menus when clicking on the control elements with the right mouse button !
- transfer the application into the terminal, firmware update, selection of the (serial) interface
Switch to other windows of the programming tool, for example:
LCD simulator, Watch window, Test Command Window, File References.
Modify options of the programming tool, query supported graphic functions,
change memory distribution in the terminal. The following options
affect the appearance of the programming tool's user interface (GUI)
but not the application created with the tool:
- User profile "Novice" :
- Novices may configure simple numeric displays by picking signals from a list,
and mainly (almost exclusively) use the 'simple' graphic editor.
The programming tool only displays the basic tabsheets which are 'always' required to create a very simple display application.
- User profile "Intermediate" :
- The more experienced user doesn't freak out when seeing a lot of tabsheets in the upper part
of the programming tool (he knows which one to chose). The programming tool still starts with the
graphic editor instead of the tabular display (with 'all display elements on the current page').
- User profile "Expert" :
- An expert user prefers to enter sourcecode directly (for the display definition and the script),
and is familiar with tables, pixel coordinates in numeric form, the versatile format strings.
In this mode, the programming tool starts with the tabular display of all elements on the first display page. The Expert knows how (and when) to switch between graphic and tabular display. He sees all tabsheets in the programming tool.
- Invoke external auxiliary programs, which may be installed additionally - for example the font editor, CAN logger utility, etc.
- Import graphics from bitmap files
- Run, Stop, Reset
- start, stop, and reset the simulated application on the PC
- Show help on various topics. Requires a properly installed HTML browser, but not necessarily an internet access
return to the description of the main window
1.4.2 Status Bar
At the bottom of the main window is a status bar, which displays some information about the current system state (e.g. "Transfer in progress" and so on).
By clicking at the "Simulator"-button you may switch to the LCD-simulator window (if its not already visible).
The second panel from the left (here: "Running") shows a quick info about the current state of the programming tool or the application program. Some possible labels are:
- Running: Your application is running (i.e. it is being executed)
- Stopped: Your application has been stopped for any reason
- Transfer: A program upload or download is in progress.
The right field in the status bar will display the last error message (if any) or other system messages. In the example shown above the last system message was an indication that the CAN interface has been successfully initialized.
You may switch to the error page by double-clicking into the status message field.
For debugging purposes you may also send a command string to the UPT's command interpreter by typing it into the status message field.
return to the description of the main window
The LCD simulator window is used to show the contents of the LCD screen, which you would see after loading your application into the user programmable terminal.
This window shows the current display page.
As long as the LCD simulator window has the "input focus" (blue title background), all keyboard inputs will be passed on to the terminal simulator.
This allows you to test your programmed event handlers etc.
The LCD simulator window can be moved and sized independent of the main window. You may even maximize it to a real "full screen view". The panel below the simulated display shows the state of (optional) LED's, digital in- and outputs. If you don't need this, or run out of (PC-)screen space, turn the lower panel off through the simulator's menu.
By clicking into the LCD simulator window with the left mouse button, you can select (or move) a single text display line. The MAIN window of the programming tool will automatically switch to the display definition tab ("Page N") where you can modify all properties of the selected line.
Holding the left mouse button pressed on a visible display line in the simulated display while slowly moving the mouse allows to move the display line aroud (only works for normal text display lines, not for general graphic commands like "line", "rectangle" etc).
When simulating terminals with a touchscreen, the left mouse button is the replacement for the "finger" (or touch pen). To check if the simulated device has a touch screen or not, use the dialog for supported graphic functions.
Clicking into the simulator window with the right mouse button opens a popup menu, which allows you to insert several display elements on the current page, and to enable the mouse wheel as a replacement for the terminal's rotary encoder knob (while the simulator is running). The option 'stay on top' (ex: 'always in the foreground') may be helpful if you only have one monitor connected to your PC, and want to debug the application (or the script) with the tool's main window maximized.
You can copy the contents of the simulated LCD into the windows clipboard by pressing "ALT-Print" while the LCD simulator window has the focus. This allows you to put "screenshots" of the simulator into document (like "users manuals" etc). You can also transfer screenshots from a real terminal into bitmap files using the snapshot via CAN utility.
If the LCD settings of the simulator dont match the display in your target device, you have to enter the LCD simulator settings to adjust them.
- Hint regarding the LCD simulator's "frame" or background image:
To align graphic buttons or other objects close to the function keys of the
terminal's keyboard, turn on a suitable background picture for the
LCD simulator (in the simulator's menu). In the
backgrounds folder, you will usually find the right
picture (bitmap) for your keyboard. If not (for example because you use a
customer specific keyboard) :
For customer-specific keyboards, usually only the surface will have a different "look", but the position of the keys will usually not be modified. So one of the standard images should be ok. If not, you can make your own background picture with a paint program as a bitmap file. Please note, the black framed region of the LCD must exactly match the size of the simulated display in pixels. Everything inside the LCD must remain white !
For a self-defined background image (like lcdsim_XYZ.bmp) you must also create a matching description file (lcdsim_XYZ.txt) with the graphic coordinates of the keys (which can be clicked to simulate pressing a key). A good example for such a 'background image description' is the file for the MKT-View II .
At the time of this writing (2013-11-14), the installer for the programming tool contained a few 'standard' background images, and a few customer specific designs:
used for the old UPT 515 (128*64 Pixel) .
used for HBG 18 (128*160 Pixel) .
used for 'ABE' handheld (128*64 Pixel) .
used for old MKT-View (320*240 Pixel) .
an OEM design (320*240) .
used for MKT-View II, III (480*272 Pixel) .
used for DT85 (320*240 Pixel) .
|Your design here ?||
Select this file if no background image
shall be displayed in the LCD simulator.
return to the table of contents
Since the introduction of large displays in March 2001, the UPT programming tool supports different types of displays. Usually the programmig tool will detect the type of the display automatically when uploading or downloading a UPT file from (or into) the target. All required information about the display is stored in the UPT program file. So, if you load a UPT file from disk, the proper LCD settings are automatically adjusted.
If you have no possibility to connect the programming tool to a target, you must define the LCD type of the simulated device yourself (otherwise the simulated screen will look very different from what you will see later..). To do this, enter the following dialog (from the Main menu, "Options" ... "LCD settings"):
Some example settings:
Screen width=128, Screen height = 64, Display type = 1 (monochrome)
- UPT 167 "monochrome", IPE-View, MKT-View:
Screen width=320, Screen height=240, Display type = 1 (monochrome)
- UPT 167 "Color":
- Screen width=320, Screen height=240, Display type = 4 (4 bits per pixel). Discontinued, replaced by "UPT 320 Color" .
- MKT-View, MKT-View "+":
Screen witdh=320, screen height=240 Pixel; display type=1 (monochrom)
- MKT-View "+", CANdb or CANopen, mounted for "Portrait Mode"
Screen width=240, height=320 Pixel; Anzeigetyp=1 (monochrom)
(Please note that your application must be written for portrait mode right from the start !
The programming tool cannot convert a program from 320*240 to 240*320 pixels automatically)
- MKT-View II, Landscape
Screen width=480, height=272 Pixel, TFT with 256 different colours (8 bit
/ pixel), touchscreen.
This is the default configuration for the MKT-View II, when mounted with the connectors on the right side of the device.
- MKT-View II, Portrait
Screen width=272, height=480, used for MKT-View II when mounted with the connectors
on the bottom of the device.
Similar 'Landscape' / 'Portrait' options are available for other devices, too.
See also: Selecting clockwise / counterclockwise rotation in portrait modes.
- MKT-View III, with Landscape and Portrait mode
- Screen resolution 480 * 272 or 272 * 480 Pixel, 4.3"-TFT with 65535 colours (16 Bit/Pixel).
Successor for the MKT-View II with a faster CPU (Cortex-M3).
- MKT-View IV, with Landscape and Portrait mode
- Screen resolution 800 * 480 or 480 * 800 Pixel, 7"-TFT with 65535 colours (16 Bit/Pixel).
Funktionalität similar to MKT-View II/III, but faster CPU, and significantly larger.
- MKT-View V, with Landscape and Portrait mode
- Successor to the MKT-View III with similar size but much faster CPU,
and at least one CAN FD capable interface (details were unknown in 09/2019).
- UPT 320 "Color":
Screen width=320, height=240 Pixel, 5.7" TFT with 65536 different colours
(16 bit / pixel), touchscreen, rotary encoder button, ARM CPU, keyboard with
6 (?) keys.
Replacement for the discontinued "UPT 167 color". Firmware available for raw CAN / CANdb (#11352) and for CANopen (#11353) .
- UPT 800:
7" - Display panel with 800 * 480 pixel ("WXGA") TFT, 65536 colours (16 bit
/ pixel), Touchscreen, but neither rotary encoder button nor keyboard.
Designed for panel mount. So far (2011-11), only available as prototype with "CANdb". Firmware #11372 (for Controller type LPC2478, ARM-7, not ARM-11).
If a standard device (with standard firmware!) is used, the programming tool
will know everything it needs to know about the target from an internal
All these settings are updated when selecting Options...Device Selection / LCD settings from the tool's main menu.
1.5.2 Optional Setup (LCD backlight settings, formerly only accessable through the device's built-in system setup)
Since 2011-07-12, the display (LCD) in few new devices can optionally be configured through the programming tool. Formerly, these hardware specific settings could only be modified in the device's built-in system menu (via System Setup / Display Setup / LCD Dimming) .
To open the following configuration screen, select Options ... Display Setup from the programming tool's main menu .
Important: When transferring the display application (*.upt or *.cvt) into the target device, these settings will only be included (in the download) if the checkmark 'Include these settings when downloading the configuration' has been set in the dialog shown above. If that option is not set, the display setup will not be saved (or sent), keeping it compatible with earlier firmware revisions.
In fact, when downloading a *.upt or *.cvt file which has the 'Include these settings'-flag set, these settings actually overwrite the system settings one single time. After that, they can still be modified through the terminal's built-in system menu, unless the key to invoke the system menu has been disabled through the 'general UPT options'.
Note: The efficiency of certain display backlights (usually white LEDs, but sometimes CFL tubes) may vary greatly between different devices. Thus the same 'brightness' control value may give different results on different devices. Details on the automatic (ambient-light depending) LCD brightness control can be found in the description of the device's system setup menu, see document #85115 .
This page is used to define the communication channels which the terminal uses to exchange data with other devices on the CANopen network.
There are different types of communication channels:
SDO channel (Service Data Object)
a "slow"device-to-device connection which allows to exchange data from a devices object dictionary. Many different objects can be accessed through a single SDO channel !
PDO channel (Process Data Object)
a "fast" communication channel which is used to transfer process data with a high priority, for example digital inputs, analogue values from sensors etc.
'Signals' defined in a
This optional functionality is only implemented in the programming tool for terminals with CANdb-functionality and therefore not explained here.
Details about variables connected to generic CAN signals ("CANdb"-signals) are here .
The type of a communication channel is implicitly defined by a variable's channel number (if it is connected to a communication channel).
Note that the terminal should only "listen" to PDO channels. It can not request the transmission of a PDO from another device (because this may cause a lot of trouble ...)
You have to define at least one communication channel for every device that the terminal shall communicate with. The channels will later be used to transfer values from other devices into the variables of your terminal program.
return to the table of contents
1.6.1 SDO Channels
- SDO channels are not supported by the MKT-View terminals with 'CANdb' !
Only for a few devices (like MKT-View II,III), there is also a firmware variant which supports CANopen.
SDO channels provide a versatile but "slow"device-to-device connection which allows to exchange data from a devices object dictionary.
You have to define the CAN-identifiers of all SDO-channels which the terminal shall use to communicate with other devices. You can do this later with a CANopen configuration tool (if you have one), or in the SDO-channel table:
You will find the Identifier values in the description of the device that transmits a particular PDO or in the CANopen Draft Standard 301 (CiA "DS301"). Most I/O-devices use a "pre-defined connection set" with the following definitions for the SDOs CAN-Identifier (which DS301 calls "COB-IDs").
SDO(server->client) : CAN-Identifier = (1408+node-ID) = 1409...1535
SDO(client->server) : CAN-Identifier = (1536+node-ID) = 1537..1663
All CAN-Identifiers here are decimal values. The "client->server"-ID will be transmitted from the client (which is the UPT) to the server (which may be an I/O-module) to initiate a transfer ("request"). The "server->client"-ID will be transmitted from the server to the client (as "answer"). If you prefer hexadecimal notation for the CAN-IDs, you can change this on the ID format panel.
Hint: If you erase all cells in the above table, only enter the server node ID's, and click "Apply" afterwards. The tool will then fill out the missing CAN ID fields according to the predefined connection set specified in CANopen DS301.
- Always be aware:
- An SDO connection is just a "point-to-point" link between two partners. You must take extra care to use only SDO connections that are not yet occupied by other devices. If a simple I/O-device only has one SDO channel and this SDO is already occupied by an other device (maybe a PLC, SPS, a servo drive or something else), you must not connect the UPT to this device via "active" SDO request because this would cause severe collisions on the network (same CAN-ID transmitted by several devices, SDO protocol violations etc.).
In the User Programmable Terminal, a variable can be connected via SDO to an other device in the network. With the newer "MKT-View with CANopen" and other (newer) UPT's with 16-Bit-CPU it is possible to read values through the build-in SDO client via interpreter funktion "sdo(<index>.<subindex>)", without using a variable.
- Variables on SDO channels
- The CANopen Object Dictionary (one of the key elements of CANopen!)
- CANopen object index and subindex
- Using SDO channels (clients) in the script language: cop.sdo, cop.sdo2
- EDS files (electronic device specification)
- Features for devices with 'CANopen V4' (applies to most devices by MKT with CANopen and a 32-bit CPU) .
1.6.2 PDO Channels
- PDO channels are not supported by the "CANdb" terminals (CAN without CANopen) !
PDO channels provide a "fast" communication channel that is used to transfer process data with high priority, for example digital inputs, analogue values from sensors etc. One PDO telegram can carry different parameters (if the transmitting device allows "variable PDO mapping"). More info can be found in the CANopen standard published by CiA.
In contrast to SDO-Channels, a single PDO-channel is always a one-way-street where the flow of traffic cannot be reversed during operation.
The following table is used to define all PDO channels ("RX" and "TX"):
For any PDO channel that you want to use in your application, you have to define:
the CAN-Identifier used by the PDO (sometimes
can be set to the default value (according to DS 301) with the button 'Default IDs'.
Use the button labelled 'Communication..', or double-click into the 'CAN-ID' column to open a Dialog to modifiy the PDO Communication Parameter - it may be easier for you to pick the values from a dialog instead of entering them in the PDO table.
- the transmission direction (transmit, receive or "be passive")
- the transmission type as it is defined by the CANopen-standard. Similar as for the 'COB-ID' (CAN-ID), it may be easier to use the PDO Communication Parameter dialog to pick one of the quite 'cryptic' PDO transmission types.
- the transmission cycle ,
- and possibly- some flags to activate "special" PDO functions .
In the (old) User Programmable Terminals like UPT515, a variable should be used to receive values from a PDO channel, or to put some data bits into a PDO which will later be transmitted, depending on the PDOs transmission type.
In the (newer) UPT II (like UPT320, UPT800), there are special variables in the CANopen Object Dictionary, which solely exist to be mapped into PDOs. They can be accessed from the application through their CANopen-index and -subindex (using the obd()-function), or be tied to interpreter variables. Because these variables do always exist, they are listed in the terminal's EDS-file, and can therefore be used by any CANopen configuration tool to setup the PDO communication in the network. More on that in the document about CANopen "V4" .
Be careful when tansmitting PDOs on a CAN-network which you do not know exactly ! Transmitting a PDO with the wrong identifier may cause a minor catastrophy - just imagine what would happen if you accidentally started an electronically controlled motor which *should* be off...). For this reason, the UPT was originally not able to transmit CAN messages, but "receive only" (this limitation had to be removed when someone wanted to use the UPT515 as a kind of PLC). Usually a CANopen device configurator / network configuration manager is used to configure "everything" in the network, including the process data channels. In newer devices with CANopen V4 (see Feature Matrix) the PDO's are controlled exclusively through the PDO communication- and mapping parameters, which are part of the standardized CANopen communication profile. So these parameters can be accessed from any CANopen configuration tool, after you loaded the application into the terminal. More information on this can be found in an extra document.
In a CAN network it is not allowed that more than one device transmit the same CAN identifier. Therefore the terminal should only "listen" to a PDO channel.
With the old UPT515 (since September 2001), it was possible to modify some of the PDO channel definitions with the UPT's interpreter. See PDO-Functions .
For terminals with CANopen V4 (since April 2005, see feature matrix), the PDO parameters can NOT be modified through the interpreter - instead, they can only be controlled through the terminal's local CANopen object dictionary !
- variables (of the interpreter)
- variables on PDO-channels
- channel number of a variable (which defines the type of the communication channel, too)
- fixed-type variables in the CANopen object dictionary of the terminal ("CANopen V4" only), which can be accessed through the function obd(<index>.<subindex>) .
You have to define the CAN-identifiers of all PDO-channels which the terminal shall receive. You will find the Identifier values in the description of the device that transmits a particular PDO or in the CANopen Draft Standard 301 (CiA "DS301"). Most I/O-devices use a "pre-defined connection set" with the following definitions for the PDOs CAN-Identifier (which DS301 calls "COB-IDs").
PDO1(tx) : CAN-Identifier = (384+node-ID)10 = 385...511
PDO1(rx) : CAN-Identifier = (512+node-ID)10 = 513...639
PDO2(tx) : CAN-Identifier = (640+node-ID)10 = 641...767
PDO2(rx) : CAN-Identifier = (768+node-ID)10 = 769...895
All CAN-Identifiers here are decimal values. Note that "tx/rx" in this table has to be seen from the I/O-devices point of view, so the "tx" PDOs are transmitted by an I/O-module and can be received by the UPT. The possible values for node-IDs are 1..127. Simple devices like I/O-Modules often use a DIP-switch to set the node-ID.
You want to receive the state of digital inputs of an I/O-Module. The I/O-Module
uses its PDO1(tx) to transmit process data, which contain the digital inputs.
The node-ID of the I/O-Module is set to "1", so the resulting CAN-Identifier
will be (384+1)=385(decimal).
To receive this PDO with the UPT-Terminal, you want to use the first PDO-channel of the UPT. Just enter the value "385" in the column "CAN-ID of PDO". The UPT is now able to receive a PDO with this identifier, and you may define variables that use the PDO data as "input values".
- Changing a CANopen device's node-ID shall affect the
PDO CAN identifiers, according to the 'predefined connection set' specified
by CANopen CiA "DS301". If your applications requires
a different CAN identifier for a certain PDO, first change
the node-ID (which resets most CAN-identifiers to the defaults),
and after that modify the CAN-IDs on the 'Channels' tab under 'PDO',
as shown in the screenshot further above.
This is always necessary if two (or more) CANopen slaves shall exchanged data via PDO directly, without a CANopen master (-> "PDO Linking") .
Since April 2000, the UPT515 supports Reception and Transmission of PDOs. Therefore you have to specify, if a PDO channel shall receive(1), transmit(2) or be passive(0). For devices with CANopen V4 (since 2005), the transmission direction is fixed for all PDO channels like in an ordinary CANopen device. See feature matrix .
Note: "Transmit" and "Receive" must be seen from the UPTs point of view.
Since April 2000, the UPT515 supports different types of PDO transmission.
The PDO transmission type is defined by a numerical value. It is taken from CiA DS301.
You may find more information on this in CiA Draft Standard 301, Version 4.0 (16.6.1999), Page 9-83 in the description of Objects 1400h-15FFh (PDO Communication Parameter), Table 54, "Description of transmission type":
A transmission type of zero means that the message shall be transmitted synchronously with the SYNC object but not periodically (?????).
A value between 1 and 240 means that the PDO is transferred synchronously and cyclically, the transmission type indicating the number of SYNC which are necessary to trigger PDO transmissions/receptions.
The transmission types 252 and 253 mean that the PDO is only transmitted on remote transmission request. The UPT515 treats both 252 and 253 exactly the same way.
Transmission type 254 is "manufacturer specific" (which is not defined yet).
Transmission type 255 is "defined in the decive profile" (which does not exist here).
For transmission types 254 and 255 you can use a PDO's Event Timer for cyclic
(but not sync-related) transmissions. See transmission cyclePdo_TxCycle.
Since August 2013, the PDO transmission type can also be modified in a special PDO Communication Parameter dialog.
The PDO transmission cycle can be used for cyclic PDO transmission without a SYNC object.
This works similar like a PDO's event timer as described in CANopen DS301 V4.0, see description of object 0x1400 subindex 5.
Note: Since September 2001, a PDO's transmission cycle can also be reprogrammed at runtime with the UPT interpreter. See PDO-FunctionsPdoFunctions .
These "Flags" have been implemented for "very special PDOs".
Only the last PDO channel can be configured to be a "System State PDO" by setting the FLAG value to "1".
The "System State PDO" has the following contents:
- Byte = UPT run mode ("Status"??) .. ignore this byte !
- Byte = digital Inputs of the UPT
- Byte = current display page of the UPT
- Byte = Key-Matrix, the "first" 8 keys of the keyboard driver.
- Byte = Key-Matrix, the "next" 8 keys of the keyboard driver.
You should leave all flags "zero" to use flexible TX-PDO-Mapping from Variables.
Again, the fixed 'system PDO' described above only exists in the old "UPT515"
with 8-bit CPU. All newer, user-programmable CANopen terminals (with 16-
or 32-bit CPU) use flexible PDO mapping so we don't need this 'fixed' mapping
(On this occasion: Early samples of the UPT128 used a membrane keyboard labelled 'UPT515', but in fact the UPT128 is not a UPT515: It has a modern 32-bit CPU inside, not a stoneage 8051-compatible controller).
In CANopen, 'PDO mapping' basically means 'defining the contents of a PDO telegram' (CAN frame carrying process data).
Due to the complexity of CANopen, the documentation was moved into a separate document .
1.7 Application Variables (display interpreter variables)
The tab sheet "Variables" of the programming tool is used to define all variables which the terminal will use to show and modify parameters.
All variables are defined in a table, their properties can be edited in the table or on a special property panel.
Most of your variables will be connected to a communication channel, but they can also be used as internal variables which keep temporary values etc.
- All "display variables" can be accessed by the display-interpreter, which means a variable name can be a part of a numeric expression.
- The name of a variable must always begin with an upper-case letter, and it may never have more than 8 characters. Only in certain devices with CANdb functionality up to 16 characters may be used (see constant parameter "max var name length" under Settings).
- The above limitation does not apply to script variables ! Script variables are not defined on the tabsheet 'Variables'. Instead, they are declared the script sourcecode.
- To assign a new value to a variable during run-time, use the assign command ("@"). This only makes sense for ('display'-) variables which do not receive their values from a communication channel.
- To show the value of a CANopen object on the screen, you don't need to connect it to an application variable. You can access any CANopen object (inside the device's own CANopen object dictionary) by its CANopen index and -subindex ( obd(index.subindex) ).
- Connecting variables to display lines with a special dialog
- Communication Channels
- Variables on SDO-Channels (only for certain terminals)
- Variables on PDO-Channels (only for certain terminals)
- Variables linked with objects in the terminal's own CANopen OD
- Variables on CANdb-SIGNALS (only for certain terminals)
- CANopen object index and -subindex
- Variable as part of a numeric expression for the interpreter
- Components of a variable which can be accessed via interpreter
- fixed-type, fixed-index CANopen variables (only for terminals with CANopen V4)
- Inspecting variables remotely, using an internet browser (only for devices with ARM-CPU)
- Finding all references to a variable (in global events, local events, display pages, etc)
- script variables
You can define all display variables in the table shown below, on the 'Variables' tab in the programming tool.
Script variables are not defined here, but in the Script sourcecode.
Network variables are a subset of display variables, using definitions imported from a DBC file ("CANdb"), or which (for CANopen devices) can be accessed via SDO, PDO, etc.
(Example of a table with variable declarations; here for CANopen)
Variable properties are:
- Name : Up to 8 characters for small systems (like UPT515), otherwise up to 16 characters
OD-Index : Only for CANopen; non-empty means this variable is connected to
one of the objects
in the terminal's own CANopen object dictionary. Details here .
Channel : Defines if
and how a variable is connected with the outside world :
0...4 = SDO client (CANopen), 5...9 = SDO server (CANopen), 10..19 = PDO (CANopen),
30 = connected to a so-called signal which is defined in a DBC-file ("CANdb", not CANopen)
31...99 = reserved for future communication channels (device specific)
100...149 = reserved for devices which have more than 5 CANopen SDO clients
150...199 = reserved for devices which have more than 5 RPDOs (Receive-PDOs)
200...249 = reserved for devices which have more than 5 RPDOs (Receive-PDOs)
250...254 = reserved for future, "exotic" communication channels
255 = this variable is not connected to the outside world (it only exists "internally").
The programming tool automatically shows the meaning of the numeric code in the definition table.
- Channel-params: PDO / SDO / CANdb_signal_definition (channel type specific)
- Update Time (or "cycle time" for CANdb-signals)
- Data Type: Should be modified only for 'internal' variables !
- Unit (only for CANdb, where physical units are defined in a database)
- Access Rights: 0=read only, 1=read/write, 2=write only
- Flags: Automatically filled in by the tool (where applicable)
- Default Value
- min, max: Limit the value for display and editing (on screen).
factor, offset, divisor: Used to convert the value sent via CAN-bus into the physical value.
Do not modify these parameters manually; they are usually taken from a database (CANdb) !
- DAQ channel number (DAQ = data acquisition unit; optional; details here )
During the simulation (in the programming tool), the current values can also be displayed
in an extra column of the definition table. To activate this option, check
Show current values in the table (last column) in the context menu.
Most properties of a variable can be modified on this "property"-panel:
Some properties (components) of a variable can also be accessed during run-time of the terminal application from the UPT's interpreter.
The update time of a variable defines, how often a variable will be updated from its input channel.
A Variable is connected to an analogue input of an I/O-module via SDO, and the Update-Time is set to "500".
In this case, the Terminal will send a "read request"-telegram every 500 ms via SDO to the I/O-module. As soon as the I/O-module answers with a "read response"-telegram, the new value for the variable is taken from the response and converted into a 32-bit-value for the variable.
- Only for variables which are connected to CANdb-"signals":
Here the 'update time' has the meaning of a 'transmission cycle time'.
In old devices (like MKT-View "Plus"), the cycle time also affected the strategy for allocating message-objects in the 'Full CAN' controller.
For transmitted CAN-Signalen (from the MKT-View's point of view), the 'Upd-Time' parameter defines the transmit cycle (for periodically transmitted CAN frames).
If necessary, the transmit cycle can be modified at runtime as in the following examples:
(Source: Test/demo application ?/programs/CdbSendT.cvt, page 4)
ThreeSines1.cy := 0; // Turn off periodic transmission ThreeSines1.cy := 300; // Periodically transmit every 300 ms
The data type of a variable defines the internal storage format and the legal value range (if it is a numeric variable). The UPT only supports numeric data types from the CanOpen-Standard. Floating point values are only supported by terminals with 32-bit CPU (ARM-7 or Cortex-M, for example MKT-View II / III). Most values are internally converted into signed 32-bit integer values (which is the "internal" storage format for all variables and expressions inside the UPT).
Data types used in the Variable Definition Table use CANopen data types, even if the terminal itself doesn't support CANopen.
(as defined in CANopen)
( as defined in CANopen)
|I8||2||8 bit SIGNED integer|
|I16||3||16 bit SIGNED integer|
|I32||4||32 bit SIGNED integer|
|U8||5||8 bit UNSIGNED integer|
|U16||6||16 bit UNSIGNED integer|
|U32||7||32 bit UNSIGNED integer|
|F32||8||32 bit floating point||not supported by some devices|
|STR||9||"visible" string ("printable" string of characters)|
|OCT||10||Octet string (a CANopen speciality ! )||not supported by any device|
If a variable is connected to a CANdb signal, the programming tool may show 'S' (signed) or 'U' (unsigned) instead of the codes shown above. But internally, any received signal is internally converted into the best fitting data type listed in the table above.
The even more exotic data types mentioned in the CANopen standard DS301 (like "time of day") are not supported by the programmable terminals.
UPT515: Variables which are connected to CANdb signals may be handled as
floating point values internally. Please note that the mantissa only contains
about 24 bits. Values like 1000000.05 cannot be stored in this kind of "short"
floating point variables !
You can determine the (CANopen-compatible) data type of a variable at
runtime using the "ty" property ("type")
- To convert a numeric data type code (a la CANopen) into a human-readable string, use the function type2str() (type-to-string) .
The property "Access Rights" of a variable defines if it can be read and/or written via communication channel.
- For example:
- A variable is connected to an analog output of an I/O-module via SDO, and you want to set the voltage of that output with the terminal. After assigning a new value to the variable (by editing it or by assigning a value with the assign-command), the terminal will send a "write request"-telegram via SDO to the I/O-module to update the output. The variable must be writeable for this purpose.
A "read-only"-Variable will never be transferred to an external device via communication channel.
A "write-only"-Variable will never be read from an external device via communication channel.
With a few exceptions (for CANdb) below, the access-rights of a variable are coded as numeric values according to the CANopen-Standard.
- Possible values are in this case (CANopen):
0 = Read Only
2 = Write Only
For variables connected to CANdb signals, the
column "Access" in the variable definition table shows if the signal is receved
or transmitted from the terminal's point of view.
(Reception is the normal case, Transmission will only be possible with new firmware since November or December 2009) .
- Possible "Access" values are, in this case (CANdb):
RX = The terminal receives this signal from the network (and all other signals
contained in the same CAN-message !)
TX = The terminal transmits this signal into the network (and all other signals contained in the same CAN-message !)
In contrast to CANopen, combined read/write access (as in CANopen) is impossible in this case,
because a CANdb file doesn't specify any protocol for that !
These values can also be seen in the combo box on the variable's property panel .
In complex display applications, you may ask yourself where a certain variable is used,
or if it is still in use anywhere at all. One possibility is to simply search for its name
in the display application (*.upt or *.cvt) with a text editor.
An alternative is to let the programming tool search for all references of a display variable. The variable-search is a available in the context menu of the variable definition table:
- Click into the variable definition table on the name of the variable (here: Tank1Level).
- Click on the 'Menu' button above the table, or click into the table with the right mouse button
(screenshot of the context menu for the variable definition table)
The programming tool will search for the name of the variable in...
- all global event definitions, in both the 'Event', and the 'Reaction' column;
- all local event definitions, on all pages;
- all display definition lines, also on all pages;
- all lines of the Script Editor (where such variables are prefixed by the keyword 'display.') .
(screenshot of the 'search variable reference' result window)
A similar function like the 'variable name search' is the global text search function,
which can be invoked through the programming tool's main menu (Edit .. Search (globally))
or from the script editor's context menu (right-click in the editor).
In contrast to the search for variable names, the global text search ignores quotation marks, and can thus be used to find any test, even in double-quoted string constants.
Click on any of the result lines to switch to the event / display line definition where the variable is used (or where the text was found).
This can give you a quick overview about the usage of certain variables, and look for orphaned variables (variables which are not in use anymore).
To close the modal dialog window, click 'Ok' or 'Cancel'.
The search results are also displayed as plain text on the error page ( → 'Errors & Messages'), from where they can be copied for documentation. A double- or right-click on a search result on the error page also switches to the place where the text was found (display page, script line, etc). Thus, switch between the 'Script' and 'Errors' tab to toggle between the the script sourecode and the list of search results.
back to the overview of Application Variables
See also: Declaration of Script Variables .
- SDO channels are not supported by the MKT-View terminal (CANdb only)
A variable can be "connected" to an object in an other device in the network via SDO channel.
The "objects" of a CANopen-device are located in a so-called dictionary. Every object of this dictionary is defined by its Object-Index and Subindex .
These parameters are defined on the following panel, which will be visible if the current variable is connected to an SDO-channel:
To "connect" a variable to an object of a CANopen-device, you have to define:
- the SDO channel number (which connects the UPT to a certain device)
- the index and subindex of the CANopen object
- the data type of the object
- the access rights (i.e. "read only")
- Channel number of a variable (which also defines the channel type, like SDO-client, SDO-server, etc)
This chapter only applies to older terminals, with a very old CANopen version.
In newer terminals, only objects in the
CANopen-OD can be mapped into a PDO.
In terminals with "CANdb" (CAN without CANopen), PDO channels are not supported at all !
The input of a variable can be connected to a part of a PDO channel (a PDO can carry up to 8 bytes of information, and you will usually only use a part of that data field).
To "connect" a variable to a PDO channel, you have to define:
- the "UPT-internal" number of the PDO channel
- the number of data bits that shall be transferred from the PDO into the variable
- the number of the fist data bit in the PDO (which is the least significant bit)
- the data type of the object
These parameters are defined on the following panel, which will be visible if the current variable is connected to a PDO-channel:
- In the "UPT-2" (with CANopen V4, like "UPT320"), it is not possible to map interpreter variables directly into a PDO. In those cases, you must use the PDO-mappable variables in the terminal's CANopen-Object Dictionary, instead of mapping the old self-defined variables into a PDO ! To access those variables from the application, use the interpreter function obd(<Index>.<Subindex>) , or connect the CANopen-objects with interpreter variables as explained here . Those special variables have the big advantage of being defined in the terminals EDS-file (in contrast to the self-defined variables), so they are recognized by any CANopen configuration tool - which greatly simplifies the configuration of the network !
- only 1-bit-parameters can be read from any bit-position in the PDO.
- 8-, 16-, 24- or 32-bit-Parameters must start on a BYTE boundary in the PDO data field, so the "number of the first bit in the PDO" must be a multiple of 8. The bit-count starts at 0 (ZERO) not 1(ONE), in contrast to some strange programming languages.
- Parameters with more than 8 databits are always transferred in "low to high-byte-order".
- The UPT simulator does not support PDO functionality, because the PCs CAN-Interface is just a BASIC-CAN-Controller.
In recent devices (especially those with 32-bit CPU), only certain objects from the CANopen OD can be mapped into a PDO, making it impossible to directly map interpreter variables into PDOs. The interpreter can access all objects in the terminal's own object dictionary (using the obd function), but accessing data by hexadecimal indices is not everybody's taste. For that reason, certain CANopen objects can also be linked with an interpreter variable. Each read-access to the interpreter variable then actually reads a CANopen object, and each write-access modifies that object. If the object is mapped into a PDO, the CANopen protocol will possibly update (or send) the PDO.
To make things easier, you don't need to remember which objects can be used for that purpose. Instead, double-click into the column titled OD-Index in the variable definition table (or press ENTER while a cell in this table is selected) :
Double-clicking that cell shows a list of CANopen objects, along with their hexadeximal object indices, along with the unspecific(*) names of these objects:
If the interpreter variable was already connected to one of the objects in
this list, the item will be already marked (here: in blue colour).
- If you are familiar with CANopen, you will have noticed that these indices are simply 0x4000 plus the CANopen data type code, for example code "4" means 32-bit signed integer.
If no CANopen object had been connected before starting the dialog, the program may decide to select an object which matches the variable's data type as close as possible (if enough unused subindices of such an object are remaining). Each object has 10 or 40 subindices, depending on the terminal firmware (option "Monster-OD" only available for devices with 32-bit CPU), resulting in a grand total of 360 individual values which can exist in this part of the OD. Unfortunately, because the CANopen-OD is 'static', these dimensions cannot be changed.
The programming tool will try to pick the next unused sub-index of the object automatically. You can see (and edit) the subindex after closing the dialog box with "Ok" .
Interpreter variables connected with the CANopen object dictionary are always visible to 'the outside world', because a CANopen configuration utility may map it into a PDO (even if you didn't map it in the UPT programming tool). Furthermore, such objects can always be accessed via SDO, if an external SDO client knows the OD-index and -subindex. For CANopen, such external connections are usually configured with a special utility (for example with the CANopen Configuration Manager, which doesn't just configure a single CANopen node, but an entire CANopen network). During normal operation ("operational state"), only PDO will be used between CANopen slave devices, because the few SDO servers in most CANopen slave devices are reserved for the CANopen master, and thus cannot be used by other devices.
Back to the overview of an interpreter variable's properties .
Unfortunately, these objects in the CANopen-OD cannot have 'talking' names,
because the name of CANopen objects is not variable (at least not in the
EDS file). For this reason, you will
only find such general, unspecific names like "Application Vars 32 bit signed"
for object 0x4004 in the EDS file.
To simplify using the display terminal as CANopen slave in combination with external PLC software (like z.B. CoDeSys), the UPT programming tool (2) can generate a DCF (device configuration file), which will then contain the "talking" names (i.e. the name of the variable, if a variable is connected to a certain CANopen object in the display's own CANopen-OD). The UPT VARIABLE NAMES will appear as Denotation in the DCF. Details about the DCF-Generator are here .
For a variable which is connected to an SDO channel, you have to define an index and a subindex.
The "objects" of a CANopen-device are located in a so-called dictionary. Every object of this dictionary is defined by its Object-Index and Subindex.
The Object-Index is a 16-bit-number which is usually defined in hexadecimal format. In the terminal programming tool, hexadecimal numbers begin with the "0x" or "$"-prefix, otherwise the interpreter would treat them as decimal numbers.
The Subindex is an 8-bit-number which is often used for arrays or structured objects.
For example, a DS401-type module with 5 digital inputs may have an Object 0x6020 which contains the state of the digital inputs. Subindex 0 of this object will have the content "5" to indicate that there are 5 digital inputs, subindex 1 will hold the actual state of the first digital input, subindex 2 the state of the second input and so on.
Index and Subindex of CANopen-Objects are often defined in a devices manual. But for many objects you may also find the required information in a so-called DeviceProfile . There are device profiles for different types of CANopen-devices, for example:
DS401: Device Profile for I/O Modules
- digital in- and outputs
- analog in- and outputs
DS401 specifies the CANopen Device Profile for I/O-Modules. If you want to connect any of these objects via SDO to a variable of your terminal program, you have to know the objects index and subindex. (For experts: Sorry, we cannot read EDS files).
Here are some of the specified objects:
Digital Inputs and Outputs
|0x6000||Read State [of] 8 Input Lines||0,1 .. max.4||Unsigned8||ro|
|0x6006||Input Interrupt Mask [for] 8 Input Lines, any change||0, 1.. max.4||Unsigned8||rw|
|0x6020||Read State [of] 1 Input Line||0, 1.. max.32||Unsigned8,
|0x6100||Read State [of] 16 Input Lines||0, [1, 2]||Unsigned16||ro|
|0x6120||Read State [of] 32 Input Lines||0, max. 1||Unsigned32||ro|
|0x6200||Write State [for] 8 Output Lines||0, 1..max.4||Unsigned8||rw|
|0x6206||Fault Mode [for] 8 Output Lines||0, 1..max 4||Unsigned8||rw|
|0x6207||Fault State [for] 8 Output Lines||0, 1..max 4||Unsigned8||rw|
|0x6220||Write State [for] 1 Ouput Line||0,
|0x6250||Fault Mode [for] 1 Output Line||0,
|0x6260||Fault State [for] 1 Output Line||0,
|0x6300||Write State [for] 16 Output Lines||0,
|0x6306||Fault Mode [for] 16 Output Lines||0,
|0x6307||Fault State [for] 16 Output Lines||0,
|0x6320||Write State [for] 32 Output Lines||0,
|0x6326||Fault Mode [for] 32 Output Lines||0,
|0x6327||Fault State [for] 32 Output Lines||0,
DS401 specifies the CANopen Device Profile for I/O-Modules. If you want to connect any of these objects via SDO to a variable of your terminal program, you have to know the objects index and subindex. Here are some of the specified objects:
Analog Inputs and Outputs
|0x6401||Reads value of the input
channel (not converted)
1 [... 4]
|0x6411||Writes value of the output channel (not converted)||0
1 [... 4]
|0x6420||Set Analogue Input Range
1 [... 4]
|0x6421||Determines which events cause an interrupt for a specific channel||0
1 [... 4]
|0x6423||Globally enable/disable Interrupt||0||Boolean||rw|
|0x6424||When enabled, interrupt triggered when analogue input rises above this value (not converted)||0
1 [... 4]
|0x6425||When enabled, interrupt triggered when analogue input falls below this value (not converted)||0
1 [... 4]
|0x6426||When enabled, interrupt triggered when analogue changes by more than thisvalue from previous reading (rising or falling) (not converted)||0
|0x6443||Output Fault Mode||0,1||Unsigned8||rw|
|0x6444||Default Output Fault value (unconverted)||0
Only for certain terminals which support the reception
of signals defined in a CANdb-file (database) !
THIS IS NOT FOR TERMINALS WITH "CANOPEN-COMPATIBLE PROTOCOLS" !
Details about connecting variables with "CANdb"-signals are in a different file .
If an UPT-variable is connected to a CANdb(tm) signal, the column "message/signal definition" contains all information which the terminal will need later to "extract" the variable's value from the received CAN telegrams. This is quite complicated and very different from CANopen ! The basic format of a CANdb Signal Definition String in this column is:
<BusNr>,<CAN-Identifier>,<position of LSBit>,<number of databits>,<INTEL/MOTOROLA-flag>,<signal type>
1 or 2, if the device has two physical CAN interfaces (e.g. MKT-View II/III/IV);
or 3 or 4, if the device supports CAN-via-UDP or LIN.
For MKT-View II / III / IV, "CAN1" and "CAN2" are labelled as such on the adapter cable (or, maybe, "KFZ-CAN1" / "KFZ-CAN2" as requested by some customer).
Those "Bus-Numbers" are usually set when importing a CAN database, because before selecting the database filename, the bus number is selected on tabsheet "CANdb" in the tree view ("CAN1", "CAN2", ...), or by using button 'Load DBC #1' (for CAN1) or 'Load DBC #2' (for CAN2). If anything else fails (because the CAN database isn't available for you anymore), you can edit the bus number on tabsheet 'Variables', but the preferred method of selecting the bus number is importing the database for a certain bus.
= 3- or 8-digit hex number, depending on 11- or 29-bit identifiers for CAN messages
- position of LSB in CAN message
is explained in another document in detail.
For CAN and LIN, data bits in the payload are numbered from 0 to 63.
If we ever get hold of a microcontroller that properly implements CANfd, the numbers may be higher, but the principle ("start counting bits at zero") remains the same.
- Number of databits
is also explained in the other document
- Flag for INTEL- or MOTOROLA format
is what makes CANdb signal processing even more complicated ;-) ...
you already guessed it, details are in another document
I = "Intel" (aka little endian, least significant byte first)
M = "Motorola" (aka big endian, most significant byte first)
- Signal type ("raw signal format" on CAN)
- U = Unsigned (Signal wird auf dem CAN-Bus als vorzeichenlose Ganzzahl übertragen)
S = Signed (Signal wird auf dem CAN-Bus als vorzeichenbehaftete Ganzzahl übertragen)
F = Float (Signal wird auf dem CAN-Bus als 32-Bit-Fliesskommawert übertragen)
D = Double (Signal wird auf dem CAN-Bus als 64-Bit-Fliesskommawert übertragen)
Additional information may be contained in the definition for MULTIPLEXED signals.
Don't try to change the CANdb signal definition yourself here ! It is possible to define everything on the 'Variable' definition tab (and possibly your only chance if you don't have a CANdb file describing your network), but you better use the method described below (and in a separate document) .
The preferred method is to use an external CANdb file editor for this, and re-import the modified CANdb file as explained here. This will take you to the 'CANdb' tabsheet, where you can browse the database, and connect a few signals to display variables ('UPT interpreter variables') :
( CAN Database display; more details here )
See also (concerning 'CANdb'):
- Basic principle to build a display application for CANdb-signals
- Timeout monitor function for CANdb signals
- Modifying the CAN-identifier of a variable connected to a CAN-signal 'on-the-fly'
- Overview of application variables
- CAN Message Generator / Bus Simulator
Not for terminals with exclusive "CANdb" functionality like MKT-View (see Feature Matrix)
The Tab Sheet "CANopen" lets you define some additional CANopen-settings
that do not belong to PDOs and SDOs. At the current time, the following elements
of CANopen can be defined here:
SYNC - Message
NMT (Network ManagementT a la CANopen)
SDO Client Channels (Button to switch to another tabsheet)
SDO Server Channels
See also (concerning 'CANopen') : Programmable displays with "CANopen V4"
CANopen uses the SYNC-telegram to synchronize the transmission of PDOs. The
UPT can transmit (produce) or receive (consume) this message if necessary.
The behaviour of the UPT concerning SYNC may be defined on a special panel
under "CANopen" configuration.
CANopen uses the NMT-protocol to control all nodes in the CANopen network.
NMT objects are used for executing NMT services. Through NMT services, nodes
are initialized, started, monitored, resetted (reset?) or stopped. All nodes
are regarded as NMT slaves. NMT requires that one device in the network fulfills
the function of the NMT Master.
You will find more information on NMT services in CANopen DS301 V4.0, chapter 18.104.22.168 (page 9-41).
The UPT can be either NMT-Master or NMT-Slave, but not both at the same time. The behaviour of the UPT concerning NMT may be defined on a special panel under "CANopen" configuration. At the present time, the UPTs built-in NMT functionality only supports minimum NMT bootup, no extended bootup !! (If you don't know what that is, you certainly don't need it). If the UPT acts as the NMT Master, it can send a "Start Remote Nodes"-broadcast after a programmable "Bootup-Time" (starting with turning on the UPTs power supply).
- CANopen object dictionary of the programmable terminal
- SDO access functions (only for terminals with CANopen V4)
- SDO error codes ("abort codes")
1.9.1 General Terminal Options
(Originally only for "UPT" = user programmable terminal,
meanwhile also for MKT-View and others)
The "General Terminal Options" dialog can be used to set some settings that will be transferred into the UPT when you upload your application. This dialog can be started by clicking on the "General Option"-value on the "Settings"-Tab.
The option Enable System Menu may be turned off if you are
shure that you do not need the UPTs system
menu functions (because you need the keyboard combination F2+F3 in your
own program and you dont want that the user of your application enters
the system menu).
However, even if the option "Enable System Menu" is turned off, you may still enter the UPTs system menu to adjust the LCD contrast if you hold F2+F3 during power-on (but at that point, the application data are not loaded yet, and "secret" parts of your application cannot be inspected).
The option Enable Debugging was intended to be used by the author of the UPT firmware only (because he didnt have a target debugger). You should leave this option off.
The option Readout Protection can be set to prevent reading the currently loaded application from the terminal later (via CAN or RS-232). Please note that this option is only supported by firmware compiled 2009-05-20 or later.
The option Auto-Scale for larger display resolutions should be set if your application doesn't use 'pixel-precise' graphic output, and you want to re-use a program once designed for 320 * 240 pixels on a 480*272-pixel display (without wasting space on the display). More info in the FAQs on how to migrate from the older MKT-View to the newer MKT-View II / III.
The key combination to enter the UPTs system menu can now be changed from the programming tool, because the old (fixed) combination F2+F3 collided with the application of a valued customer. Be careful with this option, because not all key combinations can be detected by some targets (especially those with multiplexed keyboard hardware). If you entered an impossible key combination, you can only enter the UPTs system menu by pressing F2+F3 during power-on.
Depending on your hardware- and the firmware revision, the target system ("terminal") may support one or more of these graphic functions:
- Screen inversion ("inverse" means white characters on black background, see interpreter command "di").
- Graphic buttons
- Bargraph diagrams
- user-defineable fonts
- presence of a touchscreen (required for simulation)
- and other functions which were unknown at the time of this writing !
The following dialog window can be opened by clicking on the "General Option"-value on the "Settings"-Tab:
If a checkmark is not set in this dialog, it does not necessarily mean that your terminal does not support the associated function. The information which of the graphic functions are supported is embedded in the storage file (*.upt or *.cvt). If you load an "old" application, you may find some of the functions indicated as not supported, though your "new" firmware supports them. For this reason, you can modify the "support-flags" in this dialog yourself (*). Usually, after transferring the program into a terminal and reading it back (via CAN-bus) the programming tool knows which graphic functions are really supported, and sets the checkmarks in this dialog accordingly.
(*) be careful not to activate functions which are not supported by the firmware
in your terminal. The resulting display may look very strange after downloading
your application into the terminal !
An overview of devices, firmware variants, and their capabilities is in the feature matrix .
The option "Width and Height of display elements in extra columns" cannot be set directly. This option solely depends on the firmware compilation date. If necessary, the latter can be modified on the 'Settings' tab, for example if a bidirectional transfer between programming tool and the programmable device is impossible (i.e. transfer only via memory card). Devices with firmware older than 2009-11-27 did not support width and height of display elements in these extra columns - instead, width + height were encoded inside the parameter list of a button or bargraph (which is now deprecated).
Some display applications will access files stored on the memory card, or in certain areas of the terminal's internal FLASH memory, for example audio files.
If you wrote such an application, and need to pass it on to somebody else (a customer, colleague, etc), don't forget to include all files which your application uses.
To simplify this task, the programming tool checks for external file accesses during the simulation, and when 'checking all pages'. The result of those tests can be checked by selecting "View".. "External File References" in the programming tool's main menu ("Ansicht".."Externe Datei-Referenzen" in German) :
Each line of the file list contains the name of a referenced file, the display page on which the file was referenced (if it was referenced on a display page), the line number, and the date in ISO-8601 format when the file was last referenced (this hasn't got anything to do with the file's creation date).
If you are sure you don't need the file list anymore, you can delete the entire list in the dialog shown above by clicking the 'Delete' button (button with a red cross symbol).
If you think that certain files are missing in the list, or some old files shall be removed from the list, you can do this manually by editing your UPT (or CVT) application with a text editor. You can find the list of referenced files in the section 'Audio- and other files (REFERENCES)', for example:
; ----- Audio- and other files (REFERENCES) -----
a file0="dog.wav" pn=0 li=1 da=20091207
a file1="puppy.wav" pn=0 li=2 da=20091207
a file2="sheep.wav" pn=0 li=3 da=20091207
pn= page number,
li= 'line of page', and
da= date in ISO format.
The length of the file reference list is limited to 64 entries (due to memory restrictions in the terminal firmware).
Finding all references to external files may sound trivial, but it's not. Consider this interpreter command :
audio.play( "msg" + str("***",AudioMsgNumber) + ".wav" )
where 'AudioMsgNumber' is a numeric value received through some communication channel. It is impossible (at least for the programming tool) to find out which audio file names will actually be produced by the above string expression. Even during a simulator session, not all possible values of 'AudioMsgNumber' may occurr. So, if your application uses tricks like the one shown above, maintain a list of all files used by your application, and don't forget to distribute (or upload) them along with your *.upt or *.cvt file(s).
User-defined fonts may be considered 'external files' too, but at the moment, they are not (and thus *.fnt files are not listed in the file reference table). To find out which user defined fonts are used, check the user-defined font list.
The Text Array is used to define an array of single text lines that you may use in your application to display "text messages" depending on a numerical value.
To use a text array, you have to define how much memory shall be used for text lines. You must sacrifice some "display pages" to get more "text lines". See the settings tab for more info.
To read lines from the text-array in your application, you may call some string functions in text display commands.
You can find a simple example for text
arrays in the second demo file.
- If you only want to display two or three text alternatives (like "ok"-"too hot" - "too cold"), depending on a numerical value, you can use the interpreter's "arithmetic if-then-else" within a format string. This is explained in the chapter BUTTONS(!).
- Popup window (can be used to show text messages which are received from the CAN-bus; acts like a small virtual terminal inside the terminal).
- String functions
A UPT 'display application' contains one or more 'display pages'.
The Page Definition tab is used to define a single display page for the terminal.
It is grouped into several tab which are explained in the following chapters.
(Screenshot of the 'display page definition table' in the programming tool)
- a header definition
multiple display elements which can be defined in text form,
or with the graphic 'page' editor.
- simple Text, with or without the value of a variable (using placeholders like '*****.*'),
- advanced text displays, using backslash sequences,
- edit fields,
- multi-line menus,
- icons (graphic images, switchable depending on signal values),
- bargraphs, vertical or horizontal,
- buttons (user-defineable touchscreen areas),
- text panels (can be 'printed to' via script),
- graphic panels (displays a tCanvas, filled via script),
- tables (via script, also useable as control element / selection list / etc),
- analog meters (pointer instruments),
- lines, polylines, closed and filled polygons,
- some rarely used low-level graphic display commands
- event-definitions (explained later in this manual, after the introduction of the interpreter language. Only required for special applications ! )
Besides the page definition table shown above, display pages can also be modified with a graphical editor (more on that later) :
(Screenshot of the 'simple graphical editor' for programmable display pages)
After starting, the programming tool shows 'page zero' of your application (like the 'real' display after power-on).
To switch to an other page of your terminal program, you may use the page overview , where you can see all pages that you have already programmed.
To switch from one display page to another in the programming tool, use the red-arrow-buttons (,in the upper right corner) or the display page overwiew, where you can see all programmed pages. To switch to another page in the terminal , use buttons, menus, self-defined events, or page-scan-sequences . But first, let's look at the elements which belong to a single display page...
1.11.2 Page Definition Header
The Page Definition Header contains general information about a display page, like :
the NAME of the page. Please replace the automatically generated
name by something more descriptive, like
"MainMenu" instead of "page2". For most target systems, up to 8 characters are allowed (no spaces)
- the flag "Always redraw this page completely"
- the flag "do not clear the screen automatically"
(Leave this option unchecked unless you really need it. When set, the system will not automatically clear the screen before rendering the elements on the current display page. In this case, it's your responsibility to clear the screen 'programmatically', e.g. controlled via script or display-interpreter command).
- the flag "do not update the screen if keyboard buffer is full"
- the flag "circular wrap when navigating"
- the flag "inverse screen (dark background)" [only for certain terminals]
- the flag "include this page in the page-scan sequence"
- A page update interval (in milliseconds), which can reduce the page-update rate, to improve readability of numeric values which are otherwise updated too frequently (making it difficult to read the numbers, especially on stoneage passive LCDs).
- Default text colour, default background colour, Day/Night: Only for colour displays. Details and an example are in another document.
- Special Background Filler: Usually, the background of a display page is just a "blank screen". If you enter one of the graphic commands in this field, it will replace the automatic "Clear Screen" operation. Beware: The "background filler" should erase the entire screen, not just a part of it. Example: Command to fill the screen (here: background) with a colour gradient.
(Screenshot 'Display Page Header' for a programmable page)
If the option always redraw this page completely is selected,
the whole page will always be updated completely. This requires quite a lot
of CPU time but may be necessary if you use
overlapping or moving graphics. A complete
screen update always includes erasing the screen, so there will be no remaining
garbage on the display if you let an icon crawl across the screen.
If "always redraw.." is not activated, only the text lines with modified contents may be updated to save some CPU time. A typical display update-rate will be about 10 screens per seconds (but this depends very much on the number of display-lines with flexible contents).
A typical display-update with the option "always redraw.." took about 250 ms (on old terminals like "UPT-515" and "MKT-View" / "MKT-View Plus" with 8- or 16-bit CPU). On newer devices with Cortex-M CPU (like MKT-View III), even a complete screen-update usually takes less (much less) than 100 milliseconds.
In any case, the update rate greatly depends on the complexity of the display page, and the screen resolution.
As an alternative to the option always update page, you can use the option always update this line on the display line property panel. This will save a lot of CPU power, especially if a large display or a color display is used (UPT 167, IPE-VIEW, MKT-View I / II / III).
1.11.3 Definition of Display Lines
To insert new display elements the easy way, right-click into the simulated LCD, and select what you want to insert from a list. The programming tool adds a new display-definition-line to the table which is described below. Alternatively, you can use the "simple page editor" which is explained in another chapter. Expert users will perfer to type (or copy) the definitions into this table manually.
All definitions for display lines are shown in a table on the page definition sheet:
The table on the left shows all currently defined display lines of the current display page.
The buttons below the table are used to modify the tables contents.
INSERT, DELETE, COPY and PASTE operate on complete lines. The MORE-Button
opens a popup menu (which you can also open by clicking into the table with
the right mouse button).
- The columns (or edit fields) labelled "X" and "Y"
define the position of the upper left corner of the element defined in this
line, measured in graphic pixels.
Besides entering the pixel coordinate in numeric form, you can use the graphic editor to modify an element's position.
The columns "W" and "H"
define the width and height of certain (not all!) display elements, measured
in pixels. For 'normal' alphanumeric display lines, these fields may be
empty (unless text shall be centered or aligned in a fixed-size field).
For other 'fixed size' elements (like buttons, etc) the size must always be specified.
For devices with firmware older than 2009-11-27 (ISO, YYYY-MM-DD), the columns "W" and "H" are not displayed in the table, because old devices (MK-View 1) / old firmware do not support these properties. In case of doubt, check your device's
firmware compilation datein the system menu, and -if necessary- let the programming tool know the compilation date of the device firmware on the 'Settings' tab under 'Firmware compilation date'.
For "normal text fields", width and height are usually not specified (so the element only occupies as much space on the screen as it needs to). For aligned text fields, the field size must be specified (for right-aligned text, at least the width).
In the graphic editor, the size can easily be modified by pulling the lower right 'sizing corner' (small square) with the mouse.
- The "Name" column
is rarely used so far (because only terminals with 32-bit CPU support this
function). If a display element has a name, you can easily access it from
the interpreter or via script, using this name as a reference.
The maximum length of any name in this column is 7 characters.
More details here .
- The "Text" column
can be used as format string for numerical values,
or as a menu item. The text string can also
be used to display icons ,
bargraphs, buttons and
other special graphic elements.
- The column "Var/Expr" column
usually contains the name of a variable, a numeric
function, or a string function which shall be
displayed/edited or an interpreter command which shall be executed if a menu
entry has been activated. The calculated value can be accessed from the
interpreter with the "v"-function.
- The "Access/HotKey" column
defines the access rights for a displayed variable or a hotkey
definition if the display line is used as a menu item (more about this on
the property panel).
- The columns "Draw Mode", "Color", "Font" etc
affect the appearence of the displayed line on the screen (see property panel).
The "property"-panel on the right shows more detailed information about one single display line.
You may edit the properties of a display line in the table or on the property panel, the information will always be updated on both parts.
If the simulated LCD is visible, you will immediately see the effects of the changes to a display line. For example, if you change the Y-Position of a display string via up/down-scroller in the display line property panel, you will see the text moving on the simulated LCD screen. The currently edited display line is marked with a dotted rectangle.
If some graphic elements or text lines on the screen overlap, you should be aware of their drawing order ! The order of the definition lines can be modified with the mouse. Hold the left button pressed while moving the mouse in the column "Nr" up or down. A black horizontal bar shows the location where the moved entry will be inserted when the mouse button is released. This row-moving procedure is also possible in some other tables of the programming tool.
The "display line property" panel shows the properties of a single display line that you selected in the display line table.
If the simulated LCD screen is visible, you will immediately see the effects of the changes to a display line. For example, if you change the Y-Position of a display string via up/down-scroller in the display line property panel, you will the text moving on the simulated LCD screen.
Display Line Properties are:
- X-position, Y-position
- Width and Height of the display element. Details here.
- Base: for example 2=binary, 10=decimal, 16=hexadecimal.
- Text (also used as format string with optional backslash sequences)
Draw Mode (i.e. normal, inverse, blinking; only for monochrome displays).
For colour displays, this field is meaningless because they don't support "blinking" text.
Text- and background- colours (only for color
For displays with 256 colours or more, you can double-click these fields to select a colour from a palette.
The second background colour is used for gradient fills in graphic buttons and similar objects, and to fill polygons.
Standard colour values are listed here.
Hint: Set both foreground- and background colour to -1 (minus one) for most display lines. The terminal will use the default values (from the page header) in that case, so you can easily switch between day- and night-design as explained here.
Font (since 2018, the drop-down list also contains a few vector fonts).
By clicking on the underlined label 'Font', a table showing all characters (or glyhs) contained in the current font can be displayed, along with their hexadecimal codes.
Zooming factor for text and bitmaps. There are individual controls for
'X' and 'Y' (horizontal and vertical axis).
Bitmaps and bitmap-fonts can only be zoomed by 1,2,3,4 .. 15 (integer factors). The scaling range for vector fonts is 0.2 to 15.9, because vector fonts can not only be magnified, but also downsized in small steps.
For any kind of 'display element', this field contains the name of a display variable (which delivers the displayed 'value'), or a short numeric expression, etc.
If the display element is used as a menu item, this field may contain an interpreter command which is invoked when the user selects the item.
Access: The value of
a variable with READ/WRITE access can be
edited during run-time (integer
values only, no floats).
If the access is "read only", the value can be displayed but not modified on this page.
Certain display elements (like bargraphs) will turn into an interactive control element, if this field (in the 'display line properties'!) is set to read/write instead of the default 'read only' access. For example, a bargraph can be used as a slider or scrollbar, operated via touchscreen.
Control ID: Only required
when events for this control element (button, menu item, edit field) shall
be handled in the script
The control ID allows to identify which control element has fired the event, by using a select...case statement in the script.
If this field is empty, the script will not be notified if "something special" (-> event type) happens with this control element.
Screenshot with a list of user-defined script contstants,
after double-clicking on 'Control ID' in the programming tool.
- Flags: used for menu items etc - see list below.
The Flags of a display line can be modified by clicking on one of the check boxes on the property panel:
"Update output channel while editing"
With this flag set, the current value of an edit field will be transferred to the output channel while editing the field, not only when pressing ENTER to finish editing.
"This line is a menu item"
Setting this flag turns a simple Display Line into a menu item. The user may move through the menu on a display page using the cursor keys and press ENTER to execute the command defined in the property "Variable/Expression/Menu Command" .
"always redraw this line
forces the UPT to repaint a single line of the display as often as possible. Use this option if a line has "side effects" like a dynamic text display. You do not need this option to display a simple variable which may change its value (the UPT firmware takes care of this).
Properties wich are not supported by a particular device will be disabled on the panel (weak gray color).
The connection between display lines and variables can be easily modified
with the Variable Selection Dialog.
A "format string" is one of the display line properties of a display line definition. It may contain the displayed text itself, or define how the contents of a variable shall be formatted for the display (thus the name).
The format string can...
- be a simple constant text string like "Hello, world !"
- be a 'switch-list' of different strings, to be selected from a numerical value
- contain special "place holders" like "****" for numeric digits or variable strings
- contain several backslash sequences as explained below
- be used to display icons (in backslash sequences like "\iMyIcon" )
- contain a few simple HTML-like tags, e.g. '<u> underlined text </u>'
- also be used to control the behaviour of edit fields.
* (asterisk) will be replaced by a numerical digit or a single character from a string
- For floating-point values, leading zeroes are suppressed (replaced by spaces), but not for integer values.
# will be replaced by a numerical digit, similar as the asterisk (*) .
- In contrast to the asterisk, leading zeroes are ALWAYS suppressed (for integer as well as floating point).
0 (digit zero): will be replaced by a numeric digit from the value (like '*' and '#').
- In contrast to '*' and '#', zeroes are NEVER suppressed by this placeholder.
. (point) is the decimal separator.
- CAUTION: Older devices didn't support floating-point values in an edit field !
, (comma in the Format-String, not in interpreter commands)
can be used as decimal separator for german users since 2009-10-06;
but only if the comma is immediately followed by a placeholder for a digit.
- will be replaced with the sign
- of a numeric value (+,-)
\\ displays a single backslash
\< displays an opening angle bracket (instead of interpreting it as an HTML tag)
\- displays a "-"-character (minus character, not a placeholder for the number's sign)
\0 displays a "0"-character (zero character, not a placeholder for a digit)
\ar align right (applies to the rest of the text string within its field (*) )
\al align left (applies to the rest of the text string, up to the next alignment option (**))
\ac align centered (applies to both X and Y, for the rest of the string, within its field (*) )
\ah align horizontally centered (center the X- but not the Y-coordinate, i.e. center only horizontally, and leave the vertical position unchanged (*) )
\av align vertically centered (aligns the rest of the string vertically; horizontal position remains unchanged (*) )
\at, \ab : Reserved to align fields on the screen (not the text within its field)
Only for targets with 32-bit CPU and firmware compiled 2013-03-25 or later.
The right and bottom margins for output is the position ("X","Y") plus the fixed size of the display element.
Without a fixed size of the display element, most of the 'alignment' switches treat the right and lower edge of the screen as 'the end' of the alignment area.
The following example from programs\AlignTst.cvt uses coloured backgrounds to show the alignment areas:
\acac:Center \arar:Right \ahah: H-Center \avav: V-Center \av\arVert+Right \avV-Center,\nmultiple\nlines .
It was implemented to modify the default center aligned text on graphic buttons.
inserts a Bargraph (only supported by certain
devices, explained in another file)
draws a Button (only supported by certain
- \chr(N) displays a single character with the code N, from the currently selected font. Examples:
\chr(65) displays the letter A.
\chr(v) displays a character with the code resulting from the numeric expression in the current display line (see "v"-function)
\chr(56) displays a "fast forward" symbol, if the user-defined font font "Webd3232" is selected (only for certain terminals). "Webd3232" is a symbol font, compatible to "Webdings" (c) Microsoft Corporation.
Since 08/2016, for devices like MKT-View III,IV, chr(N) also supports a few Unicode symbols. For Unicode, the code (N) should be expressed as a four-digit hexadecimal number (prefix 0x), e.g.: \chr(0x2611)
(draws a 'checkmark in a box', ☑, usable for 'checklist' tables and buttons with a checkmark).
Alternatively, use backlash-U to show characters by their hexadecimal Unicode value.
- \cN sets the text-color for the subsequent output. N should be one of the
standard colours defined here) .)
\CN sets the background-color for the subsequent output. N should be one of the standard colours defined here) .)
Usually, there's no need to change the colour within the format. Instead,
text colours are defined by the display line properties.
\dia( <diagram-definition> )
part of a Diagram-definition (only supported by
- \e( <expression> )
- Evaluate a string expression (instead of a fixed string). Only allowed at the begin of the format string in a display line definition.
- \fN selects font number N for output (N=same number as in the combo list on the display line panel)
- \fr( x1,y1, x2,y2 )
draws a rectangular frame. The coordinates are *relative* to the display
line's position. Example: Menu \M0\fr(-2,-2,260,32)
insert an Icon (see examples below)
\li( [options] x1,y1, x2,y2 [, x3,y3, ..] )
draws a graphic line or a polygon. The coordinates are *relative* to the
display line's position. Options: w=width(1..3), p=pattern (16-bit for 16
A comma between two points (coordinates) draws a line between these points, a semicolon does not (it only 'moves the pen' to the new point without drawing, aka 'pen up').
As for most other display elements, the colours used for lines or filled polygons are taken from the display element's drawing colours :
- Solid lines are painted with the foreground colour
(the same colour as used for normal text, inidividually defined for each 'definition line');
- The background of the polygon's rectangular drawing area may be filled with the first background colour,
or left transparent (dummy colour value "-2" = transparent).
- Filled polygon areas ("polyfill") use the second background colour.
To insert or edit polygons, the graphic editor can be used instead of editing the polygon 'as text'. But variable coordinates (etc) for animated graphics are only possible by entering the '\li' sequence manually.
\li(0,15, 100,15) draws a line between the two coordinates (relative to the object's position) \li(w=2,polyfill(13,44,52,44,32,12)) draws a filled triangle with 2-pixel wide border \li(font=1, "Test" ) draws a few characters using font 'Hershey Simplex' \li(font=2, rot=45, "Test" ) draws text rotated by 45° (positive = clockwise)
- Solid lines are painted with the foreground colour
\mN switches the draw mode
for the following displayed characters in the current line. In a
selected menu line (inverted), the mode is inverted automatically.
The mode may be a numeric expression in parentheses.
Example: "\m((v>0?0:10)" sets the draw mode to 'normal' (0) if v is greater than 0, and to 'erase'(10) otherwise. This allows you to hide certain parts of the display depending on variable values.
The draw mode values are the same as for the interpreter command
\MN switches the draw mode
for the following displayed characters in the current line. Unlike "\m",
the mode will not be modified even if the display line if "inverted" as a
\n new line (plus carriage return).
The output position of the following text is moved to the left margin (=position
defined in a display line) and the next line.
\panel [(optional options)] : multi-line text panel.
Defines a rectangular area, which can be used
by the script language to display
lines of text (like a small text display window).
At the moment, the multi-line text panel can only be filled by the script language, using the print command. Details about the 'panel' element are here .
\s(<condition>)?"<string1>":"<string2>" (available since May 2003)
A "switch"-list for strings. Depending on <condition> (a comparison,
etc), either <string1> or <string2> will be displayed. Follow
the link for details.
\script.<function name>(<argument list>)" (available since August 2011, only for devices which support the script language)
Invokes a script function to retrieve
a text string. The result value (which must be a string) is inserted
instead of the backslash sequence. Follow
placeholder for the name of a VARIABLE. The backslash itself is part of the
placeholder, so "\vvv" will show only the four first letters of the variable's
Prefixes like "script." will be skipped (not displayed on the screen).
placeholder for the UNIT of a variable. The backslash itself is part of the
placeholder, so "\uuu" will show four letters of the unit. If the unit is
shorter (like °C ), the rest is filled with spaces.
- \U+<hexadecimal Unicode>
Draws a single Unicode character by its hexadecimal code (only one "code" per backslash-U).
Example (in a format string): "\U+1F50D Zoom in" .
The hexadecimal code ends with the first non-hex character (usually a space as in the example, which draws a "left-pointing magnifying glass" if that character exists in the current font).
Supported special Unicode characters (and in which fonts they can be rendered) are listed here.
Most Unicode-'special characters' (with codes above 0x00FF) are implemented in the vector font 'Hershey Simplex'.
\x hexadecimal coded special characters (plural, since October 2009)
Begins a hexadecimal code sequence of 8-bit characters, similar to the "C" programming language.
All characters after Backslash-x are interpreted as two-digit hexadecimal
character codes. For each code, the equivalent character is emitted
using the current font. Details about backslash-x (and how to generate such
sequences) are here.
sets the zoom factor for characters. ONLY FOR DISPLAYS WITH 16-bit CPU. "\z0"
restores the programmed default zoom for the current display line. To set
the horizontal and vertical magnification factor independently, use two digits
\z14High but Narrow \z0Back to normal
\s(<condition>)?"<string1>":"<string2>" Conditional sub-strings (available since May 2003)
A "switch"-list for strings. Depending on <condition> (a comparison,
etc), either <string1> or <string2> will be displayed.
<String1> is used if <condition> is non-zero (= TRUE), otherwise <string2> (the 'else'-branch).
The condition should use the numeric funktion 'v' to access the value of the variable is displayed in the current line.
The comparisons can be nested, if more than two possible strings shall be displayed.
\s(v<15)?"too cold":(v>25)?"too warm":"Temp ok"
- If 'v' (Value of the variable) is less than 15, the display shows 'too cold'.
If 'v' is greater than 25, it shows 'too warm'.
Otherwise, it shows 'Temp ok'.
- Here, the value of <v> is compared with the constants 1, 2, 3,...7,
until a match is found. If there is no match, the string "err" is displayed
in this example. As an exception, the questionmark (used as "if"-suffix)
is not manatory here.
\s(v)0"Zero":1"One ":2"Two ":"****"
- Values 0, 1, 2 are shown as plain text,
all other values are shown in numeric form (decimal, integer, four digits).
func OneTwoThree( int n ) select n case 0 : return "Zero"; case 1 : return "One"; case 2 : return "Two"; case 3 : return "Three"; else : return itoa( n, 4 ); endselect; endfunc;Under 'Display Lines', column 'Variable / Expression', the following expression would be entered instead of the variable. In this example, the value of 'X' (Variable) is be passed to the user-defined script function 'OneTwoThree', which then returns a string, which finally replaces the asterisks in the format-string:
script.OneTwoThree( X )
Hex-coded special character sequences
Backslash-x begins a hexadecimal code sequence, similar to the "C" programming
language. All characters after Backslash-x are interpreted as two-digit
hexadecimal character codes. For each code, the equivalent character
is emitted using the current font.
This function is especially suited to display special characters, for which there is no equivalent "key" on a western PC keyboard.
The hexadecimal numbering scheme makes this quite easy to achieve:
If the (up to 256) characters of any 8-bit font are displayed (or printed) as a grid with 16 * 16 fields,
with the 16 grid columns labelled 0..9,a..f;
and the 16 grid rows labelled 0..9,A..F;
then the first (most significant) digit of the hexadecimal code is the table
row (0..9,A..F); while the second (least significant) digit is the table
For the terminal, it doesn't matter if A..F or a..f is used in a hex number. We only use A..F in the most significant digits, and a..f in the least significant digits to improve the readability of "longer" hex sequences.
In contrast to the "C" language, the hex sequence may be as longer than just one character. It ends at the first letter which is not a valid hex digit (for example, the space character).
The following example will show
'Hello ' if a normal alphanumeric
ASCII font is used:
To create a hexadecimal sequence of 'special characters', click on the 'more' button of the text line definition panel, and select Font Table.
(click into the font matrix to append a character to the backslash-x sequence)
Hex values above 0x00FF (= decimal 255) are treated as Unicode characters
by the LCD driver. But from the large amount of 137000 known
only a small subset can be rendered. At the time of this writing (2018-12), the following
characters could be rendered from the 'Hershey Simplex' font.
To embed such codes in a string, use backslash-U (for "Unicode"), not backslash-x.
The sample application programs/HersheyFont.cvt shows some of those special characters:
U+0203C = Unicode Character 'DOUBLE EXCLAMATION MARK' U+02190 = Unicode Character 'LEFTWARDS ARROW' U+02191 = Unicode Character 'UPWARDS ARROW' U+02192 = Unicode Character 'RIGHTWARDS ARROW' U+02193 = Unicode Character 'DOWNARDS ARROW' U+02194 = Unicode Character 'LEFT RIGHT ARROW' U+02195 = Unicode Character 'UP DOWN ARROW' U+025AD = Unicode Character 'WHITE RECTANGLE' U+025B3 = Unicode Character 'WHITE UP-POINTING TRIANGLE' U+025B7 = Unicode Character 'WHITE RIGHT-POINTING TRIANGLE' U+025BD = Unicode Character 'WHITE DOWN-POINTING TRIANGLE' U+025C1 = Unicode Character 'WHITE LEFT-POINTING TRIANGLE' U+02610 = Unicode Character 'BALLOT BOX' (empty "checkbox") U+02611 = Unicode Character 'BALLOT BOX WITH CHECK' (checkmarked) U+02612 = Unicode Character 'BALLOT BOX WITH X' U+1F50D = Unicode Character 'LEFT-POINTING MAGNIFYING GLASS' U+1F50E = Unicode Character 'RIGHT-POINTING MAGNIFYING GLASS'
See also: Unicode via function 'chr()', User-defined fonts,
Displaying special characters in a table (via Unicode),
Example: Buttons with a checkmark (via Unicode).
22.214.171.124 HTML-like 'tags'Devices with firmware since October 2017 support a few HTML-like 'tags' in the format string. For users familar with HTML, they may be easier to use than the backslash sequences listed in the previous chapter. At the time of this writing (2018-07-25), the following tags were supported:
- <b> bold text </b> (only looks good with vector fonts or large bitmap fonts, at least 12*24 pixels)
- <i> italic text </i> (artificial 'italification' by skewed printing, only ok for vector- or large bitmap fonts)
- <u> underlined text </u>
- <wN>text rendered with N-pixel wide lines</w> (only works with vector fonts)
In contrast to real HTML, the display interpreter isn't picky about nesting, and it doesn't care if beginning and ending tags are perfectly balanced. The following is ok for the display interpreter, but it would be illegal in HTML:
This text <b>is bold, <u>now also underlined,</b> now not bold anymore, </u> now not underlined anymore.
Samples with a few built-in fonts 'made bold and/or italic' can be seen in programs/FontDemo.cvt .
Same as for normal numeric or alphanumeric display fields, the appearance is controlled via format string (* = placeholder for a digit or character, etc).
Example from applikation programs/EditTest.cvt:
Notes on edit fields:
- The edited variable must have read+write access, both in the variable-definition table and in the display definition.
- The variable must be an integer, floating point, or 'string'
- In old devices (e.g. MKT-View I aka "MKT-View Plus"), only variables with data type 'integer' could be edited.
- Even if an edited variable is 'only' an integer, you can insert a decimal separator ('.', point !) in the format string to make it look like a fixed point value. For example, if you have an editable temperature value ranging from -20.0°C ... +70.0°C coded as -200 ... 700 in an integer variable, use a format string like "+**.*" (one decimal place after the point). If the display is in edit mode, the user can only select the three decimal places with the cursor but not the decimal point.
- Variables which receive their values from CANdb Signals (in the MKT-View terminals) cannot be edited.
- To enter edit mode for a certain cell, and to navigate between edit fields on a display page, use either the cursor UP/DOWN key or the rotary knob.
- For special applications, you can check if a field is in select- or edit-mode with an interpreter function (mm).
If an edit field isn't connected to a display variable, but -for example-
to a global script variable, the display interpreter doesn't know your variable's
limiting range (min,max) when incrementing or decrementing the value via cursor keys
or rotary encoder.
To set a custom min/max range when 'beginning to edit' in such cases, you can
define a Control Event Handler (OnControlEvent /
in your script, which writes
the min / max range for editing into the system variables display.EditValueMin
and display.EditValueMax .
By listening for the evEndEdit event, a script can check and 'apply' the modified value after the operator finished editing it.
This may appear a little clumsy on first sight, but it allows those min/max ranges to be determined at runtime, read from a database, received via CAN, etc.
1.11.7 Buttons (on a programmable display page)
Buttons are graphic areas (on the display screen), which, when operated, can invoke a freely programmable action.
The following methods can be used to operate a button :
- Pressing the optional hotkey (assigned to a certain button)
- Select the button with the cursor keys, or the rotary encoder knob, then press ENTER
- Use the touchscreen (optional, only available for certain devices)
Depending on the display hardware (TFT, colour or monochrome..), buttons can have different colours, colour gradients, or styles. For TFT displays with at least 255 colours, buttons can be transparent (or completely invisible), so they can be placed as invisible 'active touchscreen areas' over a background image (bitmap).
Details about the programmable buttons can be found in this extra document .
1.11.8 Icons (bitmap graphics on a display page)
Icons can be inserted on a display page as a single graphic element (on the tabsheet 'Page #X' .. Display Lines, using the 'New' button near the lower left corner of the main window; or with the 'icon' tool in the simple page editor).
Internally, an icon is just another backslash sequence in the format string for the display editor. The general syntax is:
Example (code automatically generated by the page editor:
displays an icon named "Earth2" at the element's
graphic position (specified on the display
line properties tab).
Usually, all icons must be imported into the display application before they can be used (exceptions further below).
(screenshot of the 'icon import' tab)
It is possible to insert multiple icons in a single display line. In that case, each icon is treated like a character, which allows to use icons as special characters floating with the text (if the height of the icon is approximately the same as the height of the currently used font).
It is also possible to use different glyhs for an icon, depending on the current value of a variable or expression, or (for monochrome bitmaps) to invert their foreground- and background colour depending on the state of a variable or numeric expression. Example (on the "properties" panel):
(screenshot of a complex icon definition on the "properties" panel)
- If the Icon in a "\i<Icon-Name>"-sequence is unknown (because it is not defined on the Icon Page), the sequence will be displayed as normal text.
You should activate the option "always redraw this line" in the line property
panel header, if you use "invertable" icons in a display line.
Reason: The interpreter may not notice that the state of the <Invert-Flag> has changed because the Invert-Flags are evaluated only if a display line is "redrawn".
To use the value from the "var/expr"-field as invert-flag, use the "v"-function.
You should activate the option "always redraw this page completely" in the
page definition header, if you use the "\m<Draw-Mode>"-sequence in
a format string and <DrawMode> is a variable expression.
Reason: Same as above.
- In devices with 32-Bit-CPU (like MKT-View II / III / IV), the position
of an icon on the screen can be modified at runtime
- see description of the script function display.elem.x,y .
For devices with 32-bit CPU, icons or bitmaps don't necessarily
have to be imported (with the programming tool) before they
can be used. Instead, icons can also be "loaded on demand" from a bitmap
file stored on a suitable medium. Such a storage medium may be the memory card
or (depending on the target system) a 'Flash drive' inside the programmable device.
This feature was first implemented in the "MIL-terminal" with firmware #11356, where an 8 MByte extra "Audio-Flash" could also be used as a storage for icons. The necessary files had to be loaded into the device via File Transfer Utility, because that device didn't have a memory card. Other devices don't have an extra Flash chip (but a memory card), but the principle remains the same - regardless if the "suitable medium" is a memory card, the "font_flash"-partition, the "audio_flash"-partition, the "ramdisk", or a combination of all those media.
The firmware will only try to load an icon from a bitmap file, if the icon with the specified name (in the backslash sequence) could not be found in the list of 'imported' icons.
Reason: Importing the bitmap from a file, and adapting the pixel colours for the target-specific format at runtime is slower than importing the bitmap directly into the application. In the latter case, the programming tool has already adapted the colour palette, and modified each pixel in the bitmap, for the target device at design time. Thus, use bitmaps "loaded from files at runtime" only if you really need to; for example if your application uses megabytes or even gigabytes of graphics, which are impossible to embed inside a *.upt / *.cvt application.
An example with images (bitmap graphics), which have not been embedded (imported) into the *.cvt / *.upt - file can be found in the demo application ?/programs/MKTview2/BitmapsFromExternalStorage.cvt .
Since 2015-03-25, the icon backslash sequence may contain an complete (Pseudo-)file path for that purpose, e.g.:
That way, you can be sure the bitmap will be loaded from the intended medium, even if a file with the same name exists in one of the other storages listed further above ("font_flash",etc).
Screenshots from application 'BitmapsFromExternalStorage.cvt', with (left) and without (right) the required files on a storage medium.
For non-existing images ("files not found"), the filenames are displayed instead of the graphics. Click on any image to magnify.
- For coloured icons, i.e. icons imported from bitmaps with 4 or 8 bit/pixel, one of the 16 or 256 possible colours (in the bitmap file) can be used as transparent colour. An example for such a display page can be found in the file arm7_special\transparent_color_bitmap.cvt. The second colour value (which would be the 'background colour' for normal text lines) must be set to -2 (minus two, means "no background colour but transparent"). The third colour value must be set to the colour of all pixels in the bitmap file, which shall appear transparent on the screen later. In the test application, all white pixels (colour number 7) in the wolf spider image appear transparent on the screen (see left screenshow below). Because the "spider2" icon is always painted as the last element (when updating the display), the spider seems to sit on the screen (in front of all other display elements).
(screenshots from the 'transparent bitmap demo')
Some Display Lines can also be used to implement a simple "menu".
For this purpose, set the Flag "This line is a menu item" in the display line properties of a display line definition. This turns a normal "display line" into a "menu item" which can be seleced using the CURSOR keys (or via rotary knob in some cases, or via touchscreen .... see feature matrix).
Next, define what the UPT firmware shall do if the User presses the ENTER key on that menu item. In most applications, this will be a goto-command to an other display page.
- g"Menu2" (assuming there is a display page called "Menu2" in your application)
This command has to be entered in the "Var/Expression" column of a display page definition. If you don't know the name of the 'destination' page yet, leave this field empty and use the Menu Link Dialog later to define all menu jumps (when all display pages of your application exist, much easier to use, the goto-command will then be generated automatically !).
You can additionally- define a hotkey for this kind of menu on the display line property panel.
There are some UPT interpreter functions that give you additional control over this kind of menu:
- mi : returns the line number (index, 0..n) of the current menu item.
mm: returns the current menu mode. It may be one
of the following values:
0 = Menu is "Off", that means the menu selection bar is invisible
1 = Mode "Selecting", that means the menu selection bar is visible, the user may move the selection between all "menu items" on the current page using the cursor.
Other "modes" are only valid for numeric edit fields, for example 2 = "editing the value".
There are also some "SET"-Procedures for this kind of menus, which have the same names as the "GET"-Functions:
- mi( <new_item> ) allows setting the "current" menu item under program control
- mm( <new_mode> ) allows setting the "current" menu mode under program control
You may find an example for this kind of menus in the file \programs\NEWMENUS.UPT .
Note: If you use a Display Line as a Menu Item, you cannot show the contents of a numerical parameter in that line !
1.11.11 Single Bargraph diagram (optional)All devices with a graphic-capable display support simple bargraph elements. Details here (separate document, bargr_01.htm).
1.11.12 Y(t) and X/Y-Diagrams (optional)Most devices with a graphic-capable display also support Y(t)- and X/Y-diagrams. Details here (separate document, diagr_01.htm).
1.11.13 Multi-Line Text Panels (used as "text screen" for the script language)
The backslash-sequence "\panel" defines a rectangular area, which can be
used by the script language to display
a few lines of text (like a small text display window).
At the moment, the multi-line text panel can only be filled by the script language, using the print command .
Without the optional options (in parentheses), the text panel has no visible border around the text area.
The following options can be specified inside parenthesis after the \panel keyword:
- bo=<line width of the outer border in pixels>
The outer border is is painted with the display element's foreground colour
- bi=<line width of the inner border in pixels>
- The inner border is is painted with the display element's background colour .
defines a text panel with a 6-pixel wide outer border, and a 2-pixel wide inner border ("frame") around the text area, which reduces the size of the remaining 'netto text area' by 8 pixels on each edge (upper, lower, left, right).
(Screenshot from the script example "GPS Receiver Test")
To turn a display-element into a multi-line text panel, set the display element's type to 'Multi-Line Text Panel' on the page definition tab:
During edit mode, as long as the script has not printed any text into the
text screen buffer, the programming tool will fill the text area with dummy
characters, so you can easily see if the size of the text panel is properly
aligned to a multiple of the font size. All characters in a multi-line text
panel use the same font (as defined for the display element, see screenshot
A text panel can also be used as a control event (for example, react to touchscreen events).
Details and examples can be found in the manual for the script language.
tCanvas' object that exists in your script.
Such 'Canvas'-objects can also be used as 'background' for other display elements, e.g. diagrams. In contrast to imported images ("icons"), the image displayed on a graphic panel is generated at runtime via script. There's a simple example in application script_demos/Mandelbrot.cvt (generates a fractal graphic known as Mandelbrot set). See also: Data type tCanvas (in the script language),
Canvas painting functions.
The "other command"-tab of a page definition lets you insert "special" display commands. It can also be used to see the usage of display commands and event definitions (if the box "show all types of commands" is checked).
For modern displays (e.g. MKT-View III / IV), you don't need 'low-level'
graphic commands like dm=draw mode, ic=icon,
li=line, etc, in your application anymore.
These commands only still exist for compatibility with ancient devices like 'UPT-515' and 'MKT-View I'.
Instead, use one of the configurable high-level elements listed below, or (if you really need to "paint yourself"), use the script's Canvas-element instead.
bargraphs, bitmaps, buttons, diagrams, polygons, analog meters, tables (display elements).
1.11.16 Overlapping graphics
For some special effects you may place some visible elements (text or graphics) in front of other visible elements.
For example, there may be a large icon in the background and a text display line in front of the icon.
To achive this effect, the icon must be drawn first and the text must be drawn afterwards. The sequence (or "drawing order") is defined by the row number in the screen definition tables.
The first line in the display definition table (line "0") will be drawn first, the second line will be drawn after that and so on.
When using overlapping graphics, you may have to set the option "redraw page completely" in the page definition header, even though this slows down the application a bit. The same applies for moving graphics.
If a graphic element is completely overlapped by another element (like the completely opaque vertical bargrah in the following example, which is completely overlapped by a transparent bitmap) it's sufficient to set the flag 'always redraw this line completely' (instead of completely redrawing the entire page):
(screenshot from the 'Transparent Bitmap Demo',
For any kind of overlapping graphics, it's important to draw the overlapping elements in the correct sequence. In the "three tanks" example shown above, the three bargraphs (which are used to paint the 'liquid level' in each tank) must be painted before the tank images. The tank images are in fact the same transparent bitmap, "tank1.bmp", used three times in the same display page definition).
To modify the drawing sequence, press and hold the left mouse button over the leftmost column (labelled "Nr") in the display line definition table, then (with the mouse button still pressed) move the item up or down. Remember, the topmost element in the table is painted first, and the last element in the table is painted last.
The 'simple' page editor for display pages is located on an extra tabsheet in the programming tool's main window:
This editor was added as an aid for new users, as an alternative to the 'textual' definition of display elements (which is preferred by advanced users). Both editors can be used alternatively - simply switch the tabsheet to toggle between them. Any change you make in one editor is immediately copied into the other.
The currently selected object is marked with a red frame in the simulated LCD screen. Multiple objects can be selected and moved, too.
1.12.1 Page editor toolbar
- (Arrow or Pointer tool) : Move or modify items on the screen.
Hold the mouse pressed and move it, to modify the element's pixel position.
Use the CTRL-key, or pull a marker frame (start in an empty region on the screen) to select multiple items at once. More on that further below.
Single-click on an item to select it (for cut / copy / paste operations).
Double-click on an item to open a special property editor for it.
Sizeable elements (like buttons) can be resized after being selected by dragging the small square in the element's lower right corner with the left mouse button. The 'sizing corner' then turns orange (instead of the normal red frame around the selected element), which indicates 'element is being resized'. While resizing, the element's upper left corner remains fixed:
Modifying the size of a display element (here: a button)
by dragging the orange-coloured 'sizing corner' .
- (Text tool) : Insert a simple alphanumeric TEXT line on the screen.
First select this tool (click at the symbol in the toolbar).
Single-click into the screen to place a new text item there.
After that, a special dialog opens where you can edit the new item.
- (Icon tool) : Insert an Icon (symbol; bitmap graphics).
Use this tool to insert small bitmap graphics ("Icons") on the display
Note: Before you can insert bitmaps here, they must be imported on the tabsheet "Icons" in the programming tool.
After inserting an icon, you can modify its appearance (colour, zoom, different symbols depending on the value of a variable, etc). Use the arrow tool for this, and double-click on the icon in the editor screen.
- (Button tool) : Insert a graphic button.
First select this tool, then click into the screen to add a button.
After that, a special dialog opens where you can edit the button.
- (Bargraph tool) : Insert a bargraph.
First select this tool, then click into the screen to add a bargraph.
After that, you can modify the bargraph in a special dialog window.
- (Diagram tool) : Insert a diagram.
After selecting this tool, click into the screen to add a diagram.
- (Insert Other Objects) : Opens a sub menu with other 'insertable display elements'
Those less frequently used elements include tables, polygons,
analog meters ('needle instruments'), etc.
- (Cut tool) : Cut out the selected item.
First select the item which you want to remove (with the Arrow tool),
then select the "Cut" tool (scissors).
When cutting, the selected item is copied into an internal clipboard-like memory, but this is not the windows clipboard.
- (Copy tool) : Copy the selected item.
First select the item which you want to copy (with the Arrow tool),
then select the "Copy" tool.
The selected item is copied into an internal clipboard-like memory, but this is not the windows clipboard.
- (Paste tool) : Paste item into selection.
First select the item which you want to overwrite (with the Arrow tool).
If you don't want to overwrite a selected item, select nothing.
The item stored in the internal clipboard-like memory will be pasted to the screen.
If an item was selected (marked with a red selection frame), it will be replaced with the "pasted" item.
If no item was selected, the item will be inserted at the position of the insert cursor, which is marked with a small red dot.
The insertion cursor can be set (before inserting an item) with a short click into a non-occupied screen area.
After inserting an element, the insertion cursor will be moved down (or right, at the bottom of the screen), depending on the size of the object which has been inserted, so that there will ideally be no overlap. This way, it's quite easy to fill a page with equally spaced items.
- (Undo tool) : Undo recent operation(s).
Click this 'UNDO'-button to undo the recent operation.
In the page editor, up to 20 (?) operations can be undone, because they are saved in an undo-history.
Caution: If you exit from the current page in the editor, the changes cannot be "undone" anymore !
- (Redo tool) : Redo recent undo-operation(s) aka "un-undo".
Click the 'REDO'-button to undo the recent und-operation.
In the page editor, up to 20 (?) undo-operations can be undone, there is an extra buffer for this.
Caution: If you exit from the current page in the editor, the changes can neither be "undone" nor "redone" anymore !
The selected object is marked with a red frame in the drawing area.
To move or copy a group of objects, use the 'Arrow / Pointer' tool to select multiple objects. Hold the CTRL-key pressed, and click on each object which shall be added to the selection.
Alternatively, first move the mouse (pointer) into an empty area, close to the upper left corner of the first to-be-selected object. Then press and hold down the left mouse button, while pulling the mouse from the upper left to the lower right corner of the selection area. This spans a shaded rectangle over the marked items as shown below:
(Screenshot of the 'simple graphical editor' with multiple objects selected via mouse; left mouse button still held down)
When releasing the mouse button, the shaded rectangle (spanned with the mouse) disappears,
but all objects covered by it remain selected.
To move the selected objects on the screen, grab one of the selected items with the left mouse buttons (otherwise, clicking outside the selected objects de-selects all), and -with the left mouse button held down again-, move the selected object(s) to the new position.
If multiple objects are selected by red frames, 'Copy', 'Paste' and 'Cut' applies to all of them. So you can quickly copy a block of multiple objects from one display page to another.
The combo box in the editor's toolbar allows you to select individual display elements (in addition to selecting them with the arrow tool). This may be necessary for example, if a display element is completely obscured by another, and cannot be selected with the mouse directly.
Selecting a single object in the drawing area (with the arrow tool) will also
select that object in the combo box shown above.
The entries in the combo box can be interpreted as follows :
[line number] ELEMENT-TYPE : element-text
 TEXT : The EA515..
- which means:
The currently selected display item is defined in line number 5 (an array-index;
numbering starts at zero);
the item is a simple TEXT (alphanumeric);
the display text begins with the string "The EA515..".
Graphic controls can be aligned to an 8 * 8 pixel grid. To show this grid, or let a coordinate snap to the grid, select "Option"..."Page Editor" in the programming tool's main menu. If the option "Snap coordinates to 8*8 pixel grid" is active, the upper left corner of an object will be aligned to the nearest grid point when moving the object with the mouse.
At the time of this writing, only the following display elements were supported by the "simple" page editor:
- TEXT : simple text, with or without variables (use asterisks as placeholder characters). Can be edited in a special dialog.
- ICON : small bitmap graphics ("symbols")
- BUTTON : graphic button (details in 'btns_01.htm').
- DIAGRAM : Y(t) or X/Y-Diagram (details in 'diagr_01.htm').
- TABLE : Table (Control- or display element with multiple rows and columns)
- POLYGON: Polygon (lines, or shapes like rectangles, triangles, etc; editable "point by point").
- METER: an analog meter ('needle instrument')
Special functions like graphic interpreter commands
or script-generated text
are not supported by this editor (they must be edited 'as text').
The functions Copy / Cut / Paste, and the 'Property' dialog for a certain display element can also be launched through the graphic editor's context menu (right mouse button).
Double-clicking on a normal alphanumeric display element opens the dialog shown below:
In the 'Text' field, you can enter normal static text, but also backslash sequences, placeholders for digits (*,#,0) and sign (-), HTML-like tags for bold, italic, and underlined text as specified in chapter 1.11 .
Polygons may be single lines, line segments, grids, squares, triangles, and many other geometric shapes.
Unlike bitmap graphics, polygons (like "vector drawings") can be easily scaled for any screen resolution.
The number of "points" per polygon is limited (by the maximum length of a "definition line"), thus
complex 'drawings' may have to be composed of multiple polygons (each in an own definition line).
With a max. length of 500 characters per definition line, and 6 characters per coordinate, expect up to 80 points per polygon.
- For experts and advanced users:
- The graphic editor generates an "\li" backslash sequence ("li" = "lines"), followed by the coordinates of all points in the polygon.
The argument list (after "\li") may also contain graphic elements like polygon(), polyfill(), etc.
The syntax of "\li" is described here (including the use of commas and semicolons to control drawing lines between points).
Like any other display element, a polygon can also be edited 'as text'.
To do that, mark the polygon in the editor, right-click into it, and select 'Properties' in the context menu shown further below.
Button in the graphic editor's toolbar
Menu of the graphic editor to insert 'other elements',
After selecting one of the polygon objects or predefined vector graphics from the menu, click into the drawing area to specify the position of the upper left corner of the new graphic element.
Later, you can adjust the size of the new polygon (etc) by dragging the lower right 'sizing corner' as already described.
Points, lines, or polygon vertexes can be added or deleted as described further below.
A double click into a polygon's drawing area toggles between "Move or resize the entire object" and "move, delect, insert single points". In this state, all points of the polygon are marked as small red squares. These small squares can be grabbed with the mouse, and moved within the drawing area:
Polygon in editor state 'Move / Resize'
Polygon im editor state 'Edit Points'
Less frequently used functions of the graphic editor are available in the context menu.
To open the context menu shown below, right-click into an already selected object. The appearance of the menu may depend on what was actually clicked:
Context menu of the graphic editor with options to edit a polygon
Some commands require a drawing area of at least 100 * 100 pixels. Note that all coordinates within the argument list are relative to the display-element's own position.
- Simple line with start- and endpoint taken from variables (requires manual input 'as text'):
- Four-pixel wide line (parameter "w"=width)
\li(w=4, x1,y1, x2,y2)
- Two lines (note the semicolon as separator between coordinates with "pen up")
\li(8,8, 8,88, 88,88; 16,16, 16,80, 80,80)
- Closed, but not filled polygon (here: triangle)
\li(polygon(0,99, 50,0, 99,99))
- Filled polygon with a 'thick border' :
\li(polyfill(w=4, 5,95, 50,5, 95,95))
- Filled polygon without border (no lines around the filled area) :
\li(polyfill(5,95; 50,5; 95,95))
See also: Polygons in the curve area of a diagram, general '\li' syntax, rotated text using vector fonts.
Back to the table of contents
Since 2017-08-01, analog meters and similar 'instruments' don't need to be created with polygons anymore.
Instead, they can easily be dropped on a display page like any other graphic widget. Parameters are customized as a property list on the programming tool's display page definitions tab:
Rect: Rectangular instrument (e.g. "voltmeter"), Round: e.g. "tachometer".
Arrow Type, Arrow Colour
appearence of the main indicator (needle, arrow, compass pointer, etc).
Start- and End angle
Defines the angle range of the instrument's moving 'needle' or 'pointer',
using the 'compass' angle system shown further below.
Scale start value
Value for the scale's lower endstop. Corresponds to the 'start angle' for the indicator needle.
Scale end value
Value for the scale's upper endstop. Corresponds to the 'end angle' for the indicator needle.
Numeric expressions to be displayed by the instrument's 2nd and 3rd arrow.
The first arrow's value is taken from the element's associated 'Variable' / numeric expression.
Examples for analog meters in different sizes and styles can be found in the 'Analog meter test' (demo application in file analog_meter_test.cvt):
Screenshot from application 'analog meter test'
The angle range of the instrument's moving pointer (needle) is entered as start- and end angle in the property list. Angles are specified in degrees as on a compass, as shown in the image below.
For convenience, negative angles are also accepted (-90° will be the same bearing as +270°, i.e. "points to the west").
Bearings on a compass (in degrees)
Analog voltmeter: StartAngle=-45 (or 315 degrees), EndAngle=45 .
Round tachometer: StartAngle=-135, EndAngle=135 .
Analog clock (see example shown further below): StartAngle=0, EndAngle=360 .
For round instruments, the pivot (rotating axis) is always centered.
For instruments with rectangular shape, the pivot is optimally placed for the largest possible circular path of the indicator's tip. Thus the position of the pivot depends on the angle range. For small ranges (like the "Voltmeter" with StartAngle=-45, EndAngle=45°), the pivot point may even be outside of the visible area.
Besides the main arrow (or needle), two additional indicators (pointers, needles, markers) can be displayed inside the analog meter. The position of these extra indicators may be a simple numeric constant (value), variable, or even a numeric expression to scale them properly.
To insert an analog meter on a display page, right-click into the LCD simulator window, and select 'Insert analog meter' ('Zeigerinstrument einfügen'). As for any other display element, the specific properties can be modified in the right half of the programming tool's main window:
Property panel for an analog meter (Zeigerinstrument)
in the programming tool's display page editor
The 'analog clock' shown on the right is a screenshot from sample application 'programs/analog_clock_480.cvt'. The clock consists of a single pointer instrument (with three pointers), angle range 0 to 360°, value range 0 to 12. Hour-, minute-, and second-pointer are defined as follows:
|Pointer||Arrow Type||Numeric expression (displayed values)|
|Seconds||thin_line||rtc.se * 0.2|
|Minutes||thin_line||rtc.mi * 0.2|
|Hours||short_line||(rtc.hr%12) + rtc.mi/60.0|
In the numeric expressions shown above, the 'rtc'-functions retrieve the current time (second, minute, hour) from the real time clock. By multiplying those values with suitable factors, all three values are converted into the same value range (here: 0..12), because a single instrument uses the same value range ('ScaleStart' to 'ScaleEnd') for all pointers.
Back to the table of contents
An "event" is the occurrence of a special situation that you want to handle in your terminal program.
An event can be:
- User presses or releases a certain key on the terminal
- User turns the optional rotary encoder knob
- The value of a variable exceeds a certain value (may have been received via CAN)
- One bit of a variables is set to a certain value
- and more combinations.. see event definition language in the next chapter.
For every event you also have to define a special "event reaction". A reaction can be defined as a sequence of interpreter commands .
Possible reaction methods are:
- Switching to an other display page
- Setting a certain variable to a certain value (which may be sent via CAN)
For the definition of events we use a simple event definition language, but you may also define events for a display page by selecting them from list.
Events may be defined...
- "global", that means not depending on the current display page;
- "local" on a display page, which means only active when this page is the current page.
- interpreter commands
- numeric expressions
- Event Handling in the Scripting language (for devices with 32-bit CPU, for more advanced control)
To define events and reactions, you may use this definition window (which is almost the same for global and local events):
The buttons below the table are used to modify the tables contents. INSERT, DELETE, COPY and PASTE operate on complete lines.
The propery-panel on the right shows more detailed information about one single event definition.
You may edit the properties of a display line in the table or on the property panel, the information will always be updated on both parts.
The "Add event" and "Add reaction"-Buttons on the property panel open special dialog windows, which can be used to define event definitions or reactions (especially if you are not familiar with the event definition language).
An "event" is the occurrence of a special situation that you want to handle in your terminal application. To define such an event, you may use this event-definition-language which uses the UPT's command interpreter to analyze numeric expressions.
The programming tool may display some of these events in a longer, human
readable form, like
page_enterinstead of "
A few simple expressions are listed below:
|kd||key-name||user has pressed a key|
|ku||key-name||user has released a key|
The specified key will be removed from a buffer !
|kh||any key has been hit (system keys too)|
|kc||reads and removes a system key code from a buffer.|
|kcb||reads the code of the last pressed key, but does not remove it from a buffer|
|cb||CAN-Error: Bus Off
See also : 'cs' (CAN Status)
|ce, alias ce0||Severe CAN-Error on the first CAN port|
|ce1||Severe CAN-Error on the second CAN port|
|ct||CAN-Error on transmit
See also : 'cs' (CAN Status)
|else||Returns TRUE, if the previous Event-condition was FALSE.
Only supported by firmware compiled 2012-10-15 or later ! Example
|t0 ... t3||User-timer ( nr. 0...3) has run off|
|ti_ms>1500||Over 1500 milliseconds elapsed since power-on|
|Current page has just been entered (Page Enter)|
|Current page will soon be left
Like any other page-event, this event can only occurr on the currently 'visible' page, not on any other page !
To implement a centralized method to react on 'any kind of page-switch' (regardless of the current display page number), we highly recommend to use the Script Language ("OnPageLoaded").
|Page Redraw, the current page must be redrawn. Occurs together with "pe" or after calling cls (=clear screen command), or when setting display.redraw in a script.|
|pdo[N].rcv||A PDO telegram has been received .|
|rot.l, rot.r, ...||The rotary encoder ("knob") has been turned|
|syn.rcv||A SYNC-Telegram has been received .|
The terminals interpreter evaluates the event definition as a boolean expression. You may also use more complex numeric expressions as event definitions.
If the result of an event-definition (or expression) is non-zero, the system interpreter executes the corresponding reaction method. An event reaction method is (internally) coded a string of interpreter commands.
Event (condition) Reaction (sys.vsup<120)||(sys.vsup>260) dis.VSup.bc = (ti&8)?7:4 : REM flashing supply-voltage warning else dis.VSup.bc = white : REM no voltage warning
See also: Overview of numeric interpreter functions.
1.13.3 Global and Local Events
You may define global events for situations that are independent of the current display page
(they are always "active", no matter what the "current page" is).
- For example, you may wish to "call" a certain display page whenever there is a severe error on the CAN-Bus. This can be achieved by the following example:
Event-Definition: ce (which means: "if there is a Can Error"...)
Reaction: c"CanError" (which means: ... call the page named "CanError")
Define this Event and its reaction method on the "Global Event" page, so you dont have to define it on every used page (remember, the number of lines on a page is limited !).
There are some rules for global events that you should use:
- Use global events for all events that would otherwise be equal on every page definition.
- Dont use display output commands in the reaction methods of global events, because this might "interfere" with the screen output of some of your pages.
- If you defined a certain event as a global event (like "ce" in the example above), you should not define this event again as a "local" event on any display page. However, defining an event twice does not hurt the event handler. If many event definitions are TRUE at the same time, all their correspondig reaction methods are executed.
Local events always belong to a certain display page (they are only checked if that display page is visible). In most applications, local events react on keyboard actions and switch to other pages.
Simple GLOBAL events can be selected from the global event catalog (a special dialog which can be opened from the Global Events page).
return to the event definition overview
The dialog-based assistant described below can (but doesn't have to) be invoked
from the main menu, via 'Assistant' .. 'New program, simple' or
'New program, universal'. The assistant will lead you through various steps
for creating a completely new display application. In many cases, you won't use it,
but rather 'recycle' an already existing application and adapt it as necessary.
In the first step, the hard- and software profile of the target device must be selected.
- Technical brackground:
- For many devices, for example MKT-View II, there is only one hardware profile, which contains
the screen resolution, colour model, and much more. In addition there are multiple
possible software profiles (for the same hardware), depending on the loaded firmware.
For example, you can select a software profile for a CANopen device (UPTv1=DS301 V3, UPTv2=DS301 V4); or (for all devices withoutCANopen-Firmware, but instead 'CANdb') select 'CVTv1' as the software profile (CAN-View-Terminals, z.B. MKT-View II mit Firmware #11314).
The programming tool may ask you to use a different tool; because (for example) the programming tool for devices with 'CANdb' (DBC, automotive) doesn't support CANopen itself, and thus will not be able to load the display application into the device via CAN.
In the next step, the assistant will ask for the number of display pages for your new application:
After that, you may(!) import display pages from the gallery, or from other (already existing) display applications (*.upt, *.cvt):
Depending on the invocation of the 'new application' assistant, the next step will be:
Select how to switch from one display page to another:
The unexperienced user may select a few global events from this 'catalogue':
(Screenshot 'Global Event Catalog')
- switch from one page to another
- switch to a certain page if a serious CAN-BUS error occurrs
If the 'global event catalog' was opened from the 'new application-assistant,
this was the last step guided by the assistant. Before uploading the application
into the programmable device, you will usually check the displayed variables
or fine-tune the display using the page editor.
1.14.2 Variable Selection Dialog
This dialog can be used to replace references to VARIABLES on a DISPLAY PAGE. You can open it by selecting the item "Check & Modify VAR/SIGNAL references" after right-clicking into the display line definition table, or from the tool's main menu: "Check and modify variables on current page". For example, click the "More.." button on the tabsheet "display line definitions"
(Screenshot "Buttons on the display line tab")
A popup menu appears, select "Check & modify VAR / SIGNAL references".
(Screenshot of popup menu "display lines")
This opens a dialog titled "Select Variables or Signals on page
XYZ", where you can select already existing variables to show on a
display page, or create new variables from CANdb signals which can be displayed
then. You will use this function frequently when "recycling" programs for
other applications !
(Note: This dialog may appear in other situations also, for example when using the assistant).
The table on the left side shows all display lines on the current page with numeric displays, edit fields, or other graphic elements which are connected to variables.
The panel on the right side displays either a list of all existing variables, or an overview of all Nodes+Messages+Signals which may have been loaded from a CANdb file earlier (only for devices which support CANdb signals). For terminals with CANopen, there will be an other tab on the right panel showing a list of CANopen variables in the local object dictionary (more details in another document).
First select the variable you want to replace , then -on the right side- select a variable, a signal, or a CANopen object which shall replace the old connection. If you select a CANdb signal from the threepart list (Nodes, Messages, Signals), a new variable will be created automatically, if no variable exists for this signal yet.
The "type" column in the table shows if a variable is connected to a signal ("Sig") or if its a "normal" variable (which is not connected to a communication channel). If "Sig" is followed by a question mark, the original signal definition does no longer exist in the CANdb definition table (on the tabsheet "CANdb"), most likely because the table has been erased manually because it was considered "top secret". This does not affect the normal operation of the terminal as a display (!) .
For terminals which support the script language, the Script tab (not shown in the screenshot above) contains a list of global script variables. Picking a script variable from that list will generate the prefix 'script.' before the name, so the display interpreter knows that this is not a 'normal' UPT display variable. Local script variables cannot be accessed by the display interpreter, thus they are not shown in this list.
If the option "select new line automatically" is active, the selection bar of the display definition table (=blue mark in the table) will switch to the next line whenever you click on an entry in the list on the right panel. This minimizes the amount of mouse-clicks needed to redefine a complete display page.
The option "replace name in display text" does this:
If the NAME OF THE VARIABLE is part of the old menu text, it will automatically be replaced with the name of the new variable.
- For devices with CANdb functionality only:
If you have a large number of SIGNALS, it may be difficult to find the required
signal, when you don't know the exact name of the NODE and MESSAGE. There
is a global search function for SIGNAL NAMES through all NODES and MESSAGES.
Activate it by right-clicking into the NODE LIST. A popup-menu appears; select
"Find Signal" and enter the signal name. The search function is not
case-sensitive, so don't care about upper or lower case letters when entering
the search string.
Because different messages could carry different signals with equal signal names, the search can be continued at the current position in the database ("find next occurrence of XYZ").
return to the table of contents
This dialog of the programming tool can be used to assign 'jump destinations' for all menu lines which are defined on a single display page. It will open automatically when the 'check all pages' detects a non-existant menu link, or from a popup menu on the display page definition screen.
The grid table shows all menu lines which are defined on the current page. The list on the right side shows the names of all programmed display pages (which can be "jump destinations" when the user selects a menu. Click on one of the page names to select it as a new destination for the selected menu.
The menu selection (=blue mark in the table) will switch to the next menu
line after selecting a new menu (which minimizes the number of mouse-clicks
if you want to re-define all menu links on a display page). You can also
select another menu line by clicking into the table.
- Modifying the text of menu lines, or the graphic appearance, is not the task of this dialog. Use the display definition screen to change the displayed text, font, graphic location, etc.
If there is something wrong with the menu definition, an error message in red color appears on the dialog screen. Usually, the reason is a menu link to a non-existing display page. All invalid menu destinations are also marked in red color in the table.
There are some checkboxes in the lower right corner of the menu link dialog:
- Select new line automatically
- Enables or disables the automatic selection of a menu line (to minimize the number of mouse-clicks)
- Replace (variable-) name in menu (-text)
If the name of the destination page is embedded in the menu text, it will
automatically be replaced with the name of the new destination page. If the
name of the destination page was not part of the menu text, the menu text
will not be changed.
Note: To EDIT THE MENU TEXT, use the display page definition tab.
If the menu link dialog has been opened from the display page overview, you can use the "previous" and "next" buttons to modify the menu links on another display page.
After you have selected destination pages for all existing menu lines, click "OK" to accept the changes.
return to the table of contents
The Page Overview tab shows an overview of all pages that are currently defined in your terminal application.
You may double-click on any of the page overview icons to switch to the page definition sheet, where you can modify the pages contents.
From the 'overview' tab, you can enter the display page gallery to copy pages from the gallery into your own application.
A single click on one of the pages on this screen selects it for the following actions. The selected page is marked with a colored frame.
Clicking on one of the pages on this screen with the right button opens a popup menu which allows you to...
- insert a new, empty page (before the selected page)
- delete the selected page
- copy & paste a page (to modify the page sequence)
- pick a display page from the gallery
- check all menu links on the selected page
Options for the display page overview:
- [v] Stretch view
- The display page overview uses streched (or compressed) preview-images
with a fixed size (usually smaller than the original display resolution).
You won't see each pixel with this option, but more pages will fit on the screen without scrolling.
- [v] Allow calling script
- Without this option, no script functions are called when generating the preview.
This improves the speed of the update, especially if the script must do a lot of work
(for example, read the actual display text from a network, or from a file).
Instead, when generating the preview for a display element which uses a script to retrieve the text (string), the preview will show '<generating preview>'.
Depending on your script, this option may also avoid side-effects like increased network traffic.
The Display Page Gallery shows a collection of pre-assembled display pages ("screens"), which are located in a special directory of the programming tool. You can select one of the screens from the gallery and copy it into your own application (use the "Gallery.." button on the display page overview tab).
The page overview shows all pages in your own application
The page gallery shows something which someone else (the 'artist') has made, use it for 'inspiration'.
The page gallery can also be used to pick display pages from other applications (set the File Type to "*.upt" or "*.cvt" for this purpose)
- A screen from the gallery may not be displayed properly, because some icons and/or variables are missing. Check your application after inserting pages from the gallery !
return to the table of contents
This screen of the programming tool is used to import and browse icons (bitmaps) for your application.
Depending on your terminal's display, you can import monochrome or colour
bitmaps on this tab (see feature matrix).
From the main menu, there is also the possibility to create a new (empty) icon with a certain size (Icon...Create New).
You can modify the icon pixel by pixel (click into the image on the right) but it's easier to use an image editor like "Paint".
The name of the bitmap file must be a valid DOS filename, because the internal storage of huge objects may be based on a file system similar to DOS . For that reason, make sure the filename is compliant with the following guidelines (which applies to other names, too):
- The name must begin with a letter (a..z, A..Z) .
- The name must be 1 to 8 characters long .
The 2nd to 8th character must be one of the following:
a..z, A..Z, 0..9, or _ (underscore character). NOTHING ELSE. Especially no spaces, even though some think it's cool to allow spaces in filenames. WE DON'T.
Depending on the display hardware, it may be possible to import icons with 1, 4, or 8 bit per pixel; which means monochrome, 16-colour, or 256 colour bitmaps. The colour palette is always fixed, so don't expect the image to look exactly the same way as in your paint program with 16 million colours.
- For experts:
The 256-colour palette uses 2 bits for the blue channel, 3 bits for the green
channel, and 3 bits for the red channel. Some image conversion tools (like
IrfanView) can optimize "high colour" or "true colour" image for such a palette,
using a smart colour dithering method. Such a method produces better results
than the simple import filter (implemented in the programming tool), which
always picks the closest colour from the device's 2+3+3-bit RGB palette.
The process of converting an image with IrfanView, using an optimized palette, is described in the file 'readme_irfanview.txt' located in the 'icons' folder of the programming tool.
After importing all required icons (as explained above), the icons can be used in the display-application as described here .
In newer devices (e.g. MKT-View III), instead of embedding icons directly in the application (*.cvt / *.upt), they can alternatively be loaded directly from a suitable storage medium, which saves a lot of space in the *.cvt / *.upt file.
See also (related subjects) :
"Boot Screen" (graphic shown immediately after power-on, not part of the *.cvt-application),
Canvas objects (graphics generated via script at runtime).
In most display terminals, Icons, Pages and Text Array share the same memory
inside the user programmable terminal. But there are severe differences between
newer devices (also depends on the firmware
compilation data / revision number ! ).
In old devices with 8- or 16-bit-CPU (like MKT-View 1 / MKT-View "Plus", memory had to be reserved for icons before they could be imported from bitmap files.
In devices of this class, all display pages have a fixed size in (FLASH-)memory. If a display application consists of the maximum number of display pages, there will only little memory left for other objects ( like text lines and icons).
Therefore you have to sacrifice some pages if you want to use icons in your application.
If you reduce the number of pages in your application, there will be more memory for icons.
As an example, if the terminal has enough memory for 50 display pages but you decide to use only 40, there will be about (50-40) * 1600 Bytes which you can use for icons.
Click on the "Icon Memory" button (on the icon page) to start this dialog for reserving icon memory.
For such devices, the method of storing display pages,
text array lines, icons and other objects in FLASH
memory has been completely rewritten (making use of linear 32-bit memory
pointers, which were not available for 8- and 16-bit stoneage controllers).
Now each object only occupies as much memory as necessary (for experts: Older
devices used array, new devices use linked lists in memory). Display pages
with fewer, or shorter lines use much less memory than they did in oder devices.
So usually(!), there will always be enough storage memory, even if your
application needs "many" pages and "many" text array lines (whatever "many"
actually is.. 255 pages, and 4096 text array lines). You can be generous
with the max. number of display pages, and the max. number of text messages
(text array lines) in the dialog box shown above - even if your application
will never need so many of these objects.
The programming tool will guesstimate the amoung of remaining "free" memory in the terminal, but it needs to know some parameters about the terminal to do this properly. This includes the maximum usable FLASH size and a few other hard- and firmware specific details, which are also saved in the *.CVT or *.UPT file.
When migrating (or "upgrading") from one class of devices to another (for example from "MKT-View" to "MKT-View II" or later models) you can modify this information (in an already existing application) with a suitable text editor, or with the programming tool on the 'Settings' tab which is explained in the next chapter.
To estimate the memory sizes correctly, the programming tool needs to know the following parameters :
Icon Memory Shared (which is the parameter "t icons_shared"
in the *.CVT / *.UPT - file) :
0 = Icons use their own FLASH memory sector; display page sizes are static ( "old" terminals / firmwares, MKT-View, all 16-bit CPUs)
1 = Icons and display pages use a common FLASH area, display page sizes are static (for example "UPT515")
2 = Icons, display pages, and others use a common FLASH area, all objects have a variable size in FLASH-memory (only for 32-bit CPU,
for example "MKT-View II", "MKT-View III", "UPT 320", and other devices with 32-Bit-CPU (ARM-7 or Cortex-M); firmware compiled in August 2009 or later)
Max. Data FLASH Size (which is the parameter "t max_free_mem_kbyte"
in the *.CVT / *.UPT - file) :
Spezifies the size of the FLASH memory usable to store display pages, variable definitions, text array lines, icons (images), and other objects. A different part of the FLASH memory is used for the terminal's firmware and operating system; making the available "free" memory size depending on the hard- and firmware. For example, in the "UPT 320" (terminal with 5.7" TFT display, 320*240 Pixel) with firmware #11352, there were 896 kByte FLASH memory avaiable for the user application ("display program").
Note: The calculation ( estimation ) of the free memory by the programming tool may differ slighly from the real value (found in the terminal). The real value is shown for a short moment while booting the terminal (if the bootup messages are not disabled, of course). Example:
|CANdb Display Terminal (...)
Compiled: Aug 5 2009 (...)
Loading .... ( unused : 761 kByte )
A similar value should be displayed by the programming tool on the
Icons tab, near the Icon Memory button.
If the readings differ by more than a few kByte, the parameter "max_free_mem_kbyte" in the *.UPT or *.CVT-file may be wrong (because it was copied from an application for a different target). You can fix this, as explained above, using a text editor or by reading back the application from a "real" terminal (because in this case, the programming tool and the terminal can communicate directly with each other, so the tool has the chance read a few parameters from the target device --- which is impossible if the application is transferred into the terminal via memory card only).
For that reason, to adapt an "old" application for a "newer" terminal firmware (with flexible FLASH memory usage),
select Options .. LCD Settings
/ Device Selection in the tool's main menu,
and select your target device from the list again (even if it is already selected).
The programming tool will then look up the properties of the target hardware from an internal database, and adapt the most important settings if necessary.
See also: Memory occupied by the script (which is 'completely separated' from the display's memory management for safety reasons) .
Return to the table of contents
extra file (ufont_01.htm) .
1.19 Settings (tab)
The 'Settings' tab is used to define or display some basic features that do not depend on your terminal application, plus some special adjustable parameters (see below).
You have to fill out these settings according to the settings of your terminal.
- Interface type and/or I/O-Port address of the PCs CAN-Interface
CAN Baudrate to establish a connection to the programmable terminal
(Note: There are additional CAN bit timing parameters, part of the User Settings, which only have an effect inside the programmable device)
- Terminal node ID affects the SDO-identifier of the programming tool
The settings Terminal Node ID and CAN-Baudrate must match the settings in the terminal, if you want to upload programs successfully.
- In the terminal "UPT515" you have to check these settings in the terminals system menu, which you may enter (for firmware-release 29-May-2000) after simultaneously pressing F2 and F3. Use the cursor keys to find the menu-entries "CAN-Baudrate" and "Modul/NodeID" in the UPT515 to check or modify these parameters. After modifying the parameters in the UPT515 you have to save the new settings permanently with the "Save & Exit"-function !
- In other terminals, a similar way is used to access the system menu. To navigate through it, sometimes a rotary knob is used; instead of the ENTER key press the rotary button.
- After the initialization, there may be an other key-combination required to activate the system menu (for security reasons), or it may even be impossible to enter the system menu at all (after power-on). See "general UPT options"
The settings in the following table affect the behaviour of your UPT. These settings will be uploaded in the UPT (you only have to set them in the programming tool):
- the maximum number of display pages
- the maximum number of text-array lines
- the key combination used to enter the UPT's system menu
- Up to 32 non-volatile values which can be accessed through the UPT's interpreter
- and some other adjustable parameters which are explained below
The "number of icons" shown in the table is the current number of Icons which already exist in your applications. The amount of memory for icons usually depends on the number of display pages and other "specials".
You may click on the "Number of Pages" or the "Text Array Lines" if you want to change these values. A special dialog box will open which allows you to change the memory usage. Double-click on a cell in the "Parameter list". If the parameter can be modified by the programming tool, a special input dialog will opened like the one for modifying the system-menu key combination.
To modify the initial values of the non-volatile numeric array, scroll the "Parameter" list down until you can see the values. Click on the value to open a small "edit" window.
The "Terminal Constants" cannot be changed (except for a few exceptions listed below), they are only displayed for your information. Because there is a large number of UPT firmware variants and versions out there, the UPT programming tool attempts to read this information from the terminal when a program is uploaded or downloaded. Some of the "Terminal Constants" are:
- Hardware profile
- Software profile
- Firmware Compilation Date (of the programmable device), important to avoid conflicts with 'old' firmware .
- (max number of) SDO channels
- (max number of) PDO channels
- (max number of) Variables
- maximum size of the script sourcecode (in kBytes, target specific, and unknown by the time of this writing)
- max length of a format string (also usable as static display text or as menu item)
- max length of an event "condition" definition (counted by characters, usually 25)
- max length of an event "reaction" definition (usually 48 characters)
- max number of "global" events (usually 20)
- max number of commands per display page (usually 15)
- max number of display pages without "specials" (like text array and icons, usually 150)
- max length of a page name (usually 8)
- max length of a variable name (usually 8)
- max count of text message lines (usually 1024)
- max count of icons, limited by memory manager
- display type: 1=monochrome, 4=color with 4 bits/pixel
- display width: 128 pixels for UPT515 and UPT-Handheld, 320 for UPT320, "MKT-VIEW","IPE-VIEW"; 480 for "MKT-View II / III"; 800 for UPT800.
- display height: 64 pixels for UPT515 and UPT-Handheld, 240 for UPT320, "MKT-VIEW","IPE-VIEW"; 272 for "MKT-View II / III"; 480 for UPT800.
- plus a lot of 'other' infos which were used by the software developer for debugging purposes ;-)
The "Terminal Settings" (in the lower part of the panel, listed by parameter names) can be modified by clicking into that table. Some of the parameters in that table are:
CAN-Baudrate, Sample Point, Sync Width Jump
(for CAN bus 1 and CAN bus 2 in the programmable device)
Defines the baudrate, and some less frequently used bus timing parameters for the CAN-bus, which will be used while the application is running in the terminal. Please note that this is not always the same as the CAN-baudrate used in the programming tool for downloading.
Why isn't the CAN-baudrate under "Terminal Settings" the same as under "Programming Tool Settings" ?
Because not all CAN-interfaces support all baudrates, or because the 'application CAN baudrate' may be as low as 10 kBit/second. But wherever possible, set the CAN-baudrate under "Programming Tool Settings" and "Terminal Settings" to the same value - especially if you must download the application via CAN into the terminal while the application is running (which is always the case for CANopen devices ! ). If you need to download a new application via CAN into a terminal but the transfer fails, read the extra document 'Download troubleshooting'.
- maximum number of pages,
- maximum number of icons,
maximum number of text array lines :
are required for partinioning the memory inside the terminal when downloading a new application. More on the memory distribution here.
< TBD >
To open this dialog window, select 'Options' .. 'Zum Öffnen dieses Dialogfenster dient die Funktion 'Optionen' .. 'CAN Settings' in the tool's main menu.
In devices with firmware compiled 2011-04-01 or later ( * ), the following CAN-related parameters can be modified:
CAN-Baudrate in kBit/second. The baudrate "666" actually means 666.66666
kBit/sec; "83" is 83.33333 kBit/sec. All other (and less exotic) CAN baudrates
are precise integer values, not truncated.
- Position of Sample Point
Position of the sampling point within a CAN data bit. Unit is percent (of
the nominal CAN bit time). For automotive applications, usual values are
80 ... 83 percent, where 83 % is, in most cases, actually 83.3333 % . In
most devices with CANopen, this parameter has no effect.
- Sync Jump Width (SJW)
Width of the CAN synchronisation jump, measured in 'time quanta' units. Possible
range is 1 to 4 time quanta, but additional restrictions apply (depending
on the position of the sampling point). The CAN controller / firmware divides
each CAN bit into as many possible time quanta as possible. In some automotive
specifications, the number of time quanta per CAN data bit is also called
'BTL cycles' (BTL = bit timing logic in the CAN controller). Thus the true
SJW length (in microseconds or nanoseconds) depends on the hardware; especially
on the crystal clock frequency. As a rule of thumb, each CAN data bit is
divided into 10 to 20 time quanta. The actual value (used in the programmable
device) can be examined in the system menu, as described in the chapter titled
"CAN Bit Timing Parameters" in document #85115
- Flexible Data Rate (FD)
Bitrate for the 'fast' data field after the CAN FD bitrate switch (between message-ID and data field).
Usual bitrates for CAN FD are 1000, 2000 or 4000 kBit/second, in rare cases also 8000 kBit/sec (if cable, connectors, and the transceivers on both sides permit).
This field is only enabled if the currently selected device supports CAN FD, for example the MKT-View V (under development in 2019).
When selecting a device/display, the info about which of the CAN ports also supports CAN FD is copied from an internal database into the current device profile. For example, an i.MX RT1064 has three CAN controllers, but unfortunately only one of them supports CAN FD. In that case, the device firmware would map the FD-capable controller (called "FlexCAN3" by NXP) to the first logic CAN port ("CAN 1").
See also: Notes on CAN FD capable ports in the MKT-View V.
- Activate the following flags, and include them in the config :
With this (rarely used) option, during a program transfer into the target
device, settings made in the device's System Setup menu
will be overwritten with the settings from the new application (*.cvt).
If this option is not checked, the CAN-related parameters listed below
will remain unchanged (in the nonvolatile system setup, e.g. EEPROM):
- Enable Transmit and Acknowledge
Allows transmitting CAN frames and acknowledging received frames.
If this option is unchecked, the CAN node will be turned into a 'passive listener' (Listen-Only Mode).
Note: This option only works for devices with suitable CAN-hardware or -controller, like MKT-View III / IV / V !
- Active Terminator (Resistor)
Turns on the CAN bus termination resistor (usually 120 Ohms), if that resistor
is switchable aka "software controlled". Please consult the literature
on CAN bus topologies to learn where the 120 Ohm resistor should be located
(on the end of the cable or a long stub, but that's now the whole story).
Devices with a software-switchable CAN termination resistor are MKT-View II, III, IV, V, and possibly any later device. Details about the availability of a switchable terminator (and its resistance) are only in the device's datasheet.
(*) In very old devices like MKT-View "Plus", or devices with firmware older than April 2011, only the CAN baudrate could be configured, but not the position of the sampling point and the SJW parameter (Sync Jump Width).
On the right side of the 'Settings' tab, you will find two panels which only affect the programming tool, but not the programmable terminal. The upper panel, titled 'Programming Tool Settings', is used to ...
- configure the CAN bus interface (click on the 'Select and Configure' button to open a special dialog for that),
- select the CAN baudrate (used to download the application into the terminal via CAN-bus),
select the serial interface (like "COM1"). This was formerly used to download
the application into the terminal via RS-232 (utterly slow).
This port can also be used to connect a GPS mouse, to emulate devices connected to a GPS receiver in the programming tool;
set the serial port baudrate (used by the programming tool). Note: Not
all baudrates are supported by all devices !
Especially baudrates like 230400 and 460800 bit/sec will only work with suitable hardware (like USB adapters).
This baudrate is used for the normal program download via RS-232, and also for the file transfer utility.
- select the terminal's node ID (which is important for CANopen networks, if the application is downloaded via CAN / SDO),
- modify the programming tools own node ID (which is used if the programming tool shall simulate a CANopen node, just like the terminal),
- select if and how the programming tool shall produce sounds (sampled audio, or just 'beeps', using the PC's soundcard)
Configuration of the web server emulation (inside the programming tool).
Because running a web server in a PC program may cause trouble with the PC's firewall, this option is disabled by default.
Besides the option 'emulate Embedded Web Server', the server's (TCP-)port number can also be modified on this panel. The port number (usually 80 for HTTP) only applies to the simulation on the PC ! The web server in the 'real' device (MKT-View) is configured in the device's 'Network-Setup'.
The 'TEST' button (right next to the port number) can be used to establish a connection to the server (running on the same PC, using the loop-back IP 127.0.0.1 .
The adjustable directories / paths include...
- the directory in which you want to store your terminal applications (by default, this is the 'programs' folder),
- the directory which contains the help system in HTML format (you certainly never need to change this, in contrast to selecting a different HTML browser),
- the directory from which 'Icons' are imported by default (this can save a lot of time wasted in window's "file selector" dialogs),
- the directory for your own script include files,
- the 'gallery' directory,
- the 'fonts' directory,
- the directory where the optional font editor has been installed (so the programming tool can launch it from a menu),
- the directory where the optional CAN logger utility has been installed ( " " " .. ),
- the directory with wave audio files (used to simulate certain terminals with analog audio output capabilities),
- the directory for the simulation of the memory card, used to develop advanced applications (with file I/O via script) without a 'real' target hardware.
You can revert to the default settings (as after a 'fresh install') by deleting the configuration file in the windows directory. Examples (for windows XP):
- Programming Tool for displays with 'CANopen' : C:\WINDOWS\MKT_CANopenTerminalProgTool.ini
- Programming Tool for displays with 'CANdb' : C:\WINDOWS\MKT_CANdbTerminalProgTool.ini
The programming tool itself should have been installed
into c:\MKT\CANdbTerminalProgTool\*.* - see notes on
'Circumvent trouble with non-writeable windows "Programs" folders'.
The directory settings are contained in the section beginning at [Directories] .
None of the programming tools by MKT uses the windoze registry to store important data.
The 'UPT file description' is an optional text string, contained in the *.cvt or *.upt file.
This description should be a short descriptive information (short enough to fit into a single line of the display). The script demo 'AppSelector.cvt' shows this string instead of the 'DOS'-filename because a DOS-filename, limited to 8.3 characters, is usually not sufficient to provide enough information (for a human operator) to pick the right application for a given purpose.
Example (from the 'AppSelector' demo, which uses a graphic table with all *.cvt files, or their descriptions, found on the memory card):
The file description can be modified by the programming tool via 'File' menu, 'Description' :
The file description is stored at the begin of the file, in the non-encrypted part.
That way, the 'Application Selector' script can parse it even if the file is encrypted.
The example below shows the first lines of a CVT file with the description:
The script in the AppSelector demo uses the file.read function to extract the description from a *.cvt or *.upt file.
; File: c:\MKT\CANdbTerminalProgTool\programs\Brake_T1.cvt ; Saved: 2015-03-05 11:12:13 ; Type: program file for user programmable terminal ; Producer: programming tool compiled Mar 5 2015 Description="Brake Test, Track 1" Encryption=0 PwdHint1="" Password1=""
file access via script) with no 'real' target hardware, the memory card can be emulated by a freely selectable subdirectory on the PC's harddisk (Parameter "Simulated MC" on the panel labelled "Directories").
To simulate insertion or removal of the memory card (in the card slot of a 'real' device), use the programming tool's main menu, 'Options' ..
'Simulated Memory Card' (toggles between 'INSERTED' and 'REMOVED').
There are some debugging-features in the UPT programming tool (besides the script-debugger):
- The "watch"-window can be used to examine the contents of some variables or other expressions;
- The "test command"-window lets you enter commands for simulated received CAN-telegrams etc.
- The "Error page" shows error message from protocol violations, and other messages.
- The "Logfile Replay Utility" allows to play CAN messages from a file, instead of a 'real' CAN bus.
- For the script language, additional tools like breakpoints, single-stepping, inspection of (script-)variables, trace history, etc are avaiable.
Besides that, the following debugging options can be used without a programming tool :
For devices with Ethernet (LAN) port and integrated web server (like MKT-View
II), you can remotely control and supervise the device through a web browser
(at least, with Firefox). On the 'Remote Control'-page, you can send commands
to the display interpreter, and you can inspect variables (similar to the
programming tool's 'watch'-window). Technical details about the web server
can be found
on the MKT website).
Details about the network configuration (IP address, HTTP server port, etc) can be found in document #85115, "System Setup" .
- Devices with a 32-bit CPU (like MKT-View II) have a built-in error history, which can be inspected through the terminal's system menu (in the system menu, select 'Diagnostics'..'Show Error History').
Try the table of contents if you need further help.
1.20.1 Watch window
The watch window is a debugging tool. It can be used to display the values of some numeric expressions. This window can be opened via the main menu of the programming tool ("View").
You may enter any numeric expression in
the left column of the table, but you should avoid calling functions with
"side effects" (like
kb) in the formula.
To examine values of your script (running in the background),
use the prefix 'script.'
before the name of a script variable or -function call. Inspecting entire structs or arrays
is not supported here - use the script debugger for that purpose.
The 'Format' column can be used to define how the calculated values shall be displayed (output type and number of digits). Possible format types for the watch window are:
- d,D decimal
- +,- decimal, always signed
- h,H hexadecimal
- b,B binary
You may also specify the number of digits for the watch display. Type the
number of digits directly after the format letter. Examples:
|10 / 3||+00000003 (result = integer)|
|1.0 / 3||+ 0.333 (result = floating point)|
Note: If a watch expression is incorrect, the numeric interpreter will generate error messages which may appear on the error page of the main window. Because all expressions in the watch window are evaluated frequently, the list of error messages may get quite long !
The current value of the expression is displayed in the column titled "Result". In some cases (for example if the expression is just a simple variable) it is even possible to modify (edit) the displayed value here. To do this, click into the cell with the displayed value, overwrite it (type the new value into the field), and press the ENTER key when finished.
1.20.2 Test Command Window
The "test command window" is a debugging tool. It can be used to enter some text lines with commands for the command interpreter .
This window can be opened via the main menu ("View") of the programming tool.
The upper part of this window is a little text editor where you can enter some test commands (like "sim_rx" if you want to test how your UPT-program reacts when certain CAN-Telegrams are received).
Just enter a line of text (or load an old set of commands from a text-file), set the cursor into the line with a command and press "F2" to execute that line as a command.
The lower part of the window is used to display "results" after some commands like "print" or if errors occurred during the execution of a test command.
Note: All these commands are executed "locally" by the command interpreter of the UPT programming tool. You do not have to connect a real UPT-hardware for debugging.
1.20.3 Logfile Replay Utility
The 'Logfile Replay' utility is also a debugging tool integrated in the programming tool (non-CANopen-variants only). It allows you to play back CAN messages into your application, as if they were received from a 'real' CAN bus. The messages are read from a simple text file, compatible with Vector's 'ASCII' format. Many CAN analyser programs (including MKT's CAN logger, but also the CAN snooper integrated in some terminals with 32-bit CPU) are able to record CAN traffic in this format.
This is very useful if you want to test your application's CAN message
processing, but don't have a suitable CAN bus
interface installed on your PC.
To start the Logfile Player, select
- 'Tools' ...
- Play CAN Logfile to the Simulator
from the programming tool's main menu. A file selector will ask you for the location of the CAN logfile, and for the file type (usually 'Vector ASCII Logfiles / *.asc').
After that, a control window for the logfile player will pop up:
Click on the VCR-style 'Play' button [►] to start playing CAN messages from the file into the simulated CAN-bus. In fact, the messages read from the logfile are injected into the CAN-driver's low-level receive buffer.
Optionally, you can play the logfile over and over in 'Loop Mode'. This is
especially helpful if the file only covers a few seconds of recorded CAN
Since May 2015, the relationship between CAN bus numbers in the Vector ASCII Logfile (*.asc) and the CAN interface number in the simulierted device can be edited in the Logfile Player's control window (see screenshot, "Source Channel for Bus 1" = 1", "Source Channel for Bus 2" = 2). If necessary, up to four source channels can be entered (separated by comma). With these defaults, CAN messages recorded as 'channel number one' in the ASC file will be treated as if being received from "CAN1" (in the simulated MKT-View), etc. Reason for this: A customer had to simulate a CAN network where the first CAN interface (from the MKT-View's point of view) had been recorded as channel number 8 (EIGHT) by some unknown tool.
During playback, the CAN-messages can also be displayed on the 'error page' (set the option 'Show RX Frames' to see received CAN messages; in this case: "received" means "played from the CAN logfile into the simulator").
Certain CAN messages can be suppressed when playing back a CAN logfile into the simular. For example,
CAN frames with a certain message-ID may be contained in the recorded file, but would disturb
the simulation and thus need to be suppressed. To achieve that, enter the hexadecimal message identifier(s)
in the field labelled 'Reject (Rx,Tx,id)' on the logfile player panel. Multiple entries must be separated
by comma. Furthermore, by adding 'Tx' in that field, all messages marked as 'Tx' (transmitted) in the logfile
can be suppressed during playback, while 'Rx' can suppress playing all messages marked as 'Rx' (at least in
"Vector ASCII" format). Example:
Reject(Rx,Tx,id): 0x1CFECBFF, Tx
Suppresses all CAN messages with a (29-bit) identifier 0x1CFECBFF, and all frames marked as 'Tx' in the file (which means, we guessed, 'sent' from the recording device's point of view).
The player resumes ('continues to play') when the script is script is allowed to continue (F9 = run) at the position where it had been stopped before.
This avoids a backlash in the CAN-receive-buffer of the simulated device.
It also simplifies to debug own CAN-receive handlers (in the script), because after hitting a breakpoint (for example, in a CAN receive handler) you can easily switch to the 'Errors and Messages' tab, which will optionally show the most recent CAN message(s) 'sent' into the simulation by the CAN-Logfile-Player (at the bottom of the list, in chronological order).
When finished, details about the CAN message generator / simulator will be available in in an extra file (CANSimulator_01.htm).
The packet capturing feature is integrated in the device firmware so you can examine packets received and sent by the programmable terminal. (You could, of course, let Wireshark capture the packets itself, but in that case it can only 'see' the packets which arrived at the PC, which is not necessarily the same as on the device 'at the other end of the cable'.)
The flag "received" or "sent", from the terminal's point of view, is also saved in the Wireshark-compatible capture file, so it's easy to tell which of the captured packets has been received, and which of them has been sent.
Depending on the device configuration ("Main System Menu" .. "Diagnostics" .. "Ethernet Capture"), the 'Packet Capture' buffer may contain received and transmitted Ethernet packets and/or CAN frames.
If you have no access to Wireshark, you can directly watch the Ethernet traffic on the terminal's own display.
Alternatively, the terminal can convert the captured data into simple HTML, which you can read and analyse with any modern web browser. The screenshots below show the same captured Ethernet traffic in a browser (left) and in Wireshark (right).
Blue : Received frames (from the device's point of view),
Green: Transmitted frames (from the device's point of view).
Unlike the display in Wireshark, CAN message identifiers are not shown in the 'Info' field but in the column titled 'Source' (for received frames, blue) or 'Destination' (for frames transmitted by the device, green). 11-bit message identifiers are displayed with 3 hex digits, 29-bit IDs with 8 digits. For CAN, the 'Info' field only shows the data field (max. 8 bytes, hexadecimal without prefix). Example:
Packet Capture Status : Running, captured 5 packets . No. Time Source Destination Prot Length Info 1 0.00000 CAN1:0x07B CAN 8 00 02 03 04 05 06 07 08 2 0.13405 CAN1:0x000003FF CAN 8 05 44 4C 34 59 48 46 20 3 0.43712 CAN1:0x07B CAN 8 01 02 03 04 05 06 07 08 4 0.53385 CAN1:0x000003FF CAN 8 05 44 4C 34 59 48 46 20 5 3.12532 192.168.0.206 192.168.0.234 TCP 117 TX "HTTP/1.0 200 OK\r\nContent-Type:"
The direct display as HTML lacks many of the features in Wireshark (recognized protocols, protocol errors, interactive inspection / decoding of thousands of different 'fields' in the TCP/IP data, ..). Thus, if possible, open the captured data in Wireshark (as shown in the right screenshot above).
User-friendly browsers can be configured to open Wireshark automatically when recognizing a PCAPNG file. The browser then downloads the capture buffer (capture.pcapng) and stores it as a PCAPNG file, launches Wireshark, which then loads and displays the captured frames in a matter of seconds.
Details about retrieving the wireshark-compatible capture file via integrated HTTP server can be found here (external link to the MKT documentation).
A few 'Wireshark Tricks':
- Looking for 'lost messages', for example in periodically sent CAN frames :
Define a filter like "frame.time_delta > 0.1", to show only frames following a (time-) gap of over 100 milliseconds (since the reception of the previous packet).
Because filtering for a certain CAN message ID is (or at least was) difficult in Wireshark, turn off the option 'any ID' via web browser, before starting the capture. Without the option 'any ID', the packet capture will only contain CAN messages with 'registered' message identifiers, for example messages that your application wants to receive via script, or CAN messages carrying signals defined via DBC-Import, and connected to display variables.
Since development of a 'simple display terminal for the CAN bus' many years ago, the complexity of transfer options grew significantly.
Most devices support the following transfer modes / methods between the programming tool and the programmable device :
- Transferring the application into the terminal ("Upload")
- Remote control (for devices without a keyboard)
- Transferring other files (with the File Transfer Utility)
- Upload via Ethernet ( UDP ) using the programming tool
- Uploading files via web browser (TCP/IP; external link)
- Discovering MKT devices on Ethernet (using a DHCP server)
- Automatic display program update via FLASH memory card
For devices with FLASH memory card (like MKT-View) we strongly recommend
to transfer the application (*.upt or *.cvt) via memory card, because this
is much faster than transferring files via CAN or RS-232 .
See also: Accessing files via HTTP Server (external link)
1.21.1 Program Upload
After creating and debugging your UPT application as far as possible, you
are ready to upload the application into the target (a UPT515, UPT167,
CANdb-display terminals or similar).
126.96.36.199 Transfer via CAN / CANopen or RS-232Connect the terminal with the PC with an interface cable (and/or a suitable CAN bus adapter).
Alternatively (if an RS-232 interface is availabe but no CAN), the serial port (often labelled "RS 232" on the adapter cable near the DSUB-9 connector) can be used to update the application or other files. But since the terminal's RS-232 port is often "occupied" by the application (via interpreter- or script-command), it must be temporarily be 'freed' before it can be used for transfer. To do this, enter the 'Main System Menu', enter submenu 'Other Transfers ...', and select the funktion 'Transfer via RS232 (SLAVE)'.
If the target is a terminal with CANdb functionality instead of CANopen, you must enable the program-transfer via CAN-bus:
- Enter the terminal's system menu (this is usually achieved by pressing the 2nd and 3rd function key simultaneously)
- Navigate to the menu item "Transfer via CAN = xx", press enter (or the rotary knob)
- Switch from "Transfer via CAN = OFF" to "Transfer via CAN = ON" (with the cursor keys or rotary knob)
- Press enter again to finish editing, and leave the system menu.
Note: This is required because in a generic CAN network, the IDs used
for communication between programming tool and terminal may be occupied -
and we don't want to cause collisions. For terminals with CANopen protocol,
the above step is not required because the program will be transferred via
SDO (service data object), which is always possible because the terminal's
default SDO channel is always open. Details about the upload via CAN (without
CANopen) are in this external document.
However, the above steps may be omitted if the 'Transfer Mode' is permanently enabled (i.e. set "Transfer via CAN = ON", then select "Save and Exit" in the setup). More details about the possible settings for 'Transfer via CAN' can be found in document #85115, titled System Menu and Setup.
Then, in the programming tool's main menu, select
- Transfer ...
Send Application to Terminal .
- Transfer ..
- Connection Parameters .... Medium .... CAN or Serial Port ("COM") or UDP/IP (Ethernet) .
If the programming tool cannot establish a communication, check the interface cables, termination resistors, communication parameters (baudrate etc) and try again. If still no success, check the programming tool's error page.
If you never sent a program to the terminal before, there can also be a problem with the installation of the CAN interface. Check our notes about the installation of a CAN interface, and carefully(!) read the documentation supplied with your CAN-interface.
To upload the application via CAN into terminals without CANopen protocol (like "MKT-View"), read this document too.
During the transfer, the programming tool shows its own software version (as 'recommended firmware' for the target), and the firmware version read from the remote device. Ideally, but are equal:
If the major or minor version numbers (first and second digit) are different, we urgently suggest to update the device firmware as explained here.
If only the revision or build number (3rd and 4th number) are different, new functions may possibly not exist in the target device, and an application which runs properly in the simulator (programming tool) may not work properly in the target device. An overview of software revisions, along with the latest additions, can be found here (on the MKT website).
Certain terminals like "MKT-View" can be loaded via asynchronous serial interface ("COM1" or "COM2"), or via memory card. See Feature Matrix. All terminals which have the load-via-card feature, have a unique way to update the display program automatically as described in a later chapter (-> "Autoload").
To transfer the application via serial port you will need to know the
baudrate which is currently configured in the target device.
Note: There is no universal 'default value' for the serial port speed, because some devices only support rather low speeds (especially those with 8- and 16-bit CPU);
furthermore the port's communication parameters could have been modified via command in the display application itself.
The currently used baudrate is displayed on the device's screen after entering 'transfer mode via RS-232', for example:
Transfer mode active Receiving PROGRAM RS232/3964R: 19200 bit/sec
To develop advanced applications (including scripts), the development cycle (modify-upload-test) can be speeded up by transferring the application into the target's RAM instead of the target's Flash memory. Details about script development, and how to test applications in the target's RAM (i.e. "send to terminal without flashing"), are in the document about the Script Language. Transfer 'without flashing' can save about 10 to 60 seconds, depending on the Flash chips used in the target hardware.
Last not least, certain terminals (MKT-View II / III / IV) also support a general file transfer method which uses the YModem protocol. For example, you can load all kind of files (if they are small enough) into the terminal's internal FLASH memory, or copy files to the memory card via serial interface, CAN bus, or Ethernet / UDP/IP .
188.8.131.52 Transfer via Ethernet ( UDP )
To upload the display application (and possibly other files, using the already
mentioned file transfer utility) via Ethernet / UDP, the programming tool
must be informed about the IP address and the port number of the remote device.
By default, devices like the MKT-View use DHCP to lease a 'dynamic' IP, and UDP port number 55556 for a variety of functions. This includes the CAN-via-UDP protocol, and a very simple file transfer protocol (both are based on UDP, not TCP/IP). If necessary, the target's IP adress can be detected as explained in another chapter.
To enter the IP address, and the port number, select
Transfer .. Connection Parameters .. Remote IP
(in the main menu), and enter the IP address, and (UDP-) port number of the device you want to connect. The syntax is <IP byte 1>.<IP byte 2>.<IP byte 3>.<IP byte 4> : <Port Number> .
( Entering the remote address and port number in the programming tool.
IP address and port number taken from the remote device's network setup,
see screenshot on the right. Note: CAN-via-UDP set to SERVER . )
If the development PC has multiple network interfaces (for example, multiple Ethernet adapters), the local IP address of the development PC can be picked from a list:
In the programming tool's main menu, select
Transfer .. Connection Parameters .. Local IP
to open the dialog shown below. In the dialog, pick the IP address of your PC's Ethernet port. In a few cases, there may be multiple physical interface, which is why we need this selector. If the PC only has a single network adapter, the list contains only one item.
Note: To establish a point-to-point connection via Ethernet cable (without a switch), you may have to connect the programmable device (MKT-View, etc) to the PC before you can select the interface.
Furthermore, the IP address of the remote device must be entered to program or remotely control it.
If a static IP address is used (in the device, e.g. MKT-View), this is simple: Just read out the address in the devices 'Network Setup' (field 'IPaddr') and write it down (on paper) for future use.
If a dynamic IP address is used (leased from a DHCP server somewhere in the network), you can try to 'find' the device's momentary address via the tool's main menu, 'Transfer'..'Discover MKT devices on the Ethernet LAN', or (if that doesn't work for one of many possible reasons) read out address from the device's display as described below :
( Determining the IP address of an MKT-View when DHCP is in use.
Grayed entries in field 'IPaddr' mean 'leased address, not editable'.
In this case, the fields show the currently leased IP address. )
The UDP port number is actually shared with the CAN-via-UDP server (thus, the item 'CAN via UDP' must be set to SERVER). Many devices made by MKT have this server for the CAN-via-UDP protocol built inside, as crude replacement for a physical CAN interface installed on the PC. (For developers, details about the protocol are in the documentation 'CAN-via-UDP').
But the presence of the CAN-via-UDP server in the firmware doesn't mean it is enabled ! Instead, it may be disabled through the device's Network Setup for security reasons. A typical Network Setup (with the CAN-via-UDP server enabled) looks like this:
typical CAN-via-UDP client/server configuration and Network
Setup in an MKT-View III
When initiating a transfer via Ethernet (UDP/IP), some paranoid 'Internet Security Suite', or the windows firewall, may block the transfer. In some cases, such a security software will inform you that it has blocked the access ("blabla is trying to act as an internet server" which is nonsense, anyways..), or will ask you for permission:
Other Examples :
- "Eine Anwendung, die als Internetserver fungiert, hat sich seit der letzten Ausführung verändert." (after program updates)
- "ctptwin1.exe (or uptwin2.exe) is trying to access the internet / act as a server / etc" .
- ... (feedback, please)
Kindly allow the programming tool to access the "internet" (in fact, it doesn't access the internet, it only tries to establish a connection through the local network using UDP).
Details about the Network Setup can be found in
document #85115, "System
Setup" (PDF, for users / operators) .
The protocol (on top of UDP/IP) is described in document #85140, "CAN via UDP" (PDF, for developers) .
How to use transfer other files via Ethernet is described in the 'File Transfer Utility / Transfer via Ethernet' (HTML, part of the help system) .
file transfer via web browser (HTTP; external link),
Discovering MKT devices on Ethernet (using a DHCP server) .
In most cases you will know the device's IP address or host name; thus there's no need to
'discover' the device as explained below. Simply enter the device's IP address or hostname (default: UPT)
in the address bar of your favourite web browser, and continue here .
The same applies to selecting the target device before uploading an application via Ethernet.
To 'discover' Ethernet devices by MKT in your local area network, select Transfer .. Discover MKT devices in the Ethernet LAN. This opens a dialog window, which guides you through the steps shown below. If all goes well, the program will detect the MKT device (identified by its MAC address), and show the device's current IP address (by listening to the DHCP traffic, or via openABK-'Discovery'-protocol).
|DHCP Server / OpenABK-'Discovery'
This function may be used to 'discover' an MKT-Device in the local network, without knowing the IP address of the remote device. In the next step, this program will try to find an MKT-Device, using the OpenABK-'Discovery'- and DHCP protocol. Depending on the windows version, you may have to allow this in the firewall. Click 'OK' to allow this program to act as a DHCP-SERVER and as an openABK-CLIENT temporarily.
Step 2 (old, without openABK):
|Waiting for reception of DHCP packets
The built-in DHCP server has been started, and is now waiting for reception of a 'DHCP-Discover' packet from a display made by MKT Systemtechnik. THE MKT DEVICE MUST NOW BE RE-STARTED FOR THIS PURPOSE. Please make sure the devices is configured for DHCP, and connect it to the PC via Ethernet cable. Then turn on the device. Shortly after turning the device on, the Ethernet activity LED should light up, the reception of a 'DHCP-Discover'-Packet should be detected here. Click on 'CANCEL', if you want to abort the connection set-up. Rx:DHCP-Request cip=192.168.0.106 mac=00:21:00:DD:19:A1 (etc)
|MKT device detected - connect it via Browser ?
A DHCP server has received a 'DHCP-Discover'-Paket from an MKT device, and assigned IP-address 192.168.0.101 to that device. Click 'Connect' to establish a connection to that device via web browser, or 'OK' to select this device as the current target system, or 'CANCEL', if you want to abort the connection set-up.
At the last step, click 'Connect' to establish a connection between PC and the programmable device
via web browser.
You can now use your web browser to upload display applications (*.upt or *.cvt) into the device, transfer other files, update the device firmware, remotely control it, get a screenshot of the current display (via copy-and-paste), dump the values of all display variables, examine the trace history, etc. Example:
More details about the device's integrated web server are
here (external link).
Alternatively (without a web browser), the UPT programming tool can use the new detected IP address to upload the application (or other files) as explained in the previous chapter, using UDP (not TCP/IP).
To do this, don't click on Connect in step 3 but on 'OK'. This will copy the new IP address into the programming tool's configuration. The (UDP-)port number will be set back to the default value (55556).
After this, if the target's CAN-via-UDP server is enabled, you can transfer your display application quickly into the target by selecting Transfer ... Send applikation to terminal.
184.108.40.206.2 OpenABK 'Discovery' Protocol
Besides listening to DHCP as explained in the previous chapter,
MKT devices can also be detected in the local network (Ethernet LAN) via the openABK 'Discovery' protocol.
Advantages: Doesn't rely on intercepting DHCP traffic, and thus also finds devices
with a static IP address.
Also, it's not necessary to turn the device off and on again (to force DHCP transmission) anymore.
Disadvantage: Only discovers devices with firmware compiled 2015-11-26 or later,
because older devices don't support the OpenABK-'Discovery'-protocol.
Note: Some MKT-Views (e.g. MKT-View III) support the OpenABK-Discovery-protocol, but they don't necessarily contain a fully-fledged OpenABK-HTTP-client or -server !
Devices which only support the discovery protocol will respond with "Key":"UPT" rather than "Key":"AbkServer" in their JSON-response for a 'discovery'-request (UDP broadcast).
This prevents problems with other OpenABK-clients in the network, which try to find 'their' expected OpenABK-server.
Devices 'discovered' this way are listed with their IP-address and 'name' (MKT: host name) in the programming tool:
(Screenshort with devices discovered after 'Transfer'..'Discover MKT- and OpenABK devices in the local network'.
Various devices have been found in the local network,
amongst them an MKT-View (4) with host name "MKTVIEW4WB"
and an Open-ABK-'Test'-Server reporting a wrong IP address in the response )
More details about the openABK support in the programming tool will be added here in future.
The protocol specification could be downloaded from openABK.org.
For english readers: 'openABK' = 'offenes Anzeige- und Bedienkonzept' = an 'open' protocol for the interaction between a 'display' and a 'logger', using TCP/IP, HTTP, and various web services.
When powering on, the firmware inside the terminal checks if a FLASH memory card is inserted, and if a special file is located in the root directory. The name of that file is:
- "autoload.cvt" for all terminals without CANopen (parametrized through CANdb, like the original MKT-View)
- "autoload.upt" for all terminals with CANopen-support (like the "UPT2"-family of devices)
If a file with the above name is found on the memory card, its file-date and -time will be compared with the currently loaded display program. If date or time is not equal, the firmware will automatically load that file from the memory card into the terminal's on-board FLASH. This feature can be used, for example, to prepare a complete setup for your customer (or an "unexperienced operator"), telling him: "Plug this memory card into the terminal (with the power turned off), then turn the engine/power on and start the test drive". You can also put the configuration file for the CAN-logger on the same memory card, so everything fits together. The terminal will then do the rest automatically, the operator doesn't have to press a single button to load the new configuration.
1.21.2 Firmware Update
When sending your terminal application into the terminal, the programming tool may tell you that the terminal's firmware is too old. In this case, a firmware update in the terminal is necessary to maintain the compatibility between the programming tool and the terminal.
A guide how to update the terminal's firmware is in the same directory in the file fwupdate.htm . In that document you will also find the password which must be entered in the programming tool to upload the firmware via serial port or CAN-bus.
Before updating the terminal's firmware, also read the firmware release notes carefully before proceeding. It may describe some hardware-specific limitations which are not mentioned in the programming tool's manual !
Then, in the tool's "Transfer" menu, and select "Update FIRMWARE via serial port". The tool will then prompt you for the password which you found in the above document.
- The firmware in MKT's UPT515 can only be updated via CAN-Bus, because this device has no serial port. You need a special program (written by MKT) in this case. For more info, see fwupdate.htm.
- Never interrupt a firmware update, if it's already in progress ! During transfer, do not start any other programs to minimize the risk of a PC crash. If such an accident happens, or someone rips the cables off, you must activate the terminal's bootloader manually be pressing the 1st and 3rd function key while turning the terminal's power on, and repeat the firmware update.
- (Not translated into english yet ... use your imagination ... )
Für Geräte mit ARM-CPU (z.B. MKT-View II, seit 11/2008) wird zur Ablage der Firmware nicht mehr das HEX-Format ("Intel Hex") verwendet, sondern ein platzsparenderes, segmentiertes Binärformat mit der Dateinamenserweiterung "BI2" . Achten Sie darauf, dass Sie beim Laden der Firmware für diese Geräte in der Dateiauswahlbox den Dateityp von "HEX Files" auf "SEGMENTED Binary Files (*.BI2)" ändern, andernfalls werden Sie die passende Datei nicht finden.
For newer devices with Cortex CPU, 'sufficiently large RAM, and an integrated web server
the firmware can be uploaded into the device's RAMDISK via HTTP .
Details are in the desciption of the embedded HTTP server .
1.21.3 Screen Snapshot via CAN
To generate a printed documentation for the user of your UPT application, you may include "screen photographs" of the terminals displays. You dont need a camera for this purpose, it is possible to take a screen "snapshot" via CAN-Bus.
Start the "Snapshot" dialog from the "Transfer" menu of the programming tool.
The parameters on the right side are used for the communication between the tool and the terminal. You will usually not have to modify these values (only if you want to make snapshots from devices that are not UPTs).
All you have to do is click on the "Start !"-button to freeze the actual LCD-contents in an internal buffer of the connected terminal. The buffered data will then be transferred to the snapshot utility (pixel by pixel). After completion of the transfer, you may click "OK" to save the received image as a bitmap-file, or click "CANCEL" to discard the received image.
Note: The Screen-Snapshot-via-CAN does not work for devices with CANopen V4 yet, and will never be available for terminals with "CANdb" (like MKT-View) !
Return to the table of contents
1.21.4 The PCs CAN interface
To communicate via CAN-bus, the UPT programming tool requires a CAN-interface for the PC. This interface will usually be connected to the USB port, or (a long time ago) on the parallel port (like "CAN-dongle" by PEAK or "CAN-PCC" by ESD).
Before installing the CAN-Hardware in your PC, you must read the instructions
of the CAN interfaces manufacturer !
MKT will not be responsible for any damages. More information may be found in a separate document.
The following interfaces can be used in the UPT programming tool:
PCAN-Dongle by PEAK
The PCAN dongle is a simple interface for the parallel port. Since August 2001, using one of Peak's CAN software drivers is recommended, preferrably the "PCAN Driver V2".
NTCAN by ESD
The NTCAN API supports several CAN interfaces, like interfaces for the parallel port, ISA- and PCI-slot.
A universal and very robust driver Kvaser AB, supporting all (?) of Kvaser's recent CAN bus interfaces for the PC.
Since 2019, the programming tools by MKT also support CAN FD with suitable interfaces by Kvaser. In the programming tool, the 'fast' bitrate for CAN FD must be configured in the CAN Bus Parameters dialog to match the current device settings.
VECTOR XL Driver
Last tested with 'CANcase / VN1610' on a Windows 7 PC, where the relation between 'Channel' and physical interface required a bit of trial-and-error (until arriving at the correct 'Channel Name').
See hints about the Vector CAN Hardware here.
A few more general notes about the installation of a CAN interface can be
To 'upload' (send) configurations from PC into the programmable device, we generally recommend to use other interfaces (which are much easier to install and use on a windows PC than CAN), for example a serial port (RS-232 or virtual COM port) or the Ethernet interface as explained in the next chapters.
Certain terminals (like "CVT-MIL 320") have an integrated USB-to-Serial-Port adapter, sometimes called Virtual COM Port. Recent Windows versions (at least XP) will automatically detect this type of USB adapter automatically when you plug in the device for the first time, and install a bunch of drivers (by FTDI, FT232R, VCP, etc).
If Windows fails to recognize the USB device, try to find the right
VCP driver for your operating system on the
FTDI website, and install
it yourself. Please respect the fact that we (MKT Systemtechnik) were unable
to test the FTDI VCP drivers on all of the fourteen different windows
versions which supported the FTDI chip (FT232R) in January 2010.
If you run into trouble with the USB drivers, it may help to plug the device into a different USB connector (your PC will definitely have more than one). Sometimes windows seems to lose track of the USB drivers installed on the system, and refuses to recognize the device with a message like this:
(Did you really expect to fix an USB driver bug by clicking on this message ? Get real ... )
At least on the authors machine, it helped to connect the device to a different USB port as mentioned above (plug and unplug the USB cable on the PC side a couple of times). In a tougher case, it was necessary to get rid of some USB driver junk, which had accumulated on the PC over the years. To spot the problem, use a tool like Microsoft's "USBView.exe", which could be downloaded in January 2010 on the FTDI-Website(!) under " Microsoft USBView - USB Connection Viewer". There should be an "USB Serial Converter" listed somewhere in USB View, and the connection status 'DeviceConnected'. To remove of unused USB drivers, ask your friendly search engine how to "get rid of unused USB drivers" .
- Important note on USB, which has always been a nuisance for developers:
Always connect the programmable terminal to the same USB plug on your PC.
Otherwise, Windows will always select a NEW COM PORT NUMBER which is very, very annoying.
If, for example, Windows decided to use "COM10" yesterday, but "COM11" for the same device today, you will find something like the following in the combo list of serial ports:
Furthermore, connect the terminal's "USB port" (which is in fact a virtual COM port) to the PC before starting the programming tool.
If the connection between the PC (programming tool) and the programmable device (terminal) uses USB and a Virtual COM Port, the 'serial' baudrate can be set to unusually high values (like 230400 or 460800 bit/second) on the 'programming tool settings' tab. In 2010, most new devices with ARM-CPU and USB/VCP had an automatic baudrate detector function built inside the firmware, so in those cases, the file transfer utility can use this higher baudrate even though the default baudrate (in the terminal) is only 19200 bit/second, or the display application has switched to a different baudrate via interpreter command .
Most variants of the UPT firmware have a built-in system menu that you may
enter with a special combination of keys (for example, F2 + F3 pressed
simultaneously, or whatever you defined as "key combination" under
general UPT options ).
In devices which only have a touchscreen (but no "real" keyboard), the system menu can be invoked via the touchscreen gesture "rectangular U", as shown in the photo below:
Details about the system menu are in the printable PDF, see the link to document #85115 at the end of this chapter.
In many devices, the system menu can also be operated via
remote control, for example through the RS-232
interface and a terminal program, or through the Ethernet port using TCP/IP
and TELNET. In those cases, send CTRL-S (STRG-S) from the remote terminal
as a replacement for simultaneously pressing F2+F3.
Here is one example of a system menu (snapshot taken from old UPT515 firmware, it may look totally different on your hardware but the basic principle is the same):
The basic operation of this system menu (and sub-menus) is as follows:
- press the special key-combination to enter the system menu (if not disabled by the general options, otherwise use the trick described here )
- use the Cursor UP / DOWN keys to scroll the black selection bar to the desired menu item
- press ENTER to edit the value of a menu item or to "jump" into that menu
- press ESCAPE to return from a menu
- use the menu item "Save & Exit" after modifying values that shall be saved permanently (like, for example, the contrast value for the LC-display)
Where applicable, you will find menu items to initiate a program upload manually (in the Mobile CAN Terminal, where the SDO server must be activated expecially for program upload).
Some important parameters which have to be set in the UPTs internal System/Setup menu are:
Display setup, hardware dependent, possibly
with LCD-contrast adjustment, backlight control,
clockwise or counterclockwise rotation for 'Portrait' mode (depending on how the device is mounted), touchscreen gesture options, etc;
- Audio setup, also hardware dependent, with settings like touchscreen click volume, microphone gain (where applicable), speaker output volume, etc;
- Date and Time setting, if a battery-buffered real time clock is supported;
- CAN setup: Important for the communication between UPT and programming tool.
- Module/Node-ID (very important for the communication between UPT and programming tool)
- Network Setup : see next chapter .
- other hardware dependent features like CAN-Transmit-Enable etc
- Enter an unlock code to activate certain, 'special' features
Note: CAN-Baudrate and Node-ID must be equal in the UPTs Setup menu
and in the programming tool. Otherwise you cannot upload UPT files from the
programming tool into the UPT (see chapter general
Caution: The terminal application may have to run with a CAN baudrate which is *not* supported by the PC's CAN interface (10 kBit/sec for example). For that reason there is an extra definition for the CAN-baudrate for the application in the programming tool on panel "Terminal Settings". These two different places to set the CAN baudrate caused some confusion in the past - more on that in the chapter about the tool's Terminal Settings panel (remember this when the programming tool cannot communicate with the terminal, because you changed the CAN baudrate somewhere !).
On certain terminals, there is a menu item called User Settings where you can..
- Show and modify the "operational" baudrates for two CAN interfaces. These CAN baudrates are part of the application, not part of the terminal's system settings. The "User Settings" take effect when the terminal loads and initializes the application. If there is no application loaded, the terminal uses the CAN baudrate from its "system" menu. If the CAN-baudrate in the terminal is different from the CAN-baudrate used by the programming tool, you may get into trouble... see 'Download troubleshooting' in that case !
- If you need a CAN-baudrate which you do NOT find in the list of supported baudrates, you can -alternatively- define the value written into the CAN controller's BTR (bit timing register) directly in hexadecimal form. Caution: this option only exists in a few terminals (like MKT-View "Plus"), and we highly recommend NOT to use this feature because you will have to calculate the BTR-value yourself. More info on that subject can be found in this extra document (only available in english language).
- Edit the values of the non-volatile numeric array (located in EEPROM, can be accessed through the UPT interpreter)
In devices with a sufficiently large code memory, the following 'diagnostic' functions can be invoked through the system menu / submenu "Diagnostics":
- Inquire version info, compilation date, and status of unlockable features
- Invoke the bootloader (for a firmware update)
- Restore the "BIOS" default settings (baudrates, node identifiers, etc)
- Show the error- and/or trace- history (for devices with script support)
- Browse the programmable display pages:
After switching to a different page (here: via cursor keys or rotary button), the current page number and -name as briefly displayed. Press Escape or F3 to return to the 'Diagnostic' menu.
- List all display variables (including their current values)
- List all objects currently stored in Flash memory
- Erase all Flash memory ranges with data and application ("declassify" before shipping)
- Show extended CAN / CAN FD bit timing parameters
Devices with built-in CAN logger (e.g. "MKT-View") also have a built-in CAN bus monitor (CAN Snooper), which can also be invoked through the system menu.
Some of the functions in the system menu can also be invoked directly from the user application with an interpreter command , for example to adjust the display contrast or set the battery-buffered clock (if present).
If the device has neither a keyboard, nor a rotary encoder knob, nor a touchscreen, the system menu must be invoked via Remote Control (requires a special terminal program).
Since 2011-07-12, a few (display-related) setting in the system menu can optionally be overwritten when downloading a configuration (*.cvt or *.upt). See optional display setup for details.
More information about the terminal's "System Menu" can be found in this printable document (PDF #85115) .
Alternatively, devices with Ethernet (and TCP/IP) connection can be configured via web interface (HTTP) .
For devices with Ethernet port and TCP/IP, the Main System Menu contains an item labelled Network Setup .
The network setup must be used to set the local (and static) IP address of the device, and other parameters relevant for TCP/IP (and, sometimes, UDP) .
Parameters which can be modified in the Network Setup:
- (1) The device's Ethernet MAC address .
- (2) The device's name (hostname) in the local network .
- You can access the device by entering this name in your web browser,
which may be easier than entering the IP address - especially in combination with DHCP.
The default name is "upt" (short for User Programmable Terminal), but you may want to modify the name. You must change the name if you have multiple "upt"s or MKT-Views in your local network.
- (3) Configuration of DHCP (static or dynamic IP address)
- If a dynamic IP shall be used, there must be a DHCP server somewhere in the network, and the following fields (4..6) are meaningless.
A fixed IP may be easier to use, especially when communicating with other embedded devices which don't support DHCP.
- (4) The device's own (local) IP address .
- This is the static IP, which is saved in a configuration EEPROM. Only has an effect if DHCP is disabled (see item 3).
- (5) Subnet mask
- Like the static IP (4), this parameter only has an effect DHCP is disabled.
- (6) Default Gateway Address
- Like the static IP (4), this parameter only has an effect DHCP is disabled.
- (7) Local TCP Server ports:
- HTTP: Integrated HTTP server aka "web server" (default port: 80), Telnet (default port: 23), and FTP (not functionable yet, default: 21)
- (8) CAN-via-UDP mode : Possible settings are "off", "Client", or "Server".
- Note that unlike some PC software, the terminal can be either client or server, but not both at the same time.
- (9) CAN-via-UDP parameters :
IP address of a remote CAN-via-UDP server (used if the device acts as a client),
and local port number if the device acts as a CAN-via-UDP server itself.
Note: If you are not familiar with the basics of TCP/IP, follow the external links (which mostly lead to Wikipedia). Furthermore, read a good textbook on network basics !
Pressing the enter key (or, if no such key exists, the rotary encoder button) to switch between 'Navigate' (i.e. move the selection) and 'Edit' (i.e. modify the selected parameter). A short note about the currently selected parameter is visible in the bottom line.
Details about the network setup can be found in document #85115 ("System Menu and Setup").
Alternatively, the network setup can be modified via web interface as described here .
Some "display terminals" by MKT Systemtechnik have neither a keyboard, nor a touchscreen, nor a rotary encoder button. To configure and control them (especially operate the terminal's system menu), a crude and simple remote control function was added in the firmware of such devices.
Devices with integrated web server (like MKT-View II, MKT-View III) can also be configured and supervised via embedded web server. Depending on your network settings, a device may be accessable in a web browser using a simple address (pseudo-URL) like UPT (UPT=default host name for all User Programmable Terminals).
Details about how to operate the system menu via remote control (or web browser) can be found in the document titled Remote Control for programmable terminals.
Return to the table of contents
1.23 Advanced Information
This chapter provides some information about the internal functions of the User Programmable Terminal.
- Interpreter Commands
- CANopen-Objects inside the Terminal
- SDO error codes
- Troubleshooting and frequently asked questions
1.23.3 Troubleshooting and FAQs
This chapter contains a collection of (more or less) "common" problems and their possible
solution. See also: FAQ (frequently asked questions).
- Issue: Immediately after power-on,
an MKT-View (II,III,IV,V) sends Morse code through the internal 'beeper'
but nothing appears on the screen.
- Reason: This 'Morse' output is a left-over from the firmware development phase.
It an ARM-Cortex processor 'crashes' for one of dozens of possible reasons,
it gets stuck in an 'exception' handler. If this happens before the CPU had
the chance to initialize the LC Display (for example, due to problems with
the SDRAM or Flash memory), sending out an error message in Morse code
through the internal speaker (aka 'buzzer' or 'beeper') was the only chance
to give the developer (a Ham Radio operator) a chance to "hear what had gone wrong",
because without functional SDRAM, the CPU cannot drive the LCD at all.
Fix (1): If you hear those Morse code 'dots and dashes', turn the device off, let it 'cool down' for a minute, and turn it on again. In most cases, if the crash (exception) was caused by an EMC problem, or by a too-slowly-rising supply voltage (which broke down again as soon as the CPU started "drawing current"), the 'cold start' will work properly.
If the problem occurrs more than once, and cannot be cured by a 'cold start' or a firmware update plus re-loading of the user application, return the device to the manufacturer for inspection. Leave a note for the repair crew about what happened (including environmental parameters like supply voltage and ambient temperature).
- Issue: An old UPT firmware crashed after a program update.
- Reason: The new firmware may use a new internal storage format
for the user program. More recent firmware versions automatically detect this,
and refuse to use the old configuration. Only firmware for long-outdated devices
(e.g. UPT-515) may suffer from this problem.
Fix: Bypass loading the "old" user program by holding F2+F3 on the UPT's keyboard pressed before and while turning the power on.
The UPT will then enter the system menu. Exit from the system menu by pressing ENTER with the EXIT-item highlighted. The UPT firmware will now display "no display page loaded" or something like that, because it has not loaded the (incompatible) user program. Connect the UPT to the programming tool and load a new program into the terminal.
Everything should be ok, because the terminal now has a user program in the "new" internal storage format.
- Issue: An old UPT shows "Loading XYZ.... error" when initializing after power-on.
- Reason: Similar as in the previous topic. The device tried to load some
tables from its internal EEPROM or FLASH into RAM during the initialization.
It also checked some data structures (in the "user application"), and
detected an incompatiblity. In very rare cases (EMC trouble), this was caused
by an accidental loss of the EEPROM / FLASH-contents.
Fix: Similar as for the previous topic (re-load the application).
- Issue: Reception of CANopen PDO (process data) didn't work in the programming tool (simulator).
- Reason: The simulator inside the antique 'CANopen' programming tool did not have
PDO functionality, because the PC's antique CAN-interface ("CAN-dongle" for example)
did not have a full-CAN-Controller like the "real" hardware. The "real" hardware
used a "full-CAN" controller which had enough message objects
for each CAN message identifier.
Fix: Upload your UPT program from the programming tool into a "real" UPT-device and test it there, if you want to receive PDO frames.
Recent versions of the programming tool, and any recent CAN interface you can think ok has a microcontroller built inside, which doesn't suffer from the bandwidth problems as those stone age "parallel port dongles" w/o buffering.
- Issue: While editing the "display line" table, the tool suddenly switches to another display page.
- Fix: Stop the simulation (execution of the user program) by clicking "STOP !" in the main
menu of the programming tool. The Status Line should read "STOPPED". Maybe
your user program contains some timer-event-controlled switches to other
If you encountered a problem for which you miss an item in the above list, please report this to the author of this program (at MKT Systemtechnik).
1.24 The Error Page
The error page is used to show errors which may occur during programming,
simulation, or transfer of the program into the terminal.
It can also list the output of the global search function.
If an error message contains the display page and line number of the place
where the error happened, you can quickly jump to that location by clicking
into the message list with the right mouse button. Such messages look
INTP: (page 2, line 5) Variable 'Call' not found.
The same is possible for messages from the page-switch trace, and in the output from the global search function, e.g.:
Switched from page 0 to page 2 ("Engine"), reason: GOTO on page 0, line 9 Global text search for 'ISO15765_ADDR_FORMAT_FIXED_NORMAL' : Script sourcecode, line 133 : ISO15765_ADDR_FORMAT_FIXED_NORMAL = 2; Script sourcecode, line 617 : iAddrFormat := ISO15765_ADDR_FORMAT_FIXED_NORMAL; Found 2 occurrences of 'ISO15765_ADDR_FORMAT_FIXED_NORMAL'.
If errors occurr during program upload or download, you may find some hex-coded
SDO errors, and also the CANopen-index of
the object which caused the error.
Some errors during program upload are caused by access to a non-existing object in the UPT's object dictionary. In this case, there may be an incompatibility between UPT firmware and programming tool.
Other errors may be caused by the simulated UPT application, most likely variables connected to an SDO channel with wrong SDO index and subindex.
The error message list can also be used as a simple CAN monitor. By default, the checkboxes "Show RX frames" and "Show TX frames" are disabled, but you can turn them on if you want to see the sent and/or received CAN messages (beware: some PCs are too slow to handle much traffic this way !).
The contents of the list can be erased with the "Delete" button. The "Stop" button only stops the scrolling message list, but not the application !
If the option "show Error Frames" is set, and a suitable CAN interface /
driver is used (Vector CAN XL Driver for example), then CAN error frames
may be displayed in the message window of the terminal programming tool.
(Motivation: Ideally, there shouldn't be any error frame in a CAN network. If they do occurr, the reason may be an EMC problem, missing or bad termination resistor, wrong setting of a CAN bit timing register somewhere, or even a "babbling idiot" in one of the CAN nodes connected to the network).
return to the description of the main window
The command interpreter is a part of the UPT firmware, but almost the same code is also implemented in the programming tool. Most of your "user program" is executed by the system command interpreter. The system command interpreter is used to evaluate formulas, event definitions and to execute complex graphic commands.
A lot of different commands (aka "procedures") and functions are implemented in the interpreter. Functions return a value, and can therefore be used in numeric expressions. Commands don't return a value (and cannot be used as operands in expressions), but they may be the target of an assignment.
You may enter a system command in the status bar of the programming tool, where usually error messages and warnings are displayed. This feature is only intended for experienced users and for debugging purposes.
You may also enter system commands in a special Test Command Window and save the commands in a file.
Some of the commands that you can enter are directed to the display list interpreter and may result in "strange" behaviour of the program.
Commands which will only be executed by the programming tool are:
- help, run, stop, print
- sim_rx (sends a "simulated" CAN-Message to the CAN-Rx-Handler)
All commands that cannot be processed by the programming tool will be passed to the terminals interpreter. The format of these commands will be equivalent to the syntax of event-reactions.
- overview of interpreter commands
- overview of numeric functions
- Scripting language (for devices with 32-bit CPU, for more advanced control)
- table of contents
The UPTs firmware includes an interpreter for numeric expressions. These expressions may be used as
- complex event definitions, i.e. comparisons
- calculated values for variable assignments
- parameters passed in function- or procedure calls
- debugging aid in the watch window
- Some examples for numeric expressions:
(Voltage * 100 ) / 230
(Voltage > 230) ( a comparison, usable for events)
(ce & kd0) ( CAN-Error AND (F1 pressed) )
Expressions may consist of
See also: Interpreter Commands .
Numbers can be a part of numeric expressions.
The numeric interpreter accepts numbers in the following formats:
- decimal with optional "#"-prefix
- hexadecimal with "0x" or "$"-prefix ("C" or Pascal style)
binary with "%"-prefix( '%' is reserved for the modulo operator now)
Any number may also have a signum (+ or -) which should precede the base prefix.
Hexadecimal digits may be upper- or lower case.
- Some examples for numbers:
The UPT's numeric interpreter does (usually) not support floating
point values, only 32-bit signed integer values. Therefore, -123.45 is
not an allowed number.
Only for terminals with CANdb functionality, true floating point values can be displayed and handled by the interpreter.
Operators can be a part of numeric expressions.
The numeric interpreter can handle the following simple operators (operators with two "inputs" and one "output") (*) :
/ Divide (w/o fraction)
% Modulo (calculate the fraction from a division)
== compare: equal
<> compare: not equal
< compare: less
<= compare: less or equal
> compare: higher
>= compare: higher or equal
<< shift bits left (only for integer values)
>> shift bits right (only for integer values)
& bitwise AND (only for integer values...)
&& boolean AND
| bitwise OR
|| boolean OR
^ bitwise EXOR
~ bitwise NOT (prefix)
! boolean NOT (prefix)
A very special operator from the "C"-Programming language is the "arithmetic if-then-else statement":
if (<arg1> is not zero)
then result:=<arg2> ;
- else result:=<arg3>
Boolean operators return either TRUE or FALSE, which are the values 1 and 0 here.
Inputs for boolean operators are TRUE if the argument is not zero and FALSE if the argument is zero.
The priority of the operators determines the evaluation sequence. The interpreter only knows two different priority levels, with the lower level for add, subtract, compare, "or" etc and the higher level for multiply, divide, modulo, "and". In case of doubt, use parenthesis. A subexpression in parenthesis will always be evaluated with the highest priority.
- (*) Note about these 'numeric' operators:
In devices with 16- or 32-bit-CPU, and firmware compiled 2007-02 or later,
some of these operators are also defined for string types. These operators
Only these operators can be used with strings too. The second operand must be a string literal or a string variable, but no concatenated string ("expression").
Even when operating on strings, the operators return an integer value. Examples:
"ABC"=="ABC" returns 1 (one) as an integer
"ABC"!="ABC" returns 0 (zero) as an integer.
Variables can be part of numeric expressions, for example:
TotalPower - (InputVoltage * SupplyCurrent)
The numeric interpreter can only recognize variable name that begin with an upper-case letter (this greatly simplifies the analysis for slow CPUs with 8051-compatible processors, as used in the "UPT 515" ).
In the "UPT515", names of variables must never exceed 8 characters length. Only in certain devices with CANdb functionality up to 16 characters may be used (see parameter "max var name length" on the 'Settings' tab). All variable names must be defined in a table of the programming tool.
Usually the input of variables originates from a communication channel. But you may also assign new values to a variable with the "@"-command of the command interpreter.
Inside the UPT, a variable is not just a "memory" that can store a numeric value. Due to the complexity of the UPT, a variable consists of a lot of components.
- If a variable is used as an "application variable" (which is connected to a communication channel), you may access any of the following components :
.fl reads the "flag"-field of a variable,
.ut reads the "update timer" of a variable,
.cy accesses the cycle time in millisecondes (0 = "no periodic transmission" for CAN signals),
corresponds with the 'Upd-Time' parameter on the Variables tab;
.in reads the latest "input value" from a communication channel,
.iu checks if the input value has been updated from a communication channel,
.ic counts how often the input value has been updated from a communication channel,
.ed reads the "edited value" which is currently visible on the display,
.ou reads the latest "output value" for a communication channel,
.od detects if a variable has been written to a communication channel,
.de reads the "default value" from the variable definition table,
.mi reads the "minimum value" from the variable definition table,
.ma reads the "maximum value" from the variable definition table,
.fa reads the scaling factor from the variable definition table,
.di reads the scaling divisor from the variable definition table,
.of reads the scaling offset from the variable definition table,
.ty returns the variable's type (data type code as used in CANopen),
.un returns the variable's UNIT (from the definition table),
.uo checks the "output update flags" of the variable,
.va checks if the current value (.ed) is valid.
- Only for devices with 32-bit-CPU, and support for CANdb, and firmware compiled 2009-08-21 or later:
.ci reads (or modifies) the
CAN-Identifier during runtime, if the variable is connected
to a 'CAN-signal'.
.fb, .nb, .bo, .st, .sf, .so : CAN signal definition, details here .
If you dont specify a component name (or forget the dot after the variable name), the interpreter uses the "edited value" of the variable. The "edited value" is also the only part of a variable that you can modify directly by assigning a value.
A Component Suffix may be appended to the variables name, using a
dot-character (.) as separator, for example
Some more complex components are explained here:
- in ("INput value", as component of a var-structure)
returns the "last input value" which has been received from a communication
channel. For variables connected to a
CANdb-signal, this is the "raw" can value (i.e.
the non-scaled value) which has been taken out of a CAN-message. In contrast
to the "displayed" value(.ed), this is always an integer number.
- ic ("Input Counter", a special component of a var-struct)
Reads or modifies an "input update counter" of a variable. Every variable
which is connected to a communication channel has its own counter, which
can be accessed via interpreter (for debugging or monitoring purposes). Beware:
The maximum value of this counter is 32767. If this value is exceeded, only
the LOWER BYTE will keep counting (in other words, the counter will not freeze
after 32768 updates).
To clear a variable's input-counter, use a formal assignment like this:
- iu ("Input Updated", a special component of a var-struct)
Checks if the variable has recently been updated from a communication channel
(i.e. after reception of a certain CAN message).
To reset this flag, use a formal assignment like this:
- od ("Output Done", as component of a var-struct)
Detects if a variable has been written to a communication channel ("output
done", "output updated").
Use this component if you want to test if the new value of a variable has been transferred to its "output"-channel after the value has been changed. Example:
Assume you have a variabe named StopIt which is connected to an external device via SDO-channel. In your UPT-program, you assign a new value to StopIt:
The SDO-Handler will then try to transmit a write-request to the external device and wait for a write-response from that device. While the SDO-Handler is busy, the UPT continues its "normal" operation (because the UPTs SDO-Handler works more or less- "in the background").
After some time (depending on the external device and on the execution speed of the UPT), a write-response-telegramm will be received by the UPT. A special flag of the variable (here: "StopIt.od") will be set to ONE after the response telegram has been received.
Your Application may use this flag in an event, for example:
This Event+Reaction will switch to a special display page named "StopOk", as soon as the partner has acknowledged the SDO transmission of the Variable "StopIt".
This flag can be cleared with a formal assignment like this:
- va (as component of a var-struct)
Checks if the current value of a variable is valid or 'available'. This is
usually TRUE = 1. Variables which are connected to
CANdb-signals may be 'invalid' or 'not available'
as long as they have not been received by the terminal (in contrast to CANopen
there is no way to define 'default-values', at least not in a CANdb file).
Values of variables which are connected to CANopen objects (via SDO or PDO) are always 'valid', also immediately after power-on, because the values are set to the predefined 'default values'.
Since 2012-10-19, the components listed above are also accessable
from the Script Langage.
- variables (general)
- variables on PDO-channels
- Variable references (interpreter function "var")
- fixed-type variables in the CANopen object dictionary of the terminal, which can be accessed through obd(<index>.<subindex>) (terminals with "CANopen V4" only).
The interpreter is the "heart" of the programmable terminal, but for simple applications you don't have to use interpreter directly because the programming tool can generate the interpreter commands automatically. The interpreter can only recognize function names that begin with a lower-case letter (this greatly simplifies the syntax analysis for slow CPUs like 8051-compatibles).
All "Events" can be evaluated as a part of a numeric expression, because they are internally treated as functions. The only difference between event-polling functions and the following functions is, that event functions always return a boolean value, while "normal" functions return a numeric value.
The following functions return numeric values (there may be more which are not listed here):
- ain1, ain2: returns the value from one of the analog inputs. Range is 0...1023.
- arr[row][col][comp]: access a global array with floating-point values (only for some devices)
- appl.xxx returns some information about the application (like filename, etc)
- audio.xxx returns some info about the audio recorder (recording status, playback activity, etc)
- bk, bs : Button Key, Button-State (only for some devices)
- crx CAN reception (for very special applications only; added 2010-02 for a few new devices)
- cs CAN-Status, bitcoded status of the CAN-controller
- dia.xxx Diagram functions (and -commands; only for certain devices)
- disp.<name>.<component> : Access parts of a display element definition during runtime
- gps.xxx : functions to check and initialize an external GPS receiver
- gsm.xxx : control functions for an external GSM/GPRS modem
- inp reads the current state of the UPTs digital inputs.
- isin(X) : integer-sine function from a ROM-table. X:0..1023 for one full sine wave.
- jx, jy, jc poll the (optional) analog joystick
- kd, ku, kb, kr, kc, kcb Keyboard functions, "direct" and "buffered"
- lim(value,min,max) Arithmetic limiting function.
- mm, mi : menu-mode, menu-index
- nbit(matrix,bitnr) counts bits or returns the position of the next "H"-bit
- nv read or modify the non-volatile numeric values.
- obd(index.subindex) works like "sdo" but accesses the terminal's own (local) object dictionary
- out reads(!) the current state of the UPTs digital outputs.
- pdo[N].xxx read a PDO channel's counter, data, received-flag, transmitted-flag, modified-flag, etc.
- pn(page number) returns the number of the current display page
- puc, pur (= page-update-count, page-update-rate): Diagnostic functions for page-refresh-rate
- rgb(red, green, blue) mixes a colour from its components. Returns a 32-bit integer value.
- script.XYZ accesses a global variable of the script program (only for devices which support the script language - see feature matrix)
- sdo(index.subindex, type) reads or writes a value through a CANopen Service Data channel
- ser.xxx configure, send to, and receive from the serial port (for certain terminals only)
- sigs.xxx configure timeout-monitor for signals (only for terminals with "CANdb-support")
- str(<format>,<value>) turns a numeric value into a string
- syn.xxx read the CANopen SYNC-Message-counter and received-flag.
- sys.xxx reads certain system values like supply voltage, temerature inside the housing etc (on certain terminals)
- rtc.xxx access the real-time clock (if the system has one).
- rot.xxx polling the rotary knob (only on certain terminals)
- t0...t3, tv0...tv3 functions to poll the user-programmable timers
- ti global time, incremented every 100ms.
- type2str() converts a data type code into a human-readable string.
- udp.xyz : functions (and commands) to communicate via Ethernet using UDP (User Datagram Protocol)
- v contains the "current value" (in a display line, etc)
- val(<string>) , eval(<string>,pos,ndigits,type,default) converts a string into a numeric value
- var(<name>) reference to a variable by name (with the name being a variable, too)
- xmax, ymax return the maximum x- and y-coordinate, depending on the display type (since 2011-03)
- special functions for event definitions
- string functions
- overview of interpreter commands
- User-defined functions and procedures in the script language
- UPT examples
- table of contents
The numeric interpreter has some built-in functions which will mostly be used for event definitions. But you may also use these functions as parts of numeric expressions.
All keyboard functions consist of two letters and a number directly after these letters. The letters are the abbreviated function name, the number defines the key that shall be tested (in many cases, key 0 is the first "function" key on the keyboard). In the table below, the key number is replaced by "N".
The following keyboard functions can be used:
Checks if function key N (0..7) is currently "down" (being pressed).
The key is polled when this function is called, no "buffering" takes places
(in contrast to the "kb" function, see below).
The function returns 1 (=TRUE) if the key is currently down, otherwise false.
Checks if function key N (0..7) is currently "up" (not being pressed).
In opposition to "kr", "ku" returns TRUE if a certain
key has never been pressed before.
Checks if function key N (0..7) is in the keyboard "buffer". If a
key has been pressed since the last call of this function, the function returns
1 (=TRUE) and the key is removed from the buffer (a side
effect). Compared to kd, this function also detects very short
keystrokes because the keys are polled in an interrupt in the "background",
even if the execution of the main program is very slow (because of complex
The key number N will be generated by the windows programming tool, if you select a key from a list (for example in the event definition dialog: If you select function "key pressed" ... "F1", the programming tool will generate the expression "kd0").
Devices with 32-bit CPU and firmware compiled 2009-09-30 (or later) support an extended syntax for the kb-function which is explained here.
Checks if key N has been "released" (changed from "pressed" to "not
pressed"). Like the "kb"-functions, it uses an internal event-buffer which
is cleared by reading it. Example:
kr0 || kr1 || k2checks if F1 or F2 or F3 has been released (after being pressed) .
- This function has a side effect: The key-released flags are cleared automatically be reading them ! So in this example with the logical OR, all three flags would be cleared, because the interpreter always evaluates the complete expression (unlike the "C" programming language, which would break the OR combination after the first TRUE condition).
- Firmware versions older than July 2nd, 2007 do not support this function !
For even more complex applications, it is also possible to detect the "system keys" with two keyboard functions:
Checks if any key has been pressed since the last call of the "kc"-function
(see below). Returns "0" if no key has been pressed or "1" if any of the
keys on the UPTs keyboard has been pressed (and is "waiting" in a
Reads the system system key code(!!) of a
key from a buffer, and removes it from the buffer. Should only be
executed if the "kh"-function (key hit) returns 1 (or TRUE). The next call
of "kc" will then return 0 as long as the buffer is empty. Warning: The
system key codes depend on the UPT hardware !
See detailed explanation below about the usage of "kh" and "kc".
- kcb (key code buffered)
Almost the same as the "kc"-function described above, with one important
difference: Unlike "kc", this function ("kcb") does not remove the keyboard
code from the buffer. It also doesn't get cleared when the application switches
from one page to another. If the application processes a keyboard event received
with the "kcb" function, it may clear the contents of kcb with a formal
assignment like the following:
kcb=0 : REM clear key-code-buffer so we can detect the next event
Since "kcb" -unlike "kc"- does not clear the key code when reading it, this function can be called in a lot of events to poll certain keys. Here an example to poll the ENTER key (code 13 = "carriage return") in an event definition:
@X=X+1 : kcb=0
Please note that the key is cleared in the reaction method ! Without this, the reaction would be executed over and over, until a different key is pressed. Initially, as long as no key is pressed, kcb returns the zero too.
Returns the current state of the "keyboard matrix" as a bit-combination of
up to 32 bits. This value is taken directly from the terminals
keyboard-driver. The relation between key and bit-number depends on the hardware
you are using. As a "rule of thumb", the state of first key (which is often
"F1") can be found in Bit0 and so on. The "km"-function allows you
to detect almost any keyboard combination (like F1+ESCAPE+CursorLeft) as
far as the keyboard hardware supports such a combination. Because of the
hardware-depending meaning of this function, only use this function if you
really have to !
Tip: In terminals with CANopen V4, the keyboard matrix can be mapped to a TPDO.
- keyrepeat (keyboard repeat interval in milliseconds / flag to turn repeat off)
Configures the autorepeat function for the keyboard. By default, the terminal's
keyboard behaves like a PC keyboard, with auto-repeat enabled. By setting
"keyrepeat=0", the autorepeat function can be turned off. With "keyrepeat=1000",
the autorepeat function starts if a key is held down for over 1000 milliseconds,
Note: Requires firmware compiled 2006-10-04 or later !
Allows to set the current keyboard table via interpreter command. This function
was added 2009-12-16 for a certain device which only had cursor keys, ENTER,
and ESCAPE key, but not a single function key, and no 'shift' key (which
would allow using the SHIFTED" cursor keys as function keys).
Like a shift key, the keytable command can be used to switch the keyboard assignment. For example,
keytable=0selects the default keyboard table (with the four cursor keys, ENTER, and ESCAPE);
keytable=1selects the first alternative keyboard table (where the six keys may operate as function keys F1 to F6); etc.
As a rule of thumb, keytable=0 will always select the default keyboard table, keytable=1 the first 'shifted' table (=the same table which would be used with a SHIFT key).
For hardware specifc details, please consult the hardware manual.
Note: The 'keytable' function is not supported by the programming tool's integrated simulator !
- "handle key"-command(hk) to smuggle keyboard-events in the buffer,
- table of all keyboard codes
- Keyboard handling in popup windows
- Functions to control the rotary knob (encoder)
- Functions to control the virtual keyboard (for touchscreens)
- overview of numeric functions
Since 2009-09-30, devices with 32-bit CPU support an extended syntax of the
kb-function to read a certain key from the keyboard buffer. In older devices,
kb could only poll function keys (and remove them from the buffer).
With the extended kb-function, it is also possible to selectively
read other keys from the buffer, for example cursor keys, etc.
(Background info: This function had to be implemented when certain new devices without any dedicated function keys were produced; for example a device with only cursor keys, an "OK"-button (= Enter key), and "ESC" (= Escape key, sometimes labelled 'Cancel'). )
- Checks if the 'ENTER' key has been pressed.
If so, the key is removed from the buffer. The same applies to the following examples, too...
- 'ESCAPE' key. Often labelled 'ESC'. On some keyboards, this key was labelled 'Cancel'.
On other devices, it's another symbol (but their operator hopefully knows what it means).
- Checks the 'Cursor Up' key. Often labelled with an arrow, or triangle pointing up.
On some devices (without real cursor keys), this key is emulated by a rotary encoder.
- Checks the 'Cursor Down' key. Often labelled with an arrow, or triangle pointing down.
- Checks the 'Cursor Left' key. If it exists, this key is labelled with an arrow, or triangle pointing left.
- Checks the 'Cursor Right' key. If it exists, this key is labelled with an arrow, or triangle pointing right.
- Checks the 'first function key'. On a few devices, this key is labelled 'F1'.
On the MKT-View II/III, F1 also serves as power on/off button, and is labelled accordingly.
- Checks the 'second function key'. On some devices, this key is labelled 'F2'.
On the MKT-View II/III, F2 is the 2nd key (from the top) on the right side of the device.
- Checks the 'third function key'. On some devices, this key is labelled 'F3'.
On the MKT-View II/III, F3 is the key next to the rotary encoder.
Detailed explanation of 'kh' and 'kc' (keyboard functions)
If your application requires almost direct access to all keys on the UPTs keyboard, you may use the keyboard functions "kh" (key hit) and "kc" (key code).
The "kh"-function may be used to define an event which occurrs whenever a key is hit (except the shift keys).
"kh" checks if any key has been pressed since the last call of the "kc"-function (see below). Returns "0" if no key has been pressed or "1" if any of the keys on the UPTs keyboard has been pressed (and the code is "waiting" in a buffer).
"kc" reads a key code from a buffer (and also removes one keyboard-event from the buffer).
The following event definitions are taken from an example provided in the "UPT-Programs"-directory:
The event "kh" triggers a reaction "@Key=kc" whichs reads a system key code from a buffer into the variable named "Key" (must be defined in the variable table).
If "Key" is connected to an external device (outside the UPT) via SDO link, we may reset the value of Key to zero as soon as the SDO has been transmitted to the partner (and been acknowledged).
will become TRUE(1) if the current value of Key is NOT ZERO and the value of Key has been successfulls transmitted via communication channel (.od means "output done" or "output updated").
If we would set Key back to zero as soon as there is "no key pressed", we would loose key events if the key was not pressed long enough. The example here makes sure that the partner will receive the key, no matter how long the key has been pressed by the user.
We strongly recommend that you avoid using kc wherever possible, because the codes returned by this function depend on the used keyboard; they may be different in future releases of the firmware and/or UPT hardware.
Some keys with special (fixed) functions can be polled with the functions "kc" (keyboard code) and "kcb" (key code buffered). We will try to keep all keyboard codes compatible in future devices, but cannot guarantee that. The table below contains some keyboard codes which will most likely not change in future.
(N.B. To define "hotkeys" for menus and buttons with the programming tool, you dont need the numeric values. Just type the short key name into the menu definition table.)
The table shows a set union of all keyboards, so it may contain a lot of keys which do not physically exist on your keyboard. Some of the numeric values can be used for the "handle key" command (hk), even if your keyboard doesn't have it.
|Keys with special functions,
only some of them may exist on a particular device:
|8||BACKSPACE||short name BS|
|12||QUESTIONMARK||because ASCII-'?' is MF2-scancode for "F5" (#63)|
|14||SAVE||rhombic shape with arrow|
|15||HELP||sometimes labelled "Help", customer specific|
|17||ALPHA||often labelled "A...Z"|
|18||LIGHT||sometimes lightbulb symbol, customer specific|
|19||CONTRAST||no unified symbol for this yet|
|24||PAGE_UP||encoder may be mapped to this key|
|25||PAGE_DOWN||encoder may be mapped to this key|
|28||SHIFT1||usually NOT placed in keyboard buffer|
|29||SHIFT2||usually NOT placed in keyboard buffer|
|Keys with ASCII-equivalent characters|
|48||DIGIT_0||short key names 0 .. 9 for numeric digits|
|Codes 59 to 68 are SCANCODES of the FUNCTION KEYS on MF2
F1..F3 may be the only keys which really exist on certain keyboards (MKT-View) !
|Other "special functions"...|
|71||DOUBLECLICK||double-click with encoder button ("rotary knob")|
|Codes 77,75,72,80 are SCANCODES of the CURSORBLOCK on MF2 keyboards:|
|"Shifted" cursor keys:|
|One fine day, there may be an UPT with an alphanumeric
The letter keys will produce the following codes (ASCII lower case):
Some background notes on the system key codes:
- Keyboard codes will always be in the range 1..127 (7 bit). They are internally stored as 8-bit integers. The MSB is used as "MAKE"/"BREAK"-bit (bit 7 clear means "key has been pressed", bit 7 set means "key has been released"). The interpreter function "kc" filters the break-codes out, so your application will only receive codes 1..127 .
- The remote control function, as implemented in certain displays without a "real" keyboard, uses the same keyboard codes as listed above.
Return to overview of Keyboard Functions
See also: How to query the rotary knob (encoder).
CAN-Status, bitcoded status of the CAN-controller.
0x01 = hardware error, problems with CAN-driver-DLL,
or "any other error" which has no bit of its own !
- 0x02 = RX buffer overflow
- 0x04 = TX buffer overflow
0x08 = trouble with the CAN interrupt(s)
(fires too often or never at all)
- 0x10 = no TX ACKNOWLEDGE or TX timeout
0x20 = undefineable "bus error"
(usually the result of an error message from the CAN driver DLL)
0x40 = Bus-WARNING
(abnormal error rate)
0x80 = Bus-OFF
(controller has disconnected itself from the bus due to serious problems)
For most of the CAN error bits shown above, there are special polling functions, intented for use in global event definitions. These are: cb (CAN busoff), ce (CAN error), cw (CAN warning), ch (CAN hardware fault), co (CAN 'other error'), ct (CAN transmit error).
isin(X) Integer-Sine from a ROM-table
This function returns a full sine period for X=0...1023. Value range (from
table) is +/- 32767. Not implemented in UPT515. Can be used to implement
"rotating pointers", like in the analog watch in the file "cdb_test1.cvt".
If X falls outside the range 0..1023, it is wrapped with a modulo operation
so the sine-funtion will be periodic like the math 'sin'-function
in the script language.
Hint: Devices with 32-Bit-CPU (like MKT-View III,IV) also support 'real' trigonometric funktions with 32-bit floating point arguments in the script language.
value, if (value>=min) and (value<=max)
min, if (value<min)
max, if (value>max).
Retrieve the current display page number, and the count of existing display
pages in the application. Please note that -like in other array-like objects-
the display pages are numbered from 0 (zero) to <count of pages MINUS
ONE>. For example, if the display program consists of ten pages
pcnt=10), the current page number
pn will always be between 0 and 9. These functions can
be used together with the goto-command to switch
to the "previous" or "next" display page.
- returns the current page number, ranging from 0 (zero) to <pcnt-1> ,
- returns the count of existing (programmed) display pages .
In addition to retrieving the current page number, the
pn function can also be used to retrieve the page number
of a certain page, by specifying the page's name, for example:
- returns the page number of a page called "BusOff" .
This function is sometimes used in global event definitions, for "doing
something" on all pages except a certain page. For example, if the CAN controller
switched itself into the "Bus-Off" state, the display shall switch to a page
named "BusOff", except if that is already the current page. Here is an
example for a global "bus-off" event
Global Event condition:
cb && ( pn != pn( "BusOff" ) ) .
Remember, "pn" is the current page number, and pn("BusOff") retrieves the number of a page called "BusOff" in your application .
Global Event reaction:
g( "BusOff" ) : REM switch to "BusOff" when CAN is bus-off, and not already there .
On the "BusOff" page, a warning could be displayed, or the application could try to reset the CAN controller .
- Test functions to measure the screen update speed:
puccounts the number of page updates since the current display page was invoked.
purreturns the current page update rate (in 0.1 Hz units).
Returns the current numerical value in a display line, which has been calculated from the "var/expr" field in a display line definition. This function is especially useful if you want to read the value of a variable in an icon sequence, for example if you want to invert the icon depending on the value of the variable without duplicating the name of the variable (or expression). An example can be found in the explanation of the icon-backslash-sequence, another in the demo application for 'Check-Buttons'.
Turns a string (s) into a numeric value. Examples:
- val("123") returns the number(!) 123
- val("1+2+3") returns the number(!) 6
- val(sa[X]) returns the X-th entry in the string array as a numeric value
Note: The val()-function was implemented in 2005-07 for a special purpose
(to use a part of the string-array as a numeric lookup table) . Older terminals
(and older firmware versions) do not have this function ! Terminals with
16-bit-CPU and extended string handling support an enhanced "val"-function
eval, see next paragraph.
Turns a string (s) into a numeric value, like val(), but with extended functionality. Available since 09/2005 in terminals with 16-bit-CPU and extended string handling capability.
Syntax #1 : eval(<source-string>, <number of chars to be skipped>, <number of chars to parse> [,<type> [,<default>]])
Examples for syntax #1 :
eval( "Hello 123.45 !?", 5, 7, F, 9999 )
(The first 5 characters in the string are skipped, then up to 7 characters are interpreted as a number. This example returns 123.45 as a floating-point number)
eval( "Hello 123.45 !?", 5, 7, I, 9999 )
(returns 123 as an integer number)
eval( "FFFF", 0, 4, H, 0 )
(returns 65535 as an integer number)
eval( "No number in here", 0, 10, I, 9999 )
(returns the default value, here 9999, because there is no valid number in the input string)
Syntax #2 : eval(<source-string>, <substring>, <number of chars to parse> [,<type> [,<default>]])
Here, the number of characters to skip (2nd argument in syntax #1) is not
expressed as a numeric value, but as a sub-string (token) to search for.
The interpreter searches <substring> in <source-string>, skips
it, and evaluates the number after that. So,
t=1234","t=",4) will give the same result as
because 6 characters will be skipped in both cases before the number
to be parsed. The advantage of syntax #2 is, it will work regardless of the
the number of characters to be skipped, if the length of
Examples for "eval", syntax #2 :
@Temp_I=eval(ser.rstr,"i=",8,F,Temp_I) : rem parse value #1
Reads a line of text received from the serial port (ser.rstr), searches for the first occurrence of the substring "i=", and parses up to 8 digits from the text after that substring, as a floating-point number (F). If no matching substring was found in the received line, of the floating-point format was not valid, it uses the old content of the assigned variable (here: Temp_I) as the default value. In other words: If nothing was received, the value remains unchanged.
Note: This example was taken from a test file for the serial port / MKT-View (ser_test.cvt), which you may find in the programming tool's 'programs' directory.
Note: Not all terminals support PDOs (process data objects) !
The UPT's display interpreter contains a few functions (and procedures) to access the
PDO-Channels. Some of these functions may be used for event definitions or
as part of numeric expressions.
For the script language, there are no such functions - but you can control a CANopen slave's PDO(s) via the CANopen object dictionary, which in turn can be accessed via script language (use cop.obd(index,subindex) to access the PDO-communication- and -mapping parameters).
You do not need these functions to read values from a received PDO or put values into a transmitted PDO (connect Variables to a PDO-channel to do this, as explained in the chapter "Variables on PDO-channels") !
All PDO-functions described here require an "index" to define which PDO-channel shall be used.
You may use pdo0, pdo1, pdo2 or pdo3. If you want to use a flexible index, use an expression like pdo[PdoNr] or similar.
A dot (.) is used to separate the keyword "pdo" from the pdo structure component as described later. Most three-letter-component-names may be abbreviated by two letters, for example pdo.cyc is the same as pdo.cy etc.
Overview of PDO functions in the display-interpreter:
Returns the value of a counter. Use this function to find out how often a
particular PDO has been received or transmitted since power-on.
Returns the cycle time for the transmission of a PDO in milliseconds. You
can also assign a new TX cycle time for a PDO using a formal assignment like
this: pdo.cyc = 1234 .
The TX cycle is similar to the "PDO Event Timer" as described in CANopen DS301 V4.0, look for object 0x1400 subindex 5.
Returns the current value of the [I]th data byte from PDO-channel N. You
will usually connect a variable to a PDO to extract one or more data bytes
from the PDOs data field (so you usually do not need this function,
only for "very special" cases !). You can also modify a single byte in a
TX-PDO using a formal assignment like this: pdo.dat = 123 (this only
makes sense if no variable is mapped into this PDO-data-byte).
Returns the current CAN identifier used for a PDO.
You can also set a new CAN identifier for a PDO on-the-fly using a formal assignment like this: pdo.id = 2047.
YOU MUST BE EXTREMELY CAREFUL WITH THIS BECAUSE THE UPT'S INTERPRETER DOES NOT VERIFY AT RUN-TIME IF A VALID CAN-ID IS USED. Transmitting a wrong CAN identifier into a network can cause serious trouble ! Devices with CANopen V4 don't offer this dangerous option any longer.
This numeric function checks if a PDO telegram has been received since the
last function call.
The flag will be reset internally by reading it. This function is intended to be used in event definitions only. This function can be used for "watch" or "guarding"-purposes like the "syn.rcv"-function.
This numeric function checks if a PDO telegram has been transmitted since
the last function call.
The flag will be reset internally by reading it. This function is intended to be used in event definitions only.
This is not a numeric function, but a procedure. It initiates the transmission
of a PDO by the interpreter (if the NMT state is OPERATIONAL). Use it if
you want to transmit an event-driven PDO (for example, on a key etc).
This numeric function checks if a PDO telegram has been modified and not
Returns: TRUE = The PDOs data-field has been modified but not been transmitted yet
FALSE= The PDOs data-field has not been modified since the last transmission.
- This numeric function returns the count of SYNC intervals of a paricular PDO channel since its last transmission (or evaluation). This counter is internally required for CANopen-Transmission-Types 2..241. See DS301 for more information.
A few examples for the PDO-functions can be found in the UPT examples .
Note: Not all terminalls support these functions - only devices with CANopen since 2004 (see Feature Matrix) !
This chapter was moved to a separate document when the file grew too large !
SYNC Functions of the UPT-Interpreter
Note: Not all terminals support SYNC frames !
The numeric interpreter has some built-in functions, that can be used to control or receive the CAN-SYNC-Message. Some of these functions may be used for event definitions or as part of numeric expressions.
You do not need these functions to simply receive SYNC messages (all PDO-channels with synchronous transmission check SYNC-messages theirselves)
Overview of SYNC functions:
syn.rcv (abbreviated as syn.r )
This numeric function checks if a SYNC telegram has been received since the last function call.
The flag will be reset internally by reading it. This function is intended to be used in event definitions only.
For example, you may create a special "watcher" for periodic SYNC receptions. Define "syn.rcv" as a global event and a timer-start-command like "ts0(50)" as the corresponding reaction. This will (re)start Timer 0 for 500ms on every SYNC reception. Define annother global event ("t0") and reaction (like g"NoSync"). Create a display page named "NoSync". This page will be displayed when the UPT does not receive SYNC telegrams anymore.
syn.cnt (abbreviated as syn.c )
This numeric function returns the value of a counter for all SYNC telegrams. You may use this value for testing purposes (for example, to find out if the UPT received any SYNC telegrams at all without resetting the "syn.rcv"-flag).
The UPTs interpreter recognizes only function names that begin with a lower-case letter (this greatly simplifies the analyses for slow CPUs like 8051-compatible processors). You can 'call' one of these functions from a display line by typing its name into the "Var/Expr" column in the display definition table.
The string functions which have been implemented up to now are:
- a2t( < string > ) ("ansi-to-terminal")
- Converts an ANSI-string into a string which uses the terminal's internal character set (which is usually "DOS"). Implemented in terminals with extended string processing.
- returns the full file name of the current "application". This is the filename of the *.upt or *.cvt file which has been loaded into the terminal.
returns the name of the current "application" (similar to appl.fname), but
without the path and extension.
- hex$(value, num_digits)
Turns an integer value (up to 32 bit) into a hexadecimal number,
as a string, with the specified number of digits (default: 8 digits).
- sa[ <text-array-INDEX> ]
Returns one line of the text-array specified by
its array-index. If you need to use the text-array as a numberic array, use
the val-function to convert a string read from the
table into a number.
- sr[ <text-array-REFERENCE> ]
Returns one line of the text-array specified by
WARNING: This function is very slow on most devices !
Turns a numeric value into a string. Only available for terminals with 16-
or 32-bit CPU since 2005-09 ! The format-string defines how the value shall
be formatted (sic!). Some examples, with X=1.234, double quotes in the result
inserted for clarity (to see leading spaces):
str("**.**",X) -> " 1.23"(note the leading SPACE produced by the asterisk in the format string)
str("X=00.***",X) -> "X=01.235"(a ZERO in the format string produces leading zeroes in the result)
str("X=** kHz",X) -> "X= 1 kHz"(up to 8 trailing characters are possible, here to append a unit)
Converts the numeric code of a data type (as used by CANopen) into
a human-readable string.
Example : type2str(1) returns the string "BOOL", because in CANopen the data type #1 is called "Boolean".
Further information about data types can be found here .
(maybe there are more functions which have not yet been described here... see function overview, sorted by alphabet)
Under certain conditions (see note below), whole string expressions can be used instead of fixed strings or single string functions. In such expressions, the '+' (plus character) can be used to add (concatenate) strings. A few examples of such string expressions :
- sa+" "+sa+" "+sa+" "+sa
- Adds the first four strings from the string array, with space characters as separator.
- str("***.*",Frequency*0.001)+" kHz"
- Converts a numeric value into a string, and appends a unit. The result may be something like "137.7 kHz".
- Note about extended string processing :
Extended string-processing is only available in some terminals with 16-bit
CPU and firmware newer than 2005-09-09 ! It was originally implemented to
send flexible strings through the serial port, but may be used for output
to the screen as well. Extended string processing includes:
- Adding substrings with the plus-operator
- The functions a2t (ansi-to-terminal), eval(extended val-function), and some functions for the serial interface
Tip: To use a variable string expression instead of a 'fixed' format string in a display line definition, use the backslash-e sequence to tell the display that the definition is not a fixed text, but an expression which must be evaluated .
Note: Only some "special" variants of the UPT-hard- and firmware support the real-time clock !
If the UPT firmware supports the Real Time Clock, it will sample the contents once in every "main loop" of the UPT interpreter and saves them in a temporary "latch". There will not be a "carry" problem if you read the time at 23:59:59.999 and the date after that, because date and time are always sampled together (internally, before a page-update).
The following numeric
functions may be used to read values from this
latch (not directly from the RTCs internal registers)
Returns the current year as a numeric value. The range is 2000..2000+n.
Returns the current month (of year) as a numeric value. The range is 1..12.
- rtc.da (or rtc.dm, day of month)
Returns the current day (of month) as a numeric value. The range is 1..31.
- rtc.dw (day of week)
Day of week. Values are 1=monday .. 7=sunday.
If this function returns 0, there has been an error in the calculation (most likely an illegal year number in the RTC register).
Current date (without time) as string, format YYYY-MM-DD (10 characters)
Returns the current hour as a numeric value. The range is 0..23.
Returns the current minute as a numeric value. The range is 0..59.
Returns the current second as a numeric value. The range is 0..59.
Current time as string, format hh:mm:ss (8 characters)
Returns the current DATE AND TIME, bitwise packed into a 32-bit value, format
explained further below.
Packs any calendar date (and time) into the same 32-bit value explained
further below (same format as rtc.packed) .
Very useful to 'compare' dates as an integer number, to check if a certain (absolute) day has been reached, etc .
The RTC has a small battery inside. If this battery is empty (or the RTC is defect), you will have to set the RTCs date and time after repair. This can be done in the UPTs System/Setup Menu (not in the Programming Tool !). Alternatively, you can open the system menu screen with the interpreter command sys.set_time .
(maybe there are more functions [also to set the RTC under "user" control] which have not yet been described here...)
Format of the "packed" date-and-time structure
The function rtc.packed returns the current DATE AND TIME in the following, bitwise packed format:
|Seconds / 2||4..0||0..29 (5 bit)|
|Minutes||10..5||0..59 (6 bit)|
|Hours||15..11||0..23 (5 bit)|
|Day of Month||20..16||1(!)..31 (5 bit)|
|Month of Year||24..21||1(!)..12 (4 bit)|
|Year - 1980||31..25||7 bit: 0(=year 1980)...127(=year 2107)|
Related subject: Functions for date and time in the script language.
The "nbit"-function ("next bit" or "number of bits") returns the number (1..32) of the next SET bit in a 32-bit matrix. The first argument (<matrix>) is an integer value which may contain up to 32 bits.
Syntax and examples:
<index>:0=count all "1"-bits, 1..32: return the number (1..32) of the N-th "1"-bit
nbit(0x1281,0) returns 4
- (there are FOUR bits set in the matrix)
nbit(0x1281,1) returns 1
- (the FIRST set bit is the 1st bit in the matrix)
nbit(0x1281,2) returns 8
- (the SECOND set bit is the 8th bit in the matrix)
nbit(0x1281,3) returns 10
- (the THIRD set bit is the 10th bit in the matrix)
nbit(0x1281,4) returns 13
- (the FOURTH set bit is the 13th bit in the matrix)
nbit(0x1281,5) returns 0
- (there are no FIVE set bits in the matrix 1281hex )
Note: Usually bits in a 32-bit-value are numbered from 0 to 31, BUT HERE, we count from 1 to 32 because the result 0 ("zero") means "there is no such bit".
Usually, <matrix> will be a variable, and <index> will be a constant. Passing a floating-point value to this function makes no sense, and will probably return "garbage" because the mantissa of a floating-point value (as used in the terminal) contains roughly 24 data bits only.
For this reason, when used with variables which are connected to CANdb signals, do not pass the scaled value to the nbit-function, but the non-scaled (raw) value which is an integer number which has the full 32 bit information without any rounding loss. For example, use "Sensorstatus.in" but not "Sensorstatus".
Up to 32 non-volatile values can be used in your application. They can be preset with the programming tool, and read or modified with the interpreter.
Syntax and examples:
- @X = nv
- reads one of the 32 values. The index may be 0..31. In this example, the value from nv is copied into the variable 'X'.
- assigns a new value to one of the 32 non-volatile memories
saves the contents of all 32 non-volatile values in a small EEPROM.
Caution: Use the "nvs"-command as seldom as possible because the EEPROM has a limited number of write cycles (usually 100000 write cycles).
We found an application where "nvs" was issued on every key press, and on every page switch. This is very bad practise and will lead to early device failure due to the limited lifetime of the EEPROM chip !
To protect the hardware from early failure, the internal function of the "nvs" command was modified, so it will not accept being called more frequently than once every 10 seconds ! In devices with integrated non-interruptable power supply (like MKT-View III, IV), the actual EEPROM write access may even be delayed until the device is disconnected from the main power supply.
To prevent overwriting a certain nv-cell in the target's EEPROM when loading a new application (*.cvt or *.upt), simply clear those values in the corresponding cell in the programming tool's table titled 'Terminal Settings' on tabsheet 'Settings'. Empty cells (without numeric values) will be skipped, when the device firmware imports a new application from a file, via CAN or local network. In other words, those EEPROM cells will remain unchanged.
Commands to access the 'non-volatile Array' (EEPROM) also exist in the script language.
- Note for developers:
- Internally, cells which shall not be overwritten in the target will have their values set to 0x8000FFEE.
That's the internal code for an 'invalid integer'. If, during a simulator session, your application (script, etc) overwrites this value before saving the application as a *.cvt or *.upt file, your edited nv-values in the string grid shown above will be lost.
- Not all terminals have (onboard-) digital inputs !
- For advanced applications, poll the digital inputs in the script language,
e.g. use a fast running timer
to sample the inputs (system.dwInputs) every 10 milliseconds.
That way, you can use them to measure low frequencies poll incremental encoders, etc.
- Returns the states of all (onboard-)digital inputs, combined as bits in a byte.
- Returns the state of the first(!) digital input. Result is either zero (0) or one (1).
- Returns the state of the second digital input. Result is either zero (0) or one (1).
The total number of available digital inputs, and their pin numbers on the
digital I/O connector can be found in the hardware manual of your terminal
(outside the scope of this document !).
The same applies to the analog inputs:
Returns the raw (non scaled) result of a 10-bit analog/digital conversion for the specified analog input.
The value range is 0...1023 (210-1).
The input voltage divider (between connector and input to the A/D converter) is hardware dependent.
For the MKT-View II, the input range was 0 to 15 Volts, i.e. ain1=1023 meant 15 V on the 1st analog 'on-board' input).
For other devices, consult the data sheet for the type and scaling range of the analog inputs.
In the script language, onboard analog inputs can be polled as a floating point value (0..1) via system.analog_in[0..3].
In the programming tool, the onboard analog inputs can only be emulated. To set a value, select
'Options' .. 'Simulated analog Inputs' in the main menu, select the channel (index 0..3), and enter the new value (0..100 %) in the edit field. Even arbitrary waveforms can be realized by entering numeric expressions here: The expression
50 + isin(ti_ms/3)/655
will produce a sinewave with 100 % amplitude ("full swing" for the simulated analog input), and a frequency of approximately 1 / ( 1024 milliseconds * 3 ) = 0.326 Hz .
Simulation of an onboard analog input in the programming tool, and display of the analog inputs in a watch window
Note: Only some special hardware variants like the "MTG320" have a rotary encoder !
Usually, the rotary knob is used to navigate through the menus like the up/down keys on other keyboards. Pressing the knob acts like the ENTER key. On devices without touchscreen(*), a short double-click toggles the function of the rotary knob between "Cursor up/down" and "Cursor left/right" (required in edit fields). When the user turns or pushes the knob, the firmware usually places the equivalent keyboard codes in the keyboard buffer.
If the terminal's firmware supports the Rotary Encoder, you can use some interpreter functions (and procedures) to control the rotary knob for "special purposes".
The following numeric functions may be used to read values from the rotary encoder:
Returns or modifies the current "function" of the rotary knob. Possible
rot.f knob turned CCW ("left") knob turned CW ("right") Remarks 0 no cursor key produced no cursor key produced
1 CURSOR UP CURSOR DOWN navigate through menu 2 CURSOR LEFT CURSOR RIGHT move through string 3 CURSOR DOWN CURSOR UP increment/decrement values 4
To change the cursor codes produced with the rotary knob, use a formal assignment like
Note: rot.f only affects the generation of 'cursor key' codes, but not the following function:
Returns the current position of the rotary encoder as an integer value.
Note: Assigning a new value to 'rot.p' internally changes an offset, but does not affect the current menu item etc.
If the rotary encoder is turned clockwise, rot.p will be incremented. Counterclockwise decrements. The first encoder we used produced 20 steps for a full revolution (360°).
Note: As mentioned above, you don't have to poll the encoder yourself if you only want to use it in menus (for "navigation") or to edit numerical values. The terminal firmware will do that itself, as long as you don't set
Returns 1 (= TRUE) if the knob has been turned LEFT (ccw) since the last
call of this function.
In other words, calling this function has a side effect: It clears the flag, so don't call this function from more than one place. To read the encoder position without side effects, use
rot.pinstead, and compare it with the "previous" value stored in a local variable.
Returns 1 (= TRUE) if the knob has been turned RIGHT (cw) since the last
See notes on the side effect of this function (same as for
- rot.lb, rot.rb
Similar like "rot.l" or "rot.b", but these buffered functions return TRUE
for every 'step' of the rotary button. If, for instance, the button has been
turned left 5 steps very quickly, "rot.lb" returns TRUE for 5 consecutive
calls, while "rot.l" only returns TRUE one single time.
These functions were designed for switching display pages with the rotary encoder, whenever the operator shall select a display page with a quick turn of the button (see "page-scan" example).
Like many other functions (which were designed to be used in event definitions), calling this function has a side effect:
It clears the flag internally. To read the encoder position without side effects, use
Note: In the terminal simulator window, you
can (optionally) use the mouse wheel as a replacement for the rotary encoder.
Alternatively, use CTRL-Cursor up/down to replace the encoder. This only
works while the simulator is running, and the simulator window is focused.
(*) In devices with a touchscreen, a double-click with the encoder button opens the virtual keyboard. To move the edit cursor (inside an edit field), just tap on the new location.
See also: Overview of Keyboard Functions
The UPT firmware contains an interpreter for the following purposes (here
sorted by category, not to be confused with the script language)
- event reaction methods, which are usually "goto" or "call" -commands
- graphic output commands for complex display pages
- commands to control signal LEDs and backlight,
- commands to control the UPTs digital outputs ,
- commands to control the four "User"-timers,
- commands to access any 'named display element' on the current page,
- assign command to set a new value of a variable, variable references,
save non-volatile values in EEPROM,
- CAN-transmit command which allows you to SEND any CAN-Telegram you like (once),
- PDO-commands (and functions) for "programmed" access to process data channels,
- SDO-commands and -functions for remote SDO-accesses without using extra variables,
OBD-commands and -functions to access the
own (local) CANopen-object-dictionary,
- Commands to open screens from the terminal's SYSTEM MENU, and invoke other "system" functions (like sys.reset)
- query and control the rotary encoder (only on certain terminals), page-scan-mode, etc
- commands to control the diagram (only on certain terminals..)
- commands for the serial interface, and (optional) reception of GPS data (NMEA0183 through RS-232)
- commands and functions to control a GSM modem (optional feature, for MKT-View only)
other special commands for different purposes:
CAN reset, beeper, logger,
popup messages, etc
(use your browser's "back"-button to return here !)
- overview of interpreter commands (alphabetically sorted)
- overview of numeric functions
- Script Language (with editor/debugger, compiler, and runtime library; only for certain devices with 32-bit CPU and plenty of ROM)
Some interpreter commands expect a list of parameters, others dont require any parameters.
Most parameters can be numeric expressions . (use your browser's 'back'-button to return here !). Please don't confuse these display interpreter commands with the script language - the script language is compiled before execution, and thus both are not compatible. However, if you really need to, you can invoke display interpreter commands from the script (but try to avoid that).
For testing purposes you may send commands to the interpreter using the status bar of the programming tool (not sure if this feature still exists, it was intended only for debugging).
In the UPT programming tool, you can get command-specific help by pressing F2 while the cursor and mouse is in an edit field with a valid interpreter command.
(roughly ordered by alphabet; for cateorgies see above)
- audio.xxx (commands to control the optional audio recorder)
- CAN reset, CAN transmit, reset
- draw mode, display inversion
- dia.xxx Diagram commands (and -functions; only for certain devices)
- dim : modifies the dimensions of an array (up to 3 dimensions)
- disp.<name>.<component> : Access parts of a display element definition during runtime
- goto, call, return
- gps.xxx (commands for an external GPS receiver), gsm.xxx (GSM/GPRS modem control)
- hk(handle key), inserts a character code into the keyboard buffer
- co(color), icon, line, pixel, frame, fill, cls , gf, disp (graphic commands)
- LED's, backlight control, digital outputs, beeper
- menu mode, menu item
- nvs(non-volaile storage)
- rot.xxx (rotary knob),
- sdo (service data object), obd (object dictionary),
- logger (to control the optional CAN-Logger), ....
- nscan (node-scan) is a special function to scan for nodes in a CANopen network
- page-scan control
- play, beep generate simple tone sequences ("beeps") using a pulse-width modulated output
- power=1 : Command to set the 'Power-Good'-flag (MKT-View "Plus" only)
- rem: begins a comment field in a command line or similar
- script.XYZ : Invokes the procedure (or function) named 'XYZ', in the script language.
- sys.menu, sys.show_icons, sys.edit_contrast , sys.reset and other "system control" commands
- signals.timeout, signals.tx_enable : Options for CAN-Signals ("CANdb").
- timer procedures
- udp.xyz : commands (and functions) to communicate via Ethernet using UDP (User Datagram Protocol)
- var(<name>) : Access a variable per reference (for example, using the name in another variable)
- vkey.xyz : Controls the virtual keyboard (only available for devices with touchscreen)
These commands for the UPTs built-in command interpreter are used to switch between pages of your application. All of these commands must be entered in abbreviated form (single letter).
goto: g<page-number> or g"page-name"
call: c<page-number> or c"page-name"
g(0) : REM jump to display page zero
g(pn+1) : REM jump to next display page
g(pcnt-1) : REM jump to last display page
g"MainMenu" : REM jump to a page named "MainMenu"
"Goto" and "Call" both switch to another display page, which may be defined by the page-number or (preferrably) by the page-name.
"Call" also saves the number of the current (old) page on a special "call-stack" before switching to the new page. The "called" page may switch later switch back to the "calling" page using the "return" command.
"Call" + "Return" should always be used together. If you enter a page with a "call", you should also "return" to the caller and not jump back to the caller with a "goto" (this would cause an overflow of the call stack, furthermore it does not make too much sense).
The reason to use "call" + "return" instead of "goto" is when many different callers use a common "subpage" (like a "subroutine"). After the "subroutine" has done its work (for example display an error message and wait for a key), the normal operation can resume.
Note: Neither "goto" nor "call" have an effect if the target (=new) page is the "current" (=old) page, no matter if called "by number" or "by name".
These commands can be used to switch the current display page into edit- or navigation mode, and to set the current menu item (or edit field, which is the same internally).
mm( <new menu mode>)
mi( <new menu index>)
Valid menu modes (mm) are:
- 0 = "off", neither selection bar nor blinking cursor block are visible
- 1 = "select", the current menu item (or display line, maybe an edit field) is inverted, and the user can move the selection bar with the cursor keys
- 2 = "editing", the blinking cursor is visible on one of the editable digits of a number. Only possible if it's an edit field !
Usually, when switching back from "editing" to "selecting" or even "off", the contents of the current edit field is written back into the associated variable. To abort editing (i.e. switch back without applying the edits), use the command mm(8) instead of mm(0) . Note: This is only available in devices with firmware compiled 2008-11 or later.
- 8 = "abort editing" and switch back into the "off" state.
- 9 = "abort editing" and switch back into the "select" state.
See also: Using display lines as menu items
The UPTs firmware of some variants of the User Programmable Terminal
has one command to control the built-in signal-LEDs (if the terminals has
The syntax of this command depends on the terminal capabilities. Here the simpler format for terminals with monochrome LEDs:
- led( <led-number>, <led-blink-pattern> )
- or abbreviated:
- le ( <led-number> , <led-blink-pattern> )
- <led-number> is the index of the LED that shall be switched: 0=1st LED, 1=2nd LED, ....
<led-output-pattern> is an eight-phase-code for the LED blink "rhythm". Every bit of this pattern controls a 100ms-Interval. After a cycle of 8 * 100ms the whole cycles starts again from the beginning. All LED-blink-cycles are "synchonized": that means, if two LEDs have the same blink-pattern they will flash exactly at the same time.
Here are some useful blink patterns:
- 0x00 LED is OFF (this is the default state after power-on)
- 0xFF LED is permanently ON
- 0xF0 LED blinks slowly: 400ms ON, 400ms OFF and so on.
- 0x55 LED blinks quickly: 100ms ON, 100ms OFF and so on.
- 0x01 LED gives short "flash pulses": 100ms ON, 700ms OFF and so on.
- led( <led-number>, <led-blink-pattern>, [ <red intensity>, <green intensity>, <blue intensity> ] )
The optional red, green, and blue intensities allow driving the LED in any RGB colour mixture (aka "true colour"). The intensity range is 0 ( off ) to 255 (max) . If the R/G/B intensity is not specified, the previous value is used. By default, the three colour components are set to 127 (= half level), resulting in a white(ish) colour.
Examples for RGB LEDs:
led( 0, 0xFF, 0xFF, 0xFF, 0xFF ) : REM 1st LED bright white, permanently on
led( 1, 0x55, 0xFF, 0x00, 0x00 ) : REM 2nd LED bright red, flashing rapidly
led( 2, 0xF0, 0x00, 0xFF, 0x00 ) : REM 3rd LED bright green, blinking slowly
led( 0, 0x0F, 0x00, 0x00, 0xFF ) : REM bright blue, blinking slowly (2nd phase)
led( 1, 0xFF, 0xFF, 0xFF, 0x00 ) : REM bright yellow
led( 2, 0xFF, 0xFF, 0x00, 0xFF ) : REM bright purple
led( 0, 0xFF, 0x00, 0xFF, 0xFF ) : REM bright cyan
- The demo program "MV2_DEMO.CVT" (MKT-View II Demo) contains some of the LED driving commands shown above.
- Since the RGB LEDs are not directly connected to the microcontroller (they use an internal serial port instead), it may take a short while until the new colour becomes effective. For that reason, don't try to create flashing effects by sending new LED colours every millisecond. Instead, use the blink pattern if you need to.
- In the "off"-state of the blink cycle, the RGB LEDs will not be turned completely off. They are switched to a very dim "glow", depending on the ambient light settings (by default, all three components are set to about 6 % of the maximum value. This is sufficient to see the illuminated function keys at night)
- In the script language, there is a similar command (system.led) to control the RGB-LEDs from your application.
On certain devices the LCD backlight can be controlled from the UPT application
(since May 2002).
Depending on the hardware, the backlight can either be switched on or off, or varied in intensity (MTG320).
bl(1) sets the minimun possible backlight intensity (barely visible),
bl(255) sets it to the highest possible intensity,
bl(1..254) only works on certain terminals to set the illumination to 'mid-range'.
Note: You can set the default LCD backlight intensity to a fixed value from the terminal's setup menu if you don't want to use an interpreter command.
For certain terminals with electroluminescent foil (EL) for keyboard illumination, there are some commands to turn the keyboard illumination on or off. Because EL-panels have a very limited lifetime, the illumination will always be turned off after a certain time of no activity on the keyboard or rotary switch.
- Commands to control the keyboard illumination:
kl(0) turns the keyboard light off, and also stops the keyboard-light-off
kl(N) turns the keyboard light on for (N) seconds. Example kl(60) turns the keyboard-light on for at least one minute.
By default, the keyboard illumination goes off after 600 seconds (if no key is pressed). This timeout-intervall is overwritten with the kl-command. Modifying this interval via system-setup (as for the LCD backlight) is not possible.
See also: more interpreter commands
The prefix '
script.' tells the display interpreter that
a procedure (or a function) written in the script language shall be called.
- Example (in a display interpreter commandline):
In the above example, '
SetLanguage' is the name of a user-defined
written in the script language, which expects a single integer value
(here: LANG_GER, a constant defined in the script sourcecode):
- Example (script sourcecode from the "Multi-Language-Test") :
// 'language codes' :
LANG_ENG = 10000; // internal language code for 'english'
LANG_GER = 20000; // internal language code for 'german'
LANG_ARA = 30000; // internal language code for 'arabian'
proc SetLanguage( int iLanguage ) // user defined procedure .
// Sets the new 'current language' (LANG_GER, LANG_ENG, etc).
// Called from the DISPLAY INTERPRETER, for example
// as reaction to pressing certain buttons
// in the display application.
// Note: Since 2011-09-19, when invoking a script function
// from an interpreter commandline, the SCRIPT CONSTANTS can be
// used in numeric expressions evaluated by the DISPLAY INTERPRETER !
if( language != iLanguage ) then
// Display language has been modified:
language := iLanguage; // set NEW language in a global var
display.exec("cls"); // redraw the entire display page
endproc; // end SetLanguage()
See also ( about interaction between script and display application ) :
- Accessing display variables from the script
- Accessing script variables from the display interpreter
- Invoking script procedures from the display interpreter
script functions from display pages (with a backslash
sequence in the format string)
Details about the script language are in an extra document. Please note that the script language is only available for devices with at least a 32-bit CPU, and firmware compiled after year 2010 !
The following "special" display commands are used to display graphic elements on the LCD.
- co(<fg>,<bg>) sets foreground and background colour for some of the commands below
- icon (ic) draws a small image ("icon")
- line (li) draws a line
pa(X, Y, text) prints a text string at the specified graphic coordinate.Deprecated, only for the old UPT515, don't use !
- pixel (pi) sets a single pixel
- frame(fr) draws a rectangular frame
- fill(fi) draws a solid rectangular shape
- gf fills a rectangular area with a colour gradient (gf = gradient fill)
- cls(cl) erases the screen and draws all "display fields"
- popup opens a small popup window in front of everything else
To set some additional parameters that affect the graphic drawing commands, you may use the following commands:
- dm sets the draw mode for graphic output commands.
- zo(X,Y) sets the zoom factor for drawing icons.
These commands must be entered in an abbreviated form into one command line. They are processed by the command interpreter .
- Example (from the "Dead-Pixel-Test" for MKT-View II, programs/DeadPix1.cvt, filler command for the "special background" ) :
co(BGCol,BGCol) : fi(0,0,xmax,ymax,0,0)
If some graphic elements or text lines on the screen overlap, you should be aware of their drawing order.
Only a few devices with 32-bit CPU (like the "MKT-View II") support the following commands/functions:
- disp.<NAME>.<COMPONENT> can be used to access a certain display element on the current display page. This allows you to modify parameters like the element's colour, position, format string, etc during runtime, which can otherwise only be modified with the programming tool. (Note: This only works because the "current display page" is loaded from FLASH ROM into RAM). Details about this function can be found here .
- rgb( <red>, <green>, <blue> ) : Function to mix a colour from the red, green, and blue component. Details and an example here.
This graphic command is used to draw a small picture ("icon") on the screen.
ic(<icon-name>, <x-position>, <y-position>)
The icon-name must match the name that you defined on the icon-page. Otherwise the display-list-interpreter in the programming too will generate an error. If the icon name is a simple string constant, it must be enclosed in parenthesis as usual (otherwise the interpreter would think it's a string variable).
Note: Since May 2000 you can also display icons in the format string of a standard display line. This is much easier than using the icon-command, because the position of a display line can be moved with the mouse in the LCD simulator window.
Devices with colour displays support drawing transparent bitmaps. To draw a transparent bitmap, you must specify the colour of all transparent pixels in the parameter list of the icon command, using one of the colour values specified here .
- Example to draw a transparent icon (works on colour displays only) :
In devices that support the script language, the first parameter ("icon-name") may in fact be the name of an object declared as tCanvas in your script. The image (contained in the 'Canvas' object) will be painted at the specified position (x,y), unless your script hasn't generated it at runtime yet.
sets foreground and background colour for the line- and pixel commands mentioned
below. The possible colour numbers are listed
This graphic command is used to display a graphic line on the screen.
- li( <x1>, <y1>, <x2>, <y2> )
- For all devices with graphic display. Draws a thin line (one pixel wide).
- li( <x1>, <y1>, <x2>, <y2>, <width> )
- For devices with 16-bit CPU and 320*240-pixel display. Draws a line with the specified width in pixels.
This graphic command is used to display a single pixel on the screen.
- pi( <x>, <y> )
Hint: To develop 'portable' applications which work properly on displays
with different screen resolutions ("size in pixels"), use the functions
xmax and ymax (implemented 2011-02-25, only for
newer devices). These functions return the max. possible pixel coordinate.
Beware that counting starts at x=0, y=0 for the left upper corner of the
screen. Thus, for the "MKT-View II", pixel coordinates must be between 0
and 479 (=xmax), and y between 0 and 271 (=ymax).
The same applies to other graphic commands which use 'pixel' corrdinates.
This graphic command is used to display a rectangular frame on the screen.
The interior of the frame will not be affected by this command (it remains unchanged).
fr( <x1>, <y1>, <x2>, <y2> )
x1 = left border
y1 = top
x2 = right border
y2 = bottom
Fills a rectangular shape on the screen.
- fi( <x1>, <y1>, <x2>, <y2> [ , <pattern0> , <pattern1>] )
x1=left border, y1=top, x2=right border, y2=bottom,
pattern1, pattern2 = optional "filling" pattern, default=0xFF
All "old" contents of the rectangular area will be overwritten by this command, unless you use a draw mode that does not write both display "pages" (=blink phases).
The optional filling pattern allows drawing rectangles with different shades.
Both patterns are 8-Bit-Masks, where a "1"-Bit will be "set", a "0"-Bit will
be reset. <Pattern0> will be used to fill all even graphic lines,
<Pattern1> will be used to fill all odd graphic lines.
- Examples with filling patterns:
fi(10,10,30,20, 0xFF, 0xFF) will draw a "solid "black" rectangle
fi(10,22,30,30, 0xFF, 0x00) will draw a rectangle that consists of horizontal lines
fi(10,32,30,40, 0x55, 0x55) will draw a rectangle that consists of thin vertical lines
fi(10,42,30,50, 0x55, 0xAA) will draw a "50 percent gray shaded" rectangle
If you omit the filling patterns, the interpreter assumes that you want to draw a solid rectangle (the used filling pattern will be "0xFF, 0xFF" then).
Note: For displays with 32-bit CPU and TFT colour displays, there is a special command to create gradient colour fills. See gf .
This graphic command is used to set the draw mode for all following graphic output commands.
The display in older devices (with small monochrome displays) had two "video-pages", which were alternated every 0.5 seconds to achieve "blink"-effects. For newer devices (especially those with colour- or TFT displays), there is only one 'video page' thus blinking effects are impossible.
dm( <new draw mode> )
valid parameters for the draw mode are:
- 0: Standard-output into both video-pages
- 1: "Page1", output only into page 1
- 2: "Page2", output only into page 2
- 3: Blink1 (draw into page1, erase in page 2)
- 4: Blink2 (draw into page2, erase in page 1)
6: inverse output into both video-pages .
For colour displays, this is the only supported 'draw mode' besides mode 0 (standard) !
- 7: inverse output only into page 1
- 8: (removed, was 'inverse output into video-page 1, only for small monochrome displays)
- 9: (removed, was 'erase', only for small monochrome displays)
Note: To change the draw mode in a display text line, use the backslash sequence 'm'.
On certain terminals with 16-bit CPUs, its possible to use this command to
the complete screen.
di=0 no display inversion, black charackters on white background
di=1 display inversion, white charackters on black background
(In contrast to the 'dm' command, which only affects the characters printed afterwards, the 'display inversion' command always affects the full screen. The inversion is done by hardware on certain terminals. It is quite fast, and can be used to let the screen flash rapidly to catch the user's attention. This is not possible for all displays, see dialog "supported graphic functions" )
This graphic command performs the following actions during the next display page update:
- It erases the complete screen
- All display lines are drawn again
- After the display page is complete, the screen buffer will be transferred to the LCD screen.
This command will only be required for complex display pages, for example if you have plotted lots of pixels and want to erase them all (analyze the "Pixel Plot"-example for details !). The "cl" or "cls" command also raises the Page Redraw event (pr) which can be used for very special applications.
Usually, this command is not necessary because the screen will be erased when switching from one display page to another.
See also: more interpreter commands
Since 2007-12, new terminals with 32 bit CPU and TFT colour displays support a gradient filling command. The syntax is similar to the fi command (filled rectangle) :
gf( <x1>, <y1>, <x2>, <y2>, <orientation>, <colour1>, <colour2> )
x1=left border, y1=top, x2=right border, y2=bottom,
orientation: Reserved (no function yet). One day, this value will specify if the gradient runs from top to bottom (=default), from left to right, or other special applications.
colour1 = start colour value
colour2 = end colour value
- Example to fill the entire screen with a colour gradient from green to blue:
gf( 0, 0, xmax, ymax, 0, #070, #007 )
The colour values can be any of the UPT "standard colours", or -depending on the hardware capabilities- any RGB mixture. Details about colour values can be found here here .
Note: Graphic buttons can be background-filled with a colour gradient as explained here. You don't need the "gf" command to add gradient-filled buttons in your application. But, like the gf-command, this only works for terminals with 32-bit CPU and TFT colour display.
Functions to retrieve information about the screen
Note: The functions mentioned below were implemented in 2011-03-25. They don't work on older displays like "MKT-View (1)", where the screen was always 320 pixels wide, 240 pixels high, and monochrome.
returns the maximum possible horizontal coordinate.
x=0 is on the left edge of the screen, x=xmax (typically 319 or 479) is at the right edge.
returns the maximum possible horizontal coordinate.
y=0 is on the upper edge of the screen, y=ymax (typically 239 or 271) is at the lower edge.
The display-interpreter(*) has some built-in functions and procedures to control
four "User Timers". These timers can be used to generate time intervals of
up to 65534*100ms (which is more than one hour). These timers are intended
to produce events , but you may also use them for any other purpose.
(*) Devices with script language support more flexible timers than those listed below.
- ts0 ... ts3 (timer start)
Starts one of the four "User Timers" for a given time interval. The timer
will count down from the starting value to zero, when it generates a timer
event. Starting a timer again before it reaches zero will prevent the timer
event. The maximum time for a user timer is 65534 ( * 100 ms).
Syntax: ts0(<timer starting value in 100ms>)
Example: ts0(40) starts the first timer for a time of 4 seconds. After 4 seconds there will be a "t0" event which you can handle on one of your event definitions (global or local).
- tr0 ... tr3 (timer reset)
- Resets one of the four "User Timers". This will stop the timer and prevent the generation of a timer event. Internally, a timer that has been reset contains the value 0x0FFFF which means "stopped". This value is the default value for all timers after power-on.
The following timer functions are currently implemented in the UPT's display interpreter (*). They return a boolean or numeric result.
- t0 ... t3 (t0 ... t9 for firmware compiled 2012-04-16 or later)
Checks if a user-timer has "run off", that means Timer 0 ... Timer 3 has
been decremented from 1 to 0 . Returns:
Zero (=FALSE) if the timer is not running or has not yet reached zero,
One (=TRUE) if the timer has counted down to zero (where it stops) .
Note: The flag "timer expired" is not automatically cleared by reading it !
To clear the "timer-has-run-off"-event, use the command tr0...tr3 (explained above) . Some examples:
Event: t2 // is Timer 2 expired ?
Reaction: tr2 : goto "Timeout" : REM clear timer2 and jump to the "timeout" display
The interval timers (t0..t3 or t9) operate in single-shot mode. To fire periodic events, a timer may be restarted in the reacion method. Example:
Event: t2 // is timer 2 expired ?
Reaction: beep(1000,5) : ts2(10) : REM short beep, and restart timer #2 for the next 1-second interval
- tv0 ... tv3 (timer value)
Reads the current value of a user-timer. This value runs from the started
value down to zero (decremented every 100 ms).
- ti (Time since power-on in 100-ms-steps)
Reads the current "system clock" as a 32-bit value. The system clock is a
32-bit-counter incremented every 100 ms. It does not depend on the four
"user"-timers and can neither be stopped nor modified by the user program.
After more than 6 years of uninterrupted operation of the User Programmable
Terminal, this value will become negative because it will be incremented
from ((2 power 31)-1) to (2 power 31) which is a negative value for
32-bit-Numbers. After power-on of the UPT, the global time always starts
Some demo-programs use this function to show a company logo for a short while after power-on.
- ti_ms (Time since power-on in milliseconds)
Reads the current value of a system timer, scaled into milliseconds.
Similar as 'ti', this timer does not depend on the programmable user timers, and can neither be stopped nor started via command (it is "read-only").
Approximately 2^32/(40000Hz*60*60) =: 29.8 hours after power-on, the 32-bit timestamp generator wraps around to zero, causing a step in 'ti_ms'. After each power-on or system reset, this timer starts at zero (it is not battery backed-up).
A few demo applications use this timer (ti_ms) to calculate 'very dynamic' values, which change once every millisecond (in contrast to 'ti' which only changes every 100 ms).
In the script language, system.ti_ms is an equivalent function.
This mode can be used to automatically switch between two or more display pages, timer-driven; but without the need to program extra event definitions. The page-scan mode can be controlled via interpreter:
- Turns page-scan mode on. N is the page-scan interval in SECONDS. For example, pscan=5 switches to the next page (of the page-scan-sequence) every 5 seconds.
Turns page-scan mode off. This is the default after power-on !
- pscan.next, pscan.prev
Switches immediately from the current page to the next (or previous) page
belonging to the page scan sequence.
These commands were designed to "zap" through certain display pages with softkeys or (where applicable) with the rotary knob).
Notes and hints:
- If a page shall belong to the page-scan-sequence, set the checkmark "include this page in the pscan-sequence" on the Display Page Header tab. Only those pages which have this flag set, are included in the page-scanning cycle.
For manual page-scanning with the rotary encoder knob, use two global events
as in the following example:
To toggle periodic page-scanning on and off, you may use a softkey
(programmable button) with this command:
How does this work ? 'pscan' can be accessed like a variable, it is originally 0 (zero). The above command sets pscan to 5 if it was zero, and 0 if it was 5. You can also change the button's caption, like "Scan" or "Stop". The sourcecode for such a button may look like this:
- To query the current value of the page-scan-timer, use pscan.timer . This is a countdown-timer. Unit is 0.1 seconds.
If any key is pressed during page-scan, the page-scan-timer will automatically
be reloaded with the double interval time. The effect is: Page-scan
pauses as long as the operator presses keys, but it is not turned off
This command is used to assign a new value for a variable (or a variable-like command, which uses a formal assignment to "modify something").
@<Varname> = <expression>
- You can only assign values to variables that have been defined in the variable table.
- You should not assign values to variables which get their 'input' values from a communication channel.
- Some of the interpreter's built-in commands can be called with a formal assignment too.
The "Output"-command (out)
This command is used to control the state of the UPTs built-in digital outputs.
There are two different "flavours" of this command:
- This format is used to control all digital outputs at once. Bit 0 controls the first output and so on.
Controls the state of a single output line; output line (N) numbered from
Syntax and channel numbering is compatible with the inp - function.
- out(<output_nr>, <new_state> )
- This format is used to control the state of a single output line.
- out($FF) turns all outputs on
- out($00) turns all outputs off
- out(0, 1) turns the first output on
- out1(1) also turns the first(!) output on
- out16(1) turns the sixteenth output on
- out(3, 0) turns the fourth output off
- out(out^$02) inverts the state of the second output
- out16(!out16) inverts the state of the sixteenth output.
There is not only an output-command to set the digital outputs,
but also a function named "out" that reads back the current
state of the digital outputs.
out2returns 1 if the second output is set, otherwise 0 (zero).
- Not all devices used as "User Programmable Terminal" have own digital outputs. To access outputs on a remove I/O-module, you must use a communication channel.
- Perhaps your UPT515 only has four digital outputs and six digital inputs.
- The UPTs digital inputs and outputs are "simulated" by the programming tool. The state of the outputs is displayed as round shapes in the simulator window.
Produce tone frequencies with the internal speaker. Only certain devices have a beeper. For this reason, the "beep" and "play" command are explained in another file.
To query and set the state of the graphic buttons. Not supported by all firmware variants, therefore: see explanation in another file.
Can Reset. This command resets the CAN-controller. Use this command for
example- after a CAN-Bus-Off Condition to try to get "online" again.
Note: You should **NEVER** try to reset the CAN-Controller immediately after a CAN-BUS-off occurred. This would be stupid, because it does not cure the reason for the error. Let some time expire before trying to get connected again !
For devices with two CAN buses, and a firmware not older than 2012-11-26, a 'CAN reset' can be issued selectively for one of the interfaces:
cr1 resets the first CAN controller (even if it's not in bus-off state)
cr2 resets the second CAN controller (even if it's not in bus-off state)
See the example "demo1.upt" or "demo2.upt" for a typical usage of the Can-Reset-command, and the 'cb' function (to check for CAN-Bus-Off),
or the short 'BusOff' example in the pn-function .
May be used to transmit a CAN telegram with any identifier (11- or 29-bit)
and any data-field.
We strongly recommend not to use this command, because it is very dangerous to transmit a CAN frame into a network without the knowledge of the "CAN ID management" (which may be defined in a communication profile, or in a CANdb file, etc). Remember these words, when the trolley of your CAN-controlled crane crashes into the factory wall at full speed .. ;-)
- The basic syntax of the CAN transmit command is this:
ctx( identifier, databyte, ...)
The identifier may be succeeded by ".x" if an eXtended frame (29-bit-ID) shall be transmitted. Without a prefix, the identifier is expected in hexadecimal form; otherwise use the character '#' to tell the interpreter it's decimal. Bit 29 in the identifier is also a flag to transmit an extended frame (hexadecimal mask 0x2000000 ORed to the identifier value). Note that bits are always counted from zero, so bit 29 is actually the 30-th bit in an integer value.
The data bytes may be hexadecimal constants (by default), or decimal values
(preceeded by '#'), or even numeric expressions, including variables and
function calls (caution, everything which is not "a simple number" must be
embedded in parentheseis). Note: The same format as for the CAN data field
is also used by the UDP-send
A special service has been implemented to send 16- and 32-bit values with INTEL or MOTOROLA-byte-order:
- .w or .iw = INTEL WORD,
- .l or .il = INTEL 'LONG',
- .mw = MOTOROLA WORD,
- .ml = MOTOROLA 'LONG' ('LONG' = 32 bit),
.flt = IEEE 754 single-precision floating point with INTEL byte order :
first byte = mantissa bit 7..0, 2nd byte = mantissa bit 15..8, 3rd byte = mantissa bit 23..16, 4th byte = exponent .
.flt_m = IEEE 754 single-precision floating point with MOTOROLA byte order
(very rare these days) :
first byte = exponent, 2nd byte = mantissa bit 23..16, 3rd byte = mantissa bit 15..8, 4th byte = mantissa bit 7..0 .
Note: Floating point formats are only supported since 2009-08-13, and only by devices with 32-bit CPU.
- Some examples for the "ctx"-command:
ctx(0x4D2,1,2,3,4,5,6,7,8) ; preferred notation separated by comma
ctx(0x4D2 1 2 3 4 5 6 7 8) ; optionally without comma
ctx(#1234, 7B 7C 7D 7E 7F 80) ; DECIMAL ID but HEX-DATA
ctx($4D2, #123,124,125,126,127,128) ; HEX-ID but DECIMAL Data
ctx(#1234.x, 11,22,33,44,55,66,77,88) ; EXTENDED frame (29-Bit-ID)
ctx(#1234.s, 11,22,33,44,55,66,77,88) ; STANDARD frame (11-Bit-ID)
ctx(0x4D2, $ABCD.w , #32767.w) ; two INTEL-WORDs ( 2 * 16 bit )
ctx(0x4D2, $12345678.l , #12345678.l) ; two INTEL-LONGs ( 2 * 32 bit )
ctx(0x4D2, $ABCD.mw, #32767.mw) ; two MOTOROLA-WORDs
ctx(0x4D2, $12345678.ml,#12345678.ml) ; two MOTOROLA-LONGs
ctx(0x4D2, (ti).il, (ti).ml ) ; TIME for Intel and Motorola
ctx(0x456, Temp.flt,Pressure.flt) ; two single-Precision-floats
ctx(0x456, (1.0).flt, (2.0).flt ) ; two floating point CONSTANTS, INTEL byte order
ctx(0x456,(1.0).flt_m,(2.0).flt_m) ; similar but MOTOROLA byte order
More examples can be found in the terminal application 'ctxfloat.cvt', contained in the installation archive.
By default, the ctx command expects hexadeximal numbers. But to eliminate possible ambiguity between a hex number and a name, always use the prefix '0x' or '$' before a hex number. For example, A1 may be a hexadeximal number, but also the name of a variable. But 0xA1 is surely a hex number and nothing else.
Certain terminals have two CAN-interfaces. For these terminals, there are
two different transmit commands. The
ctx command always uses
the first CAN interface (the same as
- To transmit with the 2nd interface, use the command
ctx2( identifier, databyte, ...)
The parameters for
ctx2have the same meaning as
Certain terminals (with a 32-bit CPU, and firmware compiled 2009-10-30 or later) may be able to send CAN signals and messages, using definitions imported from a database for CAN ("CANdb", *.dbc). Details about sending such signals can be found here.
Warning: As explained above, it may be dangerous to send CAN telegrams this way, if you are not absolutely sure what you are doing !
Like the 'ctx' command, this function is rarely used, because 'normally' received CAN messages are processed by a protocol-depending handler, but (almost) never directly by the display application. For example, to receive or display 'CANdb signals', connect those signals to UPT variables as explained somewhere else, but don't try to implement your own CAN-receive-handler with the crx functions listed below (it's possible, but a nightmare for maintenance).
Note: Instead of trying to handle received CAN messages with the crx-function (which belongs to the UPT's display interpreter), use the script language's can_receive function, which runs much faster because the script runs as a compiled (not interpreted) language. Only with the script language you can implement any non-trivial CAN protocol handlers (if you need to).
Syntax of the display interpreter's CAN-receive-test function :
- crx( <CAN-ID> )
checks if a CAN message with the specified CAN-ID has been received (since
the last reception has been acknowledged; see below).
The function returns 0 (zero) if nothing was received since the flag was cleared.
- crx( <CAN-ID> ) = 0
clears the 'received'-flag for the specified CAN-ID. This command clears
an internal flag which allows the next reception of a CAN
message with the specified CAN-ID.
Typically used in the reaction of an event-definition to acknowlegde reception, after the received frame has been processed in any way. See the notes at the end of this chapter, and study the "crx_demo" mentioned below to learn why it's important to clear the CAN-RX-flag only after processing the received data.
- crx( <CAN-ID> ).cnt
returns the value of a CAN message counter (for all CAN-messages with the
specified ID). In contrast to the other readout-functions listed below, this
counter may even change if your display application did not clear the
'received'-flag as mentioned above.
- crx( <CAN-ID> ).len
returns the number of data bytes in the received CAN message, aka "DLC" (data
length code). For CAN, the DLC ranges from 0 to 8 .
Once a message has been received, this value can only change after the 'received'-flag has been cleared.
- crx( <CAN-ID> ).b[N]
returns the N-th data byte (8 bit value) from the received CAN message.
N is the byte index, ranging from 0 to 7 (!).
Once a message has been received, this value can only change after the 'received'-flag has been cleared.
- crx( <CAN-ID> ).w[N]
returns the N-th data word (16 bit value in INTEL byte order, i.e. least
significant byte word). N is the word index, ranging from 0 to 3(!).
Once a message has been received, this value can only change after the 'received'-flag has been cleared.
- crx( <CAN-ID> ).dw[N]
returns the N-th doubleword (32 bit value in INTEL byte order). N is the
doubleword index, ranging from 0 to 2 (!).
Once a message has been received, this value can only change after the 'received'-flag has been cleared.
Originally (as of February 2010), the crx-function was only intended to detect the reception of CAN messages with zero message data bytes, because such messages cannot be described as a container of signals (i.e. in a "CANdb" file). The crx function could used in event definitions, see the example mentioned in the notes below.
A demo application which demonstrates the usage of the 'crx' function is
in programs/crx_demo.cvt (in the folder
of the programming tool, of course).
It uses three different 'crx' objects, and displays the number of received frames, the number of data bytes for the last received frame, and a part of the data field.
For the first crx-object (with 11-bit ID 0x333), the 'received' flag is immediately cleared in a local event definition, to enable the next update of the received data field.
For the 2nd and 3rd crx object, the 'received' flag is not cleared, which is the reason why the data field keep displaying the contents of the first received messages.
This is very important, because the received data field must not be overwritten (with a new received CAN message of the same ID) until your display application has finished processing the received message). Look at the event definitions of the first page in the demo program:
crx(0x333): REM checks if a new message with CAN-ID 0x333 has been received
Reaction: DWord0=crx(0x333).dw : DWord1=crx(0x333).dw : crx(0x333)=0 : REM handle CAN reception for ID 0x333
(Consider what would happen if a new CAN message was received between reading the two DWords : The result may be inconsistent. For that reason, the demo first processes the received data, and finally clears the CAN-received-flag to enable the next reception, i.e. the next update of the message's CAN data field)
- There is only a limited number of 'CAN receivers' (CAN message objects) available for this functions. By the time of this writing, the maximum number of different 'crx' objects (with different CAN identifiers) was eight.
- The function cannot be used in CANopen devices (only in certain terminals which support "CANdb" signals) .
- The function is only implemented in terminals with 32-bit CPU (ARM) .
This interpreter command can be used to simulate certain keystrokes, which
may not be available on the terminal's "real" keyboard. For example, the
command hk("-") sends the minus character to the system's keyboard handler
to invert the sign of the edited value (if an input field is in edit mode).
The command hk(13) has the same effect as pressing the ENTER-(or RETURN-)key.
The argument may be written as a string of characters, or as a numeric value
from the table of system key codes (Note:
not all of the system keys have a dedicated function !).
See also: Keyboard functions .
Scans a CANopen network to fill a list with all nodes, including their node IDs and device names. Described in a separate file, because this function does not belong to the standard functions of a programmable terminal.
Resets the application (and some CAN protocol layers). All variables are set to the power-on values (where applicable). All timers are reset. All pages are re-loaded from the permanent storage medium (usually a FLASH device). The program switches to page zero, like after a power-on.
Explained in another file, because the "CAN logger" is a special feature which does not exist in the standard terminal.
See also: more interpreter commands
The system-functions of the interpreter provide access to some parameters
which are usually controlled through the terminal's
system menu. They are mostly used for testing
and debugging purposes. Only functions which are mentioned here may be used
in your application (there are more, undocumented functions, which may not
be supported in future versions of the firmware, which must not be used for
Reads or writes the audio output volume aka "Speaker Volume". The same parameter
can be modified (and permanently saved) in the terminal's
The function is only implemented in certain terminals with an analog audio output - see feature matrix .
- Only for devices with touchscreen. Reads or writes the 'touchscreen click' volume. The same parameter can be modified (and permanently saved) in the terminal's system menu.
Returns the value of a counter for all lost CAN messages, unhandled interrupts
due to system overload, lost characters from the serial interface, lost events,
etc. This value is read-only. It is a sum from different sources which should
ideally be zero. The most important sources are:
- logged CAN messages
- CAN messages which should be handled by the terminal's protocol handler (but couldn't due to a buffer overflow)
- keyboard events which should be handled by the terminal application (but couldn't due to a buffer overflow)
- characters received from the serial interface (RS-232 with 3964R protocol)
- interrupts requests which could not be handled due to a massive CPU overload (usually caused by heavy bus load)
Can be used to activate a special function in the terminal's system menu
from your application. This function was once used for testing purposes
during software development, but it turned out to be quite useful so the
author never removed it from the interpreter. More info, and a list of all
possible menu numbers (x) can be found here
Opens a special setup screen where the temperature-dependent control of the
LCD contrast can be optimized. This is only required for certain devices
like MKT-VIEW and IPE-VIEW. How to use this "LCD Contrast Curve Editor" is
explained in a separate document. You can use
this command to allow the operator to 'fine-tune' the LCD contrast without
going through the terminal's system menu.
Turns the power off.
Note: Only a few terminals (for example, MKT-View II") are able to turn themselves off through this command.
How to turn the device on again depends on the hardware. For the MKT-View II, details can be found in the description of the terminal's System Menu; see document #85115 (available in PDF format), chapter "Power on/off" .
The script language's equivalent for this command is system.shutdown.
Performs a system reset, which is almost the same as turning the power off
and on again to reboot the terminal. This may be required in certain situations
to re-initialize certain CAN protocols (or to escape from CAN-gateway-mode
on certain terminals).
In devices with script language, this command can be used to switch back from the application which was loaded via system.exec(<filename.cvt>) from the memory card, into the 'App-Selektor' which is loaded from ROM (FLASH) after power-on.
Opens a screen where the real-time clock can be
set (calendar date and time). Only available on terminals which have a
battery-buffered real time clock.
Note: In the terminal's system menu, the ISO 8601 international date format is used. The date format is YYYY-MM-DD, and the time format hh:mm:ss. Search the web for "ISO 8601" if you need some reasons why to use this format. It is highly recommended to use this format in your application as well !
- Only available on terminals with a 32-bit CPU since 2008. This command turns on the display of so-called system icons, indicating (for example) the state of the memory card, the state of the power supply, the state of the CAN-bus, and the state of the CAN-Logger. Details are in this extra document.
sys.t_shutdown( < interval to open the shutdown-window in 0.1 second steps > )
This very special, and rarely used command modifies the time (duration) to
open the shutdown screen. If the power-key (which, for most devices, is the
same as function key F1) is held down longer than this time, the shutdown
screen will pop open; in which the operator may chose to shut down the system
(i.e. "turn the power off"). The default value (which the terminal uses without
this command) is 30 * 0.1 seconds.
Of course, this command only exists in devices which can be turned on an off via a button !
Note: Holding the power key down for ten seconds or more will ALWAYS shut down the terminal, without intervention of the CPU (this is a feature of the power-controller which cannot be modified without a major hardware redesign - sorry).
See also: sys.poff (to turn off immediately, without the shutdown screen).
Returns the actual supply voltage of the terminal, measured
"shortly after the protection diode". For this reason, the value is not very
accurate. You can use it for diagnostic purposes, for example if the terminal
is powered from a vehicle's battery. The unit is 0.1 Volts, so a value of
123 means "12.3 Volts".
Measures the voltage at the internal buffer capacitors, if the device is
equipped with an internal UPS (Uninterruptable Power-Supply).
Unit is millivolts. The maximum is just below 5000 (= 5.0 Volts, max. ultracap voltage rating). If the device doesn't have an internal UPS, sys.vcap always returns zero.
- Returns the current temperature inside the terminal, measured with an NTC sensor near the display. The terminal firmware uses this value for the automatic contrast control. You can use it for testing purposes, etc. Note that some displays get very "slow" below -15°C, and don't work properly below -20°C. The value returned by "sys.temp" is an integer number scaled to 0.1°C, so -185 means "-18.5 degrees Celsius".
Returns the current value from the ambient light sensor. Only exists on certain
terminals, for example MKT-View II .
An example which uses this function to automatically switch between "day- and night-design" can be found here.
- Frequently asked questions (separate document)
- Manuals for the programmable terminals (in PDF format)
- Boot Screen (optional graphics displayed after power-on)
- SDO error codes (only for terminals with CANopen)
- CANopen objects inside the terminal ( " " )
- Revision history of the family of User-Programmable Terminals (UPT)
- Document Nr. 85110 : General manual for the UPT & CANdb terminal programming tools (for UPT and MKT-Views)
- Document Nr. 85111 : Additional infomation for terminals with CANdb support ( MKT-View +, MKT-View II / III, ..) . So far, only available in German language.
- Document Nr. 85113 : Description of the CAN logger configuration utility. Only contained in the installer of that utility !
- Document Nr. 85114 : Installation of a CAN-bus interface on a PC. So far, only available in German language.
- Document Nr. 85115 : Description of the terminal's system menu
- Document Nr. 85116 : Download protocol specification. For programmers who need/want to roll their own programming tool...
- Document Nr. 85118 : Description of the optional CAN snooper (a simple CAN bus monitor, integrated in some devices)
Dokument Nr. 85122 :
Language for various (but not all) programmable display terminals by MKT
- Document Nr. 85130 : Getting started with the MKT-View II (slightly outdated, in Memoriam R.V.)
- Document Nr. 85131 : Presentation of the programming tool by its developer (in German)
- Dokument Nr. 85132 : Presentation of the optional CAN logger, and the CAN logger configuration utility (German)
- Again: Most of the above documents are also available locally on your harddisk in the 'Doku' folder, after installation of the programming tool.
Other documents, like hardware specific manuals, catalogues, etc can be
downloaded from the MKT wbsite.
page zero' .
By default, the display shows the initialisation progress (in the form of text messages on the 'console'), or the screen remains dark until the first display page appears. The above behaviour can be configured in the 'System Setup' under 'Display Setup' by setting 'Bootup Display' to 'FALSE' (which means no "bootup messages" shall be displayed on the screen).
In some cases (e.g. when compiling large scripts in the user application), having a 'completely black' screen for a few seconds may be irritating for the operator.
On colour displays, a customized graphics file can be displayed instead, while the display boots, compiles the script, etc:
(Example for a customized 'Boot Screen', 240 * 240 pixel, loaded into an MKT-View III)
To achieve this, the display of 'boot messages' should be disabled by setting 'Bootup Display' to 'FALSE'
in the devices 'System Menu / Setup' as shown below:
(Disabling the 'system' messages during device bootup, here: in an MKT-View III)
To show the customized bootup graphics 'as fast as possible after power-on', a bitmap named 'BOOTSCRN.BMP' ("boot-screen" graphics, (*) ) must be written into the device's internal FLASH.
Similar as user-defined fonts, this file is not embedded in the *.cvt file (application), because that would unnecessarily blow up the size of any *.cvt file. Instead, the boot-screen graphics can be copied ('flashed') into the device with the programming tool's integrated file transfer utility. In the device's pseudo file system, select the destination folder "font_flash" (the destination folder always appears in the right half of the file transfer window).
The image file only needs to be uploaded once because the "font_flash" is not erased when loading a new *.cvt or *.upt application.
(*) The file BOOTSCRN.BMP must be a standard, non-compressed bitmap.
The colour depth should not exceed 8 bit per pixel, i.e. 256 colours (with palette or in 'RGB332'-format).
The size (in pixels) must not exceed the size of the display (see Feature Matrix).
If necessary, size and colour format can easily be adapted with the freeware utility 'IrfanView'. To reduce the colour depth in IrfanView, select Image .. Decrease Colour Depth .. 256 Colors (8 BPP). To adapt the size, select Image .. Resize / Resample.
If the image is smaller than the display, it will be centered on the screen.
The example used here (for medium-sized displays) is contained in the programming tool's 'fonts' folder, file BOOTSCRN.BMP.
Due to its size of 240 * 240 pixels, it is suitable for the MKT-View III (etc) in landscape- as well as portrait mode.
4.4 SDO error codes
The table below shows some error codes that may occur during program upload or download.
Most of these error codes are taken from CANopen DS301 V4.
Some of these errors may also be caused by external devices on the CAN bus.
For a more sophisticated explanation of these errors you should check the CiA literature or other CAN protocol descriptions.
|0x05030000||TOGGLE-BIT NOT ALTERNATED|
|0x05040000||SDO-PROTOCOL TIMED OUT|
|0x05040001||COMMAND SPECIFIER NOT VALID OR UNKNOWN|
|0x05040002||INVALID BLOCK SIZE|
|0x05040003||INVALID SEQUENCE NUMBER|
|0x05040005||OUT OF MEMORY|
|0x06010000||UNSUPPORTED ACCESS TO AN OBJECT|
|0x06010001||ATTEMPT TO READ A WRITE-ONLY OBJECT|
|0x06010002||ATTEMPT TO WRITE A READ-ONLY OBJECT|
|0x06010047||UNSUPPORTED ACCESS, INTERNAL INCOMPATIBLE|
|0x06020000||OBJECT DOES NOT EXIST IN DICTIONARY|
|0x06040041||OBJECT CANNOT BE MAPPED TO THE PDO|
|0x06040042||MAPPED OBJECTS WOULD EXCEED PDO LENGTH|
|0x06040043||GENERAL PARAMETER INCOMPATIBILITY|
|0x06040047||GENERAL INTERNAL INCOMPATIBILITY|
|0x06060000||ACCESS FAILED DUE TO HARDWARE ERROR|
|0x0606002F||ACCESS FAILED DUE TO CAN ERROR|
|0x06070010||DATA TYPES DO NOT MATCH|
|0x06070010||LENGTH OF PARAM DOES NOT MATCH|
|0x06070012||LENGTH OF PARAM TOO HIGH|
|0x06070013||LENGTH OF PARAM TOO LOW|
|0x06090011||SUBINDEX DOES NOT EXIST|
|0x06090030||VALUE RANGE EXCEEDED|
|0x06090031||VALUE RANGE TOO HIGH|
|0x06090032||VALUE RANGE TOO LOW|
|0x06090036||MAXIMUM VALUE IS LESS THAN MINIMUM VALUE|
|0x08000020||DATA CANNOT BE TRANSFERRED TO APPLICATION|
|0x08000021||.. due to local control|
|0x08000022||.. due to device state|
|0x08000023||OBJECT DIRECTORY GENERATION FAILS|
Most information inside the User Programmable Terminal can be accessed via CAN-Bus as part of the manufacturer specific profile of a CANopen object dictionary. The programming tool uses these objects to transfer your "user program" into the terminal via CAN-bus.
There are two,
totally different, implementations
of the CANopen protocol in MKT's display terminals: The UPT515 used
a proprietary implementation due to its lack of code memory space, all other
terminals (with 16-bit CPUs and sufficient memory) like the UPT320 uses
a CANopen protocol stack written by SYS TEC.
For the UPT320 (alias "MKT-View with CANopen" and some others), the CANopen Object Dictionary is defined in an EDS file. Some details about the objects in the manufacturer specific profile area can be found in this separate document.
The following is only valid for the old UPT515, which doesn't have enough memory for a full-featured CANopen implementation :
As you upload or download a program into/from the terminal, there may be some error messages with a CANopen-index in the range of 0x5100 to 0x57FF. The possible cause for such errors may be a compatibility problem between an "old" terminal and a "new" programming software (or vice versa). The following table may help to trace such errors:
|CANopen-Index||Contents (beware, some objects only existed in the old "UPT515",
while some other objects only exist in newer devices with 32-bit CPU ! )
|0x4001..0x400F||PDO-mappable variables (UPT 2 only, not for UPT515 ! )|
|0x5000||Onboard digital inputs (for a few devices of the UPT 2 family)|
|0x5001||Keyboard matrix (for most devices of the UPT 2 family)|
|0x5080||MKTs CAN snapshot utility (UPT515 only)|
|0x5101||Constants (max number of variables, etc., UPT515 only)|
|0x5102||Names of the terminals keys (UPT515 only)|
|0x5103||Settings (number of display pages, etc., UPT515 only)|
|0x5104||Run Mode (Run, Stop, Transfer etc, UPT515 only)|
|0x5106||Save Permanent (transfers RAM data to EEPROM, UPT515 only)|
|0x5107||Erase some Flash Sectors (used for table-storage, UPT515 only)|
|0x5110||CANopen-Konfiguration (SYNC, NMT, UPT515 only)|
||Contains the complete "UPT"-Application
for Terminals with 16-Bit-CPU
(as strings with "auto-increment" for the line counter,
only for terminals with CANopen V4, so not for UPT515).
Devices with 32-Bit-CPU can be remotely controlled through this object.
|0x5112||X/YModem file server object (only for devices with 32-Bit-CPU)|
|0x5120||CANdb(!) file import history (as strings, UPT515 only)|
|0x5180||global Events-Definitions (as strings, UPT515 only)|
|0x5200..52ff||SDO-Channel-Definitions (as strings, UPT515 only)|
|0x5200||Onboard digital outputs (for a few devices of the UPT 2 family)|
|0x5300..53ff||PDO-Kanal-Definitions (as strings, UPT515 only)|
|0x5400..54ff||Variable-Definitions (as strings, UPT515 only)|
|0x5500..55ff||Display-Page-Definitions (as strings, UPT515 only)|
|0x5600..56FF||Icon-Definitions (hex-coded strings, UPT515 only)|
|0x5700..57FF||Text-Array-Definitions (strings, UPT515 only)|
|0x5800..580F||Non-volatile values which can be accessed as "nv[N]" from the
UPT515 only ! !
The data format of the definition-tables is very similar to the text-file-format which is used to save your UPT-program on a disk drive. In fact, we use the same conversion routines in the UPT firmware as in the programming tool.
Since 2005, some user-programmable terminals use a "large" implementation of the CANopen protocol DS301 V4. For more information about those terminals, read this document.
- Babbling Idiot
A defective CAN node, which (for example) isn't able to receive, but can
still transmit for some reason. This may lead to an endless transmission
because the "babbling idiot" never sees an acknowledge for his own transmission,
and -as specified by CAN- keeps on trying over and over. A Babbling Idiot
can virtually kill the entire traffic on a CAN-bus, if no special hardware
cuts it off automatically. It can also cause a lot of
error frames (which are sent by other nodes
- CiA = "CAN in Automation"
International users and manufacturers group. Supporter of
CANopen . CAN be found in the internet at
- CANdb file
CAN database file. Another way of describing CAN messages and signals in
a network (totally different from
CANdb is registered trademark of Vector Informatik GmbH. They also offered a tool to edit CANdb files, but it seems to have disappeared (at least as a standalone-product). A standalone CAN database editor is also available from Kvaser .
Is an 'open' industry standard by CiA which descibes
a huge set of transmission protocols, data types, and how data in a device
are organized in an object dictionary. DS401,
for example, is just a tiny fraction of CANopen.
CAN-Viewing Terminal. An arbitrarily
chosen file extension for certain terminal applications. In contrast to UPT,
files ending with 'CVT' are files for terminals with CANdb functionality,
while 'UPT' terminals support CANopen. The first terminal which used 'CVT'
files was the IPE-View / MKT-View terminal.
Later (in autumn 2009) someone claimed that the display terminal should be able to transmit CAN signals (described in a CANdb file). However, the file extension 'CVT' (for CAN Viewing terminals) remained unchanged, even though these displays are in fact no 'viewing terminals' but controllers .
- Device Profile
a standardized description of a device, here: as part of
CANopen from "CAN in
CANopen Device Profile for I/O-Modules. A document
from "CAN in Automation".
- Error Frame
indicates that "there is something wrong" in a CAN network. Error Frames
can be displayed by the programming tool (!), if a suitable CAN interface
/ CAN driver is used.
A built-in subroutine of the numeric interpreter that returns a value. Can
be part of a numerical expression. Its name always begins with a lower-case
letter. A function is not the same as a
A programmable display-terminal for automotive use. Not intended
to be a control terminal, though often (ab-)used this way. The first
firmware for these terminals did *not* support CANopen, but could be configured
via CANdb files. The files which can be loaded
into the MKT-View terminal have the extension
Short for Object Dictionary. Sometimes (- better? -) called Object Directory,
but CiA decided to call it CANopen Object Dictionary.
The OD contains "everything" which can be accessed through CANopen Service
Data Objects (SDO). An electronic description of a CANopen OD is the EDS
file (electronic data sheet), particular values from an OD are saved in a
DCF (device configuration file).
Process Data Object. Used to transport several different values in a particular
CAN message in a CANopen network. Often sent periodically or event-driven.
Only certain data types can be exchanged via PDO (in contrast to
SDO, which allows to read and write any
data type - including strings, etc) .
A command of the system interpreter. It does not return a value and
can not be part of a numerical expression, because a procedure
is not a function.
Service Data Object. Used to access the OD in a CANopen device via CAN bus.
Usually used to parametrize a device via CAN, but not to communicate with
a CANopen slave during 'normal' operation (in contrast to
- Suitable text editors
.. are plain text editors which do not replace the normal space character
-chr(32)- by the so-called 'non-blanking space' which is chr(160), or hex
Editors doing that automatically are really stupid; and not suited for editing *.upt or *.cvt files .
The author discovered dozens of characters with code #160 in a demo application, which had to be replaced with a suitable text editor (which was able to convert those stupid characters back into normal spaces, which can be handled by the interpreter inside the programmable terminal).
User Datagram Protocol. Part of the Internet protokoll suite. In contrast
to the more common TCP/IP, UDP is a connection-less, unsafe, but comparably
simple (and fast!) protocol. It is therefore sometimes used to transfer process
data (for example sensor data) over a standard Ethernet connection (local
area network). Some of MKT's programmable devices support a limited subset
of UDP, i.e. they can send or receive single UDP packets, with the blocksize
limited to a single Ethernet frame. More details about the UDP implementation
can be found in this external document .
User Programmable Terminal. Also the file name extension for applications
which can be loaded into this family of display devices. This was the very
first CAN-Terminal by MKT, which could be "programmed" without the knowledge
of a "true" programming language. The first modell (UPT515) had an
8051-compatible 8-bit-processor, a monochrome LCD with 128*64 pixels, cursor
key and a few function keys below the display.
The UPT515 was the scaffolding for the MKT-View terminal, which was developed years later.
A syntax element of the numeric interpreter that can store a single value.
Can be part of a numerical expression. Its name always begins with an upper-case
letter. Example for a variable assignment:
@MyCounter = MyCounter+1
(the "at"-character is used as the "assignment"-operator in this context)
- If you find severe errors in this document or in the program, and you are sure to have the latest release of this software (both programming tool and firmware!), send your response to the author:
- Software Development Engineer -
Mail: b u e s c h e r (at) m k t (minus) s y s (dot) d e
Please include in your error description:
- the tools "program information" which you find in the main menu, "Help..Version".
- the type of CAN interface and driver software version you are using
- the firmware compilation date, which you see when entering the terminals system menu (for example: UPT515: pressing F2+F3 at the same time).
- the operating system of your PC, if the problem may be related to it
Note: We cannot help you if you have trouble installing a CAN interface on your PC. Use the hotline of the CAN interface's manufacturer if you don't get their test- or 'demo'-program running.
The following list may be useful to trace incompatibility problems if you must use a new programming tool for an old UPT firmware (or vice versa).
If your UPT application must run on old UPTs (with old firmware), do not use the newer features ! All UPT terminals show their firmware compilation date on the screen for a second after power-on, or when entering the setup menu.
Below is a shortened excerpt from the firmware revision history.
The revision history of the programming tool can be found in
a separate document.
A more detailed excerpt from the device firmware revision history is in the 'readme'-file in the firmware directory.
- Development of the MKT-View IV with an even faster Cortex-M4F CPU, 200 MHz core clock, 7" TFT
- Support for new low-cost devices like 'HBG-18' (see feature matrix)
- New functions in the script language, also for CANopen
- Emergency shutdown on excessive temperature ('last rescue' for MKT-Views cooked on a hot dashboard)
- Smoothly scrolling Y(t) diagrams
- A lot of new functions in the script language, also for CANopen
- Development of 'MKT-View III' with a faster CPU (Cortex-M3), replaces MKT-View II, both with 4.3" TFT
- Bargraph with 'write access' can be used as slider control (on systems with touchscreen)
- Speed optimizations, especially for devices with ARM7 and Cortex-M CPU
- Firmware update via web browser (HTTP)
- Support for larger displays (UPT-800: 800*480 pixel)
- Extended script language with file I/O functions
- Text fields with optionally fixed size, and different types of alignmant
- Bitmaps loadable during runtime from suitable storage media
- Added support for a large number of 'new' devices, with audio recorder, etc
- Automatic scaling of a display page for displays with different resolutions
- Integrated web server / telnet access for remote control, XMODEM, YMODEM, ...
Created a new family of terminals with 32-bit CPU, TFT colour display, and
Only for these displays, some new functions were added (colour gradient fills, etc).
- added interpreter function "val" (turns strings into numeric values)
Firmware for "MKT-View with CANopen" now available, called "UPT320",
requires UPT Programming Tool II (2)
- MKT-View now no longer supported, only "MKT-View PLUS".
- Optional CAN-Logger/Snooper available for "MKT-View PLUS".
- In the making: MKT-View with CANopen (DS 301 V4).
- MKT-View will be completely replaced by "MKT-View +" soon
- New numeric functions (nbit, signals.timeout)
- Programming tool now supports german and english language
- Implementation of Y(t) and X/Y diagrams for certain devices
- more bugfixes with mixed integer- & floating-point processing
- user-defineable fonts for certain devices (MKT-View etc)
- Invertable screen, buttons, bargraphs, CANdb
- Lots of new functions for MKT-VIEW & IPE-VIEW
- bugfix for floating point (replaced float library)
- modified strategy for allocating objects for CANdb msgs.
- lots of modifications for an 'un-experienced' user, including some windoze gimmicks :-(
- error checking in the VAR definition table
- Online help system converted from *.HLP into HTML format
- A special UPT variant with rotary knob implemented ("MTG320")
- A special programming tool variant for the "Terminal with CANdb functionality(?)" was implemented
- a PDO's CAN-ID and TX-cycle time can now be set from the interpreter
- the transmission of a PDO can now be initiated directly by the interpreter
- Peak's "CAN-API V2" supported since UPT Programming Tool V1.4 .
- Implemented some objects from the CANopen device profile in the new UPT firmware for identification.
But: UPTs are still neither compatible with DSP403 nor DSP302 devices
(anyway, DSP 403 and DSP302 were "not recommended for implementation" in May 2001)
April 17th, 2001:
- Bugfix in UPT515 firmware (8-bit-values mapped into TPDO)
- Help system completed
March 29th, 2001:
- NTCAN-support, mouse-sensitive LCD simulator window
- Display lines can be used as menu items with hotkey-code
- Large displays supported (UPT167, 320*240 pixels, optional color)
- new subindices (28..40) in the UPT terminal info object (Index 0x5101)
- page- and line-update flags supported by UPT firmware since 03/2001
Feb. 20th, 2001:
- Key combination to enter the UPT Setup can now be changed from the programming tool.
July 18th, 2000:
- Real-Time-Clock access from the UPTs interpreter.
- Text-Array implemented
- Monochrome Bitmaps supported
- PDOs supported
August 25th, 1999:
First released UPT (V1.0) with basic display capabilities.
(this old firmware is definitely incompatible with the latest UPT programming tool ! )