UPS25 API Manual for Windows
98/NT4/2000/XP
Version 2.0
SWM-640020008
Rev. A
ISO9001 and AS9100 Certified
RTD Embedded Technologies, INC.
103 Innovation Blvd.
State College, PA 16803-0906
Phone: +1-814-234-8087
FAX: +1-814-234-5218
E-mail
sales@rtd.com
techsupport@rtd.com
web site
http://www.rtd.com
Revision History
UPS25 API Manual for Windows 98/NT4/2000/XP
ii
09/23/2004
Revision A issued
Documented for ISO9000
UPS25 API Manual for Windows 98/NT4/2000/XP
Published by:
RTD Embedded Technologies, Inc.
103 Innovation Blvd.
State College, PA 16803-0906
Copyright 2004 by RTD Embedded Technologies, Inc.
All rights reserved
Printed in U.S.A.
The RTD Logo is a registered trademark of RTD Embedded Technologies. cpuModule and
utilityModule are trademarks of RTD Embedded Technologies. PS/2, PC/XT, PC/AT and IBM
are trademarks of International Business Machines Inc. MS-DOS, Windows, Windows 98,
Windows NT, Windows 2000 and Windows XP are trademarks of Microsoft Corp. PC/104 is a
registered trademark of PC/104 Consortium. All other trademarks appearing in this document are
the property of their respective owners.
iii
UPS25 API Manual for Windows 98/NT4/2000/XP
Table of Contents
TABLE OF CONTENTS ..............................................................................................................4
WINDOWS INSTALLATION .....................................................................................................5
INSTALLATION OF THE DRIVER AND EXAMPLE PROGRAMS...........................................................5
THE UPS25 BOARD DRIVER..........................................................................................................5
THE DRIVER FUNCTIONS........................................................................................................5
GETTING A HANDLE TO THE BOARD ..............................................................................................5
CATCHING INTERRUPTS ................................................................................................................6
FUNCTION REFERENCE ..........................................................................................................7
BOARD CONTROL FUNCTIONS .............................................................................................8
UPS25_GET_CONTROL ........................................................................................................8
UPS25_SET_CONTROL .........................................................................................................8
UPS25_SET_DISCONNECTBATT..........................................................................................9
UPS25_SET_MODE................................................................................................................9
UPS25_SET_NODISCONNECTBATT ....................................................................................9
UPS25_SET_POWER_DOWN_CONTROL ..........................................................................10
BOARD INFORMATION FUNCTIONS..................................................................................11
UPS25_GET_INFO...............................................................................................................11
UPS25_GET_STATUS ..........................................................................................................11
UPS25_GET_POWER_DOWN_CONTROL .........................................................................12
LIMITED WARRANTY.............................................................................................................13
UPS25 API Manual for Windows 98/NT4/2000/XP
iv
Windows Installation
Installation of the Driver and Example Programs
Before installing the driver and example program files, you need to install the UPS25 board in
your PC. Please follow the instructions in the hardware manual to install the board.
On the installation diskette you can found the Setup.exe program, which installs on your PC the
UPS board driver and program. The setup program automatically detects your operating system
and installs the appropriate files on your PC.
After starting the setup, please follow the instructions on the screen to install the programs. You
can select the directory where to install the files.
The setup also adds to the ‘Start menu’ under the ‘Programs’ folder of your Windows system the
‘RTD\UPS25’ folder. It contains shortcuts to the program, the changes.txt and the readme.txt file.
The source code for the ups25 program will be installed in the target directory under the
‘Application_Src’ folder. This folder contains the program source for the UPS25 board, and the
project files for Microsoft Visual C++ users to rebuild the programs. The program is compiled
with the Microsoft Visual C++ ver. 6.0.
Uninstallation: you can uninstall the a2DIO driver and program under the ‘Control panel’ with
the ‘Add/Remove Programs’ tool.
The UPS25 board driver
The base address and IRQ of the a2DIO board are set by jumpers on the board.
For Windows 98/2000/XP the operating system uses a WDM driver and it can be configured in
the Control Panel/System/[Hardware]/Device Manager.
For Windows NT there is a Hardware Settings option available in the UPS25 program.
The Driver Functions
The resources on the a2DIO board can be accessed from Windows through the driver IOCTL
functions. Using IOCTL’s is the standard way of communicating with a windows driver using the
DeviceIOControl command
In the program source you can find different examples how to use the driver.
Getting a handle to the board
The DeviceIOControl functions that are used to communicate with the board require a handle as
the first passed parameter. To get the handle you must open the board using the following code:
HANDLE hDevice = CreateFile("\\\\.\\Ups250", GENERIC_READ |
GENERIC_WRITE, FILE_SHARE_READ, NULL, OPEN_EXISTING, 0, NULL);
Catching Interrupts
The driver can signal a program when an interrupt is received from the board. To do this, you
should use the UPS25_SET_MODE call:
OVERLAPPED o;
o.hEvent = CreateEvent(NULL, FALSE, FALSE, NULL);
ENABLEINTERRUPTS Msg;
Msg.IntEvent = o.hEvent;
ULONG i;
DeviceIoControl(hDevice,UPS25_SET_MODE,&Msg,
sizeof(ENABLEINTERRUPTS), NULL, 0, &i, &o);
When an interrupt is received from the board, the event ‘o.hEvent’ will be signaled. Normally you
would have a thread waiting on the event before performing an action. See the ‘ServiceThread’
function in the application source for how to do this. Also see the ‘OpenDevice’ function where it
creates the thread using ‘CreateThread’.
UPS25 API Manual for Windows 98/NT4/2000/XP
6
Function Reference
7
UPS25 API Manual for Windows 98/NT4/2000/XP
Board Control Functions
UPS25_GET_CONTROL
Description:
This IOCTL call returns the current configuration of the board.
Returns:
An eight bit value:
BIT 0: 0 – Interrupts Disabled
1 – Interrupts Enabled
BIT 1: 0 – Discharge Disabled
1 – Discharge Enabled
BIT 2: 0 – Batteries disconnected from board to prevent discharge
1 – Batteries connected to board for backup purposes
BIT 3: 0 – Charger active. Charging can take place
1 – Charger inactive. No charging possible.
Example:
UCHAR Control;
ULONG BytesReturned;
DeviceIOControl(hDevice,UPS25_GET_CONTROL, NULL,
0,&Control, sizeof(Control),&BytesReturned,NULL);
UPS25_SET_CONTROL
Description:
This IOCTL call sets the current configuration of the board.
Parameters:
An eight bit value:
BIT 0: 0 – Interrupts Disabled
1 – Interrupts Enabled
BIT 1: 0 – Discharge Disabled
1 – Discharge Enabled
BIT 2: 0 – Batteries disconnected from board to prevent discharge
1 – Batteries connected to board for backup purposes
BIT 3: 0 – Charger active. Charging can take place
1 – Charger inactive. No charging possible.
Example:
UPS25 API Manual for Windows 98/NT4/2000/XP
8
UCHAR Control;
ULONG BytesReturned;
DeviceIOControl(hDevice,UPS25_SET_CONTROL,&Control,sizeof(C
ontrol),NULL,0,&BytesReturned,NULL);
UPS25_SET_DISCONNECTBATT
Description:
This IOCTL call tells the driver to disconnect the battery when the system shuts down.
Parameters:
None:
Example:
ULONG BytesReturned;
DeviceIoControl(hDevice, UPS25_SET_DISCONNECTBATT, NULL, 0,
NULL, 0, &BytesReturned, NULL);
UPS25_SET_MODE
Description:
This IOCTL call initializes an event object that will be set when an interrupt occurs on the board.
Parameters:
An ENABLEINTERRUPTS structure.
Example:
OVERLAPPED o;
o.hEvent = CreateEvent(NULL, FALSE, FALSE, NULL);
ENABLEINTERRUPTS Msg;
Msg.IntEvent = o.hEvent;
ULONG i;
DeviceIoControl(hDevice,UPS25_SET_MODE,&Msg,
sizeof(ENABLEINTERRUPTS), NULL, 0, &i, &o);
UPS25_SET_NODISCONNECTBATT
Description:
This IOCTL call tells the driver not to disconnect the battery when the system shuts down.
Parameters:
None:
9
UPS25 API Manual for Windows 98/NT4/2000/XP
Example:
ULONG BytesReturned;
DeviceIoControl(hDevice, UPS25_SET_NODISCONNECTBATT, NULL,
0, NULL, 0, &BytesReturned, NULL);
UPS25_SET_POWER_DOWN_CONTROL
Description:
This IOCTL call alters the state of the backlight switch.
Parameters:
An 8 Bit value:
BIT 0: 0 – Backlight is disabled.
1 – Backlight is enabled.
Example:
UCHAR PowerDown;
ULONG BytesReturned;
PowerDown = 1;
// Enable the backlight
DeviceIOControl(hDevice,UPS25_SET_POWER_DOWN_CONTROL,
&PowerDown, sizeof(PowerDown),NULL,0,&BytesReturned,NULL);
UPS25 API Manual for Windows 98/NT4/2000/XP
10
Board Information Functions
UPS25_GET_INFO
Description:
This IOCTL gathers information about the UPS25 driver.
Return Value:
An 8 bit value:
BIT 0,1:
BIT 2:
0 – SYS Driver (Windows NT)
2 – WDM Driver (Windows98/ME/2000/XP);
0 – Interrupts Disabled. The IRQ resource is absent in the current
configuration. If you want to use interrupts you should select a
configuration with interrupts.
1 – Interrupts Enabled.
Example:
UCHAR Info;
ULONG BytesReturned;
DeviceIOControl(hDevice, UPS25_GET_INFO, NULL, 0, &Info,
sizeof(Info), &BytesReturned, NULL);
UPS25_GET_STATUS
Description:
This IOCTL gathers the current status of the board.
Return Value:
An 8 bit value:
BIT 0:
BIT 1:
BIT 2:
BIT 3:
0 – Main Supply voltage low. System is in backup state
1 – Main power OK.
0 – Battery Voltage Low.
1 – Battery Voltage OK.
Charger Status LED. See Table 4-1 ‘Charger status LED functional
description’ in the hardware manual.
Charger Temperature LED
0 – Battery Temperature out of limits. No charging possible.
1 – Battery Temperature OK. Charging can take place.
Example:
UCHAR Status;
ULONG BytesReturned;
DeviceIOControl(hDevice, UPS25_GET_STATUS, NULL, 0,
&Status, sizeof(Status), &BytesReturned, NULL);
11
UPS25 API Manual for Windows 98/NT4/2000/XP
UPS25_GET_POWER_DOWN_CONTROL
Description:
This IOCTL call returns the current status of the backlight switch.
Returns:
An 8 Bit value:
BIT 0: 0 – Backlight is disabled.
1 – Backlight is enabled.
Example:
UCHAR PowerDown;
ULONG BytesReturned;
DeviceIOControl(hDevice,UPS25_GET_POWER_DOWN_CONTROL, NULL,
0, &PowerDown, sizeof(PowerDown),&BytesReturned,NULL);
UPS25 API Manual for Windows 98/NT4/2000/XP
12
Limited Warranty
RTD Embedded Technologies, Inc. warrants the hardware and software products it
manufactures and produces to be free from defects in materials and workmanship for one
year following the date of shipment from RTD Embedded Technologies, INC. This
warranty is limited to the original purchaser of product and is not transferable.
During the one year warranty period, RTD Embedded Technologies will repair or
replace, at its option, any defective products or parts at no additional charge, provided
that the product is returned, shipping prepaid, to RTD Embedded Technologies. All
replaced parts and products become the property of RTD Embedded Technologies.
Before returning any product for repair, customers are required to contact the factory for
an RMA number.
THIS LIMITED WARRANTY DOES NOT EXTEND TO ANY PRODUCTS WHICH
HAVE BEEN DAMAGED AS A RESULT OF ACCIDENT, MISUSE, ABUSE (such
as: use of incorrect input voltages, improper or insufficient ventilation, failure to follow
the operating instructions that are provided by RTD Embedded Technologies, "acts of
God" or other contingencies beyond the control of RTD Embedded Technologies), OR
AS A RESULT OF SERVICE OR MODIFICATION BY ANYONE OTHER THAN
RTD Embedded Technologies. EXCEPT AS EXPRESSLY SET FORTH ABOVE, NO
OTHER WARRANTIES ARE EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, AND RTD Embedded Technologies
EXPRESSLY DISCLAIMS ALL WARRANTIES NOT STATED HEREIN. ALL
IMPLIED WARRANTIES, INCLUDING IMPLIED WARRANTIES FOR
MECHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE
LIMITED TO THE DURATION OF THIS WARRANTY. IN THE EVENT THE
PRODUCT IS NOT FREE FROM DEFECTS AS WARRANTED ABOVE, THE
PURCHASER'
S SOLE REMEDY SHALL BE REPAIR OR REPLACEMENT AS
PROVIDED ABOVE. UNDER NO CIRCUMSTANCES WILL RTD Embedded
Technologies BE LIABLE TO THE PURCHASER OR ANY USER FOR ANY
DAMAGES, INCLUDING ANY INCIDENTAL OR CONSEQUENTIAL DAMAGES,
EXPENSES, LOST PROFITS, LOST SAVINGS, OR OTHER DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PRODUCT.
SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF
INCIDENTAL OR CONSEQUENTIAL DAMAGES FOR CONSUMER PRODUCTS,
AND SOME STATES DO NOT ALLOW LIMITATIONS ON HOW LONG AN
IMPLIED WARRANTY LASTS, SO THE ABOVE LIMITATIONS OR
EXCLUSIONS MAY NOT APPLY TO YOU.
THIS WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS, AND YOU MAY
ALSO HAVE OTHER RIGHTS WHICH VARY FROM STATE TO STATE.
13
UPS25 API Manual for Windows 98/NT4/2000/XP
RTD Embedded Technologies, Inc.
103 Innovation Blvd.
State College PA 16803-0906
USA
Our website: www.rtd.com
UPS25 API Manual for Windows 98/NT4/2000/XP
14
Download PDF

advertising