MobileView Terminals Software Development Kit 2727-MRSDK1 User Manual
Important User Information Solid state equipment has operational characteristics differing from those of electromechanicalequipment.SafetyGuidelinesfortheApplication,Installationand Maintenance of Solid State Controls (Publication SGI-1.1 available from your local Rockwell Automation sales office or online at http://www.ab.com/manuals/gi) describessomeimportantdifferencesbetweensolidstateequipmentandhard-wired electromechanical devices.
Table of Contents Preface Using this Manual . . . . . . . . . Who Should Use This Manual Purpose of this Manual . . . . . Contents of this Manual. . . . . Manual Conventions . . . . . . . Allen-Bradley Support . . . . . . Local Product Support . . . . . . Technical Product Assistance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Table of Contents 2 Publication 2727-UM004B-EN-P - February 2004
Preface Using this Manual Read this preface to familiarize yourself with the rest of the manual. The preface covers the following topics: • • • • • who should use this manual the purpose of the manual contents of the manual conventions used in this manual Allen-Bradley support Who Should Use This Manual Use this manual if you are responsible for developing application software to run on the MobileView Terminal.
Preface 2 Manual Conventions The following conventions are used throughout this manual: • Bulleted lists such as this one provide information, not procedural steps. • Numbered lists provide sequential steps or hierarchical information.
Chapter 1 Introduction to the MobileView SDK Hardware Architecture MobileView PC2 Touch Screen MT750 & G750 PCMCIA Slot 1x Type I-III Analog resistive 4-wire Block Diagram Communication PCB Buzzer MobileView PC1 e.
1-2 Introduction to the MobileView SDK devices with a shared data ready signal. In addition, the SA-1110 provides system support logic, multiple serial communication channels, a color/gray scale LCD controller, PCMCIA support, and general-purpose I/O ports. Memory Devices Flash Device There is a flash part (32 MB to 64 MB) that emulates a disk device. The flash is partitioned to several logical storage areas. One partition provides non-volatile storage for Windows CE operating system image.
Introduction to the MobileView SDK 1-3 Keypad The MobileView terminals have a numeric keypad and cursor control keys. This includes 12 function keys. Extended software support for the bezel keypad is provided with the Windows CE operating system in the form of a keypad handler DLL. The keypad handler intercepts and operates on codes produced by the keypad driver before passing them to the application with current focus.
1-4 Introduction to the MobileView SDK • Hardware Initialization and Boot Loader, situated in the flash • Windows CE Kernel with adaptations (Hardware Adaptation Layer customized for the MobileView hardware, Built-in ISRs), situated in the boot image stored in the operating system partition of the Flash Storage • Windows CE Default Registry, which is part of the boot image.
Introduction to the MobileView SDK 1-5 The operating system then attempts to find the primary persistent registry file. If this file is not present, it attempts to find the backup persistent registry file. If no persistent registry file is found, system boot continues with the default registry already in memory. If a persistent registry file is found, the system merges the default operating system registry and the saved persistent registry; saved persistent registry takes precedence.
1-6 Introduction to the MobileView SDK keys for control panel applets and other operating system items will be maintained even in the case of operating system upgrades. On the other hand, the priority given to persistent registry information over default operating system registry information makes it possible for applications or users to cause problems with operating system startup by changing the wrong registry keys.
Introduction to the MobileView SDK 1-7 Therefore, the registry must have been flushed by one of the means described above or else changes to the registry since the last flush will be lost. It is recommended that the controlled shutdown procedure be used for shutdown even if other registry flushing by applications is in place. Local File Systems The Windows CE operating system provides support for two separate local file systems.
1-8 Introduction to the MobileView SDK Table 1.1 RAM File System Directory Description \Windows\Fonts Not used \Windows\Recent Not used \Windows\Startup Contains links (shortcuts) to certain executables in \Windows The FAT16 (persistent) file system, “\Flash Storage”, is organized as follows: Table 1.2 FAT16 File System Directory Description \Flash Storage Contains backups of the system registry and the system exceptions log.
Introduction to the MobileView SDK 1-9 PCMCIA New or upgraded components of application programs and the operating system can be copied from the PCMCIA memory card to Storage Card memory to replace and upgrade the existing components. In the Windows Explorer, the PCMCIA Memory Card will show up as an icon named “\Storage Card”. Application Run Time Environment Path The notion of a path to executable files is much the same as with any other Windows or DOS system.
1-10 Introduction to the MobileView SDK Table 1.3 MobileView Terminals Launch Order Sequence Program or File Description Depend50 14 00 IE 00 When device.exe and gwes.exe complete startup Launch70 kukinit.exe Used for touch calibration Depend70 14 00 IE 00 When device.exe and gwes.exe complete startup Launch90 provides a launch point at startup for an OEM that assures that the device drivers, TCP/IP, registry and GUI functions are up and running.
Chapter 2 Developing CE Drivers and Applications General Considerations There are two general considerations for developing drivers and applications for the MobileView: • Distributing and installing applications • Persistence considerations Application Distribution and Installation Application programs consist of EXE and DLL files that will reside in the FAT partition of the Flash Storage. They will be installed much like applications for Windows desktop operating systems.
2-2 Developing CE Drivers and Applications Copy the script from a PC host using Data Exchange or from a PCMCIA ATA memory card to the “\Flash Storage\” folder on the MobileView and run the script on the MobileView. Run the script directly from a PCMCIA ATA memory card on the MobileView. Remote Installations The install package can be quite large and the decompression process can consume high levels of memory, so remote installation is an attractive option. Data Exchange, using CeAppMgr.
Developing CE Drivers and Applications 2-3 The solution is to place shortcuts in \Flash Storage\Windows or in a directory under it. In a normal system initialization sequence, everything in \Flash Storage\Windows\ (in the persistent file system), including subdirectories and their contents, is copied to \Windows (in the RAM filesystem) following the startup of gwes.exe. (For further information see “Launching Applications At Start-Up” above.
2-4 Developing CE Drivers and Applications TIP Microsoft Embedded Visual Tools 4.x is available without charge, except for a nominal shipping and handling charge. Accordingly, it is an economical tool for developers of new CE only applications. Device driver developers should consider also installing the Microsoft Windows CE Platform Builder, which contains support for kernel level CE development that is not found in the other toolkits.
Developing CE Drivers and Applications 2-5 Microsoft Embedded Visual C++ 4.x is available without charge, except for a nominal shipping and handling charge. Accordingly, it is a highly economical tool for developers of CE application programs. Device driver developers should also consider installing Microsoft Windows CE Platform Builder 4.1, which has extensive support for kernel level CE development that is not found in the other toolkits.
2-6 Developing CE Drivers and Applications Publication 2727-UM004B-EN-P - February 2004
Chapter 3 MobileView Terminals SDK Overview The MobileView Terminals SDK provides developers with access to an extensive set of functions that are specific to the MobileView Terminals hardware and constitute extensions of the standard Windows CE API. These functions, like the standard Windows CE functions, are implemented in the C language and can be called directly from C or C++ programs. A file called “ketopapi.bas” is included in the MobileView Terminals SDK.
3-2 MobileView Terminals SDK Publication 2727-UM004B-EN-P - February 2004
Chapter 4 SDK (Software Development Kit) for MobileView Terminals Introduction The SDK (Software Development Kit) resides in a single dynamic link library (DLL). All functions described in this document are exported from this DLL.
4-2 SDK (Software Development Kit) for MobileView Terminals Error Handling Rules Functions expecting an input parameter verify that the parameter is inside the range and has the correct data type. • If a parameter is located outside the range the function returns INVALID_ARG_RANGE. • Functions expecting a pointer for output data as a parameter verify that the pointer is valid (for example, the pointer must not be NULL). If the pointer is invalid, the function returns INVALID_ARG_INVALID_PTR.
SDK (Software Development Kit) for MobileView Terminals 4-3 KtpAPIInit Table 4.3 Declaration: Visual C: UINT8 KtpAPIInit(void); Visual Basic: KtpAPIInit() As Byte; Description: This method initializes the MobileView SDK. KtpAPIDeinit Table 4.4 Declaration: Configuration Functions Visual C: void KtpAPIDeinit(void); Visual Basic: KtpAPIDeinit() Description: This method cancels all initialization of the MobileView SDK.
4-4 SDK (Software Development Kit) for MobileView Terminals KtpSetContrast Table 4.6 Declaration: Visual C: UINT8 KtpSetContrast(/*[in]*/UINT8 u8_Contrast); Visual Basic: KtpSetContrast(ByVal contrast As Byte) As Byte Description: This method sets the contrast of the LC display on the device. Arguments 0 to 31, 0 = min, 31 = max (MobileView: 0 to 63, 0 = min, 63 = max) KtpSwitchBacklight Table 4.
SDK (Software Development Kit) for MobileView Terminals 4-5 KtpSetScreenSaverTimeOutSec Table 4.9 Declaration: Visual C: UINT8 SetScreenSaverTimeOutMin(/*[in]*/UINT16 u16_ScreenSaverTO); Visual Basic: KtpSetScreenSaverTimeOutSec(ByVal sreenSaverTO As Integer) As Byte Description: Sets the timeout value of the screensaver in seconds. Arguments 0-65535, 0 = off, 65535 = max KtpSetBuzzerVolume Table 4.
4-6 SDK (Software Development Kit) for MobileView Terminals KtpGetContrast Table 4.12 Declaration: Visual C: UINT8 KtpGetContrast(void); Visual Basic: KtpGetContrast() As Byte Description: Gets the current contrast value of the LC display. KtpGetBacklight Table 4.13 Declaration: Publication 2727-UM004B-EN-P - February 2004 Visual C: TKtpBacklightStat KtpGetBacklight(void); Visual Basic: KtpGetBacklight() As Integer Description: Gets the current status of the background lighting.
SDK (Software Development Kit) for MobileView Terminals 4-7 KtpGetScreenSaverTimeoutMin Table 4.14 Declaration: Visual C: UINT8 GetScreenSaverTimeOutMin(void); Visual Basic: KtpGetScreenSaverTimeOutMin() As Byte Description: Gets the current timeout value of the screensaver in minutes. KtpGetScreenSaverTimeoutSec Table 4.
4-8 SDK (Software Development Kit) for MobileView Terminals Peripheral Functions KtpJoystickIsInstalled Table 4.17 Declaration: Visual C: UINT8 KtpJoystickIsInstalled(void); Visual Basic: KtpJoystickIsInstalled() As Byte Description: Returns the number of joystick axes. If no joystick is installed on the device, 0 will be returned. KtpWheelIsInstalled Table 4.
SDK (Software Development Kit) for MobileView Terminals 4-9 KtpGetJoystickPos Table 4.20 Declaration: Visual C: UINT8 KtpGetJoystickPos (/*[out]*/TKtpJoystickPos *p_jPos); Description: Gets the current joystick position. Arguments TKtpJoystickPos structure. Each component in the structure may only range between -15 and 15. Remarks Calling this function is only allowed if a joystick is installed on the device. If no joystick is installed the values of the components are undefined.
4-10 SDK (Software Development Kit) for MobileView Terminals KtpGetJoystickPosEx Table 4.21 Declaration: Visual C UINT8 KtpGetJoystickPosEx(/*[out]*/int *posX, int *posY, int *posZ); Visual Basic: KtpGetJoystickPosEx(ByRef posX As Integer, ByRef posY As Integer, ByRef posZ As Integer) As Byte Description: Gets the current joystick position. Arguments Each component in the structure may only range between -15 and 15.
SDK (Software Development Kit) for MobileView Terminals 4-11 Table 4.23 Visual Basic: KtpGetJoystickPosEx(ByRef posX As Integer, ByRef posY As Integer, ByRef posZ As Integer) As Byte Description: Gets the actual raw data of the joystick. Remarks Calling this function is only allowed if a joystick is installed on the device. If no joystick is installed the values of the components are undefined. KtpGetJoystickCalibData Table 4.
4-12 SDK (Software Development Kit) for MobileView Terminals Table 4.25 Description: Gets the current value of the override potentiometers. Arguments: Pointer to the variable containing the current value of the override potentiometer. Remarks This function may only be called if a override potentiometer is installed on the device. If no override potentiometer is installed, the value of the components are undefined. KtpGetOverridePotiRaw Table 4.
SDK (Software Development Kit) for MobileView Terminals 4-13 KtpSetPotiCalibData Table 4.28 Declaration: Visual C: UINT8 KtpSetPotiCalibData(/*in*/ UINT16 rawMin, UINT16 rawMax, UINT16 calibRange); Visual Basic: KtpSetPotiCalibData(ByVal rawMin As Integer, ByVal rawMax As Integer, ByVal calibRange As Arguments: UINT16 rawMin: value for smallest raw value UINT16 rawMax: maximum raw value UINT16 calibRange: maximum range of overridepoti Description: Calibration of override potentiometer.
4-14 SDK (Software Development Kit) for MobileView Terminals KtpSetWheelValue Table 4.30 Declaration: Other Functions Visual C: UINT8 KtpSetWheelValue(/*in*/UINT16 val); Visual Basic: KtpSetWheelValue(ByVal val As Integer) As Byte Description: Sets the current position of the handwheel to the value transferred in val. Arguments: val is the value the handwheel should be set to. Remarks: This function may only be called if a handwheel is installed on the device.
SDK (Software Development Kit) for MobileView Terminals 4-15 KtpWriteToFlash Table 4.32 Declaration: Visual C: UINT8 WriteToFlash(void); Visual Basic: KtpGetWriteToFlash() As Byte Description: Writes the registry of the device to the flash. KtpReset Table 4.33 Declaration: Visual C: UINT8 KtpReset(void); Visual Basic: KtpReset () As Byte Description: Restarts the device new. KtpGetVersionString Table 4.
4-16 SDK (Software Development Kit) for MobileView Terminals KtpGetEEPromData Table 4.35 Declaration: Visual C: UINT8 KtpGetEEPromData(/*out*/TEEPromData *data); Visual Basic: not implemented. Description: Reads data from the EEProm. Arguments: TEEPromData data: data structure for the data contained in the EEProm KtpWriteByteToEEProm Table 4.
SDK (Software Development Kit) for MobileView Terminals 4-17 KtpLaunchTouchScreenCalibApp Table 4.38 Declaration: Visual C: UINT8 KtpLaunchTouchScreenCalibApp (void); Visual Basic: KtpLaunchTouchScreenCalibApp () As Byte; Description: Starts the touch-screen calibration tool. KtpGetTemperature Table 4.39 Declaration: Visual C: UINT8 KtpGetTemperature (void); Visual Basic: KtpGetTemperature () As Integer; Description: Returns the current temperature of the MobileView. KtpPlaySound Table 4.
4-18 SDK (Software Development Kit) for MobileView Terminals KtpDoBeep Table 4.41 Declaration: Visual C: UINT8 KtpDoBeep (/*in*/ UINT8 beepTime10ms); Visual Basic: KtpDoBeep (ByVal beepTime10ms As Byte) As Byte; Description: Is active for beepTime10ms * 10 ms Arguments: UINT8 beeptime10ms: duration of beeps in n* 10ms KtpGetVariantData Table 4.
SDK (Software Development Kit) for MobileView Terminals 4-19 Table 4.43 Visual Basic: function not implemented Description: Subscribes a callback function for the WheelEvent and returns an index (cookie) for the callback function. Arguments: TKtpWheelEventCallback pWheelProc: callback function to be called when the event occurs. int cookie: The index for the callback function is required for removing the callback function. KtpRemoveWheelEventCallback Table 4.
4-20 SDK (Software Development Kit) for MobileView Terminals KtpRemoveOutEventCallback Table 4.46 Declaration: Visual C: UINT8 KtpRemoveOvrEventCallback (int cookie); Visual Basic: function not implemented Description: Removes the OverrideEventCallback function. Arguments: int cookie: index for the callback function to be removed. KtpInstallKbdEventCallback Table 4.
SDK (Software Development Kit) for MobileView Terminals 4-21 KtpInstallJoyEventCallback Table 4.49 Declaration: Visual C: UINT8 KtpInstallJoyEventCallback (/*in*/ TktpJoyEventCallback pJoyProc, /*out*/ int *cookie); Visual Basic: function not implemented Description: Subscribes a callback function for the JoystickEvent and returns an index (cookie) for the callback function. Arguments: TktpJoyEventCallback pJoyProc: callback function to be called when the event occurs.
4-22 SDK (Software Development Kit) for MobileView Terminals Publication 2727-UM004B-EN-P - February 2004
Index C Central processing unit (CPU) 1-1 common data types 4-1 configuration functions 4-3 KtpScreenSaverTimeOutMin 4-4 KtpSetBrightness 4-3 KtpSetBuzzerVolume 4-5 KtpSetContrast 4-4 KtpSetScreenSaverTimeOutSec 4-5 KtpSwitchBacklight 4-4 E error handling 4-2 error codes 4-2 rules 4-2 host system setting up C/C++ development 2-3 I Input device handlers 1-8 Installation development system 2-3 distribution 2-1 methods 2-1 persistence considerations 2-2 setting up host machine C/C++ development 2-3 upgrades
2 Index KtpJoystickIsInstalled 4-8 KtpPotilsInstalled 4-8 KtpSetPotiCalibData 4-13 KtpSetWheelValue 4-14 KtpWheelIsInstalled 4-8 R Registry 1-5 Runtime environment 1-9 S Publication 2727-UM004B-EN-P - February 2004 SDK overview 3-1 Software boot sequence 1-4 input device handlers 1-8 local file systems 1-7 runtime environment 1-9 system shutdown 1-10 Windows CE OS 1-3 Windows CE Registry 1-5 start and close functions 4-2 KtpAPIDeinit 4-3 KtpAPIInit 4-3
Rockwell Automation Support Rockwell Automation provides technical information on the web to assist you in using our products. At http://support.rockwellautomation.com, you can find technical manuals, a knowledge base of FAQs, technical and application notes, sample code and links to software service packs, and a MySupport feature that you can customize to make the best use of these tools.
